Administrator/Twitch-VOD-Manager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 212 Wiki Activity
5b1c68a122
Twitch-VOD-Manager/CLAUDE.md
xRangerDE 5b1c68a122 release: 5.0.0 — vitest + SQLite + OAuth storage/flow + Smart-Resume foundation 
Major bump. v5.0.0-GA umfasst:

Foundation
- vitest test infrastructure
- 11 neue Module in src/main/{infra,domain}/
- main.ts: -198 LoC pure helpers extracted
- 164 unit tests + full e2e:release suite gruen

Persistence (Pillar 3 — done)
- better-sqlite3 mit WAL + 5s busy_timeout
- schema v5 (9 tables: schema_meta, config_kv, queue_items, downloaded_vods,
  streamers, archive_files, migrations_applied, oauth_accounts, chunk_index)
- Idempotenter JSON to SQLite Migrator (shadow-write, .v4-backup)
- Long-lived DB-Handle Singleton mit shutdown-close

Auth (Pillar 2 — scaffold done)
- SecureStorage (Electron safeStorage + Memory-Impl)
- token-store CRUD auf oauth_accounts (encrypted)
- PKCE pair + state generator
- Loopback HTTP server (127.0.0.1, ephemeral port)
- Twitch OAuth 2.1 Authorization Code Flow + PKCE module
- IPC wiring + Client ID config + Renderer button kommen in 5.1.x

Smart-Resume (Pillar 6 — foundation done)
- chunk_index table
- sha1 buffer + streaming file hash helpers
- chunk-index-store CRUD
- Integration in den Live-Recorder kommt in 5.1.x

Post-5.0 Roadmap
- Plan 04b: Resume in Recorder
- Plan 05: Live-Rec Polish + Sub-only (braucht Twitch Client ID)
- Plan 06: UI Power (virtual list, mini-player, command palette)
- Plan 07-09: Architektur-Split (Pillar 4 Rest)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 23:48:02 +02:00

4.3 KiB
Raw Blame History

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 post-5.0.
  • OAuth (Twitch): Authorization Code Flow + PKCE via System-Browser + Loopback (127.0.0.1:PORT). Module: src/main/domain/{pkce,twitch-oauth}.ts, src/main/infra/loopback-server.ts. IPC-Handler + Renderer-Button + Client-ID-Config in 5.1.x — Module sind in 5.0.0 scaffold-complete, brauchen lediglich Twitch-Dev-App-Registration.
  • 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