61 lines
4.0 KiB
Markdown
61 lines
4.0 KiB
Markdown
# 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
|