@argo-video/cli 0.1.0 → 0.2.0

package/docs/superpowers/plans/2026-03-12-argo.md

@@ -1,208 +0,0 @@
-# Argo Implementation Plan
-
-> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Build Argo — a CLI + library that turns Playwright demo scripts into polished product demo videos with AI-generated voiceover.
-
-**Architecture:** Four-stage pipeline (TTS → Record → Align → Export) orchestrated by a CLI. Library exports Playwright fixtures and helpers for authoring demos. Kokoro TTS via Transformers.js for local voiceover generation, ffmpeg for final video export.
-
-**Tech Stack:** TypeScript, Playwright, @huggingface/transformers (Kokoro TTS), ffmpeg (system dep), commander (CLI), vitest (testing)
-
----
-
-## File Structure
-
-```
-argo/
-├── src/
-│   ├── index.ts          # Public library exports
-│   ├── cli.ts            # CLI entry point — commander program
-│   ├── fixtures.ts       # Playwright test fixture (injects narration)
-│   ├── narration.ts      # NarrationTimeline class
-│   ├── captions.ts       # DOM caption overlay helpers
-│   ├── tts/
-│   │   ├── engine.ts     # TTSEngine interface + WAV utilities + MockTTSEngine
-│   │   ├── kokoro.ts     # Kokoro TTS via @huggingface/transformers
-│   │   ├── cache.ts      # ClipCache — SHA-256 content-addressed caching
-│   │   ├── generate.ts   # generateClips — reads manifest, checks cache, calls engine
-│   │   └── align.ts      # Clip alignment with overlap prevention
-│   ├── record.ts         # Playwright recording wrapper
-│   ├── export.ts         # ffmpeg video+audio merge
-│   ├── pipeline.ts       # Orchestrates TTS→record→align→export
-│   ├── config.ts         # ArgoConfig type, defineConfig(), loadConfig(), demosProject()
-│   └── init.ts           # Scaffolding: creates demos/, example files, config
-├── tests/
-│   ├── config.test.ts
-│   ├── narration.test.ts
-│   ├── captions.test.ts
-│   ├── fixtures.test.ts
-│   ├── export.test.ts
-│   ├── pipeline.test.ts
-│   ├── cli.test.ts
-│   ├── init.test.ts
-│   └── tts/
-│       ├── engine.test.ts
-│       ├── kokoro.test.ts
-│       ├── cache.test.ts
-│       ├── generate.test.ts
-│       └── align.test.ts
-├── bin/
-│   └── argo.js           # CLI bin shim
-├── package.json
-├── tsconfig.json
-└── .gitignore
-```
-
----
-
-## Chunk 1: Foundation (Tasks 1-4)
-
-### Task 1: Project Setup
-
-**Files:** Create: `package.json`, `tsconfig.json`, `bin/argo.js`, `.gitignore`, `src/index.ts`, `src/cli.ts`
-
-- [ ] **Step 1.1:** Create package.json with type: module, ESM config, dependencies (commander, @huggingface/transformers), peer deps (playwright, @playwright/test), dev deps (typescript, vitest)
-- [ ] **Step 1.2:** Create tsconfig.json (target ES2022, module NodeNext, outDir dist, strict)
-- [ ] **Step 1.3:** Create bin/argo.js shim: `#!/usr/bin/env node` + `import('../dist/cli.js')`
-- [ ] **Step 1.4:** Create .gitignore (node_modules, dist, .argo, videos, *.tsbuildinfo)
-- [ ] **Step 1.5:** Create placeholder src/index.ts and src/cli.ts
-- [ ] **Step 1.6:** npm install and verify tsc --noEmit passes
-- [ ] **Step 1.7:** Commit: "chore: project setup with deps, tsconfig, and bin shim"
-
-### Task 2: Config System
-
-**Files:** Create: `src/config.ts`, Test: `tests/config.test.ts`
-
-- [ ] **Step 2.1:** Write failing tests for defineConfig (defaults, merging, custom engine), demosProject (returns Playwright project), loadConfig (defaults, .js, .mjs, explicit path)
-- [ ] **Step 2.2:** Run tests — verify they fail
-- [ ] **Step 2.3:** Implement ArgoConfig types, defineConfig (deep merge with defaults), demosProject helper, loadConfig (searches for argo.config.ts/.js/.mjs, dynamic import)
-- [ ] **Step 2.4:** Run tests — verify they pass
-- [ ] **Step 2.5:** Commit: "feat: config system with defineConfig, loadConfig, and demosProject"
-
-### Task 3: NarrationTimeline
-
-**Files:** Create: `src/narration.ts`, Test: `tests/narration.test.ts`
-
-- [ ] **Step 3.1:** Write failing tests: start sets t=0, mark records elapsed ms, mark throws before start, mark throws on duplicate, getTimings returns copy, flush writes JSON and creates dirs
-- [ ] **Step 3.2:** Run tests — verify they fail
-- [ ] **Step 3.3:** Implement NarrationTimeline with Map-based timings, Date.now() tracking
-- [ ] **Step 3.4:** Run tests — verify they pass
-- [ ] **Step 3.5:** Commit: "feat: NarrationTimeline with start, mark, getTimings, and flush"
-
-### Task 4: Caption Helpers
-
-**Files:** Create: `src/captions.ts`, Test: `tests/captions.test.ts`
-
-- [ ] **Step 4.1:** Write failing tests: showCaption injects+waits+removes, hideCaption removes, withCaption wraps action, withCaption cleans up on throw
-- [ ] **Step 4.2:** Run tests — verify they fail
-- [ ] **Step 4.3:** Implement showCaption/hideCaption/withCaption using page.evaluate with styled overlay div
-- [ ] **Step 4.4:** Run tests — verify they pass
-- [ ] **Step 4.5:** Commit: "feat: caption helpers (showCaption, hideCaption, withCaption)"
-
----
-
-## Chunk 2: TTS System (Tasks 5-8)
-
-### Task 5: TTS Engine Interface + WAV Utilities
-
-**Files:** Create: `src/tts/engine.ts`, Test: `tests/tts/engine.test.ts`
-
-- [ ] **Step 5.1:** Write failing tests: createWavBuffer (valid header, correct data size, preserves samples), parseWavHeader (round-trip, rejects small/invalid), MockTTSEngine (interface compliance, valid WAV, records calls)
-- [ ] **Step 5.2:** Run tests — verify they fail
-- [ ] **Step 5.3:** Implement TTSEngine interface, createWavBuffer (mono 24kHz 32-bit float), parseWavHeader (find data chunk), createMockTTSEngine
-- [ ] **Step 5.4:** Run tests — verify they pass
-- [ ] **Step 5.5:** Commit: "feat(tts): TTSEngine interface, WAV utilities, and MockTTSEngine"
-
-### Task 6: Kokoro TTS Engine
-
-**Files:** Create: `src/tts/kokoro.ts`, Test: `tests/tts/kokoro.test.ts`
-
-- [ ] **Step 6.1:** Implement KokoroEngine: lazy-loads pipeline from @huggingface/transformers, generates WAV via createWavBuffer
-- [ ] **Step 6.2:** Write integration test (skipped in CI): generates valid WAV, throws on empty text
-- [ ] **Step 6.3:** Commit: "feat(tts): KokoroEngine with lazy model loading"
-
-### Task 7: Clip Caching
-
-**Files:** Create: `src/tts/cache.ts`, Test: `tests/tts/cache.test.ts`
-
-- [ ] **Step 7.1:** Write failing tests: isCached false/true, getCachedClip null/buffer, invalidation on text/voice/speed change, independent per demo
-- [ ] **Step 7.2:** Run tests — verify they fail
-- [ ] **Step 7.3:** Implement ClipCache: SHA-256 hash of {scene,text,voice,speed}, stores in .argo/<demo>/clips/<hash>.wav
-- [ ] **Step 7.4:** Run tests — verify they pass
-- [ ] **Step 7.5:** Commit: "feat(tts): ClipCache with SHA-256 content-addressed caching"
-
-### Task 8: TTS Generate Command
-
-**Files:** Create: `src/tts/generate.ts`, Test: `tests/tts/generate.test.ts`
-
-- [ ] **Step 8.1:** Write failing tests: generates all entries, uses cache on rerun, regenerates only changed, applies defaults, throws on missing file/invalid JSON/missing fields
-- [ ] **Step 8.2:** Run tests — verify they fail
-- [ ] **Step 8.3:** Implement generateClips: read manifest, validate entries, check cache, call engine, cache results
-- [ ] **Step 8.4:** Run tests — verify they pass
-- [ ] **Step 8.5:** Commit: "feat(tts): generateClips with manifest parsing and cache integration"
-
----
-
-## Chunk 3: Recording & Alignment (Tasks 9-10)
-
-### Task 9: Playwright Fixtures
-
-**Files:** Create: `src/fixtures.ts`, Test: `tests/fixtures.test.ts`
-
-- [ ] **Step 9.1:** Write failing tests: createNarrationFixture (creates timeline, starts, provides, flushes; flushes on throw), demoType (types with delay, custom delay)
-- [ ] **Step 9.2:** Run tests — verify they fail
-- [ ] **Step 9.3:** Implement createNarrationFixture factory, demoType helper (pressSequentially), test.extend with narration fixture
-- [ ] **Step 9.4:** Run tests — verify they pass
-- [ ] **Step 9.5:** Commit: "feat: Playwright fixtures with narration injection and demoType"
-
-### Task 10: Alignment
-
-**Files:** Create: `src/tts/align.ts`, Test: `tests/tts/align.test.ts`
-
-- [ ] **Step 10.1:** Write failing tests: places clips at timestamps, prevents overlap with 100ms gap, correct output buffer duration, mixes samples at correct positions, handles empty, orders by timestamp, skips unknown scenes
-- [ ] **Step 10.2:** Run tests — verify they fail
-- [ ] **Step 10.3:** Implement alignClips: filter/sort by timing, overlap prevention, create silence buffer, mix samples
-- [ ] **Step 10.4:** Run tests — verify they pass
-- [ ] **Step 10.5:** Commit: "feat(tts): clip alignment with overlap prevention and sample mixing"
-
----
-
-## Chunk 4: Export, Pipeline, CLI & Init (Tasks 11-14)
-
-### Task 11: Export (ffmpeg)
-
-**Files:** Create: `src/export.ts`, Test: `tests/export.test.ts`
-
-- [ ] **Step 11.1:** Write failing tests: checkFfmpeg (available/missing), exportVideo (correct args, custom config, missing files, non-zero exit)
-- [ ] **Step 11.2:** Run tests — verify they fail
-- [ ] **Step 11.3:** Implement checkFfmpeg (execSync ffmpeg -version), exportVideo (spawnSync with -c:v libx264 -preset -crf -c:a aac -shortest)
-- [ ] **Step 11.4:** Run tests — verify they pass
-- [ ] **Step 11.5:** Commit: "feat: ffmpeg export with configurable encoding options"
-
-### Task 12: Pipeline Orchestration
-
-**Files:** Create: `src/pipeline.ts`, Test: `tests/pipeline.test.ts`
-
-- [ ] **Step 12.1:** Write failing tests: calls all steps in order (tts → record → export), checks ffmpeg first
-- [ ] **Step 12.2:** Implement runPipeline: checkFfmpeg, then generateClips → record → alignClips → exportVideo with console progress
-- [ ] **Step 12.3:** Run tests — verify they pass
-- [ ] **Step 12.4:** Commit: "feat: pipeline orchestration for end-to-end demo generation"
-
-### Task 13: CLI
-
-**Files:** Create: `src/cli.ts`, Test: `tests/cli.test.ts`
-
-- [ ] **Step 13.1:** Write failing tests: record/tts generate/tts align/export/pipeline/init commands call correct functions, --config passes to loadConfig
-- [ ] **Step 13.2:** Implement createProgram with commander: all commands as thin wrappers that load config and delegate
-- [ ] **Step 13.3:** Run tests — verify they pass
-- [ ] **Step 13.4:** Commit: "feat: CLI with commander for all pipeline commands"
-
-### Task 14: Init + Library Exports
-
-**Files:** Create: `src/init.ts`, Modify: `src/index.ts`, Test: `tests/init.test.ts`
-
-- [ ] **Step 14.1:** Write failing tests: creates demos/, example.demo.ts, example.voiceover.json, argo.config.ts; does not overwrite existing
-- [ ] **Step 14.2:** Implement init: writeIfMissing for each scaffold file with template content
-- [ ] **Step 14.3:** Update src/index.ts: export test, expect, demoType, NarrationTimeline, showCaption, hideCaption, withCaption, defineConfig, demosProject, TTSEngine type
-- [ ] **Step 14.4:** Run all tests: `npx vitest run`
-- [ ] **Step 14.5:** Commit: "feat: init scaffolding and complete library exports"