docs: v5.0.0 goal + roadmap + foundation plan

- tasks/v5.0.0-goal.md: 7-Pillar Vision, Breaking Changes, Release-Phasen
- tasks/v5.0.0-roadmap.md: Reality-Check vs Goal, 11-Plan Execution-Order
- tasks/v5.0.0-plan-01-foundation.md: Vitest + 5 Pure-Module-Extraktionen

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tasks/v5.0.0-goal.md

@@ -0,0 +1,275 @@
+# Twitch VOD Manager — v5.0.0 Goal
+
+**Baseline:** v4.6.155 (Stand 2026-05-11)
+**Target:** v5.0.0
+**Status:** Draft / nicht freigegeben
+**Sprache:** Deutsch (Stack-Begriffe englisch)
+
+---
+
+## 1. Executive Summary
+
+Nach 155 Patches im 4.6er-Zyklus ist das Produkt poliert, aber im Kern unverändert seit 4.0: monolithische `main.ts` (~3700 Zeilen), JSON-File-Persistenz, Vanilla-DOM-Renderer, kein Live-Recording, keine sub-only Unterstützung, keine Tests jenseits Playwright-Smoke.
+
+**v5.0.0 ist der Bruch:** Aufnahme statt nur Download, SQLite statt JSON, modulare Domain-Architektur, Twitch-OAuth, optionales Web-Worker-Offloading für grosse Listen. Sieben Feature-Pillars, drei harte Breaking Changes, klarer Migrationspfad von 4.6.x.
+
+**Was 5.0.0 NICHT ist:** kein React/Vue-Rewrite, kein Plattform-Hop (bleibt Electron + Win), kein neues Bezahlmodell. Es bleibt der gleiche Single-User-Desktop-Client — nur deutlich erwachsener.
+
+---
+
+## 2. Why Major Bump?
+
+Ein Major-Sprung ist gerechtfertigt, wenn **mindestens zwei** Kriterien erfuellt sind:
+
+| Kriterium | 5.0.0 trifft zu? | Belege |
+|---|---|---|
+| Breaking Change im Config-/Datenformat | Ja | JSON → SQLite Migration, Schema v4 → v5 |
+| Neues Kern-Feature (nicht Inkrement) | Ja | Live-Stream-Recording (sub-only via OAuth), Scheduled-Recording |
+| Architektur-Bruch | Ja | main.ts Split in 6+ Domain-Module |
+| Min-OS-/Runtime-Bump | Ja | Electron 28 → 32, Node 18 → 22, Drop Win < 10 1809 |
+| User-spuerbare UI-Verschiebung | Ja | Virtual-List, Mini-Player, Theme-Engine |
+
+---
+
+## 3. Themes & Vision
+
+Drei Leitthemen ueber allen Features:
+
+### 3.1 Vom Downloader zum Recorder
+v4 reagiert: VOD existiert auf Twitch → wir laden runter. v5 agiert proaktiv: Stream geht live → wir nehmen direkt mit. Damit fallen Sub-Only-VODs (oft 60 Tage Retention), 7-Tage-Standard-Retention und geloeschte VODs als Verlust-Szenarien weg.
+
+### 3.2 Vom Tool zur Platform
+Domain-Module mit klaren Schnittstellen statt einem 3700-Zeilen-Monolith. Optionaler Plugin-Hook fuer Post-Download-Actions (z. B. Auto-Upload-Skript, Custom-Rename, Notify-Discord). Spaeter wartbar, leichter testbar.
+
+### 3.3 Vom Hobby zum stabilen Daily-Driver
+SQLite + Crash-Recovery + Chunk-Hashing + echte Unit-Tests. Wer 500 VODs queued, soll nicht in JSON-Lock-Konflikte laufen oder beim Crash 4 Stunden Download verlieren.
+
+---
+
+## 4. Feature-Pillars
+
+### Pillar 1 — Live Stream Recording (P0)
+
+**Was:** App kann laufende Streams in Echtzeit mitschneiden, nicht nur VODs post-hoc downloaden.
+
+**Warum:** Sub-only Streams haben oft keine VOD-Retention oder Sub-only-VODs werden nach 60 Tagen geloescht. Recording ist der einzige Weg, sie dauerhaft zu sichern.
+
+**Scope:**
+- Streamlink-basierte Aufnahme aktiver Live-Streams (Quality-Selector wie bei VODs)
+- Auto-Start: "wenn Streamer X live geht, Recording starten" (Polling-Intervall pro Streamer konfigurierbar, default 60s)
+- Auto-Stop bei Stream-Ende + Final-Mux mit ffmpeg
+- Resume bei Mid-Stream-Disconnect (neuer HLS-Segment-Pointer, append-Mode)
+- Sub-only Streams: nutzt OAuth-Token aus Pillar 2
+
+**Acceptance:**
+- 4-Stunden-Test-Stream wird ohne Datenverlust aufgenommen
+- Disconnect-Wiederherstellung in < 15s
+- File-Output ist mux-fertig MP4 (kein .ts-Reste, kein orphan-Index)
+- UI zeigt "LIVE REC" Badge + Recording-Dauer im Streamer-Eintrag
+
+### Pillar 2 — Twitch-OAuth (Device Code Flow) (P0)
+
+**Was:** Native Anmeldung mit Twitch-Account, OAuth-Token wird verschluesselt in OS-Keychain (Win Credential Manager) gespeichert.
+
+**Warum:** Sub-only Inhalte, hoehere Rate-Limits (Helix mit User-Token > App-Token in vielen Endpoints), private Follow-Liste fuer Auto-Discovery, korrekte Mature-Content-Gating-Behandlung.
+
+**Scope:**
+- Device Code Flow (kein Browser-Embed, kein localhost-Callback noetig — sauberer fuer Desktop)
+- Multi-Account: bis zu 3 parallele Accounts (Haupt, Alt, Auto-Sub)
+- Token-Refresh automatisch, Fail-Soft auf App-Token
+- Settings-Tab "Accounts" mit Liste, Login/Logout, "Default fuer Recording"
+
+**Acceptance:**
+- Login dauert < 60s vom Klick bis Token in Keychain
+- Sub-only Test-Channel laesst sich aufnehmen mit eingeloggtem Sub-Account
+- Logout entfernt Token sauber aus Keychain (audit per Tool: kein orphan-Entry)
+
+### Pillar 3 — SQLite-Migration (P0, Breaking)
+
+**Was:** Alle App-Daten (Queue, Stats, Archiv-Index, Streamer-Liste, Recording-History) wandern von JSON-Files nach `app.db` (better-sqlite3 oder besser-im-Bundle-Alternative).
+
+**Warum:** JSON wird ab ~1000 VODs spuerbar lahm (Full-File-Rewrite bei jedem Save). SQLite gibt indexed lookups, atomic transactions, kein Lock-Konflikt bei parallelen Writes, einfache Migrationen.
+
+**Scope:**
+- Schema v5 mit Tabellen: `queue`, `archive`, `streamers`, `recordings`, `stats_daily`, `clip_index`, `config_blob`
+- Migrator-Script: liest alle `C:\ProgramData\Twitch_VOD_Manager\*.json` und schreibt in `app.db`
+- Backup vor Migration: `.json` → `.json.v4-backup`
+- Read-Path bleibt API-kompatibel fuer Renderer (IPC-Surface unveraendert)
+- WAL-Mode + busy-timeout 5000ms
+
+**Acceptance:**
+- Migrator laeuft idempotent (zweimal aufrufen = gleicher Endzustand, kein Daten-Duplikat)
+- Failure-Rollback: bei Migrator-Crash bleibt App auf JSON, kein Daten-Verlust
+- Query "alle VODs eines Streamers" < 50ms bei 10k Archiv-Eintraegen (gemessen)
+
+### Pillar 4 — Architektur-Refactor: main.ts Split (P1)
+
+**Was:** `main.ts` (3700 LoC) wird in Domain-Module zerlegt.
+
+**Ziel-Struktur:**
+```
+src/main/
+  index.ts              Entry, app lifecycle, BrowserWindow
+  domain/
+    twitch-api.ts       Helix + GraphQL Calls, Rate-Limit-Handling
+    downloader.ts       Streamlink/ffmpeg Orchestration (VOD + Live)
+    recorder.ts         Live-Stream-Recording (NEU)
+    queue.ts            Queue-State-Machine, persistence-call
+    config.ts           Settings-Schema, defaults, validation
+    auth.ts             OAuth, Token-Storage, Keychain (NEU)
+    cache.ts            In-Memory-TTL-Caches
+    updater.ts          electron-updater Wrapper
+  infra/
+    db.ts               SQLite-Wrapper, prepared statements
+    logger.ts           Strukturiertes Logging (JSON-Lines)
+    ipc.ts              Channel-Registry, type-safe Handler
+  ipc-bridge.ts         exportiert nur die API-Surface fuer preload.ts
+```
+
+**Constraint:** Renderer-IPC-Surface bleibt rueckwaertskompatibel — kein Renderer-Rewrite noetig.
+
+**Acceptance:**
+- Kein Modul groesser als 800 LoC
+- Zyklische Imports = 0 (`madge --circular` oder aequivalent)
+- E2E-Tests gruen ohne Anpassung
+
+### Pillar 5 — UI Power-Features (P1)
+
+**Was:** Renderer-seitige Spruenge, die User direkt sehen.
+
+**Scope:**
+- **Virtualized List** fuer Queue/Archive (react-window-aequivalent vanilla, oder `@tanstack/virtual-core` vanilla-Adapter) — 10k Eintraege ohne Lag
+- **Mini-Player Panel**: HLS-Stream in App-eigenem `<video>` (hls.js), kollabierbar, fuer Recording-Live-Preview + VOD-Vorschau
+- **Theme-Engine**: drei eingebaute Themes (Default, Dark High-Contrast, Light) + Custom-CSS-Slot mit Live-Reload
+- **Template-Preview live**: Title-Template aendert sich, Beispiel-Output rendert in Echtzeit unter dem Input
+- **Drag-Reorder** in Queue (HTML5-DnD, persistiert Position-Index in DB)
+- **Command-Palette** (Ctrl+K): Schnellaktionen, Streamer-Suche, Settings-Jump
+
+**Acceptance:**
+- Scroll-Performance bei 5000 Eintraegen: 60fps (Chrome DevTools Performance-Trace)
+- Theme-Switch ohne Reload
+- Command-Palette < 100ms First-Result-Latency
+
+### Pillar 6 — Smart-Resume & Integrity (P1)
+
+**Was:** Downloads/Recordings ueberleben Crash, Disconnect, Reboot.
+
+**Scope:**
+- Jeder HLS-Segment-Chunk bekommt sha1, geschrieben in DB-Tabelle `chunk_index`
+- Bei Resume: vergleicht local-chunk-hash mit Manifest, ueberspringt valide Chunks, faengt am ersten Mismatch an
+- Crash-Recovery beim Startup: scannt `recordings`-Tabelle nach `state=running` und bietet Resume-Dialog an
+- Final-Integrity-Check: ffprobe-Aufruf auf fertige Datei, schreibt `verified=1` in DB
+
+**Acceptance:**
+- App-Kill mid-download → Neustart → Resume genau ab Abbruch-Chunk (manueller Test)
+- Korrupte Chunk-Datei wird erkannt und neu geladen (per Mutation-Test: zufaelliges Byte flippen)
+
+### Pillar 7 — Scheduled Recording & Auto-Discovery (P2)
+
+**Was:** Automatisierungs-Layer ueber Pillar 1+2.
+
+**Scope:**
+- Pro Streamer: "Auto-Record on Live: ja/nein" + Quality-Preset
+- Zeit-Plan: "nur zwischen 18-02 Uhr aufnehmen" (vermeidet Reruns/Marathons)
+- **Top-Clip-Crawler**: pro Streamer alle X Tage die N besten Clips (Helix `/clips`) downloaden
+- **Follow-Sync**: importiert eingeloggte Follow-Liste als Streamer-Eintraege (opt-in)
+
+**Acceptance:**
+- 3-Streamer-Auto-Record-Test ueber 24h ohne Eingriff, kein Doppelaufnahme bei Stream-Reconnect
+
+---
+
+## 5. Breaking Changes
+
+| # | Was bricht | Migration | User-Impact |
+|---|---|---|---|
+| BC-1 | Config-Speicherort | Migrator on first 5.0 start, `.v4-backup` der JSONs bleibt liegen | Einmalig 5-30s Migrations-Dialog |
+| BC-2 | Min-Windows: Win10 1809 (Oktober 2018) | Installer-Check, blockiert Setup auf alten OS | Sehr wenige User betroffen |
+| BC-3 | Node-API-Version: Plugins die auf Node 18 N-API gebaut sind muessen rebuild (relevant fuer better-sqlite3, evtl. fsevents) | Pre-built Binaries im Bundle | Transparent fuer User |
+| BC-4 | Streamer-Eintrag-Format aendert sich (neue Felder: `oauth_account_id`, `auto_record`, `record_quality`) | Auto-Default bei Migration | Transparent |
+| BC-5 | Auto-Updater Channel: alte 4.x-Clients sehen 5.0 nicht im stable-Channel, sondern in `next` (opt-in) | User muss bewusst Channel wechseln; nach 4 Wochen Beta: 5.0 → stable | Bewusste User-Aktion |
+
+---
+
+## 6. Tech-Stack Upgrades
+
+| Komponente | 4.6 | 5.0 | Grund |
+|---|---|---|---|
+| Electron | 28.x | 32.x (oder LTS aktuell) | Security-Patches, Chromium-Upgrade |
+| Node | 18 | 22 | LTS, V8 perf |
+| TypeScript | 5.3 | 5.6+ | satisfies / decorators stable |
+| ESLint | 10 | aktueller flat-config | passt |
+| Neu: better-sqlite3 | — | latest | SQLite-Persistenz |
+| Neu: hls.js | — | latest | Mini-Player |
+| Neu: keytar (oder Electron safeStorage) | — | latest | OAuth-Token-Storage |
+| Playwright | 1.59 | aktuell | E2E |
+| Neu: vitest | — | latest | Unit-Tests |
+
+---
+
+## 7. Quality & DevX
+
+- **Unit-Tests (Vitest):** mind. 60% Coverage in `src/main/domain/*` zum 5.0.0-GA. Reine Logik-Tests, kein Electron-Boot.
+- **E2E (Playwright):** bestehende Suite plus drei neue Szenarien (Login, Live-Record-Start, SQLite-Migration).
+- **CI:** weiterhin lokal (Solo-Projekt), aber `npm run check:all` = build + lint + vitest + e2e in einem Skript.
+- **Logging:** strukturiert JSONL in `logs/app-YYYY-MM-DD.jsonl`, 14-Tage-Retention, mit Level (debug/info/warn/error) und Trace-IDs pro Download/Recording.
+- **Crash-Reports:** opt-in Sentry (oder einfacher: lokaler Crash-Log-Export + Copy-to-Clipboard-Button). Default: aus, kein Telemetrie-Surprise.
+
+---
+
+## 8. Release-Phasen
+
+| Phase | Version | Was rein | Wann (relativ) |
+|---|---|---|---|
+| Alpha-1 | 5.0.0-alpha.1 | SQLite-Migrator + Architektur-Split | T+0 |
+| Alpha-2 | 5.0.0-alpha.2 | OAuth + Live-Recording (Baseline) | T+2 Wo |
+| Beta-1 | 5.0.0-beta.1 | UI Power-Features, Smart-Resume | T+4 Wo |
+| Beta-2 | 5.0.0-beta.2 | Scheduled/Auto-Discovery, Bug-Fixes | T+6 Wo |
+| RC | 5.0.0-rc.1 | nur noch Bugfixes, kein Feature-Add | T+8 Wo |
+| GA | 5.0.0 | Public, `next`-Channel → `stable` | T+10 Wo |
+
+Konkret Daten setze ich nicht — die haengen davon ab, wie eng du das fahren willst.
+
+---
+
+## 9. Out-of-Scope (bewusst NICHT in 5.0.0)
+
+- React/Vue/Svelte-Rewrite des Renderers (Risiko zu gross, Vanilla bleibt)
+- macOS/Linux-Builds (Electron-Builder kann, aber kein Test-Setup → erst 5.1+)
+- Cloud-Sync (Queue/Settings ueber Geraete) — eigener Major-Bump waert
+- Chat-Recording / Chat-Renderer (TwitchDownloaderCLI Integration) — verlockend, aber Scope-Creep → 5.1
+- Mobile-Companion-App
+- Plugin-API fuer Dritte (Hooks koennen wir intern bauen, aber kein public-API-Versprechen in 5.0)
+- AI-Highlight-Detection (lokales LLM) — Forschung, kein Produkt-Feature 2026
+
+---
+
+## 10. Definition of Done (5.0.0 GA)
+
+Alle Punkte erfuellt:
+
+1. [ ] Pillars 1-6 implementiert und in E2E-Tests abgedeckt (Pillar 7 darf teilweise sein, mind. Auto-Record-on-Live)
+2. [ ] SQLite-Migrator getestet auf realer 4.6-Installation mit 5k+ Archive-Eintraegen, idempotent, mit Rollback-Path
+3. [ ] OAuth-Token landet in Keychain, audit zeigt sauberen Logout
+4. [ ] Vitest-Coverage `src/main/domain` >= 60%
+5. [ ] Playwright-Suite gruen, inkl. drei neue Szenarien
+6. [ ] Mini-Player + Theme-Engine + Virtual-List manuell verifiziert (Demo-Video)
+7. [ ] Auto-Updater: bestehende 4.6-Installation kriegt 5.0 ueber `next`-Channel, Migration laeuft, App startet
+8. [ ] README + CLAUDE.md aktualisiert (neue Architektur, neue Commands, neue Settings)
+9. [ ] CHANGELOG-Eintrag mit allen Breaking Changes prominent oben
+10. [ ] Frische Installation aus `Twitch-VOD-Manager-Setup-5.0.0.exe` auf clean Win11-VM: erstes Recording lauft binnen 5 Minuten User-Klicks
+
+---
+
+## 11. Naechste Schritte (wenn du dieses Goal annimmst)
+
+1. Goal mit eigenem Realitaetscheck lesen — was streichen, was zuerst
+2. Pillar 3 (SQLite) zuerst, weil es Voraussetzung fuer 1, 6, 7 ist
+3. Branch `feat/v5-foundation` aufmachen, dort Architektur-Split + SQLite parallel
+4. Nach Alpha-1 entscheiden, ob OAuth vor UI-Refactor oder umgekehrt
+5. Eigenes `tasks/v5.0.0-checklist.md` aus Pillar-Acceptance-Criteria generieren, abhakbar
+
+---
+
+**Autor:** Claude (Opus 4.7, 1M context) — 2026-05-11
+**Review-Status:** unreviewed, Erstentwurf

