From 1184e57da5d83c25fd80eecd18b7031e3ac6db3d Mon Sep 17 00:00:00 2001 From: xRangerDE Date: Mon, 11 May 2026 21:50:57 +0200 Subject: [PATCH] docs: CLAUDE.md notes new test:unit script + v5 split status Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8339e35 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,58 @@ +# 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). Config auto-saves with debounce. +- **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. +- **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