Twitch-VOD-Manager/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run Commands

Command	Purpose
npm run build	Compile TypeScript (tsc → dist/)
npm start	Build + launch Electron app
npm run test:unit	Vitest Unit-Tests (src/**/*.test.ts)
npm run test:unit:watch	Vitest Watch-Mode
npm run test:e2e:update-logic	Unit test for version comparison logic (fast, no Playwright)
npm run test:e2e	Basic Playwright smoke test
npm run test:e2e:guide	Template guide smoke test
npm run test:e2e:full	Full end-to-end test suite
npm run test:e2e:release	Full pre-release verification (build + unit + update-logic + 3 Playwright-Stages)
npm run dist:win	Run all tests then build Windows NSIS installer
npm run release:gitea	Upload release assets to Gitea (requires GITEA_TOKEN env var)

Architecture

Electron app (TypeScript, no UI framework — vanilla HTML/CSS/JS in renderer).

Process Model

• Main process (src/main.ts, ~7300 lines): Core logic — Twitch API, download queue, streamlink/ffmpeg orchestration, config persistence, auto-updater, caching
• Preload (src/preload.ts): Context bridge exposing a controlled window.api IPC surface
• Renderer (src/renderer*.ts): UI split across multiple files by concern (queue, settings, updates, streamers, localization)
• Extrahierte Module (src/main/): v5-Architektur-Umbau im Gang. Reine Helpers bereits ausgelagert nach src/main/infra/ (fs-atomic, duration) und src/main/domain/ (update-version-utils, i18n-backend, config-normalize). Roadmap fuer den vollstaendigen Split: tasks/v5.0.0-roadmap.md.

Key Patterns

• IPC via context bridge only — all main↔renderer communication goes through preload.ts. Never use ipcRenderer directly.
• State: Global variables in both processes. Main process is source of truth; renderer syncs via IPC events.
• Persistence: JSON files in C:\ProgramData\Twitch_VOD_Manager\ (config, queue, debug log) bleiben Source-of-Truth. Config auto-saves with debounce. Seit v5.0.0-alpha.1 spiegelt der Migrator (src/main/domain/migrator.ts) Konfiguration, Queue, downloaded_vod_ids und Streamer-Listen einmalig nach app.db (SQLite, better-sqlite3). Schema: src/main/infra/schema-v5.ts. Cutover (SQLite wird Master) in spaeterem Plan.
• Queue sync throttling: Adaptive refresh rates based on window visibility (900ms active → 9000ms hidden).
• Caching: Multi-tier in-memory caches (user IDs, VOD lists, clip info) with configurable TTL and periodic cleanup.
• Error classification: Errors categorized as network/rate_limit/auth/tooling/integrity/io/validation/unknown with retry scheduling.
• Secrets: OAuth-Token (Twitch + spaeter) landen verschluesselt via Electron safeStorage (Win Credential Manager) in oauth_accounts Tabelle der SQLite. Zugriff ueber src/main/domain/token-store.ts. Memory-Impl fuer Tests.
• Smart-Resume: HLS-Chunk-sha1-Hashes koennen in chunk_index Tabelle protokolliert werden (src/main/domain/chunk-index-store.ts, src/main/infra/chunk-hash.ts). Vorbereitung fuer Crash-Recovery + Integrity-Check; Integration in Live-Recorder folgt in Plan 04b.
• Localization: EN (renderer-locale-en.ts) and DE (renderer-locale-de.ts) string tables.

External Tools

Downloads depend on streamlink and ffmpeg being available. The app caches their paths with 10-second TTL.

Release Process

Documented in README_AI_RELEASE.md. Key points:

• Hosted on Gitea at git.24-music.de
• Auto-updater requires 3 assets per release: .exe, .exe.blockmap, latest.yml
• Version set via npm version X.Y.Z --no-git-tag-version, commit as release: X.Y.Z, tag as vX.Y.Z
• Never commit tokens; use $env:GITEA_TOKEN in PowerShell

TypeScript Config

• Target: ES2022, strict mode enabled
• Source in src/, compiled to dist/
• No linter configured — TypeScript strict mode is the primary safety net