tasks/v5.0.0-roadmap.md

@@ -0,0 +1,84 @@
+# v5.0.0 Roadmap (Reality-Aligned)
+
+**Baseline:** v4.6.155
+**Spec:** `tasks/v5.0.0-goal.md`
+**Last verified:** 2026-05-11
+
+---
+
+## Reality Check vs. Goal
+
+Beim Vergleich der echten Codebase (`src/main.ts` 7485 LoC mit 30+ Sektionen) gegen die Goal-Annahmen zeigt sich: einige "neu zu bauenden" Features existieren teilweise schon.
+
+| Pillar | Goal sagt | Reality | Restarbeit % |
+|---|---|---|---|
+| P1 — Live Stream Recording | "neu" | Auto-Record-Poller, Live-Recording-Events-Log, Live-Chat-Capture existieren | ~30% (Polish + Sub-only-Pfad nach OAuth) |
+| P2 — Twitch OAuth | "neu" | App nutzt nur public Web-Client-ID, keine User-Auth | 100% |
+| P3 — SQLite-Migration | "Breaking" | Config + Queue + Stats sind JSON-Files | 100% |
+| P4 — main.ts Split | "neu" | 7485 LoC Monolith, 30 Sektionen, schon klar getrennt | 100% (mechanische Arbeit) |
+| P5 — UI Power-Features | "neu" | Vanilla DOM, keine Virtualisierung, kein Mini-Player, ein Theme | 90% |
+| P6 — Smart-Resume | "neu" | `auto_resume_live_recording` Flag existiert, `auto_merge_resumed_parts`, Crash-Recovery rudimentaer | ~60% (Chunk-Hash + Integrity-Check fehlen) |
+| P7 — Scheduled/Auto-Discovery | "neu" | Auto-VOD-Download-Poller + Live-Status-Batch-Poller schon implementiert | ~30% (Top-Clip-Crawler, Follow-Sync fehlen) |
+
+**Konsequenz:** Reihenfolge der Plane orientiert sich am Restarbeits-Volumen und Dependencies.
+
+---
+
+## Execution Order
+
+```
+Plan 01: Foundation — Vitest + Pure-Utility-Extraction          [START HIER]
+  └─> Plan 02: Domain Modules (twitch-api, config, queue split)
+       └─> Plan 03: Domain Modules (download, record, cutter, stats)
+            └─> Plan 04: Final main.ts Split (ipc + index.ts + delete old main.ts)
+                 └─> Plan 05: SQLite Migration (P3)
+                      └─> Plan 06: OAuth (P2)
+                           ├─> Plan 07: Live-Recording Polish + Sub-only (P1)
+                           ├─> Plan 08: Auto-Discovery Erweiterung (P7)
+                           └─> Plan 09: UI Power-Features (P5)
+                                └─> Plan 10: Smart-Resume Finalisierung (P6)
+                                     └─> Plan 11: v5.0.0-rc.1 → GA
+```
+
+Plan 01-04 = Pillar 4 (Architektur-Split, monolithische Aufgabe in 4 Teile gesplittet).
+Plan 05 = Pillar 3.
+Plan 06 = Pillar 2.
+Plan 07-09 = Pillars 1, 7, 5 parallelisierbar (verschiedene Subsysteme).
+Plan 10 = Pillar 6.
+Plan 11 = Release-Phase.
+
+---
+
+## Plan Status
+
+| # | Plan | Datei | Status |
+|---|---|---|---|
+| 01 | Foundation: Vitest + Pure-Utility-Extraction | `tasks/v5.0.0-plan-01-foundation.md` | bereit, wird ausgefuehrt |
+| 02 | Domain Split Pt. 1 | `tasks/v5.0.0-plan-02-domain-pt1.md` | erstellt nach Plan 01 |
+| 03 | Domain Split Pt. 2 | `tasks/v5.0.0-plan-03-domain-pt2.md` | nach Plan 02 |
+| 04 | Final Architektur-Split | `tasks/v5.0.0-plan-04-final-split.md` | nach Plan 03 |
+| 05 | SQLite-Migration | `tasks/v5.0.0-plan-05-sqlite.md` | nach Plan 04 |
+| 06 | OAuth | `tasks/v5.0.0-plan-06-oauth.md` | nach Plan 05 |
+| 07 | Live-Rec Polish + Sub-only | `tasks/v5.0.0-plan-07-live-rec.md` | nach Plan 06 |
+| 08 | Auto-Discovery Erweiterung | `tasks/v5.0.0-plan-08-auto-disc.md` | nach Plan 06 |
+| 09 | UI Power | `tasks/v5.0.0-plan-09-ui-power.md` | nach Plan 06 |
+| 10 | Smart-Resume Final | `tasks/v5.0.0-plan-10-smart-resume.md` | nach Plan 09 |
+| 11 | Release 5.0.0 GA | `tasks/v5.0.0-plan-11-release.md` | nach Plan 10 |
+
+---
+
+## Versionsstrategie
+
+| Plan abgeschlossen | Version |
+|---|---|
+| Plan 01 | 5.0.0-alpha.0 (Foundation, opt-in via `next` channel) |
+| Plan 02 | 5.0.0-alpha.1 |
+| Plan 03 | 5.0.0-alpha.2 |
+| Plan 04 | 5.0.0-alpha.3 |
+| Plan 05 | 5.0.0-beta.0 (SQLite Migrator live, Breaking) |
+| Plan 06 | 5.0.0-beta.1 (OAuth live) |
+| Plan 07 + 08 + 09 | 5.0.0-beta.2, .3, .4 |
+| Plan 10 | 5.0.0-rc.1 |
+| Plan 11 | 5.0.0 (stable) |
+
+Pro Plan: ein Release-Tag, Auto-Updater Channel `next`. 4.6-User bleiben auf `stable` und kriegen nur Bugfix-Patches der 4.6 Linie (sofern bestellt).