Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
Native binary CLI (codex-style): hermetic runtimes, whisper.cpp, bundled studio + MCP (#16)
Nika Siradze33b7af2dbd1a
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlnew file mode 100644index 0000000..6ed6316--- /dev/null+++ b/.github/workflows/release.yml@@ -0,0 +1,183 @@+# Cuts a release on a v* tag: cross-compiles the Go launcher for all 5 targets,+# builds whisper.cpp per platform, publishes both as release assets (the names+# the npm wrapper, self-update, and provisioner expect), then publishes npm.+#+# The whisper.cpp matrix below is unverified until the first tagged run — the+# binary name / cmake flags may need adjustment for the pinned whisper.cpp ref.+name: release++on:+ push:+ tags:+ - 'v*'++# Default to read-only; only the release job that publishes assets gets write.+permissions:+ contents: read++jobs:+ build:+ runs-on: ubuntu-latest+ strategy:+ matrix:+ include:+ - { goos: darwin, goarch: amd64 }+ - { goos: darwin, goarch: arm64 }+ - { goos: linux, goarch: amd64 }+ - { goos: linux, goarch: arm64 }+ - { goos: windows, goarch: amd64 }+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-go@v5+ with:+ go-version: '1.23'+ - name: Build launcher+ working-directory: cli+ env:+ GOOS: ${{ matrix.goos }}+ GOARCH: ${{ matrix.goarch }}+ CGO_ENABLED: '0'+ run: |+ VERSION="${GITHUB_REF_NAME#v}"+ go generate ./... # sync backend + PodStack commands for go:embed+ EXT=""+ [ "${{ matrix.goos }}" = "windows" ] && EXT=".exe"+ OUT="podcli-${{ matrix.goos }}-${{ matrix.goarch }}${EXT}"+ go build -trimpath -ldflags "-s -w -X main.Version=${VERSION}" -o "../${OUT}" .+ echo "ASSET=${OUT}" >> "$GITHUB_ENV"+ - uses: actions/upload-artifact@v4+ with:+ name: ${{ env.ASSET }}+ path: ${{ env.ASSET }}++ whisper:+ strategy:+ fail-fast: false+ matrix:+ include:+ - { runner: macos-14, goos: darwin, goarch: arm64 }+ - { runner: macos-13, goos: darwin, goarch: amd64 }+ - { runner: ubuntu-latest, goos: linux, goarch: amd64 }+ - { runner: ubuntu-24.04-arm, goos: linux, goarch: arm64 }+ - { runner: windows-latest, goos: windows, goarch: amd64 }+ runs-on: ${{ matrix.runner }}+ env:+ WHISPER_REF: v1.7.4 # pin a known-good whisper.cpp tag+ steps:+ - name: Clone whisper.cpp+ uses: actions/checkout@v4+ with:+ repository: ggml-org/whisper.cpp+ ref: ${{ env.WHISPER_REF }}+ - name: Build (static; Metal embedded on macOS)+ shell: bash+ run: |+ EXTRA=""+ if [ "${{ matrix.goos }}" = "darwin" ]; then EXTRA="-DGGML_METAL_EMBED_LIBRARY=ON"; fi+ cmake -B build -DBUILD_SHARED_LIBS=OFF -DCMAKE_BUILD_TYPE=Release $EXTRA+ cmake --build build --config Release --target whisper-cli -j+ - name: Stage asset+ shell: bash+ run: |+ EXT=""; [ "${{ matrix.goos }}" = "windows" ] && EXT=".exe"+ SRC=$(find build -name "whisper-cli${EXT}" -type f | head -1)+ OUT="whisper-cli-${{ matrix.goos }}-${{ matrix.goarch }}${EXT}"+ cp "$SRC" "$OUT"+ echo "ASSET=$OUT" >> "$GITHUB_ENV"+ - uses: actions/upload-artifact@v4+ with:+ name: ${{ env.ASSET }}+ path: ${{ env.ASSET }}++ studio:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: '20'+ - name: Build studio bundle+ run: |+ npm ci+ sh scripts/build-studio.sh dist/studio+ tar -czf studio-bundle.tar.gz -C dist/studio .+ - uses: actions/upload-artifact@v4+ with:+ name: studio-bundle.tar.gz+ path: studio-bundle.tar.gz++ remotion:+ # Per-platform: @rspack and the Remotion compositor ship native binaries, so+ # the bundle is not portable across os/arch.+ strategy:+ fail-fast: false+ matrix:+ include:+ - { runner: macos-14, goos: darwin, goarch: arm64 }+ - { runner: macos-13, goos: darwin, goarch: amd64 }+ - { runner: ubuntu-latest, goos: linux, goarch: amd64 }+ - { runner: ubuntu-24.04-arm, goos: linux, goarch: arm64 }+ - { runner: windows-latest, goos: windows, goarch: amd64 }+ runs-on: ${{ matrix.runner }}+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: '20'+ - name: Build remotion bundle+ shell: bash+ run: |+ sh scripts/build-remotion.sh dist/remotion-bundle+ OUT="remotion-bundle-${{ matrix.goos }}-${{ matrix.goarch }}.tar.gz"+ tar -czf "$OUT" -C dist/remotion-bundle .+ echo "ASSET=$OUT" >> "$GITHUB_ENV"+ - uses: actions/upload-artifact@v4+ with:+ name: ${{ env.ASSET }}+ path: ${{ env.ASSET }}++ release:+ needs: [build, whisper, studio, remotion]+ runs-on: ubuntu-latest+ permissions:+ contents: write+ steps:+ - uses: actions/download-artifact@v4+ with:+ path: dist+ merge-multiple: true+ - name: Generate checksums+ working-directory: dist+ run: |+ sha256sum * > "$RUNNER_TEMP/checksums.txt"+ mv "$RUNNER_TEMP/checksums.txt" checksums.txt+ - uses: softprops/action-gh-release@v2+ with:+ files: dist/*+ generate_release_notes: true++ publish-npm:+ needs: release+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: '20'+ registry-url: 'https://registry.npmjs.org'+ - name: Assert NPM_TOKEN is set+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}+ run: |+ if [ -z "$NODE_AUTH_TOKEN" ]; then+ echo "::error::NPM_TOKEN secret is not set — refusing to publish. The GitHub release and assets are already published; set the secret and re-run this job." >&2+ exit 1+ fi+ - name: Publish wrapper pinned to the tag+ working-directory: npm+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}+ run: |+ VERSION="${GITHUB_REF_NAME#v}"+ npm version "$VERSION" --no-git-tag-version --allow-same-version+ npm publish --access publicdiff --git a/.gitignore b/.gitignoreindex 977be1e..2c5527a 100644--- a/.gitignore+++ b/.gitignore@@ -44,3 +44,7 @@ episodes/*.srtuploads/output/+cli/internal/backend/files/+cli/internal/podstack/commands/+cli/podcli+podcli-clips/diff --git a/AGENTS.podstack.md b/AGENTS.podstack.mdindex 13623a9..a046563 100644--- a/AGENTS.podstack.md+++ b/AGENTS.podstack.md@@ -174,7 +174,8 @@ PodStack ships one source-of-truth (`commands/`) and installs to the right locat| opencode | `.opencode/commands/*.md` | `AGENTS.md` || Generic | `commands/*.md` | `AGENTS.md` |-Install: `./setup.sh --host <name>`. See `README.md` for per-host usage examples.+These command files ship with podcli; place the set for your tool (left column) in+its command dir. See `README.md` for per-host usage examples.---diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 3468c15..5f9ddfe 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -2,20 +2,41 @@Thank you for helping improve podcli. This project is AGPL-3.0 — contributions are welcome under the same license.+## Architecture++podcli ships as a native Go launcher (`cli/`) that provisions hermetic runtimes+and routes commands to the Python backend (`backend/`) and the Node studio/MCP+server (`src/`). End users install a prebuilt binary; the source trees below are+for development.+## Development setup+Backend (Python) + studio (TypeScript):+```bash-./setup.sh+./setup.sh # venv + Python depsnpm install-npm run build+npm run build # tsc + studio bundle+```++Native launcher (Go 1.23+):++```bash+cd cli+go generate ./... # sync backend + PodStack commands for go:embed+go build -o podcli .```-Python backend lives in `backend/`. TypeScript MCP server and Web UI live in `src/`.+`cli/internal/backend/files/` is generated by `go generate` (gitignored) — edit+the canonical `backend/` instead.## Project layout-| Path | Purpose |+| Path | Purpose || --------------------------------------- | --------------------------------------------------------------- |+| `cli/` | Go launcher — provisioning, self-update, command routing |+| `backend/` | Python engine (transcription, rendering, clip generation) |+| `src/` | TypeScript MCP server + Web UI || `.podcli/` | Config home (knowledge, presets, assets, settings) — gitignored || `data/` | Runtime data (cache, output, working) — gitignored || `backend/config/paths.py` | Canonical path resolution (Python) |@@ -25,10 +46,11 @@ Python backend lives in `backend/`. TypeScript MCP server and Web UI live in `sr## Before you open a PR-1. Run tests: `python3 -m unittest discover -s tests -v`-2. Run TypeScript build: `npm run build`-3. If you change paths, env vars, or cache layout, update `README.md` and add a note to the config migration logic.-4. Keep diffs focused — one feature or fix per PR when possible.+1. Python tests: `python3 -m pytest tests/ -q`+2. TypeScript: `npm run build` and `npx vitest run`+3. Go (if you touched `cli/`): `cd cli && go build ./... && go test ./... && gofmt -l .`+4. If you change paths, env vars, or cache layout, update `README.md` and the config migration logic, and keep `backend/config/paths.py` and `src/config/paths.ts` aligned.+5. Keep diffs focused — one feature or fix per PR when possible.## Path and cache conventionsdiff --git a/README.md b/README.mdindex 7ecaac1..24fbfde 100644--- a/README.md+++ b/README.md@@ -27,7 +27,7 @@<p align="center"><sub>▶ <a href="https://x.com/nikasiradze_/status/2056061654664708570">Watch with sound on X</a></sub></p>```bash-./podcli process episode.mp4+podcli process episode.mp4```One command transcribes, picks the best moments, crops to the face, and burns captions in. Nothing leaves your machine.@@ -63,14 +63,14 @@ The first half is **video processing** — podcli's core engine. The second half### 1. Drop in your episode```bash-./setup.sh --ui+podcli # then choose "Open Web UI"# → http://localhost:3847```Drag your video into the Web UI, or use the CLI:```bash-./podcli process episode.mp4+podcli process episode.mp4```### 2. Get clips automatically@@ -147,63 +147,47 @@ Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your sh- **Preset system** — save named configurations per show- **MCP server** — 17 tools for Claude Desktop / Claude Code integration- **Web UI** — single-page flow at `localhost:3847`-- **CLI** — one-command processing: `./podcli process episode.mp4`+- **CLI** — one-command processing: `podcli process episode.mp4`----## Prerequisites+## Install-| Tool | Install |-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |-| **Node.js** >= 18 | [nodejs.org](https://nodejs.org) |-| **Python** >= 3.10 | [python.org](https://python.org) |-| **FFmpeg** | `brew install ffmpeg` / `sudo apt install ffmpeg` |-| **Claude Code** (optional) | [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) — needed for PodStack slash commands |-| **Codex** (optional) | [openai.com/codex](https://openai.com/index/introducing-codex/) — alternative AI engine for clip suggestion (auto-detected if Claude is unavailable) |--## Quick Start+No prerequisites — the install fetches a self-contained binary, and the first run+provisions everything it needs (Python, Node, FFmpeg, whisper.cpp, models) into a+managed directory. You don't need Go, Node, Python, or FFmpeg installed.**macOS / Linux**```bash-git clone https://github.com/nmbrthirteen/podcli.git-cd podcli-chmod +x setup.sh podcli-./setup.sh+curl -fsSL https://raw.githubusercontent.com/nmbrthirteen/podcli/main/install.sh | sh```-**Windows**+**Windows (PowerShell)**```powershell-git clone https://github.com/nmbrthirteen/podcli.git-cd podcli+irm https://raw.githubusercontent.com/nmbrthirteen/podcli/main/install.ps1 | iex```-Then double-click **`install.cmd`** (or run it in a terminal). It installs everything and keeps the window open so you can see the result. To launch the studio afterwards:+**With npm** (if you already have Node):-```powershell-powershell -ExecutionPolicy Bypass -File setup.ps1 -Ui+```bash+npm install -g podcli```-This will:--1. Check system dependencies (Node, Python, FFmpeg)-2. Create a Python virtual environment and install packages-3. Install Node packages and build TypeScript-4. Set up PodStack slash commands and knowledge base templates-5. Create the local `.podcli/` data directory-6. Launch the web UI at **http://localhost:3847**--### Setup options+Then just run it — the first launch sets itself up:```bash-./setup.sh # full install + launch UI-./setup.sh --install # install only-./setup.sh --ui # launch UI only (skip install)-./setup.sh --mcp # print MCP config for Claude+podcli # interactive menu (and Web UI)+podcli process episode.mp4 # transcribe + export clips```-On Windows, use `.\setup.ps1` with `-Install`, `-Ui`, or `-Mcp`, and run the CLI via `podcli.cmd` (e.g. `podcli process video.mp4 --top 5`).+**Optional**, for AI clip suggestion and the PodStack slash commands: install+[Claude Code](https://docs.anthropic.com/en/docs/claude-code) or+[Codex](https://openai.com/index/introducing-codex/) (auto-detected).++> Building from source needs Go 1.23+ (and Node for the studio bundle); see+> [`plans/native-cli.md`](plans/native-cli.md).---@@ -212,7 +196,7 @@ On Windows, use `.\setup.ps1` with `-Install`, `-Ui`, or `-Mcp`, and run the CLI### Web UI```bash-./setup.sh --ui+podcli # then choose "Open Web UI"# → http://localhost:3847```@@ -227,17 +211,17 @@ On Windows, use `.\setup.ps1` with `-Install`, `-Ui`, or `-Mcp`, and run the CLI```bash# One command. Auto-transcribes, picks moments, renders clips.-./podcli process episode.mp4+podcli process episode.mp4```With more control:```bash# Use an existing transcript instead of transcribing-./podcli process episode.mp4 --transcript transcript.txt --top 5+podcli process episode.mp4 --transcript transcript.txt --top 5# Full options-./podcli process episode.mp4 \+podcli process episode.mp4 \--transcript transcript.txt \--top 8 \--caption-style branded \@@ -248,9 +232,9 @@ With more control:### Presets```bash-./podcli presets save myshow --caption-style branded --logo logo.png --top 5-./podcli presets list-./podcli process video.mp4 --preset myshow+podcli presets save myshow --caption-style branded --logo logo.png --top 5+podcli presets list+podcli process video.mp4 --preset myshow```### Content Workflow (PodStack)@@ -305,30 +289,25 @@ Manage via the web UI at `/knowledge.html` (drag & drop, inline editor) or throupodcli is a [Model Context Protocol](https://modelcontextprotocol.io) server — Claude can use it as a tool to create clips through conversation.+**Claude Code** — register the bundled MCP server in one command:++```bash+podcli mcp install+```+**Claude Desktop** — add to `claude_desktop_config.json`:```json{"mcpServers": {"podcli": {- "command": "node",- "args": ["/path/to/podcli/dist/index.js"],- "env": {- "PYTHON_PATH": "/path/to/podcli/venv/bin/python3"- }+ "command": "podcli",+ "args": ["mcp"]}}}```-**Claude Code:**--```bash-claude mcp add podcli -- node /path/to/podcli/dist/index.js-```--Run `./setup.sh --mcp` to get the exact config with your paths filled in.-### MCP Tools| Tool | Description |@@ -368,8 +347,9 @@ Run `./setup.sh --mcp` to get the exact config with your paths filled in.```podcli/-├── podcli # CLI entry point-├── setup.sh # one-command install & launch+├── cli/ # Go launcher (native binary, provisioning, self-update)+├── install.sh / install.ps1 # node-less installers+├── setup.sh # dev environment setup (venv + npm)├── package.json├── CLAUDE.md # PodStack master config│diff --git a/RELEASE.md b/RELEASE.mdnew file mode 100644index 0000000..f518e74--- /dev/null+++ b/RELEASE.md@@ -0,0 +1,50 @@+# Releasing podcli++Distribution is fully automated by `.github/workflows/release.yml`: pushing a+`v*` tag builds the launcher for all five platforms, builds whisper.cpp, bundles+the studio and Remotion, generates `checksums.txt`, publishes a GitHub release,+and publishes the npm package. End users then install with no prerequisites:++```bash+curl -fsSL https://raw.githubusercontent.com/nmbrthirteen/podcli/main/install.sh | sh+# or: npm install -g podcli (Windows: install.ps1)+```++## One-time setup++- Set the **`NPM_TOKEN`** repository secret (an npm automation token with publish+ rights). Without it the GitHub release still publishes; the npm job fails and+ can be re-run after the secret is added.++## Cutting a release++1. Pick the version `X.Y.Z`. Set it in **`npm/package.json`** (`install.js` fetches+ the binary from `releases/download/vX.Y.Z/`, so the npm version must equal the+ tag). Optionally align the root `package.json`.+2. Merge to `main` and make sure CI is green.+3. Tag and push:+ ```bash+ git tag vX.Y.Z+ git push origin vX.Y.Z+ ```+4. Watch the `release` workflow. It produces these assets (the names the npm+ wrapper, self-update, and provisioner expect):+ - `podcli-{darwin,linux,windows}-{amd64,arm64}[.exe]` — static launchers+ - `whisper-cli-<os>-<arch>[.exe]`+ - `studio-bundle.tar.gz`+ - `remotion-<os>-<arch>.tar.gz`+ - `checksums.txt`+5. Verify the npm publish succeeded (`npm view podcli version`).++## Smoke test (ideally one machine per OS)++```bash+curl -fsSL .../install.sh | sh # or npm i -g podcli+podcli doctor # paths + engine resolution+podcli process sample.mp4 --top 1 # transcribe -> suggest -> export a clip+podcli # interactive menu -> Open Web UI+```++First run downloads the hermetic runtimes (Python, Node, FFmpeg, model) once.+Needs outbound HTTPS to github.com, huggingface.co, nodejs.org, and the ffmpeg+hosts. glibc Linux only (Alpine/musl is unsupported).diff --git a/backend/cli.py b/backend/cli.pyindex 9bf6a98..dd735cf 100644--- a/backend/cli.py+++ b/backend/cli.py@@ -14,6 +14,7 @@ import argparseimport jsonimport osimport shutil+import subprocessimport sysimport textwrapimport time@@ -26,7 +27,7 @@ for _stream in (sys.stdout, sys.stderr):except (ValueError, OSError):pass-_env_file = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".env")+_env_file = os.environ.get("PODCLI_ENV_FILE") or os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".env")try:from dotenv import load_dotenvload_dotenv(_env_file)@@ -152,17 +153,24 @@ def _auto_migrate_cli(args) -> None:summary = auto_migrate_legacy_if_pending(quiet=True)if not summary:return+ home = summary.get("home_migration") or {}+ imported_home = home.get("imported")moved_cache = summary.get("moved_json") or summary.get("moved_remotion_bundle")moved_presets = (summary.get("presets_migration") or {}).get("moved")- if moved_cache or moved_presets:+ copied_env = (summary.get("env_migration") or {}).get("copied")+ if imported_home or moved_cache or moved_presets or copied_env:gray = "\033[38;5;245m"green = "\033[38;2;74;222;128m"reset = "\033[0m"+ if imported_home:+ print(f" {green}✓{reset} {gray}Imported your presets, knowledge & assets → {home.get('target_home')}{reset}")if moved_cache:- print(f" {green}✓{reset} {gray}Migrated legacy cache → {summary.get('target_dir')}{reset}")+ print(f" {green}✓{reset} {gray}Migrated transcript cache → {summary.get('target_dir')}{reset}")if moved_presets:pm = summary.get("presets_migration") or {}print(f" {green}✓{reset} {gray}Migrated presets → {pm.get('target_dir')}{reset}")+ if copied_env:+ print(f" {green}✓{reset} {gray}Copied .env → {(summary.get('env_migration') or {}).get('target')}{reset}")print()@@ -285,7 +293,11 @@ def _resolve_output_dir(if explicit_output_dir:return explicit_output_dir- base_output_dir = configured_output_dir or os.path.join(os.path.dirname(video_path), "clips")+ base_output_dir = (+ configured_output_dir+ or os.environ.get("PODCLI_OUTPUT")+ or os.path.join(os.path.dirname(video_path), "clips")+ )if not preset_name:return base_output_dir@@ -313,7 +325,7 @@ def _should_enter_post_render_loop(config: dict, interrupted: bool, results: lisdef cmd_studio(args):"""Cut a fragment + wrap it with Remotion intro/outro bookends.- Thin wrapper around scripts/clip_studio.py (which orchestrates the+ Thin wrapper around clip_studio.py (which orchestrates thefragment render, bookend renders, and the concat). Runs it as asubprocess with this same interpreter so the venv is reused."""@@ -321,8 +333,7 @@ def cmd_studio(args):print("Error: provide either --start and --end, or --paragraph \"text\"", file=sys.stderr)sys.exit(1)- project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))- script = os.path.join(project_root, "scripts", "clip_studio.py")+ script = os.path.join(os.path.dirname(os.path.abspath(__file__)), "clip_studio.py")if not os.path.exists(script):print(f"Error: clip_studio.py not found at {script}", file=sys.stderr)sys.exit(1)@@ -416,6 +427,8 @@ def cmd_process(args):save_corrections(merged)# CLI overrides+ if getattr(args, "engine", None):+ os.environ["PODCLI_ENGINE"] = args.engineif args.caption_style:config["caption_style"] = args.caption_styleif args.crop:@@ -586,12 +599,18 @@ def cmd_process(args):def _transcribe_progress(pct, msg):_spin_msg[0] = f"{msg} ({pct}%)" if pct < 100 else msg- result = transcribe_file(- file_path=video_path,- model_size=config.get("whisper_model", "base"),- enable_diarization=not config.get("no_speakers", False),- progress_callback=_transcribe_progress,- )+ try:+ result = transcribe_file(+ file_path=video_path,+ model_size=config.get("whisper_model", "base"),+ enable_diarization=not config.get("no_speakers", False),+ progress_callback=_transcribe_progress,+ )+ except (RuntimeError, FileNotFoundError, subprocess.CalledProcessError) as e:+ _spin_stop.set()+ spin_thread.join(timeout=1)+ print(f"\r{' ' * 70}\r ✗ {e}\n", flush=True)+ sys.exit(1)_spin_stop.set()spin_thread.join(timeout=1)words = result["words"]@@ -1103,160 +1122,10 @@ def _print_clips(clips: list):def _find_moment_with_claude(description: str, segments: list, existing_clips: list) -> list:- """Use Claude to find a specific moment described by the user."""- from services.claude_suggest import _find_ai_cli_candidates, _run_ai_command- from presets import MIN_CLIP_DURATION, MAX_CLIP_DURATION, TARGET_CLIP_DURATION_MIN, TARGET_CLIP_DURATION_MAX-- candidates = _find_ai_cli_candidates()- if not candidates:- print(" ⚠ No AI CLI available for moment search")- return []-- # Build transcript text- lines = []- for seg in segments:- speaker = seg.get("speaker", "")- speaker_label = f"[{speaker}] " if speaker else ""- start = seg.get("start", 0)- text = seg.get("text", "").strip()- if text:- lines.append(f"[{start:.1f}s] {speaker_label}{text}")- transcript_text = "\n".join(lines)-- # Build list of existing clip timestamps to avoid- existing_desc = ""- if existing_clips:- existing_desc = "\n\nALREADY SELECTED (do not re-suggest these):\n"- for c in existing_clips:- existing_desc += f"- {c['start_second']}s-{c['end_second']}s: {c['title']}\n"-- import tempfile, subprocess, json as _json-- prompt = f"""Find the moment the user is describing in this podcast transcript. Return ONLY valid JSON.--USER WANTS: "{description}"-{existing_desc}-RULES:-- Find the EXACT moment matching the user's description-- Return 1-3 matching moments (best match first)-- All timestamps in SECONDS as numbers-- Duration target: {TARGET_CLIP_DURATION_MIN}-{TARGET_CLIP_DURATION_MAX} seconds, max {MAX_CLIP_DURATION} seconds-- Cut tight: start at the hook, end when the point lands-- Use segments to cut filler if needed--Return this JSON:-{{- "clips": [- {{- "title": "First sentence of the moment",- "start_second": 123.4,- "end_second": 158.4,- "segments": [{{"start": 123.4, "end": 158.4}}],- "duration": 35,- "content_type": "guest_story",- "scores": {{"standalone": 4, "hook": 5, "relevance": 4, "quotability": 3}},- "total_score": 16,- "quote": "The key quote",- "why": "Why this matches what the user asked for"- }}- ]-}}--Transcript:-{transcript_text}"""-- project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")- with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False, dir=project_dir) as f:- f.write(prompt)- prompt_file = f.name-- try:- for idx, (cli_path, engine) in enumerate(candidates):- if idx > 0:- print(f" ⚠ Retrying moment search with {'Claude' if engine == 'claude' else 'Codex'}")- try:- result = _run_ai_command(- cli_path=cli_path,- engine=engine,- prompt=prompt,- prompt_file=prompt_file,- project_dir=project_dir,- timeout=300,- )- except Exception:- continue-- if result.returncode != 0 or not result.stdout.strip():- continue-- response = result.stdout.strip()- if "```" in response:- import re- fence_match = re.search(r"```(?:json)?\s*\n?(.*?)\n?\s*```", response, re.DOTALL)- if fence_match:- response = fence_match.group(1).strip()-- try:- json_start = response.find("{")- if json_start >= 0:- decoder = _json.JSONDecoder()- data, _ = decoder.raw_decode(response, json_start)- else:- data = _json.loads(response)- except Exception:- continue+ """Use Claude/Codex to find a specific moment described by the user."""+ from services.claude_suggest import find_moments_from_text- found = []- for c in data.get("clips", []):- scores = c.get("scores", {})- total = sum(scores.values()) if scores else c.get("total_score", 0)- raw_segments = c.get("segments", [])- keep_segments = []- for seg in raw_segments:- s = round(float(seg.get("start", 0)), 1)- e = round(float(seg.get("end", 0)), 1)- if e > s:- keep_segments.append({"start": s, "end": e})-- start_sec = round(float(c.get("start_second", 0)), 1)- end_sec = round(float(c.get("end_second", 0)), 1)- if not keep_segments and end_sec > start_sec:- keep_segments = [{"start": start_sec, "end": end_sec}]-- kept_duration = sum(seg["end"] - seg["start"] for seg in keep_segments)- if kept_duration < MIN_CLIP_DURATION or kept_duration > MAX_CLIP_DURATION:- continue-- found.append({- "title": c.get("title", "Untitled")[:55],- "start_second": keep_segments[0]["start"] if keep_segments else start_sec,- "end_second": keep_segments[-1]["end"] if keep_segments else end_sec,- "segments": keep_segments,- "duration": round(kept_duration),- "score": total,- "content_type": c.get("content_type", "unknown"),- "reasoning": c.get("why", ""),- "preview_text": c.get("quote", "")[:120],- "suggested_caption_style": "hormozi",- "quote": c.get("quote", ""),- "why": c.get("why", ""),- "reasons": [c.get("content_type", "")],- "preview": c.get("quote", "")[:120],- })-- if found:- return found-- return []-- except Exception as e:- print(f" ⚠ Search error: {e}")- return []- finally:- try:- os.unlink(prompt_file)- except Exception:- pass+ return find_moments_from_text(description, segments, existing_clips, max_results=3)def _review_clips(clips: list, segments: list, energy_scores: list | None, config: dict) -> list:@@ -2224,6 +2093,11 @@ def cmd_thumbnails(args):video = getattr(args, "video", None)as_json = getattr(args, "json", False)+ # Interactive callers build a bare namespace without --output's argparse+ # default, so fall back to the same default the CLI documents.+ if not getattr(args, "output", None):+ args.output = "./thumbnails"+# An exact timestamp wins: extract that frame from the video and use it as the photo.timestamp = getattr(args, "timestamp", None)if photo is None and video and timestamp is not None:@@ -2611,6 +2485,15 @@ def _print_config_result(action: str, data: dict) -> None:if action == "migrate":print(f"\n {bold}Legacy migration{reset}")+ home_mig = data.get("home_migration") or {}+ if home_mig.get("imported") or home_mig.get("skipped_existing"):+ print(f" {gray}brand brain (presets, knowledge, assets, history, config){reset}")+ print(f" {gray}from{reset}: {home_mig.get('legacy_home')}")+ print(f" {gray}to{reset}: {home_mig.get('target_home')}")+ if home_mig.get("skipped_existing"):+ print(f" {gray}skipped{reset}: global home already has data")+ else:+ print(f" {gray}imported{reset}: yes")print(f" {gray}cache{reset}")print(f" {gray}from{reset}: {data.get('legacy_dir')}")print(f" {gray}to{reset}: {data.get('target_dir')}")@@ -2629,6 +2512,10 @@ def _print_config_result(action: str, data: dict) -> None:print(f" {gray}moved{reset}: {presets.get('moved')}")if presets.get("skipped"):print(f" {gray}skipped{reset}: {presets['skipped']} (already in target)")+ env_mig = data.get("env_migration") or {}+ if env_mig.get("copied"):+ print(f" {gray}.env{reset}")+ print(f" {gray}to{reset}: {env_mig.get('target')}")if not data.get("dry_run"):print(f"\n {green}✓{reset} Migration complete")print()@@ -3024,8 +2911,20 @@ def cmd_info(args):print(f" Platform: {info['system']}")print(f" Encoder: {info['best']}")print(f" Available: {', '.join(info['available'])}")+ import importlib.util+ try:+ diarization_available = importlib.util.find_spec("pyannote.audio") is not None+ except (ImportError, ValueError):+ diarization_available = False+ if not diarization_available:+ speakers_status = f"{yellow}✗ not available in this install (source install only)"+ elif hf_token:+ speakers_status = f"{green}✓ configured"+ else:+ speakers_status = f"{yellow}✗ set HF_TOKEN in .env"+print(f" AI CLI: {green}{('Claude' if ai_engine == 'claude' else 'Codex') + ' (' + ai_path + ')' if ai_path else f'{yellow}not found — install Claude Code or Codex'}{reset}")- print(f" Speakers: {green + '✓ configured' if hf_token else yellow + '✗ set HF_TOKEN in .env'}{reset}")+ print(f" Speakers: {speakers_status}{reset}")print()@@ -3084,7 +2983,12 @@ def print_banner():hf_token = line.strip().split("=", 1)[1].strip()break- speakers_ok = bool(hf_token)+ import importlib.util+ try:+ _diarization_ok = importlib.util.find_spec("pyannote.audio") is not None+ except (ImportError, ValueError):+ _diarization_ok = False+ speakers_ok = bool(hf_token) and _diarization_ok# Check AI CLI (Claude Code or Codex)from services.claude_suggest import _find_ai_cli@@ -3235,6 +3139,7 @@ def main():proc.add_argument("-n", "--top", type=int, help="Number of top clips to export (default: 5)")proc.add_argument("-o", "--output", help="Output directory (default: ./clips)")proc.add_argument("-p", "--preset", help="Load a saved preset")+ proc.add_argument("--engine", choices=["whisper-py", "whispercpp"], help="Transcription engine (default: whisper-py; whispercpp is the native, PyTorch-free path)")proc.add_argument("--fast", action="store_true", help="Draft mode: tiny Whisper, heuristic selection, center crop, low quality")proc.add_argument("--caption-style", choices=["branded", "hormozi", "karaoke", "subtle"])proc.add_argument("--crop", choices=["center", "face", "speaker", "speaker-hardcut"])@@ -3558,20 +3463,47 @@ def interactive_menu():returnelif choice == "webui":import subprocess as sp- repo = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..")- spa = os.path.join(repo, "dist", "ui", "public", "index.html")+ import shutil as _shutil+ backend_dir = os.path.dirname(os.path.abspath(__file__))port = os.environ.get("PORT", "3847")- ok = True- # npm is npm.cmd on Windows; subprocess can't run a batch file without a shell.- _npm_shell = sys.platform == "win32"- if not os.path.exists(spa):- print(f"\n {gray}Building the studio (first run)…{reset}\n")- ok = sp.run(["npm", "run", "build"], cwd=repo, shell=_npm_shell).returncode == 0- if not ok:- print(f"\n {yellow}Build failed — run 'npm install' then try again.{reset}\n")- if ok:+ node = os.environ.get("PODCLI_NODE") or _shutil.which("node")+ studio = os.environ.get("PODCLI_STUDIO") or os.path.join(backend_dir, "..", "studio")+ server = os.path.join(studio, "web-server.mjs")+ repo = os.path.join(backend_dir, "..")+ if node and os.path.exists(server):+ # Bundled studio: hermetic Node serves it, rendering delegated to+ # this same Python backend + ffmpeg via the env below.+ env = {+ **os.environ,+ "PORT": str(port),+ "PODCLI_BACKEND": backend_dir,+ "PYTHON_PATH": sys.executable,+ "PODCLI_HOME": paths["home"],+ # data_dir is the cache's parent — output is now decoupled+ # (clips render to the working dir), so don't derive it from output.+ "PODCLI_DATA": os.path.dirname(paths["cache"]),+ "PODCLI_OUTPUT": paths["output"],+ "FFMPEG_PATH": os.environ.get("PODCLI_FFMPEG", "ffmpeg"),+ "FFPROBE_PATH": os.environ.get("PODCLI_FFPROBE", "ffprobe"),+ }print(f"\n {gray}Studio:{reset} {accent}http://localhost:{port}{reset} {dim}(Ctrl+C to stop){reset}\n")- sp.run(["npm", "run", "ui:prod"], cwd=repo, shell=_npm_shell)+ sp.run([node, server], env=env)+ elif os.path.exists(os.path.join(repo, "package.json")) and _shutil.which("npm"):+ # Source checkout (dev): build + serve via npm.+ _npm_shell = sys.platform == "win32"+ spa = os.path.join(repo, "dist", "ui", "public", "index.html")+ ok = True+ if not os.path.exists(spa):+ print(f"\n {gray}Building the studio (first run)…{reset}\n")+ ok = sp.run(["npm", "run", "build"], cwd=repo, shell=_npm_shell).returncode == 0+ if not ok:+ print(f"\n {yellow}Build failed — run 'npm install' then try again.{reset}\n")+ if ok:+ print(f"\n {gray}Studio:{reset} {accent}http://localhost:{port}{reset} {dim}(Ctrl+C to stop){reset}\n")+ sp.run(["npm", "run", "ui:prod"], cwd=repo, shell=_npm_shell)+ else:+ print(f"\n {yellow}Studio isn't provisioned yet.{reset}")+ print(f" {dim}Run{reset} {accent}podcli setup{reset} {dim}to fetch the bundled studio + Node.{reset}\n")elif choice == "assets":_interactive_assets()elif choice == "presets":@@ -4478,6 +4410,7 @@ def _interactive_thumbnails():video=video or None,logo=None,variations=3,+ output="./thumbnails",)cmd_thumbnails(args_ns)diff --git a/scripts/clip_studio.py b/backend/clip_studio.pysimilarity index 96%rename from scripts/clip_studio.pyrename to backend/clip_studio.pyindex cac3eb2..bbb9d87 100644--- a/scripts/clip_studio.py+++ b/backend/clip_studio.py@@ -37,6 +37,9 @@ os.chdir(os.path.join(ROOT, "backend"))FFMPEG = os.environ.get("PODCLI_FFMPEG", "ffmpeg")NODE = os.environ.get("PODCLI_NODE", "node")+# Share the prewarmed, project-independent composition bundle with the fragment+# caption render (clip_generator) and the bookend render.+os.environ.setdefault("PODCLI_CACHE_DIR", os.path.join(ROOT, "remotion", ".bundle-cache"))# Brand config: remembered handle / platforms / colors / outro title so they# don't have to be retyped each run. CLI flags override these; these override@@ -69,7 +72,7 @@ def _save_brand(data: dict):def _probe_duration(path: str) -> float:out = subprocess.run(- ["ffprobe", "-v", "error", "-show_entries", "format=duration",+ [os.environ.get("PODCLI_FFPROBE", "ffprobe"), "-v", "error", "-show_entries", "format=duration","-of", "default=nw=1:nk=1", path],capture_output=True, text=True,)@@ -236,7 +239,8 @@ def main():video = os.path.abspath(video)if not os.path.exists(video):raise SystemExit(f"Video not found: {video}")- out_dir = os.path.join(ROOT, "data", "output")+ data_dir = os.environ.get("PODCLI_DATA") or os.path.join(ROOT, "data")+ out_dir = os.path.join(data_dir, "output")os.makedirs(out_dir, exist_ok=True)# Need a transcript if cutting by paragraph or if rendering captions.diff --git a/backend/config/paths.py b/backend/config/paths.pyindex 66dd38a..2a603e3 100644--- a/backend/config/paths.py+++ b/backend/config/paths.py@@ -44,6 +44,7 @@ def _build_paths() -> dict[str, str]:home = _resolve_home()project_root = _project_root()data_dir = Path(os.environ.get("PODCLI_DATA", str(project_root / "data"))).expanduser().resolve()+ output_dir = Path(os.environ.get("PODCLI_OUTPUT", str(data_dir / "output"))).expanduser().resolve()return {"home": str(home),"project_root": str(project_root),@@ -51,7 +52,7 @@ def _build_paths() -> dict[str, str]:"transcripts": str(data_dir / "cache" / "transcripts"),"packed": str(home / "packed"),"working": str(data_dir / "working"),- "output": str(data_dir / "output"),+ "output": str(output_dir),"logs": str(data_dir / "logs"),"assets": str(home / "assets"),"assetsRegistry": str(home / "assets" / "registry.json"),diff --git a/backend/config_bundle.py b/backend/config_bundle.pyindex 612be04..1e1e000 100644--- a/backend/config_bundle.py+++ b/backend/config_bundle.py@@ -4,6 +4,7 @@ import jsonimport osimport reimport shutil+import tempfileimport zipfilefrom datetime import datetime, timezonefrom pathlib import Path@@ -60,12 +61,34 @@ def _migration_marker_path() -> Path:return _data_dir() / MIGRATION_MARKER_NAME+# Migration reads the working directory (the old project-local ./podcli folder)+# and imports it into the global store. PODCLI_CWD is injected by the launcher.+def _legacy_project_dir() -> Path:+ return Path(os.environ.get("PODCLI_CWD") or os.getcwd()).expanduser().resolve()+++def _global_home() -> Path:+ return Path(paths["home"]).resolve()+++def _legacy_home_dir() -> Path:+ return _legacy_project_dir() / ".podcli"++def _legacy_cache_dir() -> Path:- return Path(paths["project_root"]) / ".podcli" / "cache"+ # Old layouts stored the transcript cache under <proj>/.podcli/cache (original)+ # or <proj>/data/cache (interim project-local). Prefer whichever holds content.+ proj = _legacy_project_dir()+ for candidate in (proj / ".podcli" / "cache", proj / "data" / "cache"):+ if candidate.is_dir() and any(candidate.iterdir()):+ return candidate+ return proj / ".podcli" / "cache"def _legacy_presets_dir() -> Path:- return Path(paths["project_root"]) / "presets"+ # Ancient layout kept presets at <proj>/presets, outside .podcli. Presets+ # inside .podcli/presets are covered by the brand-brain import instead.+ return _legacy_project_dir() / "presets"def _legacy_presets_has_content() -> bool:@@ -73,8 +96,48 @@ def _legacy_presets_has_content() -> bool:return legacy.is_dir() and any(legacy.glob("*.json"))+def _legacy_env_file() -> Path:+ return _legacy_project_dir() / ".env"+++def _global_env_file() -> Path:+ # Match the file the launcher/loader actually reads (PODCLI_ENV_FILE), so the+ # migrated secrets land where they'll be loaded and "pending" clears correctly.+ return Path(os.environ.get("PODCLI_ENV_FILE") or (_global_home() / ".env"))+++def _legacy_env_pending() -> bool:+ src = _legacy_env_file()+ return src.is_file() and src.resolve() != _global_env_file().resolve() and not _global_env_file().exists()+++def _legacy_home_pending() -> bool:+ legacy = _legacy_home_dir()+ if legacy.resolve() == _global_home():+ return False+ return _has_managed_content(legacy) and not _has_managed_content(_global_home())+++def _asset_alias_keys(raw: str, source: Path) -> list[str]:+ """All string forms of an asset path. The rewrite matches the literal stored+ value, which differs from its realpath through a symlink (macOS /var)."""+ keys: list[str] = []+ for k in (raw, str(Path(raw).expanduser()) if raw else "", str(source), str(source.resolve())):+ if k and k not in keys:+ keys.append(k)+ return keys++def _legacy_migration_pending() -> bool:- return _legacy_cache_has_content() or _legacy_presets_has_content()+ # Never treat the global managed dir itself as a legacy project to import.+ if _legacy_project_dir().resolve() == _global_home().resolve():+ return False+ return (+ _legacy_home_pending()+ or _legacy_cache_has_content()+ or _legacy_presets_has_content()+ or _legacy_env_pending()+ )def _read_json(path: Path) -> Any:@@ -150,16 +213,18 @@ def export_config(bundle_path: str, source_home: str | None = None) -> dict[str,for index, item in enumerate(raw_assets):if not isinstance(item, dict):continue- source = Path(str(item.get("path", ""))).expanduser()+ raw_path = str(item.get("path", ""))+ source = Path(raw_path).expanduser()if not source.exists():continuearchive_name = _archive_name_for(index, str(item.get("name", "asset")), source)archive_path = f"{ASSET_ARCHIVE_DIR}/{archive_name}"zf.write(source, arcname=archive_path)registry_export.append({**item, "path": archive_path})- path_map[str(source.resolve())] = archive_path+ for key in _asset_alias_keys(raw_path, source):+ path_map[key] = archive_path- extra_sources: list[Path] = []+ extra_sources: list[tuple[str, Path]] = []for rel in ["ui-state.json"]:src = home / relif src.exists():@@ -168,7 +233,7 @@ def export_config(bundle_path: str, source_home: str | None = None) -> dict[str,for candidate in _collect_asset_paths(raw):candidate_path = Path(candidate).expanduser()if candidate_path.exists():- extra_sources.append(candidate_path)+ extra_sources.append((candidate, candidate_path))presets_dir = home / "presets"if presets_dir.exists():@@ -179,16 +244,19 @@ def export_config(bundle_path: str, source_home: str | None = None) -> dict[str,for candidate in _collect_asset_paths(raw):candidate_path = Path(candidate).expanduser()if candidate_path.exists():- extra_sources.append(candidate_path)+ extra_sources.append((candidate, candidate_path))- for source in extra_sources:+ for raw_candidate, source in extra_sources:resolved = str(source.resolve())if resolved in path_map:+ # Already archived; still register this literal so its JSON gets rewritten.+ path_map.setdefault(raw_candidate, path_map[resolved])continuearchive_name = _archive_name_for(len(path_map), source.stem or "asset", source)archive_path = f"{ASSET_ARCHIVE_DIR}/{archive_name}"zf.write(source, arcname=archive_path)- path_map[resolved] = archive_path+ for key in _asset_alias_keys(raw_candidate, source):+ path_map[key] = archive_pathzf.writestr("assets/registry.json", json.dumps({"assets": registry_export}, indent=2) + "\n")manifest["path_map"] = path_map@@ -231,7 +299,7 @@ def migrate_legacy_cache(*, dry_run: bool = False) -> dict[str, Any]:"dry_run": dry_run,}- if not legacy.is_dir():+ if not legacy.is_dir() or legacy.resolve() == target.resolve():return resulttarget.mkdir(parents=True, exist_ok=True)@@ -299,7 +367,7 @@ def migrate_legacy_presets(*, dry_run: bool = False) -> dict[str, Any]:"skipped": 0,"dry_run": dry_run,}- if not legacy.is_dir():+ if not legacy.is_dir() or legacy.resolve() == target.resolve():return resulttarget.mkdir(parents=True, exist_ok=True)for src in legacy.glob("*.json"):@@ -319,6 +387,53 @@ def migrate_legacy_presets(*, dry_run: bool = False) -> dict[str, Any]:return result+def migrate_legacy_home(*, dry_run: bool = False) -> dict[str, Any]:+ """Import a project-local .podcli into the global home — only when the global+ home is empty, so it never clobbers an existing profile."""+ legacy = _legacy_home_dir()+ home = _global_home()+ result: dict[str, Any] = {+ "legacy_home": str(legacy),+ "target_home": str(home),+ "imported": False,+ "dry_run": dry_run,+ }+ if legacy.resolve() == home or not _has_managed_content(legacy):+ return result+ if _has_managed_content(home):+ result["skipped_existing"] = True+ return result+ if dry_run:+ result["imported"] = True+ return result+ # Reuse export/import so asset files get archived and absolute path references+ # inside presets/config are rewritten to the new global home.+ with tempfile.TemporaryDirectory() as tmp:+ bundle = os.path.join(tmp, "legacy-home.zip")+ export_config(bundle, source_home=str(legacy))+ import_config(bundle, target_home=str(home), activate=False)+ result["imported"] = True+ return result+++def migrate_legacy_env(*, dry_run: bool = False) -> dict[str, Any]:+ src = _legacy_env_file()+ dest = _global_env_file()+ result: dict[str, Any] = {+ "source": str(src),+ "target": str(dest),+ "copied": False,+ "dry_run": dry_run,+ }+ if not src.is_file() or src.resolve() == dest.resolve() or dest.exists():+ return result+ if not dry_run:+ dest.parent.mkdir(parents=True, exist_ok=True)+ shutil.copy2(str(src), str(dest))+ result["copied"] = True+ return result++def auto_migrate_legacy_if_pending(*, quiet: bool = True) -> dict[str, Any] | None:if not _legacy_migration_pending():return None@@ -328,28 +443,31 @@ def auto_migrate_legacy_if_pending(*, quiet: bool = True) -> dict[str, Any] | Nodef ensure_legacy_migrated(*, quiet: bool = True) -> dict[str, Any]:marker = _migration_marker_path()had_marker = marker.exists()+ home_summary = migrate_legacy_home(dry_run=False)summary = migrate_legacy_cache(dry_run=False)presets_summary = migrate_legacy_presets(dry_run=False)+ env_summary = migrate_legacy_env(dry_run=False)+ summary["home_migration"] = home_summarysummary["presets_migration"] = presets_summary+ summary["env_migration"] = env_summarytry:from services.transcript_packer import migrate_transcript_cache_layoutlayout = migrate_transcript_cache_layout()summary["transcript_layout"] = layout- changed = bool(- summary.get("moved_json")- or summary.get("moved_remotion_bundle")- or summary.get("removed_duplicate_remotion_bundle")- or layout.get("moved_to_transcripts")- or presets_summary.get("moved")- )+ layout_moved = layout.get("moved_to_transcripts")except Exception:- changed = bool(- summary.get("moved_json")- or summary.get("moved_remotion_bundle")- or summary.get("removed_duplicate_remotion_bundle")- or presets_summary.get("moved")- )+ summary["transcript_layout"] = {"moved_to_transcripts": 0, "skipped": 0}+ layout_moved = 0+ changed = bool(+ home_summary.get("imported")+ or summary.get("moved_json")+ or summary.get("moved_remotion_bundle")+ or summary.get("removed_duplicate_remotion_bundle")+ or layout_moved+ or presets_summary.get("moved")+ or env_summary.get("copied")+ )if not had_marker or changed:marker.parent.mkdir(parents=True, exist_ok=True)marker.write_text(@@ -539,8 +657,10 @@ def get_config_status() -> dict[str, Any]:"home": get_active_home(),"cache": paths["cache"],"profile_marker": paths["profileMarker"],+ "legacy_home_pending": _legacy_home_pending(),"legacy_cache_pending": _legacy_cache_has_content(),"legacy_presets_pending": _legacy_presets_has_content(),+ "legacy_env_pending": _legacy_env_pending(),"migration_marker": str(marker) if marker.exists() else None,"migration": migration_info,}@@ -560,8 +680,9 @@ def run_config_action(if act == "migrate":if dry_run:cache = migrate_legacy_cache(dry_run=True)- presets = migrate_legacy_presets(dry_run=True)- cache["presets_migration"] = presets+ cache["home_migration"] = migrate_legacy_home(dry_run=True)+ cache["presets_migration"] = migrate_legacy_presets(dry_run=True)+ cache["env_migration"] = migrate_legacy_env(dry_run=True)return cachereturn ensure_legacy_migrated(quiet=True)if act == "export":diff --git a/backend/main.py b/backend/main.pyindex 079ff5c..5812ad5 100644--- a/backend/main.py+++ b/backend/main.py@@ -21,7 +21,7 @@ for _stream in (sys.stdout, sys.stderr):# Load .env file (for HF_TOKEN, etc.)try:from dotenv import load_dotenv- load_dotenv(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".env"))+ load_dotenv(os.environ.get("PODCLI_ENV_FILE") or os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".env"))except ImportError:passimport traceback@@ -377,6 +377,32 @@ def handle_suggest_clips(task_id: str, params: dict):emit_result(task_id, "success", data={"clips": clips})+def handle_find_moment(task_id: str, params: dict):+ """Locate user-pasted/described moments in the transcript via the AI CLI."""+ from services.claude_suggest import find_moments_from_text++ text = (params.get("text") or params.get("description") or "").strip()+ segments = params.get("segments", [])+ existing_clips = params.get("existing_clips", [])+ max_results = params.get("max_results", 8)++ if not text:+ emit_result(task_id, "error", error="text is required")+ return+ if not segments:+ emit_result(task_id, "error", error="segments is required")+ return++ clips = find_moments_from_text(+ text,+ segments,+ existing_clips,+ progress_callback=lambda pct, msg: emit_progress(task_id, "searching", pct, msg),+ max_results=max_results,+ )+ emit_result(task_id, "success", data={"clips": clips})++def handle_generate_content(task_id: str, params: dict):"""Generate titles, descriptions, tags for a clip using PodStack knowledge base."""from services.content_generator import generate_clip_content@@ -485,6 +511,7 @@ TASK_HANDLERS = {"presets": handle_presets,"corrections": handle_corrections,"suggest_clips": handle_suggest_clips,+ "find_moment": handle_find_moment,"generate_content": handle_generate_content,"manage_integrations": handle_manage_integrations,"run_integration_tool": handle_run_integration_tool,diff --git a/backend/presets.py b/backend/presets.pyindex ff74696..70f30f6 100644--- a/backend/presets.py+++ b/backend/presets.py@@ -40,7 +40,7 @@ DEFAULT_PRESET = {"energy_boost": True,"quality": "max","no_speakers": False,- "allow_ass_fallback": False,+ "allow_ass_fallback": True,"use_ass_captions": False,"generate_thumbnails": True,"generate_content": True,diff --git a/backend/requirements-runtime.txt b/backend/requirements-runtime.txtnew file mode 100644index 0000000..408f153--- /dev/null+++ b/backend/requirements-runtime.txt@@ -0,0 +1,11 @@+# Hermetic native-CLI runtime deps. Transcription is whisper.cpp (a native+# binary), so openai-whisper/torch are intentionally absent — that is the ~2GB+# the native install saves. --engine whisper-py remains a dev/source-only option+# via backend/requirements.txt.+opencv-python-headless>=4.8.1.78+numpy>=1.24.0+Pillow>=10.0.0+questionary>=2.0.0+python-dotenv>=1.2.2+google-api-python-client>=2.0.1+google-auth-oauthlib>=1.0.0diff --git a/backend/requirements.txt b/backend/requirements.txtindex ca445ef..e5fcbfc 100644--- a/backend/requirements.txt+++ b/backend/requirements.txt@@ -9,7 +9,7 @@ openai-whisper>=20231117# speechbrain>=1.0.0# Face detection (optional, for smart cropping)-opencv-python-headless>=4.8.0+opencv-python-headless>=4.8.1.78numpy>=1.24.0# Thumbnails@@ -19,8 +19,8 @@ Pillow>=10.0.0questionary>=2.0.0# Utilities-python-dotenv>=1.0.0+python-dotenv>=1.2.2# YouTube analytics (optional — only needed for live OAuth sync; CSV import works without these)-google-api-python-client>=2.0.0+google-api-python-client>=2.0.1google-auth-oauthlib>=1.0.0diff --git a/backend/scripts/remotion_screenshot.cjs b/backend/scripts/remotion_screenshot.cjsindex e6f2f9b..0942669 100644--- a/backend/scripts/remotion_screenshot.cjs+++ b/backend/scripts/remotion_screenshot.cjs@@ -2,7 +2,7 @@const path = require("node:path");const rendererRoot = path.resolve(__dirname, "..", "..", "node_modules", "@remotion", "renderer", "dist");-const {openBrowser} = require("@remotion/renderer");+const {openBrowser, ensureBrowser} = require("@remotion/renderer");const {screenshot} = require(path.join(rendererRoot, "puppeteer-screenshot.js"));const [htmlPath, outputPath, widthArg, heightArg, waitMsArg] = process.argv.slice(2);@@ -46,6 +46,7 @@ const waitForAssets = async (page) => {};(async () => {+ await ensureBrowser({logLevel: "error"});const browser = await openBrowser("chrome", {logLevel: "error"});const closeBrowser = () => { try { browser.close({silent: true}); } catch {} };process.on("SIGINT", () => { closeBrowser(); process.exit(1); });diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.pyindex 2f406c7..e180477 100644--- a/backend/services/claude_suggest.py+++ b/backend/services/claude_suggest.py@@ -375,6 +375,163 @@ def _dedupe_clips_by_range(clips: list[dict]) -> list[dict]:return deduped+def find_moments_from_text(+ description: str,+ segments: list[dict],+ existing_clips: Optional[list[dict]] = None,+ progress_callback: Optional[Callable[[int, str], None]] = None,+ max_results: int = 3,+) -> list[dict]:+ """Locate the moment(s) the user described/pasted in the transcript via an AI+ CLI. Returns clip dicts (same shape as suggest_with_claude). Status goes to+ progress_callback; warnings to stderr — never stdout, which is the task+ runner's JSON-RPC channel."""+ existing_clips = existing_clips or []+ candidates = _find_ai_cli_candidates()+ if not candidates:+ print("No AI CLI available for moment search", file=sys.stderr, flush=True)+ return []++ if progress_callback:+ progress_callback(15, "Reading transcript...")+ transcript_text = _build_transcript_text(segments)++ existing_desc = ""+ if existing_clips:+ existing_desc = "\n\nALREADY SELECTED (do not re-suggest these):\n"+ for c in existing_clips:+ existing_desc += f"- {c.get('start_second')}s-{c.get('end_second')}s: {c.get('title', '')}\n"++ upper = max(1, int(max_results))+ prompt = f"""Find the moment(s) the user is describing in this podcast transcript. Return ONLY valid JSON.++USER WANTS: "{description}"+{existing_desc}+RULES:+- Find the EXACT moment(s) matching what the user pasted/described+- The user may list several moments — return one clip per distinct moment they mention+- Return 1-{upper} matching moments (best match first)+- All timestamps in SECONDS as numbers+- Duration target: {TARGET_CLIP_DURATION_MIN}-{TARGET_CLIP_DURATION_MAX} seconds, max {MAX_CLIP_DURATION} seconds+- Cut tight: start at the hook, end when the point lands+- Use segments to cut filler if needed++Return this JSON:+{{+ "clips": [+ {{+ "title": "First sentence of the moment",+ "start_second": 123.4,+ "end_second": 158.4,+ "segments": [{{"start": 123.4, "end": 158.4}}],+ "duration": 35,+ "content_type": "guest_story",+ "scores": {{"standalone": 4, "hook": 5, "relevance": 4, "quotability": 3}},+ "total_score": 16,+ "quote": "The key quote",+ "why": "Why this matches what the user asked for"+ }}+ ]+}}++Transcript:+{transcript_text}"""++ # Prompt goes to .podcli/tmp/ (gitignored), not the repo root, so a crash+ # mid-run never litters the working tree with transcript dumps.+ project_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")+ from utils.prompt_files import write_prompt_file+ prompt_file = write_prompt_file(prompt)++ try:+ for idx, (cli_path, engine) in enumerate(candidates):+ if progress_callback:+ label = "Claude" if engine == "claude" else "Codex"+ progress_callback(40, f"Searching transcript with {label}...")+ try:+ result = _run_ai_command(+ cli_path=cli_path,+ engine=engine,+ prompt=prompt,+ prompt_file=prompt_file,+ project_dir=project_dir,+ timeout=300,+ )+ except Exception:+ continue++ if result.returncode != 0 or not result.stdout.strip():+ continue++ response = result.stdout.strip()+ if "```" in response:+ import re++ fence_match = re.search(r"```(?:json)?\s*\n?(.*?)\n?\s*```", response, re.DOTALL)+ if fence_match:+ response = fence_match.group(1).strip()++ try:+ json_start = response.find("{")+ if json_start >= 0:+ data, _ = json.JSONDecoder().raw_decode(response, json_start)+ else:+ data = json.loads(response)+ except Exception:+ continue++ found = []+ for c in data.get("clips", []):+ scores = c.get("scores", {})+ total = sum(scores.values()) if scores else c.get("total_score", 0)+ keep_segments = []+ for seg in c.get("segments", []):+ s = round(float(seg.get("start", 0)), 1)+ e = round(float(seg.get("end", 0)), 1)+ if e > s:+ keep_segments.append({"start": s, "end": e})++ start_sec = round(float(c.get("start_second", 0)), 1)+ end_sec = round(float(c.get("end_second", 0)), 1)+ if not keep_segments and end_sec > start_sec:+ keep_segments = [{"start": start_sec, "end": end_sec}]++ kept_duration = sum(seg["end"] - seg["start"] for seg in keep_segments)+ if kept_duration < MIN_CLIP_DURATION or kept_duration > MAX_CLIP_DURATION:+ continue++ found.append({+ "title": c.get("title", "Untitled")[:55],+ "start_second": keep_segments[0]["start"] if keep_segments else start_sec,+ "end_second": keep_segments[-1]["end"] if keep_segments else end_sec,+ "segments": keep_segments,+ "duration": round(kept_duration),+ "score": total,+ "content_type": c.get("content_type", "unknown"),+ "reasoning": c.get("why", ""),+ "preview_text": c.get("quote", "")[:120],+ "suggested_caption_style": "hormozi",+ "quote": c.get("quote", ""),+ "why": c.get("why", ""),+ "reasons": [c.get("content_type", "")],+ "preview": c.get("quote", "")[:120],+ })++ if found:+ return _dedupe_clips_by_range(found)++ return []++ except Exception as e:+ print(f"Moment search error: {e}", file=sys.stderr, flush=True)+ return []+ finally:+ try:+ os.unlink(prompt_file)+ except Exception:+ pass++def suggest_with_claude(segments: list[dict],top_n: int = 5,diff --git a/backend/services/clip_generator.py b/backend/services/clip_generator.pyindex 9608bf4..90e2adc 100644--- a/backend/services/clip_generator.py+++ b/backend/services/clip_generator.py@@ -424,20 +424,25 @@ def _render_with_remotion(return False, None# Check node is available- node_path = shutil.which("node")+ node_path = os.environ.get("PODCLI_NODE") or shutil.which("node")if not node_path:_remotion_available = Falsereturn False, None- remotion_env = {**os.environ, "PODCLI_CACHE_DIR": paths["cache"]}+ # Cache the compiled bundle next to the render script. The compositions are+ # project-independent, so a single global bundle (in the managed runtime dir+ # for native installs) is reused across every project instead of rebuilt per+ # data/cache.+ bundle_cache_root = os.path.join(os.path.dirname(render_script), ".bundle-cache")+ remotion_env = {**os.environ, "PODCLI_CACHE_DIR": bundle_cache_root}- cache_dir = os.path.join(paths["cache"], "remotion-bundle")+ cache_dir = os.path.join(bundle_cache_root, "remotion-bundle")bundle_index = os.path.join(cache_dir, "index.html")if not os.path.exists(bundle_index):try:r = subprocess.run([node_path, render_script, "--prebundle"],- timeout=30,+ timeout=180,cwd=project_root,env=remotion_env,capture_output=True,@@ -545,16 +550,16 @@ def _render_with_remotion(if stdout:lines = [l.strip() for l in stdout.strip().split("\n") if l.strip()]if lines:- print(f" Remotion: {lines[-1][:120]}", flush=True)+ print(f" Remotion: {lines[-1][:120]}", file=sys.stderr, flush=True)- print(" Remotion: falling back to ASS for this clip", flush=True)+ print(" Remotion: falling back to ASS for this clip", file=sys.stderr, flush=True)return False, Noneexcept subprocess.TimeoutExpired:- print(" Remotion: timed out, using ASS for this clip", flush=True)+ print(" Remotion: timed out, using ASS for this clip", file=sys.stderr, flush=True)return False, Noneexcept Exception:- print(" Remotion: render error, using ASS for this clip", flush=True)+ print(" Remotion: render error, using ASS for this clip", file=sys.stderr, flush=True)return False, Nonefinally:try:@@ -695,6 +700,7 @@ def generate_clip(print(f" Boundary revert: post-trim duration {duration:.1f}s < "f"75% of asked {llm_total:.1f}s - using original range",+ file=sys.stderr,flush=True,)start_second = llm_start_seconddiff --git a/backend/services/encoder.py b/backend/services/encoder.pyindex 346fcb5..1479ef1 100644--- a/backend/services/encoder.py+++ b/backend/services/encoder.py@@ -159,7 +159,7 @@ def _encoder_cache_path() -> str:def _ffmpeg_fingerprint() -> str:"""Cheap fingerprint (path + mtime) to invalidate cache when ffmpeg changes."""import shutil- ffbin = shutil.which("ffmpeg") or "ffmpeg"+ ffbin = os.environ.get("PODCLI_FFMPEG") or shutil.which("ffmpeg") or "ffmpeg"try:st = os.stat(ffbin)return f"{ffbin}:{int(st.st_mtime)}:{st.st_size}"diff --git a/backend/services/thumbnail_html.py b/backend/services/thumbnail_html.pyindex 3aaaa52..68cf3ea 100644--- a/backend/services/thumbnail_html.py+++ b/backend/services/thumbnail_html.py@@ -173,7 +173,7 @@ def _build_remotion_screenshot_command(wait_ms: int,) -> Optional[list[str]]:"""Build a Remotion-backed screenshot command if the repo can run it."""- node_bin = shutil.which("node")+ node_bin = os.environ.get("PODCLI_NODE") or shutil.which("node")repo_root = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "..")renderer_pkg = os.path.join(repo_root, "node_modules", "@remotion", "renderer", "package.json")if not node_bin or not os.path.exists(script_path) or not os.path.exists(renderer_pkg):@@ -657,6 +657,8 @@ def generate_thumbnail(if not commands:raise RuntimeError("No browser screenshot command available")+ screenshot_cwd = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".."))+for cmd in commands:cmd_label = " ".join(cmd[:3]) if len(cmd) > 3 else " ".join(cmd)try:@@ -665,6 +667,7 @@ def generate_thumbnail(capture_output=True,text=True,timeout=timeout_s,+ cwd=screenshot_cwd,# .cmd/npx shims need cmd.exe on Windows; shell=True with a list breaks on POSIX.shell=sys.platform == "win32",)diff --git a/backend/services/transcript_packer.py b/backend/services/transcript_packer.pyindex 2d7beec..f311496 100644--- a/backend/services/transcript_packer.py+++ b/backend/services/transcript_packer.py@@ -62,8 +62,18 @@ def legacy_md5_cache_path(video_path: str) -> str:return os.path.join(_legacy_cache_dir(), hashlib.md5(raw.encode()).hexdigest() + ".json")+def _engine_cache_suffix() -> str:+ """Namespace the cache by engine so a whisper.cpp run doesn't reuse a+ whisper-py transcript (their timings/word splits differ). whisper-py keeps+ the bare filename, which the TS transcript cache also writes."""+ engine = os.environ.get("PODCLI_ENGINE", "whisper-py").strip().lower()+ if engine in ("whispercpp", "whisper-cpp", "whisper.cpp", "cpp"):+ return "-whispercpp"+ return ""++def transcript_json_path(cache_hash: str) -> str:- return os.path.join(_transcripts_cache_dir(), f"{cache_hash}.json")+ return os.path.join(_transcripts_cache_dir(), f"{cache_hash}{_engine_cache_suffix()}.json")def load_cached_transcript_for_video(video_path: str) -> dict[str, Any] | None:@@ -72,12 +82,16 @@ def load_cached_transcript_for_video(video_path: str) -> dict[str, Any] | None:if os.path.exists(canonical):with open(canonical, encoding="utf-8") as f:return json.load(f)- legacy = legacy_md5_cache_path(video_path)- if os.path.exists(legacy):- with open(legacy, encoding="utf-8") as f:- data = json.load(f)- save_cached_transcript_for_video(video_path, data)- return data+ # The legacy md5 cache predates the engine split and only ever held+ # whisper-py output, so don't let a whisper.cpp run adopt it under its own+ # namespace.+ if _engine_cache_suffix() == "":+ legacy = legacy_md5_cache_path(video_path)+ if os.path.exists(legacy):+ with open(legacy, encoding="utf-8") as f:+ data = json.load(f)+ save_cached_transcript_for_video(video_path, data)+ return datareturn Nonediff --git a/backend/services/transcription.py b/backend/services/transcription.pyindex 69f7493..9ca581e 100644--- a/backend/services/transcription.py+++ b/backend/services/transcription.py@@ -8,12 +8,77 @@ Produces word-level timestamps with speaker labels by:"""import os+import shutilimport subprocessimport sysimport tempfilefrom typing import Optional, Callable+def _managed_home() -> str:+ h = os.environ.get("PODCLI_HOME")+ if h:+ return h+ home = os.path.expanduser("~")+ if sys.platform == "darwin":+ return os.path.join(home, "Library", "Application Support", "podcli")+ if sys.platform == "win32":+ return os.environ.get("LOCALAPPDATA") or os.path.join(home, "AppData", "Local", "podcli")+ return os.environ.get("XDG_DATA_HOME") or os.path.join(home, ".local", "share", "podcli")+++def _whispercpp_cli() -> Optional[str]:+ """Resolve the whisper.cpp binary: explicit env, PATH, then the hermetic+ runtime location the native installer provisions."""+ cli = os.environ.get("PODCLI_WHISPER_CLI")+ if cli and (os.path.exists(cli) or shutil.which(cli)):+ return cli+ found = shutil.which("whisper-cli") or shutil.which("whisper-cpp")+ if found:+ return found+ exe = "whisper-cli.exe" if sys.platform == "win32" else "whisper-cli"+ hermetic = os.path.join(_managed_home(), "runtime", "whisper", exe)+ return hermetic if os.path.exists(hermetic) else None+++def _whispercpp_model(model_size: str) -> str:+ return os.environ.get("PODCLI_WHISPERCPP_MODEL") or os.path.join(+ _managed_home(), "models", f"ggml-{model_size}.bin"+ )+++def _whispercpp_ready(model_size: str) -> bool:+ return _whispercpp_cli() is not None and os.path.exists(_whispercpp_model(model_size))+++def _transcribe_with_whispercpp(file_path, model_size, language, progress_callback):+ from services import transcription_whispercpp as wcpp++ if progress_callback:+ progress_callback(10, "Transcribing with whisper.cpp...")++ cli = _whispercpp_cli() or "whisper-cli"+ model = _whispercpp_model(model_size)+ if not os.path.exists(model):+ raise FileNotFoundError(+ f"whisper.cpp model not found: {model}. "+ "Set PODCLI_WHISPERCPP_MODEL or run provisioning."+ )+ vad = os.environ.get("PODCLI_WHISPERCPP_VAD", "").strip().lower() in ("1", "true", "yes", "on")+ result = wcpp.transcribe_file(+ file_path,+ model_path=model,+ whisper_cli=cli,+ ffmpeg=os.environ.get("PODCLI_FFMPEG", "ffmpeg"),+ language=language,+ vad=vad,+ vad_model=os.environ.get("PODCLI_WHISPERCPP_VAD_MODEL") or None,+ )+ if progress_callback:+ progress_callback(100, "Transcription complete")+ return result++def transcribe_file(file_path: str,model_size: str = "base",@@ -39,15 +104,31 @@ def transcribe_file(if not os.path.exists(file_path):raise FileNotFoundError(f"File not found: {file_path}")+ requested = os.environ.get("PODCLI_ENGINE", "").strip().lower()+ engine = requested or "whisper-py"+ if engine in ("whispercpp", "whisper-cpp", "whisper.cpp", "cpp"):+ return _transcribe_with_whispercpp(file_path, model_size, language, progress_callback)+# ================================================================# Step 1: Whisper transcription# ================================================================if progress_callback:progress_callback(5, "Loading Whisper model...")- import whisper+ # Native installs ship whisper.cpp, not openai-whisper. Fall back to it+ # automatically — whether whisper is missing OR a broken install fails to+ # load/run — unless the user explicitly asked for the whisper-py engine.+ try:+ import whisper- model = whisper.load_model(model_size)+ model = whisper.load_model(model_size)+ except Exception as e:+ if not requested and _whispercpp_ready(model_size):+ return _transcribe_with_whispercpp(file_path, model_size, language, progress_callback)+ raise RuntimeError(+ "The whisper-py engine needs the full source install (openai-whisper + torch). "+ "This native install ships whisper.cpp — rerun with --engine whispercpp."+ ) from eif progress_callback:progress_callback(10, f"Transcribing with Whisper ({model_size})...")diff --git a/backend/services/transcription_whispercpp.py b/backend/services/transcription_whispercpp.pynew file mode 100644index 0000000..d62f8be--- /dev/null+++ b/backend/services/transcription_whispercpp.py@@ -0,0 +1,216 @@+"""whisper.cpp adapter behind the transcribe_file contract.++Tokens carry a leading-space convention (" and", continuations have none); we+merge on that boundary and strip word text. The strip must match the rest of the+pipeline exactly — apply_corrections() and caption spacing key on stripped text.+"""++import json+import os+import re+import shutil+import subprocess+import sys+import tempfile+from typing import Optional++_SPECIAL = re.compile(r"^\[.*\]$") # [_BEG_], [_TT_...], etc.+++def _extract_wav(media_path: str, wav_path: str, ffmpeg: str = "ffmpeg") -> None:+ subprocess.run(+ [ffmpeg, "-y", "-loglevel", "error", "-i", media_path,+ "-ar", "16000", "-ac", "1", wav_path],+ check=True,+ timeout=1800,+ )+++def _tokens_to_words(tokens: list[dict]) -> list[dict]:+ """Merge whisper.cpp subword tokens into words with start/end seconds."""+ words: list[dict] = []+ cur_text = ""+ cur_start: Optional[float] = None+ cur_end: Optional[float] = None++ def flush():+ nonlocal cur_text, cur_start, cur_end+ text = cur_text.strip().lstrip("▁").strip()+ if text and cur_start is not None:+ words.append({+ "word": text,+ "start": round(cur_start / 1000.0, 3),+ "end": round(cur_end / 1000.0, 3),+ "speaker": None,+ })+ cur_text, cur_start, cur_end = "", None, None++ for tok in tokens:+ raw = tok.get("text", "")+ if _SPECIAL.match(raw.strip()):+ continue+ off = tok.get("offsets") or {}+ t0, t1 = off.get("from"), off.get("to")+ starts_word = raw.startswith(" ") or raw.startswith("▁")+ if starts_word and cur_text:+ flush()+ if cur_start is None and t0 is not None:+ cur_start = t0+ cur_text += raw+ if t1 is not None:+ cur_end = t1+ flush()+ return words+++def _voiced_intervals(wav_path: str, bridge: float = 0.3, thresh_ratio: float = 0.07):+ import wave++ import numpy as np++ try:+ w = wave.open(wav_path, "rb")+ sr, width, n = w.getframerate(), w.getsampwidth(), w.getnframes()+ raw = w.readframes(n)+ w.close()+ except Exception:+ return []+ if width != 2 or sr <= 0 or not raw:+ return []+ samples = np.frombuffer(raw, dtype=np.int16).astype(np.float32)+ hop = max(1, int(sr * 0.010))+ frame = max(hop, int(sr * 0.025))+ if len(samples) < frame:+ return []+ nf = 1 + (len(samples) - frame) // hop+ idx = np.arange(nf)[:, None] * hop + np.arange(frame)[None, :]+ rms = np.sqrt((samples[idx] ** 2).mean(axis=1))+ peak = float(rms.max())+ if peak <= 0:+ return []+ voiced = rms > thresh_ratio * peak+ intervals, start = [], None+ for i, v in enumerate(voiced):+ if v and start is None:+ start = i * hop / sr+ elif not v and start is not None:+ intervals.append([start, i * hop / sr])+ start = None+ if start is not None:+ intervals.append([start, nf * hop / sr])+ merged = []+ for iv in intervals:+ if merged and iv[0] - merged[-1][1] <= bridge:+ merged[-1][1] = iv[1]+ else:+ merged.append(iv)+ return merged+++def _snap_words_to_voiced(words: list[dict], wav_path: str) -> list[dict]:+ """Pull word timings back into the voiced span. whisper.cpp sometimes+ stretches trailing words across trailing silence; clamping to [first voiced,+ last voiced] (with a small pad) and re-flowing keeps captions in sync without+ disturbing words that already overlap speech."""+ if not words:+ return words+ intervals = _voiced_intervals(wav_path)+ if not intervals:+ return words+ pad = 0.15+ lo = max(0.0, intervals[0][0] - pad)+ hi = intervals[-1][1] + pad+ out, prev_end = [], lo+ for w in words:+ s = min(max(float(w.get("start", 0.0)), lo), hi)+ e = min(max(float(w.get("end", 0.0)), lo), hi)+ if s < prev_end:+ s = prev_end+ if e <= s:+ # A word clamped to hi would otherwise collapse to zero length; a+ # tiny overhang past the voiced pad is harmless, a zero-length+ # caption event is not.+ e = s + 0.05+ prev_end = e+ out.append({**w, "start": round(s, 3), "end": round(e, 3)})+ return out+++def transcribe_file(+ file_path: str,+ model_path: str,+ whisper_cli: str = "whisper-cli",+ ffmpeg: str = "ffmpeg",+ language: Optional[str] = "en",+ dtw_model: str = "base",+ threads: int = 4,+ vad: bool = False,+ vad_model: Optional[str] = None,+ **_ignored,+) -> dict:+ if not os.path.exists(file_path):+ raise FileNotFoundError(file_path)+ if not os.path.exists(model_path):+ raise FileNotFoundError(f"ggml model not found: {model_path}")++ tmpdir = tempfile.mkdtemp(prefix="wcpp_")+ wav = os.path.join(tmpdir, "audio.wav")+ out_base = os.path.join(tmpdir, "out")+ try:+ _extract_wav(file_path, wav, ffmpeg)++ cmd = [whisper_cli, "-m", model_path, "-f", wav, "-ojf",+ "-of", out_base, "-t", str(threads)]+ if dtw_model:+ cmd += ["-dtw", dtw_model]+ if vad and vad_model and os.path.exists(vad_model):+ # VAD removes the trailing-words-into-silence failure mode but adds a+ # systematic early bias (silence-removal remapping). Off by default;+ # the energy-snap below addresses the same defect without the bias.+ cmd += ["--vad", "--vad-model", vad_model]+ if language:+ cmd += ["-l", language]+ subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True, timeout=7200)++ with open(out_base + ".json", encoding="utf-8") as f:+ data = json.load(f)++ transcription = data.get("transcription", [])+ segments, words = [], []+ for i, seg in enumerate(transcription):+ off = seg.get("offsets") or {}+ segments.append({+ "id": i,+ "start": round((off.get("from") or 0) / 1000.0, 3),+ "end": round((off.get("to") or 0) / 1000.0, 3),+ "text": (seg.get("text") or "").strip(),+ "speaker": None,+ })+ words.extend(_tokens_to_words(seg.get("tokens", [])))++ if os.environ.get("PODCLI_WHISPERCPP_NO_SNAP", "").strip().lower() not in ("1", "true", "yes", "on"):+ words = _snap_words_to_voiced(words, wav)++ return {+ "transcript": " ".join(s["text"] for s in segments).strip(),+ "segments": segments,+ "words": words,+ "duration": segments[-1]["end"] if segments else 0.0,+ "language": (data.get("params") or {}).get("language") or language or "en",+ }+ finally:+ shutil.rmtree(tmpdir, ignore_errors=True)+++if __name__ == "__main__":+ # Quick CLI: transcribe_whispercpp <media> <model> [out.json]+ media, model = sys.argv[1], sys.argv[2]+ out = sys.argv[3] if len(sys.argv) > 3 else None+ result = transcribe_file(media, model)+ payload = json.dumps(result, indent=2, ensure_ascii=False)+ if out:+ with open(out, "w", encoding="utf-8") as f:+ f.write(payload)+ print(f"{len(result['words'])} words, {len(result['segments'])} segments -> {out}")+ else:+ print(payload)diff --git a/backend/utils/proc.py b/backend/utils/proc.pyindex d118dd9..e48b530 100644--- a/backend/utils/proc.py+++ b/backend/utils/proc.py@@ -8,12 +8,24 @@ the server or swallow failures silently.from __future__ import annotationsimport logging+import osimport subprocessimport timefrom typing import Sequencelog = logging.getLogger("podcli.proc")+_TOOL_ENV = {"ffmpeg": "PODCLI_FFMPEG", "ffprobe": "PODCLI_FFPROBE"}+++def _resolve_tool(cmd: Sequence[str]) -> list[str]:+ if not cmd:+ return list(cmd)+ override = os.environ.get(_TOOL_ENV.get(cmd[0], ""))+ if override and os.path.exists(override):+ return [override, *cmd[1:]]+ return list(cmd)+class ProcError(RuntimeError):"""Raised when a wrapped subprocess fails or times out."""@@ -45,6 +57,7 @@ def run("""if not cmd:raise ValueError("proc.run: cmd must be non-empty")+ cmd = _resolve_tool(cmd)tool = cmd[0]t0 = time.monotonic()log.debug("proc.start tool=%s argc=%d timeout=%.0fs", tool, len(cmd), timeout)diff --git a/cli/go.mod b/cli/go.modnew file mode 100644index 0000000..848df68--- /dev/null+++ b/cli/go.mod@@ -0,0 +1,3 @@+module podcli++go 1.23diff --git a/cli/internal/backend/embed.go b/cli/internal/backend/embed.gonew file mode 100644index 0000000..be0a363--- /dev/null+++ b/cli/internal/backend/embed.go@@ -0,0 +1,48 @@+// Package backend ships the Python processing backend inside the launcher+// binary so an installed podcli runs without the source repo. The files/ tree is+// synced from the repo backend/ at build time (`go generate ./...` or CI) and is+// gitignored — never edit files/ by hand.+package backend++import (+ "embed"+ "io/fs"+ "os"+ "path/filepath"+)++//go:generate sh sync.sh+//go:embed all:files+var files embed.FS++// Extract replaces dest with the embedded backend tree. dest is removed first so+// a stale dev symlink or an older extracted copy never shadows the shipped one.+func Extract(dest string) error {+ if err := os.RemoveAll(dest); err != nil {+ return err+ }+ return fs.WalkDir(files, "files", func(p string, d fs.DirEntry, err error) error {+ if err != nil {+ return err+ }+ rel, err := filepath.Rel("files", p)+ if err != nil {+ return err+ }+ if rel == "." {+ return nil+ }+ target := filepath.Join(dest, rel)+ if d.IsDir() {+ return os.MkdirAll(target, 0o755)+ }+ data, err := files.ReadFile(p)+ if err != nil {+ return err+ }+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ return os.WriteFile(target, data, 0o644)+ })+}diff --git a/cli/internal/backend/sync.sh b/cli/internal/backend/sync.shnew file mode 100644index 0000000..51ca2ac--- /dev/null+++ b/cli/internal/backend/sync.sh@@ -0,0 +1,19 @@+#!/bin/sh+# Sync the repo Python backend into files/ for go:embed. Run via `go generate+# ./...` before building. files/ is gitignored; this is its only writer.+set -e+here="$(cd "$(dirname "$0")" && pwd)"+src="$here/../../../backend"+dest="$here/files"+rm -rf "$dest"+mkdir -p "$dest"+rsync -a \+ --exclude='__pycache__' \+ --exclude='*.pyc' \+ --exclude='venv' \+ --exclude='.venv' \+ --exclude='requirements.txt' \+ --exclude='models/res10_300x300_ssd_iter_140000.caffemodel' \+ --exclude='models/deploy.prototxt' \+ "$src"/ "$dest"/+echo "synced backend -> $dest"diff --git a/cli/internal/config/config.go b/cli/internal/config/config.gonew file mode 100644index 0000000..ef972fe--- /dev/null+++ b/cli/internal/config/config.go@@ -0,0 +1,83 @@+// Package config persists launcher settings (currently the auto-update+// off-switch) in the managed dir's config.json.+package config++import (+ "encoding/json"+ "fmt"+ "os"+ "strings"++ "podcli/internal/paths"+)++type Config struct {+ Update struct {+ Auto *bool `json:"auto,omitempty"`+ } `json:"update"`+}++func Load() Config {+ var c Config+ if b, err := os.ReadFile(paths.ConfigPath()); err == nil {+ json.Unmarshal(b, &c)+ }+ return c+}++func (c Config) Save() error {+ if err := os.MkdirAll(paths.Home(), 0o755); err != nil {+ return err+ }+ b, _ := json.MarshalIndent(c, "", " ")+ return os.WriteFile(paths.ConfigPath(), b, 0o644)+}++func truthy(s string) bool {+ switch strings.ToLower(strings.TrimSpace(s)) {+ case "1", "true", "yes", "on":+ return true+ }+ return false+}++// AutoUpdate is true unless disabled via config update.auto or PODCLI_NO_UPDATE.+func AutoUpdate() bool {+ if truthy(os.Getenv("PODCLI_NO_UPDATE")) {+ return false+ }+ if a := Load().Update.Auto; a != nil {+ return *a+ }+ return true+}++func Get(key string) (string, error) {+ switch key {+ case "update.auto":+ if a := Load().Update.Auto; a != nil && !*a {+ return "off", nil+ }+ return "on", nil+ }+ return "", fmt.Errorf("unknown config key %q (known: update.auto)", key)+}++func Set(key, val string) error {+ switch key {+ case "update.auto":+ on := !offValue(val)+ c := Load()+ c.Update.Auto = &on+ return c.Save()+ }+ return fmt.Errorf("unknown config key %q (known: update.auto)", key)+}++func offValue(s string) bool {+ switch strings.ToLower(strings.TrimSpace(s)) {+ case "off", "false", "no", "0", "disable", "disabled":+ return true+ }+ return false+}diff --git a/cli/internal/engine/engine.go b/cli/internal/engine/engine.gonew file mode 100644index 0000000..82cae60--- /dev/null+++ b/cli/internal/engine/engine.go@@ -0,0 +1,263 @@+// Package engine routes podcli subcommands to the Python backend.+package engine++import (+ "bytes"+ "fmt"+ "os"+ "os/exec"+ "path/filepath"+ "runtime"+ "strings"++ "podcli/internal/paths"+)++// stderrFilter drops the macOS/OpenCV/Whisper startup noise the old bash+// launcher stripped with `grep -v`, so native runs aren't louder than before.+// It buffers partial lines and forwards everything else to real stderr.+type stderrFilter struct{ buf []byte }++func isStderrNoise(line string) bool {+ return strings.HasPrefix(line, "objc[") ||+ strings.Contains(line, "FP16 is not supported") ||+ strings.HasPrefix(strings.TrimSpace(line), "warnings.warn(")+}++func (w *stderrFilter) Write(p []byte) (int, error) {+ w.buf = append(w.buf, p...)+ for {+ i := bytes.IndexByte(w.buf, '\n')+ if i < 0 {+ break+ }+ line := w.buf[:i]+ w.buf = w.buf[i+1:]+ if !isStderrNoise(string(line)) {+ os.Stderr.Write(append(line, '\n'))+ }+ }+ return len(p), nil+}++func (w *stderrFilter) flush() {+ if len(w.buf) > 0 && !isStderrNoise(string(w.buf)) {+ os.Stderr.Write(w.buf)+ }+ w.buf = nil+}++// IsHermeticPython reports whether the resolved interpreter is the provisioned+// one (which lacks openai-whisper, so transcription must default to whisper.cpp).+func IsHermeticPython() bool {+ return strings.HasPrefix(Python(), paths.RuntimeDir())+}++func exists(p string) bool {+ _, err := os.Stat(p)+ return err == nil+}++func BackendRoot() (string, bool) {+ if b := os.Getenv("PODCLI_BACKEND"); b != "" && exists(filepath.Join(b, "cli.py")) {+ return b, true+ }+ if dir, err := os.Getwd(); err == nil {+ for {+ cand := filepath.Join(dir, "backend")+ if exists(filepath.Join(cand, "cli.py")) {+ return cand, true+ }+ parent := filepath.Dir(dir)+ if parent == dir {+ break+ }+ dir = parent+ }+ }+ cand := filepath.Join(paths.RuntimeDir(), "backend")+ if exists(filepath.Join(cand, "cli.py")) {+ return cand, true+ }+ return "", false+}++func Python() string {+ if p := os.Getenv("PODCLI_PYTHON"); p != "" {+ return p+ }+ hermetic := []string{+ filepath.Join(paths.RuntimeDir(), "python", "bin", "python3"),+ filepath.Join(paths.RuntimeDir(), "python", "python.exe"),+ }+ for _, p := range hermetic {+ if exists(p) {+ return p+ }+ }+ if root, ok := BackendRoot(); ok {+ venv := filepath.Join(filepath.Dir(root), "venv", "bin", "python3")+ if runtime.GOOS == "windows" {+ venv = filepath.Join(filepath.Dir(root), "venv", "Scripts", "python.exe")+ }+ if exists(venv) {+ return venv+ }+ }+ return "python3"+}++func runtimeBin(sub, name string) string {+ for _, p := range []string{+ filepath.Join(paths.RuntimeDir(), sub, name),+ filepath.Join(paths.RuntimeDir(), sub, name+".exe"),+ } {+ if exists(p) {+ return p+ }+ }+ return ""+}++func FFmpeg() string { return runtimeBin("ffmpeg", "ffmpeg") }+func FFprobe() string { return runtimeBin("ffmpeg", "ffprobe") }+func WhisperCLI() string { return runtimeBin("whisper", "whisper-cli") }++func Node() string {+ for _, p := range []string{+ filepath.Join(paths.RuntimeDir(), "node", "bin", "node"),+ filepath.Join(paths.RuntimeDir(), "node", "node.exe"),+ } {+ if exists(p) {+ return p+ }+ }+ return ""+}++func StudioServer() string {+ p := filepath.Join(paths.RuntimeDir(), "studio", "web-server.mjs")+ if exists(p) {+ return p+ }+ return ""+}++func MCPServer() string {+ p := filepath.Join(paths.RuntimeDir(), "studio", "mcp-server.mjs")+ if exists(p) {+ return p+ }+ return ""+}++// nodeEnv builds the env a bundled Node server (studio/MCP) needs: the TS+// paths.ts reads these names (note PYTHON_PATH/FFMPEG_PATH differ from the+// PODCLI_* names the Python side uses). Project data stays cwd-local.+func nodeEnv() []string {+ env := os.Environ()+ if root, ok := BackendRoot(); ok {+ env = append(env, "PODCLI_BACKEND="+root)+ }+ env = append(env, "PYTHON_PATH="+Python())+ if ff := FFmpeg(); ff != "" {+ env = append(env, "FFMPEG_PATH="+ff)+ }+ if fp := FFprobe(); fp != "" {+ env = append(env, "FFPROBE_PATH="+fp)+ }+ env = append(env, DataEnv()...)+ return env+}++// RunMCP execs the bundled MCP stdio server under hermetic Node. stdout carries+// JSON-RPC, so nothing here may write to it.+func RunMCP() (int, error) {+ node, server := Node(), MCPServer()+ if node == "" || server == "" {+ return 1, fmt.Errorf("MCP server not provisioned — run `podcli setup`")+ }+ cmd := exec.Command(node, server)+ cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr+ cmd.Env = nodeEnv()+ if err := cmd.Run(); err != nil {+ if ee, ok := err.(*exec.ExitError); ok {+ return ee.ExitCode(), nil+ }+ return 1, err+ }+ return 0, nil+}++// DataEnv tells the backend where data lives. The brand brain (presets,+// knowledge, assets, history, config) and the transcript cache live in the+// global managed dir so they follow the user across directories; only rendered+// clips go under the working directory (PODCLI_OUTPUT). Explicit env always wins+// so power users and tests can override any single path.+func DataEnv() []string {+ var env []string+ home := paths.Home()+ if os.Getenv("PODCLI_HOME") == "" {+ env = append(env, "PODCLI_HOME="+home)+ }+ if os.Getenv("PODCLI_DATA") == "" {+ env = append(env, "PODCLI_DATA="+filepath.Join(home, "data"))+ }+ if os.Getenv("PODCLI_ENV_FILE") == "" {+ env = append(env, "PODCLI_ENV_FILE="+filepath.Join(home, ".env"))+ }+ if cwd, err := os.Getwd(); err == nil {+ if os.Getenv("PODCLI_CWD") == "" {+ env = append(env, "PODCLI_CWD="+cwd)+ }+ if os.Getenv("PODCLI_OUTPUT") == "" {+ env = append(env, "PODCLI_OUTPUT="+filepath.Join(cwd, "podcli-clips"))+ }+ }+ return env+}++func Run(args []string) (int, error) {+ root, ok := BackendRoot()+ if !ok {+ return 1, fmt.Errorf("python backend not found — set PODCLI_BACKEND or run inside the repo")+ }+ cli := filepath.Join(root, "cli.py")+ full := append([]string{"-W", "ignore::UserWarning", cli}, args...)++ cmd := exec.Command(Python(), full...)+ sf := &stderrFilter{}+ cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, sf+ env := append(os.Environ(),+ "OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES",+ "PYTHONIOENCODING=utf-8",+ "PYTHONUTF8=1",+ )+ if ff := FFmpeg(); ff != "" {+ env = append(env, "PODCLI_FFMPEG="+ff)+ }+ if fp := FFprobe(); fp != "" {+ env = append(env, "PODCLI_FFPROBE="+fp)+ }+ if wc := WhisperCLI(); wc != "" {+ env = append(env, "PODCLI_WHISPER_CLI="+wc)+ }+ if nd := Node(); nd != "" {+ env = append(env, "PODCLI_NODE="+nd)+ }+ if ss := StudioServer(); ss != "" {+ env = append(env, "PODCLI_STUDIO="+filepath.Dir(ss))+ }+ env = append(env, DataEnv()...)+ cmd.Env = env++ err := cmd.Run()+ sf.flush()+ if err != nil {+ if ee, ok := err.(*exec.ExitError); ok {+ return ee.ExitCode(), nil+ }+ return 1, err+ }+ return 0, nil+}diff --git a/cli/internal/paths/paths.go b/cli/internal/paths/paths.gonew file mode 100644index 0000000..d510e3d--- /dev/null+++ b/cli/internal/paths/paths.go@@ -0,0 +1,45 @@+// Package paths resolves the global managed directory where podcli keeps its+// hermetic runtimes, models, binaries, and config. Per-project working data+// (.podcli/) stays in the user's current directory and is not handled here.+package paths++import (+ "os"+ "path/filepath"+ "runtime"+)++// Home is the global managed dir. Override with PODCLI_HOME (used by tests and+// power users). Layout matches plans/native-cli.md:+//+// darwin ~/Library/Application Support/podcli+// windows %LOCALAPPDATA%\podcli+// linux $XDG_DATA_HOME/podcli (or ~/.local/share/podcli)+func Home() string {+ if h := os.Getenv("PODCLI_HOME"); h != "" {+ return h+ }+ home, err := os.UserHomeDir()+ if err != nil {+ home = "."+ }+ switch runtime.GOOS {+ case "darwin":+ return filepath.Join(home, "Library", "Application Support", "podcli")+ case "windows":+ if d := os.Getenv("LOCALAPPDATA"); d != "" {+ return filepath.Join(d, "podcli")+ }+ return filepath.Join(home, "AppData", "Local", "podcli")+ default:+ if d := os.Getenv("XDG_DATA_HOME"); d != "" {+ return filepath.Join(d, "podcli")+ }+ return filepath.Join(home, ".local", "share", "podcli")+ }+}++func RuntimeDir() string { return filepath.Join(Home(), "runtime") }+func ModelsDir() string { return filepath.Join(Home(), "models") }+func BinDir() string { return filepath.Join(Home(), "bin") }+func ConfigPath() string { return filepath.Join(Home(), "config.json") }diff --git a/cli/internal/podstack/podstack.go b/cli/internal/podstack/podstack.gonew file mode 100644index 0000000..9a5d346--- /dev/null+++ b/cli/internal/podstack/podstack.go@@ -0,0 +1,173 @@+// Package podstack forwards PodStack workflow commands (auto, generate-titles,+// …) to an AI agent CLI (Claude Code or Codex), porting the old bash launcher.+// The commands are Claude Code slash commands driving the podcli MCP tools, so+// they run inside the agent, not the terminal. The slash-command files are+// embedded and installed into the working project on demand.+package podstack++import (+ "embed"+ "fmt"+ "io/fs"+ "os"+ "os/exec"+ "path/filepath"+ "sort"+ "strings"+ "syscall"+)++//go:generate sh sync.sh+//go:embed all:commands+var commands embed.FS++const (+ colAccent = "\033[38;2;212;135;74m"+ colGreen = "\033[38;2;74;222;128m"+ colYellow = "\033[38;2;250;204;21m"+ colBold = "\033[1m"+ colDim = "\033[2m"+ colReset = "\033[0m"+)++// Names lists the supported PodStack commands, derived from the embedded files.+func Names() []string {+ entries, err := commands.ReadDir("commands")+ if err != nil {+ return nil+ }+ var names []string+ for _, e := range entries {+ if strings.HasSuffix(e.Name(), ".md") {+ names = append(names, strings.TrimSuffix(e.Name(), ".md"))+ }+ }+ sort.Strings(names)+ return names+}++func IsCommand(name string) bool {+ name = strings.TrimPrefix(strings.TrimPrefix(name, "--"), "/")+ for _, n := range Names() {+ if n == name {+ return true+ }+ }+ return false+}++// installCommands writes the embedded slash-command files into+// <project>/.claude/commands so the agent can resolve /<cmd>. Existing files are+// left untouched, so a user's local edits win.+func installCommands(project string) error {+ dest := filepath.Join(project, ".claude", "commands")+ if err := os.MkdirAll(dest, 0o755); err != nil {+ return err+ }+ return fs.WalkDir(commands, "commands", func(p string, d fs.DirEntry, err error) error {+ if err != nil || d.IsDir() {+ return err+ }+ target := filepath.Join(dest, filepath.Base(p))+ if _, err := os.Stat(target); err == nil {+ return nil+ }+ data, err := commands.ReadFile(p)+ if err != nil {+ return err+ }+ return os.WriteFile(target, data, 0o644)+ })+}++// Run launches the agent for cmd with the remaining args as the slash-command+// arguments. Engine selection: --claude / --codex / --ai <engine>, else+// PODCLI_AI, else auto (Claude preferred, Codex fallback).+func Run(cmd string, args []string) int {+ cmd = strings.TrimPrefix(strings.TrimPrefix(cmd, "--"), "/")+ engine := os.Getenv("PODCLI_AI")+ if engine == "" {+ engine = "auto"+ }+ var promptArgs []string+ for i := 0; i < len(args); i++ {+ switch a := args[i]; {+ case a == "--codex":+ engine = "codex"+ case a == "--claude":+ engine = "claude"+ case a == "--ai":+ if i+1 < len(args) {+ engine = args[i+1]+ i+++ }+ case strings.HasPrefix(a, "--ai="):+ engine = strings.TrimPrefix(a, "--ai=")+ default:+ promptArgs = append(promptArgs, a)+ }+ }+ switch engine {+ case "auto", "claude", "codex":+ default:+ fmt.Fprintf(os.Stderr, " %sInvalid AI engine:%s %s — use --claude, --codex, or --ai auto\n", colBold, colReset, engine)+ return 1+ }++ project, err := os.Getwd()+ if err != nil {+ project = "."+ }+ if err := installCommands(project); err != nil {+ fmt.Fprintf(os.Stderr, " %swarning:%s could not install slash commands: %v\n", colYellow, colReset, err)+ }++ prompt := "/" + cmd+ if len(promptArgs) > 0 {+ prompt += " " + strings.Join(promptArgs, " ")+ }+ codexPrompt := fmt.Sprintf("Run the PodStack workflow from .claude/commands/%s.md with these arguments, then follow that workflow exactly: %s", cmd, prompt)++ claudeBin, _ := exec.LookPath("claude")+ codexBin, _ := exec.LookPath("codex")++ if engine == "codex" && codexBin == "" {+ fmt.Fprintf(os.Stderr, "\n %sCodex not found in PATH.%s\n Install it, then run:\n %scodex --cd %q %q%s\n\n", colBold, colReset, colAccent, project, codexPrompt, colReset)+ return 1+ }+ if engine == "claude" && claudeBin == "" {+ fmt.Fprintf(os.Stderr, "\n %sClaude Code not found in PATH.%s\n Install it, then run:\n %sclaude %q%s\n\n", colBold, colReset, colAccent, prompt, colReset)+ return 1+ }++ if engine != "codex" && claudeBin != "" {+ fmt.Fprintf(os.Stderr, "\n %s▶%s Launching Claude Code with: %s%s%s\n %scwd: %s%s\n\n", colGreen, colReset, colAccent, prompt, colReset, colDim, project, colReset)+ if code := runIn(project, claudeBin, prompt); code == 0 || engine == "claude" || codexBin == "" {+ return code+ }+ fmt.Fprintf(os.Stderr, "\n %s⚠%s Claude exited nonzero; trying Codex...\n", colYellow, colReset)+ }++ if codexBin == "" {+ fmt.Fprintf(os.Stderr, "\n %sNo AI agent CLI found in PATH.%s\n Install Claude Code or Codex, then run one of:\n %sclaude %q%s\n %scodex --cd %q %q%s\n\n", colBold, colReset, colAccent, prompt, colReset, colAccent, project, codexPrompt, colReset)+ return 1+ }+ fmt.Fprintf(os.Stderr, "\n %s▶%s Launching Codex with: %s%s%s\n %scwd: %s%s\n\n", colGreen, colReset, colAccent, prompt, colReset, colDim, project, colReset)+ return runIn(project, codexBin, "--cd", project, codexPrompt)+}++func runIn(dir, bin string, args ...string) int {+ cmd := exec.Command(bin, args...)+ cmd.Dir = dir+ cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr+ if err := cmd.Run(); err != nil {+ if ee, ok := err.(*exec.ExitError); ok {+ if ws, ok := ee.Sys().(syscall.WaitStatus); ok {+ return ws.ExitStatus()+ }+ return 1+ }+ return 1+ }+ return 0+}diff --git a/cli/internal/podstack/sync.sh b/cli/internal/podstack/sync.shnew file mode 100644index 0000000..8b20678--- /dev/null+++ b/cli/internal/podstack/sync.sh@@ -0,0 +1,12 @@+#!/bin/sh+# Sync the repo PodStack slash commands into commands/ for go:embed. Run via+# `go generate ./...` before building. commands/ is gitignored; this is its+# only writer.+set -e+here="$(cd "$(dirname "$0")" && pwd)"+src="$here/../../../.claude/commands"+dest="$here/commands"+rm -rf "$dest"+mkdir -p "$dest"+cp "$src"/*.md "$dest"/+echo "synced PodStack commands -> $dest"diff --git a/cli/internal/provision/provision.go b/cli/internal/provision/provision.gonew file mode 100644index 0000000..ce31c5d--- /dev/null+++ b/cli/internal/provision/provision.go@@ -0,0 +1,813 @@+// Package provision fetches pinned models into the global managed dir.+package provision++import (+ "archive/tar"+ "archive/zip"+ "compress/gzip"+ "crypto/sha256"+ "encoding/hex"+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "os"+ "os/exec"+ "path/filepath"+ "runtime"+ "strings"+ "time"++ "podcli/internal/paths"+)++type model struct {+ URL string+ SHA256 string // empty: verification skipped+}++var models = map[string]model{+ "base": {+ URL: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-base.bin",+ SHA256: "60ed5bc3dd14eea856493d334349b405782ddcaf0028d4b5df4088345fba2efe",+ },+ "tiny.en": {+ URL: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-tiny.en.bin",+ },+ "small": {+ URL: "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin",+ },+}++const vadURL = "https://huggingface.co/ggml-org/whisper-vad/resolve/main/ggml-silero-v5.1.2.bin"+const vadSHA = "29940d98d42b91fbd05ce489f3ecf7c72f0a42f027e4875919a28fb4c04ea2cf"++func ModelPath(size string) string {+ return filepath.Join(paths.ModelsDir(), "ggml-"+size+".bin")+}++func VADModelPath() string {+ return filepath.Join(paths.ModelsDir(), "ggml-silero-v5.1.2.bin")+}++func have(p string) bool {+ if fi, err := os.Stat(p); err == nil && fi.Size() > 0 {+ return true+ }+ return false+}++func EnsureModel(size string) (string, error) {+ dest := ModelPath(size)+ if have(dest) {+ return dest, nil+ }+ m, ok := models[size]+ if !ok {+ return "", fmt.Errorf("unknown model size %q (known: base, tiny.en, small)", size)+ }+ if err := download(m.URL, dest, m.SHA256, "ggml-"+size); err != nil {+ return "", err+ }+ return dest, nil+}++func EnsureVADModel() (string, error) {+ dest := VADModelPath()+ if have(dest) {+ return dest, nil+ }+ if err := download(vadURL, dest, vadSHA, "silero-vad"); err != nil {+ return "", err+ }+ return dest, nil+}++const maxAttempts = 6++// fetch resumes via HTTP Range across transient stalls rather than restarting,+// writing to dest atomically.+func fetch(url, dest, label string) error {+ if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {+ return err+ }+ tmp := dest + ".part"+ var lastErr error+ for attempt := 1; attempt <= maxAttempts; attempt++ {+ done, err := downloadOnce(url, tmp, label)+ if err == nil && done {+ lastErr = nil+ break+ }+ lastErr = err+ fmt.Fprintf(os.Stderr, "\n %s interrupted (attempt %d/%d): %v — resuming\n", label, attempt, maxAttempts, err)+ time.Sleep(time.Duration(attempt) * time.Second)+ }+ if lastErr != nil {+ os.Remove(tmp)+ return lastErr+ }+ return os.Rename(tmp, dest)+}++func download(url, dest, wantSHA, label string) error {+ if err := fetch(url, dest, label); err != nil {+ return err+ }+ if wantSHA == "" {+ fmt.Fprintf(os.Stderr, " (no pinned checksum for %s — skipped verification)\n", label)+ return nil+ }+ got, err := sha256file(dest)+ if err != nil {+ return err+ }+ if got != wantSHA {+ os.Remove(dest)+ return fmt.Errorf("checksum mismatch for %s: got %s want %s", label, got, wantSHA)+ }+ return nil+}++// verifyDownload checks a downloaded archive against an upstream sha256sum-style+// manifest. Fails closed on a mismatch (removes the file); fails open with a+// warning when the manifest or its entry can't be fetched, so a transient+// network issue on the sums file doesn't block provisioning.+func verifyDownload(archive, sumsURL, name string) error {+ resp, err := downloadHTTPClient().Get(sumsURL)+ if err != nil {+ fmt.Fprintf(os.Stderr, " (could not fetch checksums for %s — skipped verification)\n", name)+ return nil+ }+ defer resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ fmt.Fprintf(os.Stderr, " (no checksums for %s — skipped verification)\n", name)+ return nil+ }+ data, err := io.ReadAll(io.LimitReader(resp.Body, 4<<20))+ if err != nil {+ return err+ }+ want := ParseChecksums(data)[name]+ if want == "" {+ fmt.Fprintf(os.Stderr, " (no checksum entry for %s — skipped verification)\n", name)+ return nil+ }+ got, err := sha256file(archive)+ if err != nil {+ return err+ }+ if got != want {+ os.Remove(archive)+ return fmt.Errorf("checksum mismatch for %s: got %s want %s", name, got, want)+ }+ return nil+}++func downloadOnce(url, tmp, label string) (bool, error) {+ var start int64+ if fi, err := os.Stat(tmp); err == nil {+ start = fi.Size()+ }++ req, err := http.NewRequest(http.MethodGet, url, nil)+ if err != nil {+ return false, err+ }+ if start > 0 {+ req.Header.Set("Range", fmt.Sprintf("bytes=%d-", start))+ }+ resp, err := downloadHTTPClient().Do(req)+ if err != nil {+ return false, err+ }+ defer resp.Body.Close()++ switch resp.StatusCode {+ case http.StatusRequestedRangeNotSatisfiable:+ return true, nil // already complete on disk+ case http.StatusOK:+ if start > 0 { // server ignored Range — restart cleanly+ os.Truncate(tmp, 0)+ start = 0+ }+ case http.StatusPartialContent:+ default:+ return false, fmt.Errorf("HTTP %d", resp.StatusCode)+ }++ out, err := os.OpenFile(tmp, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)+ if err != nil {+ return false, err+ }+ defer out.Close()++ pw := &progress{label: label, total: start + resp.ContentLength, written: start}+ _, copyErr := io.Copy(io.MultiWriter(out, pw), resp.Body)+ if copyErr != nil {+ return false, copyErr+ }+ pw.done()+ return true, nil+}++// symlinkTargetInside reports whether a symlink at linkPath pointing to linkname+// resolves within root (root has a trailing separator). Absolute targets and+// any path that escapes via .. are rejected — this is the symlink half of the+// zip-slip defense, since the path guard alone only validates the link's own+// location, not where it points.+func symlinkTargetInside(linkPath, linkname, root string) bool {+ if filepath.IsAbs(linkname) {+ return false+ }+ resolved := filepath.Clean(filepath.Join(filepath.Dir(linkPath), linkname))+ return strings.HasPrefix(resolved+string(os.PathSeparator), root)+}++// ParseChecksums parses sha256sum-style "<hex> <name>" lines into a name->hash+// map, keyed by basename so it matches the asset filenames consumers request.+func ParseChecksums(data []byte) map[string]string {+ out := map[string]string{}+ for _, line := range strings.Split(string(data), "\n") {+ fields := strings.Fields(line)+ if len(fields) < 2 {+ continue+ }+ out[filepath.Base(fields[len(fields)-1])] = strings.ToLower(fields[0])+ }+ return out+}++// Sha256File returns the lowercase hex SHA-256 of the file at path.+func Sha256File(path string) (string, error) { return sha256file(path) }++func sha256file(path string) (string, error) {+ f, err := os.Open(path)+ if err != nil {+ return "", err+ }+ defer f.Close()+ h := sha256.New()+ if _, err := io.Copy(h, f); err != nil {+ return "", err+ }+ return hex.EncodeToString(h.Sum(nil)), nil+}++type ffArchive struct {+ URL string+ Bins []string+}++// Static ffmpeg sources are not yet pinned by checksum (upstream "latest" URLs);+// they get our own pinned builds once podcli hosts releases.+var ffmpegSpecs = map[string][]ffArchive{+ "darwin/amd64": {+ {URL: "https://evermeet.cx/ffmpeg/getrelease/ffmpeg/zip", Bins: []string{"ffmpeg"}},+ {URL: "https://evermeet.cx/ffmpeg/getrelease/ffprobe/zip", Bins: []string{"ffprobe"}},+ },+ "darwin/arm64": {+ {URL: "https://evermeet.cx/ffmpeg/getrelease/ffmpeg/zip", Bins: []string{"ffmpeg"}},+ {URL: "https://evermeet.cx/ffmpeg/getrelease/ffprobe/zip", Bins: []string{"ffprobe"}},+ },+ "linux/amd64": {+ {URL: "https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz", Bins: []string{"ffmpeg", "ffprobe"}},+ },+ "linux/arm64": {+ {URL: "https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-arm64-static.tar.xz", Bins: []string{"ffmpeg", "ffprobe"}},+ },+ "windows/amd64": {+ {URL: "https://github.com/BtbN/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip", Bins: []string{"ffmpeg.exe", "ffprobe.exe"}},+ },+}++func exeSuffix() string {+ if runtime.GOOS == "windows" {+ return ".exe"+ }+ return ""+}++const podcliRepo = "nmbrthirteen/podcli"++func WhisperCLIBin() string {+ return filepath.Join(paths.RuntimeDir(), "whisper", "whisper-cli"+exeSuffix())+}++func latestReleaseAssets() (map[string]string, error) {+ req, _ := http.NewRequest(http.MethodGet, "https://api.github.com/repos/"+podcliRepo+"/releases/latest", nil)+ req.Header.Set("Accept", "application/vnd.github+json")+ resp, err := releaseHTTPClient().Do(req)+ if err != nil {+ return nil, err+ }+ defer resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ return nil, fmt.Errorf("no published release (HTTP %d)", resp.StatusCode)+ }+ var rel struct {+ Assets []struct {+ Name string `json:"name"`+ URL string `json:"browser_download_url"`+ } `json:"assets"`+ }+ if err := json.NewDecoder(resp.Body).Decode(&rel); err != nil {+ return nil, err+ }+ out := make(map[string]string, len(rel.Assets))+ for _, a := range rel.Assets {+ out[a.Name] = a.URL+ }+ return out, nil+}++func latestReleaseAssetURL(name string) (string, error) {+ assets, err := latestReleaseAssets()+ if err != nil {+ return "", err+ }+ if u, ok := assets[name]; ok {+ return u, nil+ }+ return "", fmt.Errorf("asset %s not in latest release", name)+}++// allowedReleaseHost pins binary downloads to GitHub's own hosts so a redirect+// can't divert a download to an attacker-controlled host.+func allowedReleaseHost(h string) bool {+ h = strings.ToLower(h)+ switch h {+ case "github.com", "api.github.com", "objects.githubusercontent.com", "codeload.github.com":+ return true+ }+ return strings.HasSuffix(h, ".githubusercontent.com")+}++func releaseHTTPClient() *http.Client {+ return &http.Client{+ Transport: &http.Transport{ResponseHeaderTimeout: 30 * time.Second},+ CheckRedirect: func(req *http.Request, via []*http.Request) error {+ if len(via) >= 10 {+ return fmt.Errorf("too many redirects")+ }+ if !allowedReleaseHost(req.URL.Hostname()) {+ return fmt.Errorf("refusing redirect to untrusted host %q", req.URL.Hostname())+ }+ return nil+ },+ }+}++// allowedDownloadHost pins large-binary/model downloads to their known source+// hosts and CDNs. Several of these payloads (Node, CPython, ffmpeg) are not+// checksum-verified, so blocking redirects to unknown hosts is the main defense+// against a diverted download. Initial request URLs are hardcoded (trusted);+// this only constrains where a redirect may land.+func allowedDownloadHost(h string) bool {+ h = strings.ToLower(h)+ for _, base := range []string{+ "github.com", // release assets+ "githubusercontent.com", // objects.* / release-assets.* CDN+ "huggingface.co", // whisper.cpp models + cdn-lfs*.huggingface.co+ "nodejs.org", // hermetic Node+ "evermeet.cx", // macOS ffmpeg+ "johnvansickle.com", // linux ffmpeg+ } {+ if h == base || strings.HasSuffix(h, "."+base) {+ return true+ }+ }+ return false+}++func downloadHTTPClient() *http.Client {+ return &http.Client{+ Transport: &http.Transport{ResponseHeaderTimeout: 60 * time.Second},+ CheckRedirect: func(req *http.Request, via []*http.Request) error {+ if len(via) >= 10 {+ return fmt.Errorf("too many redirects")+ }+ if !allowedDownloadHost(req.URL.Hostname()) {+ return fmt.Errorf("refusing redirect to untrusted host %q", req.URL.Hostname())+ }+ return nil+ },+ }+}++func httpGetBytes(url string) ([]byte, error) {+ resp, err := releaseHTTPClient().Get(url)+ if err != nil {+ return nil, err+ }+ defer resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ return nil, fmt.Errorf("HTTP %d for %s", resp.StatusCode, url)+ }+ return io.ReadAll(io.LimitReader(resp.Body, 1<<20))+}++// verifyReleaseAsset checks the file at path against the release's checksums.txt.+// It fails closed on a real checksum mismatch, but fails open (with a warning)+// when checksums.txt or the asset's entry is absent — so a release published+// before checksum manifests, or a CI hiccup, never bricks an install.+func verifyReleaseAsset(assets map[string]string, assetName, path string) error {+ sumsURL, ok := assets["checksums.txt"]+ if !ok {+ fmt.Fprintf(os.Stderr, " (no checksums.txt in release — skipped verification of %s)\n", assetName)+ return nil+ }+ data, err := httpGetBytes(sumsURL)+ if err != nil {+ fmt.Fprintf(os.Stderr, " (could not fetch checksums.txt: %v — skipped verification of %s)\n", err, assetName)+ return nil+ }+ want, ok := ParseChecksums(data)[assetName]+ if !ok {+ fmt.Fprintf(os.Stderr, " (no checksum entry for %s — skipped verification)\n", assetName)+ return nil+ }+ got, err := sha256file(path)+ if err != nil {+ return err+ }+ if !strings.EqualFold(got, want) {+ os.Remove(path)+ return fmt.Errorf("checksum mismatch for %s: got %s want %s", assetName, got, want)+ }+ return nil+}++func EnsureWhisperCpp() (string, error) {+ bin := WhisperCLIBin()+ if have(bin) {+ return bin, nil+ }+ name := fmt.Sprintf("whisper-cli-%s-%s%s", runtime.GOOS, runtime.GOARCH, exeSuffix())+ assets, err := latestReleaseAssets()+ if err != nil {+ return "", err+ }+ url, ok := assets[name]+ if !ok {+ return "", fmt.Errorf("asset %s not in latest release", name)+ }+ if err := os.MkdirAll(filepath.Dir(bin), 0o755); err != nil {+ return "", err+ }+ if err := fetch(url, bin, "whisper-cli"); err != nil {+ return "", err+ }+ if err := verifyReleaseAsset(assets, name, bin); err != nil {+ return "", err+ }+ if runtime.GOOS != "windows" {+ os.Chmod(bin, 0o755)+ }+ return bin, nil+}++func FFmpegBin() string {+ return filepath.Join(paths.RuntimeDir(), "ffmpeg", "ffmpeg"+exeSuffix())+}++func EnsureFFmpeg() (string, error) {+ bin := FFmpegBin()+ if have(bin) {+ return bin, nil+ }+ specs, ok := ffmpegSpecs[runtime.GOOS+"/"+runtime.GOARCH]+ if !ok {+ return "", fmt.Errorf("no ffmpeg build for %s/%s", runtime.GOOS, runtime.GOARCH)+ }+ dir := filepath.Join(paths.RuntimeDir(), "ffmpeg")+ if err := os.MkdirAll(dir, 0o755); err != nil {+ return "", err+ }+ for _, a := range specs {+ sum := sha256.Sum256([]byte(a.URL))+ archive := filepath.Join(os.TempDir(), "podcli-ff-"+hex.EncodeToString(sum[:8]))+ if err := fetch(a.URL, archive, "ffmpeg-archive"); err != nil {+ return "", err+ }+ err := extractBins(archive, a.Bins, dir)+ os.Remove(archive)+ if err != nil {+ return "", err+ }+ }+ if !have(bin) {+ return "", fmt.Errorf("ffmpeg missing after extraction in %s", dir)+ }+ return bin, nil+}++func extractBins(archive string, bins []string, dest string) error {+ f, err := os.Open(archive)+ if err != nil {+ return err+ }+ magic := make([]byte, 6)+ io.ReadFull(f, magic)+ f.Close()+ switch {+ case magic[0] == 'P' && magic[1] == 'K':+ return extractZip(archive, bins, dest)+ case magic[0] == 0xFD && string(magic[1:6]) == "7zXZ\x00":+ return extractTarXz(archive, bins, dest)+ default:+ return fmt.Errorf("unrecognized archive format")+ }+}++func wantSet(bins []string) map[string]bool {+ m := make(map[string]bool, len(bins))+ for _, b := range bins {+ m[b] = true+ }+ return m+}++func extractZip(archive string, bins []string, dest string) error {+ zr, err := zip.OpenReader(archive)+ if err != nil {+ return err+ }+ defer zr.Close()+ want := wantSet(bins)+ for _, zf := range zr.File {+ if zf.FileInfo().IsDir() || !want[filepath.Base(zf.Name)] {+ continue+ }+ rc, err := zf.Open()+ if err != nil {+ return err+ }+ err = writeBin(rc, filepath.Join(dest, filepath.Base(zf.Name)))+ rc.Close()+ if err != nil {+ return err+ }+ }+ return nil+}++func extractTarXz(archive string, bins []string, dest string) error {+ tmp, err := os.MkdirTemp("", "podcli-ffx-")+ if err != nil {+ return err+ }+ defer os.RemoveAll(tmp)+ listing, err := exec.Command("tar", "-tf", archive).Output()+ if err != nil {+ return fmt.Errorf("tar list (is tar installed?): %w", err)+ }+ for _, name := range strings.Split(string(listing), "\n") {+ name = strings.TrimSpace(name)+ if name == "" {+ continue+ }+ clean := filepath.Clean(name)+ if filepath.IsAbs(clean) || clean == ".." || strings.HasPrefix(clean, ".."+string(os.PathSeparator)) {+ return fmt.Errorf("refusing archive with unsafe path: %q", name)+ }+ }+ cmd := exec.Command("tar", "-xf", archive, "-C", tmp)+ cmd.Stderr = os.Stderr+ if err := cmd.Run(); err != nil {+ return fmt.Errorf("tar extract (is tar installed?): %w", err)+ }+ want := wantSet(bins)+ return filepath.WalkDir(tmp, func(p string, d os.DirEntry, err error) error {+ if err != nil || d.IsDir() || !want[filepath.Base(p)] {+ return err+ }+ in, err := os.Open(p)+ if err != nil {+ return err+ }+ defer in.Close()+ return writeBin(in, filepath.Join(dest, filepath.Base(p)))+ })+}++func writeBin(r io.Reader, dest string) error {+ out, err := os.OpenFile(dest, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0o755)+ if err != nil {+ return err+ }+ defer out.Close()+ _, err = io.Copy(out, r)+ return err+}++var pyTriples = map[string]string{+ "darwin/amd64": "x86_64-apple-darwin",+ "darwin/arm64": "aarch64-apple-darwin",+ "linux/amd64": "x86_64-unknown-linux-gnu",+ "linux/arm64": "aarch64-unknown-linux-gnu",+ "windows/amd64": "x86_64-pc-windows-msvc",+}++func PythonBin() string {+ if runtime.GOOS == "windows" {+ return filepath.Join(paths.RuntimeDir(), "python", "python.exe")+ }+ return filepath.Join(paths.RuntimeDir(), "python", "bin", "python3")+}++// pythonAssetURL resolves a python-build-standalone install_only tarball for+// this platform via the GitHub latest-release API, so it tracks upstream+// without a hardcoded version that rots.+func pythonAssetURL() (url, name, sumsURL string, err error) {+ triple, ok := pyTriples[runtime.GOOS+"/"+runtime.GOARCH]+ if !ok {+ return "", "", "", fmt.Errorf("no python build for %s/%s", runtime.GOOS, runtime.GOARCH)+ }+ req, _ := http.NewRequest(http.MethodGet, "https://api.github.com/repos/astral-sh/python-build-standalone/releases/latest", nil)+ req.Header.Set("Accept", "application/vnd.github+json")+ resp, err := releaseHTTPClient().Do(req)+ if err != nil {+ return "", "", "", err+ }+ defer resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ return "", "", "", fmt.Errorf("github api: HTTP %d", resp.StatusCode)+ }+ var rel struct {+ Assets []struct {+ Name string `json:"name"`+ URL string `json:"browser_download_url"`+ } `json:"assets"`+ }+ if err := json.NewDecoder(resp.Body).Decode(&rel); err != nil {+ return "", "", "", err+ }+ sums := ""+ for _, a := range rel.Assets {+ if a.Name == "SHA256SUMS" {+ sums = a.URL+ break+ }+ }+ match := func(prefer string) (string, string) {+ for _, a := range rel.Assets {+ if strings.Contains(a.Name, triple) && strings.HasSuffix(a.Name, "install_only.tar.gz") && strings.Contains(a.Name, prefer) {+ return a.URL, a.Name+ }+ }+ return "", ""+ }+ if u, n := match("cpython-3.12."); u != "" {+ return u, n, sums, nil+ }+ if u, n := match("cpython-3."); u != "" {+ return u, n, sums, nil+ }+ return "", "", "", fmt.Errorf("no install_only python asset for %s", triple)+}++func EnsurePython(requirements string) (string, error) {+ bin := PythonBin()+ if !have(bin) {+ url, name, sumsURL, err := pythonAssetURL()+ if err != nil {+ return "", err+ }+ sum := sha256.Sum256([]byte(url))+ archive := filepath.Join(os.TempDir(), "podcli-py-"+hex.EncodeToString(sum[:8])+".tar.gz")+ if err := fetch(url, archive, "cpython"); err != nil {+ return "", err+ }+ if sumsURL != "" {+ if err := verifyDownload(archive, sumsURL, name); err != nil {+ return "", err+ }+ }+ err = extractTarGz(archive, paths.RuntimeDir())+ os.Remove(archive)+ if err != nil {+ return "", err+ }+ if !have(bin) {+ return "", fmt.Errorf("python missing after extraction")+ }+ }+ if requirements != "" {+ if err := pipInstall(bin, requirements); err != nil {+ return "", err+ }+ }+ return bin, nil+}++func pipInstall(pybin, requirements string) error {+ fmt.Fprintf(os.Stderr, " installing python deps (%s) — pulls ~80MB, first run takes a minute\n", filepath.Base(requirements))+ cmd := exec.Command(pybin, "-m", "pip", "install", "--disable-pip-version-check", "--progress-bar=on", "-r", requirements)+ cmd.Stdout, cmd.Stderr = os.Stderr, os.Stderr+ cmd.Env = append(os.Environ(), "PYTHONUNBUFFERED=1")+ return cmd.Run()+}++func extractTarGz(archive, dest string) error {+ f, err := os.Open(archive)+ if err != nil {+ return err+ }+ defer f.Close()+ gz, err := gzip.NewReader(f)+ if err != nil {+ return err+ }+ defer gz.Close()+ tr := tar.NewReader(gz)+ root := filepath.Clean(dest) + string(os.PathSeparator)+ for {+ h, err := tr.Next()+ if err == io.EOF {+ break+ }+ if err != nil {+ return err+ }+ target := filepath.Join(dest, h.Name)+ if !strings.HasPrefix(target, root) {+ return fmt.Errorf("unsafe path in archive: %s", h.Name)+ }+ switch h.Typeflag {+ case tar.TypeDir:+ if err := os.MkdirAll(target, 0o755); err != nil {+ return err+ }+ case tar.TypeReg:+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ out, err := os.OpenFile(target, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, os.FileMode(h.Mode))+ if err != nil {+ return err+ }+ _, err = io.Copy(out, tr)+ out.Close()+ if err != nil {+ return err+ }+ case tar.TypeSymlink:+ if !symlinkTargetInside(target, h.Linkname, root) {+ return fmt.Errorf("unsafe symlink %s -> %s in archive", h.Name, h.Linkname)+ }+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ os.Remove(target)+ if err := os.Symlink(h.Linkname, target); err != nil {+ return err+ }+ case tar.TypeLink:+ linkTarget := filepath.Join(dest, h.Linkname)+ if !strings.HasPrefix(linkTarget, root) {+ return fmt.Errorf("unsafe hardlink %s -> %s in archive", h.Name, h.Linkname)+ }+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ os.Remove(target)+ if err := os.Link(linkTarget, target); err != nil {+ return err+ }+ }+ }+ return nil+}++type progress struct {+ label string+ total int64+ written int64+ lastPct int+ lastTick time.Time+}++func (p *progress) Write(b []byte) (int, error) {+ n := len(b)+ p.written += int64(n)+ now := time.Now()+ if now.Sub(p.lastTick) < 200*time.Millisecond {+ return n, nil+ }+ p.lastTick = now+ if p.total > 0 {+ pct := int(p.written * 100 / p.total)+ if pct != p.lastPct {+ p.lastPct = pct+ fmt.Fprintf(os.Stderr, "\r fetching %s ... %d%% (%d/%d MB)", p.label, pct, p.written>>20, p.total>>20)+ }+ } else {+ fmt.Fprintf(os.Stderr, "\r fetching %s ... %d MB", p.label, p.written>>20)+ }+ return n, nil+}++func (p *progress) done() {+ fmt.Fprintf(os.Stderr, "\r fetching %s ... done (%d MB)%s\n", p.label, p.written>>20, " ")+}diff --git a/cli/internal/provision/provision_manual_test.go b/cli/internal/provision/provision_manual_test.gonew file mode 100644index 0000000..d44c3a9--- /dev/null+++ b/cli/internal/provision/provision_manual_test.go@@ -0,0 +1,47 @@+package provision++import (+ "os"+ "os/exec"+ "strings"+ "testing"++ "podcli/internal/paths"+)++// Guarded network integration check (set PODCLI_MANUAL=1). Validates GitHub-API+// asset resolution, tar.gz extraction (incl. symlinks), and that the provisioned+// interpreter runs. PODCLI_PY_ARCHIVE=<file> extracts a local tarball instead of+// downloading; PODCLI_REQS also tests pip install.+func TestEnsurePythonManual(t *testing.T) {+ if os.Getenv("PODCLI_MANUAL") == "" {+ t.Skip("set PODCLI_MANUAL=1 to run")+ }+ if arc := os.Getenv("PODCLI_PY_ARCHIVE"); arc != "" {+ if err := os.MkdirAll(paths.RuntimeDir(), 0o755); err != nil {+ t.Fatal(err)+ }+ if err := extractTarGz(arc, paths.RuntimeDir()); err != nil {+ t.Fatal(err)+ }+ assertRuns(t, PythonBin())+ return+ }+ bin, err := EnsurePython(os.Getenv("PODCLI_REQS"))+ if err != nil {+ t.Fatal(err)+ }+ assertRuns(t, bin)+}++func assertRuns(t *testing.T, bin string) {+ out, err := exec.Command(bin, "--version").CombinedOutput()+ if err != nil {+ t.Fatal(err)+ }+ v := strings.TrimSpace(string(out))+ t.Logf("python %s -> %s", bin, v)+ if !strings.HasPrefix(v, "Python 3.") {+ t.Fatalf("unexpected version: %q", v)+ }+}diff --git a/cli/internal/provision/redirect_test.go b/cli/internal/provision/redirect_test.gonew file mode 100644index 0000000..8e03c9e--- /dev/null+++ b/cli/internal/provision/redirect_test.go@@ -0,0 +1,45 @@+package provision++import (+ "net/http"+ "net/http/httptest"+ "testing"+)++func TestAllowedDownloadHost(t *testing.T) {+ allow := []string{+ "github.com", "objects.githubusercontent.com", "release-assets.githubusercontent.com",+ "huggingface.co", "cdn-lfs.huggingface.co", "cdn-lfs-us-1.huggingface.co",+ "nodejs.org", "evermeet.cx", "johnvansickle.com", "www.johnvansickle.com",+ }+ for _, h := range allow {+ if !allowedDownloadHost(h) {+ t.Errorf("expected %q to be allowed", h)+ }+ }+ // Suffix spoofing must not pass: a trusted name as a left-label is not enough.+ deny := []string{+ "evil.com", "github.com.evil.com", "huggingface.co.attacker.net",+ "githubusercontent.com.evil.com", "127.0.0.1", "",+ }+ for _, h := range deny {+ if allowedDownloadHost(h) {+ t.Errorf("expected %q to be denied", h)+ }+ }+}++func TestDownloadClientRefusesUntrustedRedirect(t *testing.T) {+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ http.Redirect(w, r, "https://attacker.example/payload", http.StatusFound)+ }))+ defer srv.Close()++ resp, err := downloadHTTPClient().Get(srv.URL)+ if err == nil {+ if resp != nil {+ resp.Body.Close()+ }+ t.Fatal("expected redirect to an untrusted host to be refused")+ }+}diff --git a/cli/internal/provision/security_test.go b/cli/internal/provision/security_test.gonew file mode 100644index 0000000..7a747c1--- /dev/null+++ b/cli/internal/provision/security_test.go@@ -0,0 +1,96 @@+package provision++import (+ "archive/tar"+ "bytes"+ "compress/gzip"+ "os"+ "path/filepath"+ "runtime"+ "testing"+)++func TestParseChecksums(t *testing.T) {+ in := []byte("abc123 podcli-darwin-arm64\n" ++ "DEADBEEF ./dist/whisper-cli-linux-amd64\n" ++ "\n" ++ "malformed-line\n")+ got := ParseChecksums(in)+ if got["podcli-darwin-arm64"] != "abc123" {+ t.Fatalf("podcli hash = %q", got["podcli-darwin-arm64"])+ }+ if got["whisper-cli-linux-amd64"] != "deadbeef" {+ t.Fatalf("whisper hash = %q (want lowercased, basename-keyed)", got["whisper-cli-linux-amd64"])+ }+ if len(got) != 2 {+ t.Fatalf("expected 2 entries, got %d: %v", len(got), got)+ }+}++func TestSymlinkTargetInside(t *testing.T) {+ root := filepath.Clean("/tmp/dest") + string(os.PathSeparator)+ cases := []struct {+ name string+ linkPath string+ linkname string+ ok bool+ }{+ {"relative inside", "/tmp/dest/a/link", "../b", true},+ {"to root", "/tmp/dest/link", ".", true},+ {"escape via dotdot", "/tmp/dest/link", "../../etc/passwd", false},+ {"absolute", "/tmp/dest/link", "/etc/passwd", false},+ {"deep escape", "/tmp/dest/a/b/link", "../../../outside", false},+ }+ for _, c := range cases {+ if got := symlinkTargetInside(c.linkPath, c.linkname, root); got != c.ok {+ t.Errorf("%s: symlinkTargetInside(%q,%q)=%v want %v", c.name, c.linkPath, c.linkname, got, c.ok)+ }+ }+}++// TestExtractTarGzRejectsEscapingSymlink builds an in-memory tarball with a+// symlink that escapes the destination and confirms extraction refuses it.+func TestExtractTarGzRejectsEscapingSymlink(t *testing.T) {+ if runtime.GOOS == "windows" {+ t.Skip("symlink semantics differ on Windows")+ }+ var buf bytes.Buffer+ gz := gzip.NewWriter(&buf)+ tw := tar.NewWriter(gz)+ if err := tw.WriteHeader(&tar.Header{Name: "evil", Typeflag: tar.TypeSymlink, Linkname: "../../../../etc", Mode: 0o777}); err != nil {+ t.Fatal(err)+ }+ tw.Close()+ gz.Close()++ dir := t.TempDir()+ archive := filepath.Join(dir, "evil.tar.gz")+ if err := os.WriteFile(archive, buf.Bytes(), 0o644); err != nil {+ t.Fatal(err)+ }+ dest := filepath.Join(dir, "out")+ if err := extractTarGz(archive, dest); err == nil {+ t.Fatal("expected extractTarGz to reject escaping symlink, got nil error")+ }+}++func TestExtractTarGzRejectsEscapingHardlink(t *testing.T) {+ var buf bytes.Buffer+ gz := gzip.NewWriter(&buf)+ tw := tar.NewWriter(gz)+ if err := tw.WriteHeader(&tar.Header{Name: "evil", Typeflag: tar.TypeLink, Linkname: "../../../../etc/passwd", Mode: 0o644}); err != nil {+ t.Fatal(err)+ }+ tw.Close()+ gz.Close()++ dir := t.TempDir()+ archive := filepath.Join(dir, "evil.tar.gz")+ if err := os.WriteFile(archive, buf.Bytes(), 0o644); err != nil {+ t.Fatal(err)+ }+ dest := filepath.Join(dir, "out")+ if err := extractTarGz(archive, dest); err == nil {+ t.Fatal("expected extractTarGz to reject escaping hardlink, got nil error")+ }+}diff --git a/cli/internal/provision/studio.go b/cli/internal/provision/studio.gonew file mode 100644index 0000000..f11a40e--- /dev/null+++ b/cli/internal/provision/studio.go@@ -0,0 +1,312 @@+package provision++import (+ "archive/tar"+ "archive/zip"+ "compress/gzip"+ "fmt"+ "io"+ "os"+ "os/exec"+ "path/filepath"+ "runtime"+ "strings"++ "podcli/internal/paths"+)++// nodeVersion is the hermetic Node.js used to serve the studio web UI. Node only+// runs the bundled server (rendering is delegated to the Python backend), so any+// recent LTS works; pin for reproducibility.+const nodeVersion = "20.18.1"++var nodeTriples = map[string]string{+ "darwin/amd64": "darwin-x64",+ "darwin/arm64": "darwin-arm64",+ "linux/amd64": "linux-x64",+ "linux/arm64": "linux-arm64",+ "windows/amd64": "win-x64",+}++func NodeDir() string { return filepath.Join(paths.RuntimeDir(), "node") }++func NodeBin() string {+ if runtime.GOOS == "windows" {+ return filepath.Join(NodeDir(), "node.exe")+ }+ return filepath.Join(NodeDir(), "bin", "node")+}++func StudioDir() string { return filepath.Join(paths.RuntimeDir(), "studio") }+func StudioServer() string { return filepath.Join(StudioDir(), "web-server.mjs") }++func EnsureNode() (string, error) {+ bin := NodeBin()+ if have(bin) {+ return bin, nil+ }+ triple, ok := nodeTriples[runtime.GOOS+"/"+runtime.GOARCH]+ if !ok {+ return "", fmt.Errorf("no node build for %s/%s", runtime.GOOS, runtime.GOARCH)+ }+ ext := "tar.gz"+ if runtime.GOOS == "windows" {+ ext = "zip"+ }+ base := fmt.Sprintf("node-v%s-%s", nodeVersion, triple)+ url := fmt.Sprintf("https://nodejs.org/dist/v%s/%s.%s", nodeVersion, base, ext)+ archive := filepath.Join(os.TempDir(), "podcli-"+base+"."+ext)+ if err := fetch(url, archive, "node"); err != nil {+ return "", err+ }+ defer os.Remove(archive)+ if err := verifyDownload(archive, fmt.Sprintf("https://nodejs.org/dist/v%s/SHASUMS256.txt", nodeVersion), base+"."+ext); err != nil {+ return "", err+ }+ if err := os.RemoveAll(NodeDir()); err != nil {+ return "", err+ }+ var err error+ if ext == "zip" {+ err = extractZipStrip1(archive, NodeDir())+ } else {+ err = extractTarGzStrip1(archive, NodeDir())+ }+ if err != nil {+ return "", err+ }+ if runtime.GOOS != "windows" {+ os.Chmod(bin, 0o755)+ }+ if !have(bin) {+ return "", fmt.Errorf("node missing after extraction in %s", NodeDir())+ }+ return bin, nil+}++func RemotionDir() string { return filepath.Join(paths.RuntimeDir(), "remotion") }+func RemotionScript() string { return filepath.Join(RemotionDir(), "render.mjs") }++// EnsureRemotion fetches the per-platform Remotion render bundle (remotion/ ++// a production node_modules with native bindings) and extracts it into the+// runtime dir so remotion/ and node_modules/ sit beside backend/. Per-platform+// because @rspack and the Remotion compositor ship native binaries.+func EnsureRemotion() (string, error) {+ if have(RemotionScript()) {+ return RemotionDir(), nil+ }+ name := fmt.Sprintf("remotion-bundle-%s-%s.tar.gz", runtime.GOOS, runtime.GOARCH)+ assets, err := latestReleaseAssets()+ if err != nil {+ return "", err+ }+ url, ok := assets[name]+ if !ok {+ return "", fmt.Errorf("asset %s not in latest release", name)+ }+ archive := filepath.Join(os.TempDir(), "podcli-"+name)+ if err := fetch(url, archive, "remotion"); err != nil {+ return "", err+ }+ defer os.Remove(archive)+ if err := verifyReleaseAsset(assets, name, archive); err != nil {+ return "", err+ }+ if err := os.RemoveAll(RemotionDir()); err != nil {+ return "", err+ }+ if err := os.RemoveAll(filepath.Join(paths.RuntimeDir(), "node_modules")); err != nil {+ return "", err+ }+ if err := extractTarGz(archive, paths.RuntimeDir()); err != nil {+ return "", err+ }+ if !have(RemotionScript()) {+ return "", fmt.Errorf("remotion render.mjs missing after extraction")+ }+ return RemotionDir(), nil+}++// PrewarmRemotion compiles the project-independent composition bundle once into+// the managed dir so the first caption render skips the ~20s bundling step.+func PrewarmRemotion() error {+ node := NodeBin()+ if !have(node) || !have(RemotionScript()) {+ return fmt.Errorf("node/remotion not provisioned")+ }+ cmd := exec.Command(node, RemotionScript(), "--prebundle")+ cmd.Dir = RemotionDir()+ cmd.Env = append(os.Environ(), "PODCLI_CACHE_DIR="+filepath.Join(RemotionDir(), ".bundle-cache"))+ cmd.Stderr = os.Stderr+ return cmd.Run()+}++// EnsureRemotionBrowser pre-downloads the Chrome Headless Shell the Remotion+// renderer needs, so the first caption render works offline. Best-effort: if it+// fails, the renderer downloads the browser on first use.+func EnsureRemotionBrowser() error {+ node := NodeBin()+ if !have(node) || !have(RemotionScript()) {+ return fmt.Errorf("node/remotion not provisioned")+ }+ cmd := exec.Command(node, "-e",+ "import('@remotion/renderer').then(r=>r.ensureBrowser()).then(()=>process.exit(0)).catch(e=>{console.error(String(e));process.exit(1)})")+ cmd.Dir = RemotionDir()+ cmd.Stderr = os.Stderr+ return cmd.Run()+}++// EnsureStudio fetches the prebuilt, platform-independent studio bundle (server ++// SPA) from the latest release into StudioDir.+func EnsureStudio() (string, error) {+ server := StudioServer()+ if have(server) {+ return StudioDir(), nil+ }+ assets, err := latestReleaseAssets()+ if err != nil {+ return "", err+ }+ url, ok := assets["studio-bundle.tar.gz"]+ if !ok {+ return "", fmt.Errorf("asset studio-bundle.tar.gz not in latest release")+ }+ archive := filepath.Join(os.TempDir(), "podcli-studio-bundle.tar.gz")+ if err := fetch(url, archive, "studio"); err != nil {+ return "", err+ }+ defer os.Remove(archive)+ if err := verifyReleaseAsset(assets, "studio-bundle.tar.gz", archive); err != nil {+ return "", err+ }+ if err := os.RemoveAll(StudioDir()); err != nil {+ return "", err+ }+ if err := os.MkdirAll(StudioDir(), 0o755); err != nil {+ return "", err+ }+ if err := extractTarGz(archive, StudioDir()); err != nil {+ return "", err+ }+ if !have(server) {+ return "", fmt.Errorf("studio server missing after extraction in %s", StudioDir())+ }+ return StudioDir(), nil+}++// strip1 drops the leading path component (node tarballs/zips nest everything+// under node-vX-os-arch/).+func strip1(name string) string {+ name = filepath.ToSlash(name)+ if i := strings.IndexByte(name, '/'); i >= 0 {+ return name[i+1:]+ }+ return ""+}++func extractTarGzStrip1(archive, dest string) error {+ f, err := os.Open(archive)+ if err != nil {+ return err+ }+ defer f.Close()+ gz, err := gzip.NewReader(f)+ if err != nil {+ return err+ }+ defer gz.Close()+ tr := tar.NewReader(gz)+ root := filepath.Clean(dest) + string(os.PathSeparator)+ for {+ h, err := tr.Next()+ if err == io.EOF {+ break+ }+ if err != nil {+ return err+ }+ rel := strip1(h.Name)+ if rel == "" {+ continue+ }+ target := filepath.Join(dest, rel)+ if !strings.HasPrefix(target, root) {+ return fmt.Errorf("unsafe path in archive: %s", h.Name)+ }+ switch h.Typeflag {+ case tar.TypeDir:+ if err := os.MkdirAll(target, 0o755); err != nil {+ return err+ }+ case tar.TypeReg:+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ out, err := os.OpenFile(target, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, os.FileMode(h.Mode))+ if err != nil {+ return err+ }+ _, err = io.Copy(out, tr)+ out.Close()+ if err != nil {+ return err+ }+ case tar.TypeSymlink:+ if !symlinkTargetInside(target, h.Linkname, root) {+ return fmt.Errorf("unsafe symlink %s -> %s in archive", h.Name, h.Linkname)+ }+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ os.Remove(target)+ if err := os.Symlink(h.Linkname, target); err != nil {+ return err+ }+ }+ }+ return nil+}++func extractZipStrip1(archive, dest string) error {+ zr, err := zip.OpenReader(archive)+ if err != nil {+ return err+ }+ defer zr.Close()+ root := filepath.Clean(dest) + string(os.PathSeparator)+ for _, zf := range zr.File {+ rel := strip1(zf.Name)+ if rel == "" {+ continue+ }+ target := filepath.Join(dest, rel)+ if !strings.HasPrefix(target, root) {+ return fmt.Errorf("unsafe path in archive: %s", zf.Name)+ }+ if zf.FileInfo().IsDir() {+ if err := os.MkdirAll(target, 0o755); err != nil {+ return err+ }+ continue+ }+ if err := os.MkdirAll(filepath.Dir(target), 0o755); err != nil {+ return err+ }+ rc, err := zf.Open()+ if err != nil {+ return err+ }+ out, err := os.OpenFile(target, os.O_CREATE|os.O_TRUNC|os.O_WRONLY, zf.Mode())+ if err != nil {+ rc.Close()+ return err+ }+ _, err = io.Copy(out, rc)+ out.Close()+ rc.Close()+ if err != nil {+ return err+ }+ }+ return nil+}diff --git a/cli/internal/update/update.go b/cli/internal/update/update.gonew file mode 100644index 0000000..4a3fb7f--- /dev/null+++ b/cli/internal/update/update.go@@ -0,0 +1,253 @@+// Package update checks GitHub Releases for a newer podcli and (once releases+// publish per-platform binaries) applies it. For now a manual update points the+// user at their package manager, matching the npm/bun reinstall fallback.+package update++import (+ "encoding/json"+ "fmt"+ "io"+ "net/http"+ "os"+ "path/filepath"+ "runtime"+ "strconv"+ "strings"+ "time"++ "podcli/internal/config"+ "podcli/internal/paths"+ "podcli/internal/provision"+)++const repo = "nmbrthirteen/podcli"++func exeExt() string {+ if runtime.GOOS == "windows" {+ return ".exe"+ }+ return ""+}++// managedBin is the binary the npm shim and direct installs both exec, so+// replacing it updates podcli regardless of how it was installed.+func managedBin() string {+ return filepath.Join(paths.BinDir(), "podcli"+exeExt())+}++func assetName() string {+ return fmt.Sprintf("podcli-%s-%s%s", runtime.GOOS, runtime.GOARCH, exeExt())+}++func assetURL(tag string) string {+ return fmt.Sprintf("https://github.com/%s/releases/download/v%s/%s", repo, tag, assetName())+}++func checksumsURL(tag string) string {+ return fmt.Sprintf("https://github.com/%s/releases/download/v%s/checksums.txt", repo, tag)+}++func allowedHost(h string) bool {+ h = strings.ToLower(h)+ switch h {+ case "github.com", "api.github.com", "objects.githubusercontent.com", "codeload.github.com":+ return true+ }+ return strings.HasSuffix(h, ".githubusercontent.com")+}++func guardedClient() *http.Client {+ return &http.Client{+ Transport: &http.Transport{ResponseHeaderTimeout: 30 * time.Second},+ CheckRedirect: func(req *http.Request, via []*http.Request) error {+ if len(via) >= 10 {+ return fmt.Errorf("too many redirects")+ }+ if !allowedHost(req.URL.Hostname()) {+ return fmt.Errorf("refusing redirect to untrusted host %q", req.URL.Hostname())+ }+ return nil+ },+ }+}++func latestTag(timeout time.Duration) (string, error) {+ client := &http.Client{Timeout: timeout}+ req, _ := http.NewRequest(http.MethodGet, "https://api.github.com/repos/"+repo+"/releases/latest", nil)+ req.Header.Set("Accept", "application/vnd.github+json")+ resp, err := client.Do(req)+ if err != nil {+ return "", err+ }+ defer resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ return "", fmt.Errorf("no published release (HTTP %d)", resp.StatusCode)+ }+ var rel struct {+ Tag string `json:"tag_name"`+ }+ if err := json.NewDecoder(resp.Body).Decode(&rel); err != nil {+ return "", err+ }+ return strings.TrimPrefix(rel.Tag, "v"), nil+}++func parseVer(v string) [3]int {+ v = strings.TrimPrefix(v, "v")+ v = strings.SplitN(v, "-", 2)[0] // drop -dev / pre-release+ var out [3]int+ for i, p := range strings.SplitN(v, ".", 3) {+ out[i], _ = strconv.Atoi(p)+ }+ return out+}++func newer(remote, current string) bool {+ r, c := parseVer(remote), parseVer(current)+ for i := 0; i < 3; i++ {+ if r[i] != c[i] {+ return r[i] > c[i]+ }+ }+ return false+}++// NotifyIfOutdated prints a one-line notice when a newer release exists. Fast,+// silent on any error, and respects the off-switch.+func NotifyIfOutdated(current string) {+ if !config.AutoUpdate() {+ return+ }+ tag, err := latestTag(1500 * time.Millisecond)+ if err != nil {+ return+ }+ if newer(tag, current) {+ fmt.Fprintf(os.Stderr, " ↑ podcli %s available (you have %s) — run `podcli update`\n", tag, current)+ }+}++func Run(current string) int {+ tag, err := latestTag(10 * time.Second)+ if err != nil {+ fmt.Fprintf(os.Stderr, "podcli: update check failed: %v\n", err)+ return 1+ }+ if !newer(tag, current) {+ fmt.Printf("podcli %s is up to date.\n", current)+ return 0+ }+ fmt.Printf("Updating podcli %s → %s ...\n", current, tag)+ if err := apply(tag); err != nil {+ fmt.Fprintf(os.Stderr, "podcli: self-update failed (%v).\n", err)+ fmt.Fprintln(os.Stderr, "Reinstall via your package manager: npm i -g podcli (or: bun add -g podcli)")+ return 1+ }+ fmt.Printf("Updated to podcli %s.\n", tag)+ return 0+}++// apply downloads the release binary for this platform and swaps the managed+// binary atomically.+func apply(tag string) error {+ dest := managedBin()+ if err := os.MkdirAll(filepath.Dir(dest), 0o755); err != nil {+ return err+ }+ staged := dest + ".new"+ if err := downloadFile(assetURL(tag), staged); err != nil {+ return err+ }+ if err := verifyStaged(tag, staged); err != nil {+ os.Remove(staged)+ return err+ }+ if runtime.GOOS != "windows" {+ if err := os.Chmod(staged, 0o755); err != nil {+ return err+ }+ }+ return swap(staged, dest)+}++// verifyStaged checks the downloaded binary against the release's checksums.txt.+// Fails closed on a mismatch; fails open (warning) only when checksums.txt is+// absent, so an older release without a manifest still updates.+func verifyStaged(tag, staged string) error {+ resp, err := guardedClient().Get(checksumsURL(tag))+ if err != nil {+ return err+ }+ defer resp.Body.Close()+ if resp.StatusCode == http.StatusNotFound {+ fmt.Fprintln(os.Stderr, " (no checksums.txt in release — skipped verification)")+ return nil+ }+ if resp.StatusCode != http.StatusOK {+ return fmt.Errorf("HTTP %d fetching checksums.txt", resp.StatusCode)+ }+ data, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))+ if err != nil {+ return err+ }+ want, ok := provision.ParseChecksums(data)[assetName()]+ if !ok {+ fmt.Fprintf(os.Stderr, " (no checksum entry for %s — skipped verification)\n", assetName())+ return nil+ }+ got, err := provision.Sha256File(staged)+ if err != nil {+ return err+ }+ if !strings.EqualFold(got, want) {+ return fmt.Errorf("checksum mismatch: got %s want %s", got, want)+ }+ return nil+}++// swap replaces dest with staged. On Windows a running .exe can't be overwritten,+// so the old binary is moved aside first; on Unix the rename is atomic.+func swap(staged, dest string) error {+ if runtime.GOOS == "windows" {+ old := dest + ".old"+ os.Remove(old)+ moved := false+ if _, err := os.Stat(dest); err == nil {+ if err := os.Rename(dest, old); err != nil {+ return err+ }+ moved = true+ }+ if err := os.Rename(staged, dest); err != nil {+ if moved {+ os.Rename(old, dest) // restore the original so the CLI isn't bricked+ }+ return err+ }+ return nil+ }+ return os.Rename(staged, dest)+}++func downloadFile(url, dest string) error {+ resp, err := guardedClient().Get(url)+ if err != nil {+ return err+ }+ defer resp.Body.Close()+ if resp.StatusCode != http.StatusOK {+ return fmt.Errorf("HTTP %d for %s", resp.StatusCode, url)+ }+ tmp := dest + ".part"+ f, err := os.Create(tmp)+ if err != nil {+ return err+ }+ _, err = io.Copy(f, resp.Body)+ f.Close()+ if err != nil {+ os.Remove(tmp)+ return err+ }+ return os.Rename(tmp, dest)+}diff --git a/cli/internal/update/update_test.go b/cli/internal/update/update_test.gonew file mode 100644index 0000000..7be03c2--- /dev/null+++ b/cli/internal/update/update_test.go@@ -0,0 +1,45 @@+package update++import (+ "os"+ "path/filepath"+ "testing"+)++func TestSwapReplacesBinary(t *testing.T) {+ dir := t.TempDir()+ dest := filepath.Join(dir, "podcli")+ if err := os.WriteFile(dest, []byte("OLD"), 0o755); err != nil {+ t.Fatal(err)+ }+ staged := dest + ".new"+ if err := os.WriteFile(staged, []byte("NEW"), 0o755); err != nil {+ t.Fatal(err)+ }+ if err := swap(staged, dest); err != nil {+ t.Fatal(err)+ }+ b, _ := os.ReadFile(dest)+ if string(b) != "NEW" {+ t.Fatalf("swap left %q, want NEW", b)+ }+}++func TestNewer(t *testing.T) {+ cases := []struct {+ remote, current string+ want bool+ }{+ {"2.0.1", "2.0.0", true},+ {"2.0.0", "2.0.0", false},+ {"1.9.9", "2.0.0", false},+ {"2.1.0", "2.0.9", true},+ {"v2.0.1", "2.0.0", true},+ {"3.0.0", "2.9.9", true},+ }+ for _, c := range cases {+ if got := newer(c.remote, c.current); got != c.want {+ t.Errorf("newer(%q, %q) = %v, want %v", c.remote, c.current, got, c.want)+ }+ }+}diff --git a/cli/main.go b/cli/main.gonew file mode 100644index 0000000..6d24257--- /dev/null+++ b/cli/main.go@@ -0,0 +1,415 @@+// podcli — native launcher. Reserved verbs are handled here; everything else+// routes to the Python engine.+package main++import (+ "fmt"+ "os"+ "os/exec"+ "path/filepath"+ "strings"++ "podcli/internal/backend"+ "podcli/internal/config"+ "podcli/internal/engine"+ "podcli/internal/paths"+ "podcli/internal/podstack"+ "podcli/internal/provision"+ "podcli/internal/update"+)++// Version is set at build time via -ldflags "-X main.Version=...".+var Version = "2.0.0-dev"++func main() {+ args := os.Args[1:]+ if len(args) == 0 {+ os.Exit(runEngine(args)) // backend's branded interactive menu+ }++ switch args[0] {+ case "version", "--version", "-v":+ fmt.Printf("podcli %s\n", Version)+ case "doctor":+ doctor()+ case "update":+ os.Exit(update.Run(Version))+ case "setup":+ os.Exit(setup(args[1:]))+ case "mcp":+ if len(args) >= 2 && args[1] == "install" {+ os.Exit(mcpInstall())+ }+ code, err := engine.RunMCP()+ if err != nil {+ fmt.Fprintln(os.Stderr, "podcli:", err)+ }+ os.Exit(code)+ case "config":+ if len(args) >= 2 && (args[1] == "get" || args[1] == "set") {+ os.Exit(configCmd(args[1:]))+ }+ os.Exit(runEngine(args)) // status/export/import/use → Python+ case "help", "--help", "-h":+ printHelp()+ default:+ if podstack.IsCommand(args[0]) {+ os.Exit(podstack.Run(args[0], args[1:]))+ }+ os.Exit(runEngine(args))+ }+}++// wantsRuntime gates first-run auto-provisioning: only commands that need the+// backend trigger the download, not lightweight ones like config.+func wantsRuntime(args []string) bool {+ if len(args) == 0 {+ return true+ }+ switch args[0] {+ case "process", "transcribe", "studio", "auto":+ return true+ }+ return false+}++// ensureRuntime self-provisions on first run so `podcli` works without a separate+// `podcli setup`. Not called on the mcp path, whose stdout is the JSON-RPC channel.+func ensureRuntime() {+ if _, ok := engine.BackendRoot(); ok {+ return+ }+ fmt.Fprintln(os.Stderr, "First run — setting up podcli (one-time download)…")+ setup(nil)+}++func runEngine(args []string) int {+ update.NotifyIfOutdated(Version)+ if wantsRuntime(args) {+ ensureRuntime()+ }+ if transcribeEngine(args) == "whispercpp" {+ model, err := provision.EnsureModel(transcribeModel(args))+ if err != nil {+ fmt.Fprintln(os.Stderr, "podcli: provisioning model:", err)+ return 1+ }+ os.Setenv("PODCLI_ENGINE", "whispercpp")+ os.Setenv("PODCLI_WHISPERCPP_MODEL", model)+ }+ code, err := engine.Run(args)+ if err != nil {+ fmt.Fprintln(os.Stderr, "podcli:", err)+ return 1+ }+ return code+}++func transcribeModel(args []string) string {+ for _, arg := range args {+ if arg == "--fast" {+ return "tiny.en"+ }+ }+ return "base"+}++func configCmd(args []string) int {+ switch {+ case args[0] == "get" && len(args) == 2:+ v, err := config.Get(args[1])+ if err != nil {+ fmt.Fprintln(os.Stderr, "podcli:", err)+ return 1+ }+ fmt.Println(v)+ case args[0] == "set" && len(args) == 3:+ if err := config.Set(args[1], args[2]); err != nil {+ fmt.Fprintln(os.Stderr, "podcli:", err)+ return 1+ }+ fmt.Printf("%s = %s\n", args[1], args[2])+ default:+ fmt.Fprintln(os.Stderr, "usage: podcli config get <key> | config set <key> <value>")+ return 2+ }+ return 0+}++// transcribeEngine resolves which engine a run will use, honoring --engine,+// PODCLI_ENGINE, then defaulting to whisper.cpp on a hermetic Python (which has+// no openai-whisper). Covers every entry point that can transcribe: the no-arg+// interactive menu, process, studio, and transcribe.+func transcribeEngine(args []string) string {+ cmd := ""+ if len(args) > 0 {+ cmd = args[0]+ }+ switch cmd {+ case "", "process", "studio", "transcribe":+ default:+ return ""+ }+ sel := strings.ToLower(os.Getenv("PODCLI_ENGINE"))+ for i, a := range args {+ if a == "--engine" && i+1 < len(args) {+ sel = strings.ToLower(args[i+1])+ } else if strings.HasPrefix(a, "--engine=") {+ sel = strings.ToLower(strings.TrimPrefix(a, "--engine="))+ }+ }+ if sel == "" && engine.IsHermeticPython() {+ sel = "whispercpp"+ }+ switch sel {+ case "whispercpp", "whisper-cpp", "whisper.cpp", "cpp":+ return "whispercpp"+ }+ return sel+}++func setup(args []string) int {+ size := "base"+ vad := false+ for i := 0; i < len(args); i++ {+ switch args[i] {+ case "--model":+ if i+1 < len(args) {+ size = args[i+1]+ i+++ }+ case "--vad":+ vad = true+ }+ }+ fmt.Printf("Provisioning into %s\n", paths.Home())+ p, err := provision.EnsureModel(size)+ if err != nil {+ fmt.Fprintln(os.Stderr, "podcli: setup:", err)+ return 1+ }+ fmt.Printf(" model: %s\n", p)+ if vad {+ vp, err := provision.EnsureVADModel()+ if err != nil {+ fmt.Fprintln(os.Stderr, "podcli: setup:", err)+ return 1+ }+ fmt.Printf(" vad: %s\n", vp)+ }+ if fp, err := provision.EnsureFFmpeg(); err != nil {+ fmt.Fprintf(os.Stderr, " ffmpeg: skipped (%v) — backend will use PATH ffmpeg\n", err)+ } else {+ fmt.Printf(" ffmpeg: %s\n", fp)+ }+ backendDir := filepath.Join(paths.RuntimeDir(), "backend")+ if err := backend.Extract(backendDir); err != nil {+ fmt.Fprintf(os.Stderr, " backend: skipped (%v) — falling back to repo/PODCLI_BACKEND\n", err)+ backendDir, _ = engine.BackendRoot()+ } else {+ fmt.Printf(" backend: %s\n", backendDir)+ }+ if backendDir != "" {+ reqs := filepath.Join(backendDir, "requirements-runtime.txt")+ if pb, err := provision.EnsurePython(reqs); err != nil {+ fmt.Fprintf(os.Stderr, " python: skipped (%v) — using dev venv / system python\n", err)+ } else {+ fmt.Printf(" python: %s\n", pb)+ }+ }+ if wc, err := provision.EnsureWhisperCpp(); err != nil {+ fmt.Fprintf(os.Stderr, " whisper: skipped (%v) — backend will use PATH whisper-cli\n", err)+ } else {+ fmt.Printf(" whisper: %s\n", wc)+ }+ if nb, err := provision.EnsureNode(); err != nil {+ fmt.Fprintf(os.Stderr, " node: skipped (%v) — Web UI will use system Node if present\n", err)+ } else {+ fmt.Printf(" node: %s\n", nb)+ }+ if sd, err := provision.EnsureStudio(); err != nil {+ fmt.Fprintf(os.Stderr, " studio: skipped (%v) — Web UI needs a published release\n", err)+ } else {+ fmt.Printf(" studio: %s\n", sd)+ }+ if rd, err := provision.EnsureRemotion(); err != nil {+ fmt.Fprintf(os.Stderr, " remotion: skipped (%v) — captions/thumbnails need a published release\n", err)+ } else {+ fmt.Printf(" remotion: %s\n", rd)+ if err := provision.PrewarmRemotion(); err != nil {+ fmt.Fprintf(os.Stderr, " bundle: deferred to first render (%v)\n", err)+ } else {+ fmt.Printf(" bundle: prebuilt\n")+ }+ if err := provision.EnsureRemotionBrowser(); err != nil {+ fmt.Fprintf(os.Stderr, " browser: deferred to first render (%v)\n", err)+ } else {+ fmt.Printf(" browser: ready\n")+ }+ }+ if engine.MCPServer() != "" {+ if mcpRegisteredToSelf() {+ fmt.Printf(" mcp: already registered\n")+ } else if err := registerMCPServer(); err != nil {+ fmt.Fprintf(os.Stderr, " mcp: not registered (%v) — run `podcli mcp install`\n", err)+ } else {+ fmt.Printf(" mcp: registered with Claude Code\n")+ }+ }+ fmt.Println("Done.")+ return 0+}++// registerMCPServer points Claude Code at this binary's `mcp` command. Remove+// first so re-runs refresh a stale path and stay idempotent.+func registerMCPServer() error {+ claude, err := exec.LookPath("claude")+ if err != nil {+ return fmt.Errorf("Claude Code CLI not found on PATH")+ }+ self, err := os.Executable()+ if err != nil {+ return err+ }+ exec.Command(claude, "mcp", "remove", "podcli").Run()+ if out, err := exec.Command(claude, "mcp", "add", "podcli", "--", self, "mcp").CombinedOutput(); err != nil {+ return fmt.Errorf("%v: %s", err, strings.TrimSpace(string(out)))+ }+ return nil+}++func mcpRegisteredToSelf() bool {+ claude, err := exec.LookPath("claude")+ if err != nil {+ return false+ }+ self, err := os.Executable()+ if err != nil {+ return false+ }+ out, err := exec.Command(claude, "mcp", "get", "podcli").CombinedOutput()+ return err == nil && strings.Contains(string(out), self)+}++func mcpInstall() int {+ if err := registerMCPServer(); err != nil {+ self, _ := os.Executable()+ fmt.Fprintf(os.Stderr, "podcli: %v\n", err)+ fmt.Fprintf(os.Stderr, "Register manually: claude mcp add podcli -- %s mcp\n", self)+ return 1+ }+ fmt.Println("Registered podcli MCP server with Claude Code.")+ return 0+}++func doctor() {+ fmt.Printf("podcli %s\n\n", Version)+ fmt.Println("Paths")+ fmt.Printf(" home: %s\n", paths.Home())+ fmt.Printf(" runtime: %s\n", paths.RuntimeDir())+ fmt.Printf(" models: %s\n", paths.ModelsDir())+ fmt.Printf(" presets/knowledge/assets/history/cache: %s (global — follow you everywhere)\n", paths.Home())+ if cwd, err := os.Getwd(); err == nil {+ fmt.Printf(" clips: %s (rendered into your working directory)\n", filepath.Join(cwd, "podcli-clips"))+ }+ fmt.Println("\nEngine resolution")+ if root, ok := engine.BackendRoot(); ok {+ fmt.Printf(" backend: %s\n", root)+ } else {+ fmt.Printf(" backend: NOT FOUND (set PODCLI_BACKEND or run inside the repo)\n")+ }+ fmt.Printf(" python: %s\n", engine.Python())+ if ff := engine.FFmpeg(); ff != "" {+ fmt.Printf(" ffmpeg: %s (hermetic)\n", ff)+ } else {+ fmt.Printf(" ffmpeg: PATH fallback (not yet hermetic)\n")+ }+ if fp := engine.FFprobe(); fp != "" {+ fmt.Printf(" ffprobe: %s (hermetic)\n", fp)+ }+ if wc := engine.WhisperCLI(); wc != "" {+ fmt.Printf(" whisper: %s (hermetic)\n", wc)+ } else {+ fmt.Printf(" whisper: PATH fallback (install whisper-cli, or provisioned once hosted)\n")+ }+ if nd := engine.Node(); nd != "" {+ fmt.Printf(" node: %s (hermetic)\n", nd)+ } else {+ fmt.Printf(" node: PATH fallback (Web UI uses system Node, or run `podcli setup`)\n")+ }+ if ss := engine.StudioServer(); ss != "" {+ fmt.Printf(" studio: %s\n", ss)+ } else {+ fmt.Printf(" studio: not provisioned (Web UI needs a published release)\n")+ }+ if ms := engine.MCPServer(); ms != "" {+ fmt.Printf(" mcp: %s\n", ms)+ } else {+ fmt.Printf(" mcp: not provisioned (needs a published release)\n")+ }+ if rs := provision.RemotionScript(); fileExists(rs) {+ fmt.Printf(" remotion: %s\n", rs)+ } else {+ fmt.Printf(" remotion: not provisioned (captions/thumbnails need a published release)\n")+ }+ fmt.Println("\nModels")+ fmt.Printf(" base: %s\n", presence(provision.ModelPath("base")))+ fmt.Printf(" vad: %s\n", presence(provision.VADModelPath()))+}++func presence(p string) string {+ if fi, err := os.Stat(p); err == nil && fi.Size() > 0 {+ return fmt.Sprintf("%s (%s)", p, humanBytes(fi.Size()))+ }+ return "not provisioned — run `podcli setup`"+}++func fileExists(p string) bool {+ _, err := os.Stat(p)+ return err == nil+}++func humanBytes(n int64) string {+ switch {+ case n >= 1<<20:+ return fmt.Sprintf("%d MB", n>>20)+ case n >= 1<<10:+ return fmt.Sprintf("%d KB", n>>10)+ default:+ return fmt.Sprintf("%d B", n)+ }+}++func printHelp() {+ fmt.Printf(`podcli %s — AI podcast clip generator++Usage:+ podcli <command> [args]++Engine commands (routed to the processing backend):+ process <video> Transcribe a video and export short-form clips+ studio <video> Cut a fragment + intro/outro bookends+ clips Browse and edit saved clips+ thumbnails Generate thumbnails+ knowledge | presets | assets | youtube | config | cache | info++PodStack commands (run inside Claude Code / Codex):+ auto <video> One-verb pipeline: drop footage, get rendered clips+ generate-titles | generate-descriptions | plan-thumbnails | plan-episode+ process-transcript | produce-shorts | review-content | publish-checklist+ retro-episode Add --codex / --claude to pick the agent++Launcher commands:+ doctor Show resolved paths, interpreter, backend, ffmpeg, models+ version Print version+ update Check for and apply a newer release+ setup [--model base] [--vad]+ Provision runtimes + models into the managed dir+ mcp Run the MCP server (stdio) for Claude/Codex+ mcp install Register the MCP server with Claude Code+ config set update.auto off Disable auto-update (also: PODCLI_NO_UPDATE=1)+ config get update.auto++Run a command with --help for its options.+`, Version)+}diff --git a/cli/main_test.go b/cli/main_test.gonew file mode 100644index 0000000..d3a1b74--- /dev/null+++ b/cli/main_test.go@@ -0,0 +1,12 @@+package main++import "testing"++func TestTranscribeModel(t *testing.T) {+ if got := transcribeModel([]string{"process", "episode.mp4"}); got != "base" {+ t.Fatalf("default model = %q, want base", got)+ }+ if got := transcribeModel([]string{"process", "episode.mp4", "--fast"}); got != "tiny.en" {+ t.Fatalf("fast model = %q, want tiny.en", got)+ }+}diff --git a/install.ps1 b/install.ps1new file mode 100644index 0000000..d89591e--- /dev/null+++ b/install.ps1@@ -0,0 +1,47 @@+# podcli installer for Windows — downloads the prebuilt native binary (no Go,+# Node, Python, or ffmpeg needed; the binary provisions those on first run).+# Usage: irm https://raw.githubusercontent.com/nmbrthirteen/podcli/main/install.ps1 | iex+$ErrorActionPreference = 'Stop'+$repo = 'nmbrthirteen/podcli'+$target = 'windows-amd64'++$homeDir = Join-Path $env:LOCALAPPDATA 'podcli'+$binDir = Join-Path $homeDir 'bin'+New-Item -ItemType Directory -Force -Path $binDir | Out-Null++$version = $env:PODCLI_VERSION+if (-not $version) {+ $rel = Invoke-RestMethod "https://api.github.com/repos/$repo/releases/latest" -Headers @{ 'User-Agent' = 'podcli-install' }+ $version = $rel.tag_name -replace '^v', ''+}++$asset = "podcli-$target.exe"+$base = "https://github.com/$repo/releases/download/v$version"+Write-Host "Installing podcli v$version ($target)…"++$dest = Join-Path $binDir 'podcli.exe'+Invoke-WebRequest "$base/$asset" -OutFile $dest -UseBasicParsing++try {+ $sums = (Invoke-WebRequest "$base/checksums.txt" -UseBasicParsing).Content+ $want = $sums -split "`n" |+ Where-Object { $_ -match ([regex]::Escape($asset) + '\s*$') } |+ ForEach-Object { ($_ -split '\s+')[0] } | Select-Object -First 1+ if ($want) {+ $got = (Get-FileHash $dest -Algorithm SHA256).Hash.ToLower()+ if ($got -ne $want.ToLower()) { Remove-Item $dest -Force; throw "checksum mismatch (got $got want $want)" }+ Write-Host " checksum verified"+ } else {+ Write-Host " no checksum entry for $asset — skipped verification"+ }+} catch {+ Write-Host " checksum verification skipped: $($_.Exception.Message)"+}++$userPath = [Environment]::GetEnvironmentVariable('Path', 'User')+if ($userPath -notlike "*$binDir*") {+ [Environment]::SetEnvironmentVariable('Path', "$binDir;$userPath", 'User')+ Write-Host " added to PATH (restart your terminal)"+}+Write-Host ""+Write-Host "Done — run: podcli"diff --git a/install.sh b/install.shnew file mode 100755index 0000000..4b2a2db--- /dev/null+++ b/install.sh@@ -0,0 +1,77 @@+#!/bin/sh+# podcli installer — downloads the prebuilt native binary (no Go, Node, Python,+# or ffmpeg needed; the binary provisions those itself on first run).+# Usage: curl -fsSL https://raw.githubusercontent.com/nmbrthirteen/podcli/main/install.sh | sh+set -eu++REPO="nmbrthirteen/podcli"+err() { echo "podcli-install: $*" >&2; exit 1; }+command -v curl >/dev/null 2>&1 || err "curl is required"++os=$(uname -s 2>/dev/null || echo unknown)+arch=$(uname -m 2>/dev/null || echo unknown)+case "$os" in+ Darwin) goos=darwin; home_dir="$HOME/Library/Application Support/podcli" ;;+ Linux) goos=linux; home_dir="${XDG_DATA_HOME:-$HOME/.local/share}/podcli" ;;+ *) err "unsupported OS: $os (on Windows use install.ps1)" ;;+esac+case "$arch" in+ x86_64|amd64) goarch=amd64 ;;+ arm64|aarch64) goarch=arm64 ;;+ *) err "unsupported architecture: $arch" ;;+esac+target="${goos}-${goarch}"+bin_dir="$home_dir/bin"+mkdir -p "$bin_dir"++version="${PODCLI_VERSION:-}"+if [ -z "$version" ]; then+ version=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" \+ | sed -n 's/.*"tag_name":[ ]*"v\{0,1\}\([^"]*\)".*/\1/p' | head -1)+ [ -n "$version" ] || err "could not resolve the latest release"+fi++asset="podcli-${target}"+base="https://github.com/$REPO/releases/download/v${version}"+echo "Installing podcli v${version} (${target})…"++tmp=$(mktemp -d)+trap 'rm -rf "$tmp"' EXIT+curl -fSL --proto '=https' --tlsv1.2 "$base/$asset" -o "$tmp/$asset" || err "download failed"++if curl -fsSL "$base/checksums.txt" -o "$tmp/sums" 2>/dev/null; then+ want=$(grep "[ /]$asset\$" "$tmp/sums" | awk '{print $1}' | head -1)+ if [ -n "$want" ]; then+ if command -v sha256sum >/dev/null 2>&1; then+ got=$(sha256sum "$tmp/$asset" | awk '{print $1}')+ else+ got=$(shasum -a 256 "$tmp/$asset" | awk '{print $1}')+ fi+ [ "$got" = "$want" ] || err "checksum mismatch (got $got want $want)"+ echo " checksum verified"+ else+ echo " no checksum entry for $asset — skipped verification" >&2+ fi+else+ echo " no checksums.txt in release — skipped verification" >&2+fi++cp "$tmp/$asset" "$bin_dir/podcli"+chmod 0755 "$bin_dir/podcli"+echo " installed: $bin_dir/podcli"++linked=""+for d in /usr/local/bin "$HOME/.local/bin"; do+ if [ -d "$d" ] && [ -w "$d" ]; then+ ln -sf "$bin_dir/podcli" "$d/podcli" 2>/dev/null && { linked="$d/podcli"; break; }+ fi+done++echo+if [ -n "$linked" ]; then+ echo "Done — run: podcli"+else+ echo "Done. Add podcli to your PATH:"+ echo " export PATH=\"$bin_dir:\$PATH\""+ echo "Then run: podcli"+fidiff --git a/npm/README.md b/npm/README.mdnew file mode 100644index 0000000..5cfa5c1--- /dev/null+++ b/npm/README.md@@ -0,0 +1,18 @@+# podcli++AI podcast clip generator — transcribe, find viral moments, and export vertical+short-form clips with burned captions.++```sh+npm i -g podcli # or: bun add -g podcli+podcli setup # one-time: provisions a self-contained runtime+podcli process episode.mp4 --top 5+```++Installing this package downloads the native `podcli` binary for your platform+into a managed directory; the `podcli` command is a thin shim that runs it. The+binary is self-contained — `podcli setup` provisions its own Python, ffmpeg,+whisper.cpp, and models, so there is nothing else to install.++Updates: `podcli update` checks for a newer release. Disable auto-update checks+with `podcli config set update.auto off` (or `PODCLI_NO_UPDATE=1`).diff --git a/npm/bin/podcli.js b/npm/bin/podcli.jsnew file mode 100644index 0000000..afc9bbd--- /dev/null+++ b/npm/bin/podcli.js@@ -0,0 +1,24 @@+#!/usr/bin/env node+'use strict';++const fs = require('fs');+const { spawnSync } = require('child_process');+const { binPath, ensure } = require('../scripts/install');++(async () => {+ let bin = binPath();+ if (!fs.existsSync(bin)) {+ try {+ bin = await ensure();+ } catch (e) {+ console.error('podcli: failed to fetch native binary:', e.message);+ process.exit(1);+ }+ }+ const r = spawnSync(bin, process.argv.slice(2), { stdio: 'inherit' });+ if (r.error) {+ console.error('podcli:', r.error.message);+ process.exit(1);+ }+ process.exit(r.status == null ? 1 : r.status);+})();diff --git a/npm/package.json b/npm/package.jsonnew file mode 100644index 0000000..318a39c--- /dev/null+++ b/npm/package.json@@ -0,0 +1,31 @@+{+ "name": "podcli",+ "version": "2.0.0",+ "description": "AI podcast clip generator — native CLI. Transcribe, find viral moments, export vertical clips with burned captions.",+ "bin": {+ "podcli": "bin/podcli.js"+ },+ "scripts": {+ "postinstall": "node scripts/install.js"+ },+ "files": [+ "bin/",+ "scripts/"+ ],+ "engines": {+ "node": ">=16"+ },+ "license": "AGPL-3.0-only",+ "repository": {+ "type": "git",+ "url": "https://github.com/nmbrthirteen/podcli.git"+ },+ "keywords": [+ "podcast",+ "clips",+ "shorts",+ "whisper",+ "ffmpeg",+ "cli"+ ]+}diff --git a/npm/scripts/install.js b/npm/scripts/install.jsnew file mode 100644index 0000000..e67a0f4--- /dev/null+++ b/npm/scripts/install.js@@ -0,0 +1,157 @@+'use strict';++// Fetches the native podcli binary for this platform into the managed dir. Runs+// on npm/bun postinstall, and again lazily from the bin shim if the binary is+// missing. PODCLI_BINARY_SRC=<path> copies a local binary instead of downloading+// (used for testing and from the release build before publishing).++const os = require('os');+const fs = require('fs');+const path = require('path');+const https = require('https');+const crypto = require('crypto');+const { version } = require('../package.json');++const REPO = 'nmbrthirteen/podcli';++function allowedHost(h) {+ h = String(h).toLowerCase();+ if (['github.com', 'api.github.com', 'objects.githubusercontent.com', 'codeload.github.com'].includes(h)) return true;+ return h.endsWith('.githubusercontent.com');+}++const TARGETS = {+ 'darwin-x64': 'darwin-amd64',+ 'darwin-arm64': 'darwin-arm64',+ 'linux-x64': 'linux-amd64',+ 'linux-arm64': 'linux-arm64',+ 'win32-x64': 'windows-amd64',+};++function defaultHome() {+ const h = os.homedir();+ if (process.platform === 'darwin') return path.join(h, 'Library', 'Application Support', 'podcli');+ if (process.platform === 'win32') return path.join(process.env.LOCALAPPDATA || path.join(h, 'AppData', 'Local'), 'podcli');+ return process.env.XDG_DATA_HOME ? path.join(process.env.XDG_DATA_HOME, 'podcli') : path.join(h, '.local', 'share', 'podcli');+}++function binPath() {+ const home = process.env.PODCLI_HOME || defaultHome();+ return path.join(home, 'bin', process.platform === 'win32' ? 'podcli.exe' : 'podcli');+}++function target() {+ const key = `${process.platform}-${process.arch}`;+ const t = TARGETS[key];+ if (!t) throw new Error(`unsupported platform ${key}`);+ return t;+}++function download(url, dest, redirects) {+ redirects = redirects || 0;+ return new Promise((resolve, reject) => {+ let host;+ try { host = new URL(url).hostname; } catch (e) { return reject(e); }+ if (!allowedHost(host)) return reject(new Error(`refusing to download from untrusted host ${host}`));+ https+ .get(url, { headers: { 'User-Agent': 'podcli-install' } }, (res) => {+ if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirects < 6) {+ res.resume();+ return resolve(download(res.headers.location, dest, redirects + 1));+ }+ if (res.statusCode !== 200) {+ res.resume();+ return reject(new Error(`HTTP ${res.statusCode} for ${url}`));+ }+ const tmp = dest + '.part';+ const file = fs.createWriteStream(tmp);+ res.pipe(file);+ file.on('finish', () => file.close(() => {+ fs.renameSync(tmp, dest);+ resolve();+ }));+ file.on('error', reject);+ })+ .on('error', reject);+ });+}++function fetchText(url, redirects) {+ redirects = redirects || 0;+ return new Promise((resolve, reject) => {+ let host;+ try { host = new URL(url).hostname; } catch (e) { return reject(e); }+ if (!allowedHost(host)) return reject(new Error(`refusing to fetch from untrusted host ${host}`));+ https+ .get(url, { headers: { 'User-Agent': 'podcli-install' } }, (res) => {+ if ([301, 302, 307, 308].includes(res.statusCode) && res.headers.location && redirects < 6) {+ res.resume();+ return resolve(fetchText(res.headers.location, redirects + 1));+ }+ if (res.statusCode === 404) { res.resume(); return resolve(null); }+ if (res.statusCode !== 200) { res.resume(); return reject(new Error(`HTTP ${res.statusCode} for ${url}`)); }+ let body = '';+ res.setEncoding('utf8');+ res.on('data', (c) => { body += c; });+ res.on('end', () => resolve(body));+ })+ .on('error', reject);+ });+}++function parseChecksums(text) {+ const out = {};+ for (const line of text.split('\n')) {+ const f = line.trim().split(/\s+/);+ if (f.length < 2) continue;+ out[path.basename(f[f.length - 1])] = f[0].toLowerCase();+ }+ return out;+}++function sha256(file) {+ return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');+}++// verify checks dest against checksums.txt for this release. Fails closed on a+// mismatch; fails open (warning) when the manifest or entry is absent.+async function verify(dest, name, tag) {+ const text = await fetchText(`https://github.com/${REPO}/releases/download/v${tag}/checksums.txt`);+ if (!text) { console.error('podcli: no checksums.txt in release — skipped verification'); return; }+ const want = parseChecksums(text)[name];+ if (!want) { console.error(`podcli: no checksum entry for ${name} — skipped verification`); return; }+ const got = sha256(dest);+ if (got !== want) {+ fs.rmSync(dest, { force: true });+ throw new Error(`checksum mismatch for ${name}: got ${got} want ${want}`);+ }+}++async function ensure() {+ const dest = binPath();+ fs.mkdirSync(path.dirname(dest), { recursive: true });+ const src = process.env.PODCLI_BINARY_SRC;+ if (src) {+ fs.copyFileSync(src, dest);+ } else {+ const ext = process.platform === 'win32' ? '.exe' : '';+ const name = `podcli-${target()}${ext}`;+ const url = `https://github.com/${REPO}/releases/download/v${version}/${name}`;+ await download(url, dest);+ await verify(dest, name, version);+ }+ if (process.platform !== 'win32') fs.chmodSync(dest, 0o755);+ return dest;+}++module.exports = { binPath, ensure };++if (require.main === module) {+ ensure()+ .then((d) => console.log(`podcli binary ready: ${d}`))+ .catch((e) => {+ // Don't hard-fail the install — the bin shim fetches it on first run.+ console.error(`podcli: could not pre-fetch binary (${e.message}); it will be fetched on first run.`);+ process.exit(0);+ });+}diff --git a/package.json b/package.jsonindex fde9871..9164b4e 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "podcli",- "version": "1.1.0",+ "version": "2.0.0","description": "AI-powered podcast clip generator for TikTok/YouTube Shorts. Transcribe, find viral moments, export vertical clips with burned captions.","type": "module","license": "AGPL-3.0-only",diff --git a/plans/native-cli.md b/plans/native-cli.mdnew file mode 100644index 0000000..32b9d0e--- /dev/null+++ b/plans/native-cli.md@@ -0,0 +1,137 @@+# podcli → Native CLI (codex-style)++> Goal: turn podcli from a git-clone + `setup.sh` + venv/npm hybrid into a **native CLI you install once and that auto-updates** — like `openai/codex`. Users run `npm i -g podcli` (or `bun add -g podcli`) and `podcli process video.mp4` just works, everywhere, with no Python/Node/FFmpeg setup.++## North star++```+npm i -g podcli # or: bun add -g podcli+podcli process pod.mp4 --top 5+ → first run: silently provisions a hermetic runtime (one time)+ → 9:16 clips with burned captions+podcli # auto-updates itself on launch+```++No `setup.sh`. No venv. No `pip`. No `npm install` of the engine. No "is the right Python/FFmpeg on PATH?" The system environment becomes irrelevant.++---++## Why this is hard (the core tension)++codex is a single static Rust binary with **zero** runtime deps. podcli is the opposite — a **three-runtime hybrid**:++- **Python engine** (`backend/cli.py`, ~188KB): Whisper (→ PyTorch ~2GB), OpenCV face-crop, Pillow, FFmpeg, Google API.+- **Node/TS**: MCP server (`src/server.ts`), React web UI, Remotion → headless **Chromium** (studio bookends).+- **Bash launcher** routing PodStack AI commands to Claude/Codex, everything else to Python.++You can't fold PyTorch + Chromium + FFmpeg into one static binary. So we **package the hybrid**: a tiny native launcher that provisions and drives hermetic runtimes, and we **kill the single worst dependency (PyTorch) by swapping Whisper → whisper.cpp.**++---++## Locked decisions++| Area | Decision |+|---|---|+| **Target artifact** | Package the hybrid. Thin Go launcher provisions + drives hermetic runtimes; self-updates. Not a rewrite. |+| **Launcher language** | **Go.** One `go build` → 5 static binaries. Replaces both bash `podcli` and `install.cmd`. |+| **Runtimes** | **Fully hermetic.** Launcher downloads pinned standalone CPython, static FFmpeg, whisper.cpp (+ Node/Chromium later). System python/node/ffmpeg ignored. |+| **Transcription** | **whisper.cpp** replaces `openai-whisper`/PyTorch. GGUF models. Metal on Apple Silicon, CUDA/CPU elsewhere. ~145MB vs ~2GB. |+| **Bundle model** | Tiny launcher; **first run provisions the full core stack** (download-once, like today's `setup.sh` but automatic + cross-platform). |+| **Storage** | **Global** managed dir for runtimes + model cache (`%LOCALAPPDATA%\podcli` / `~/Library/Application Support/podcli` / `~/.local/share/podcli`). **Per-project** `.podcli/` (knowledge, output, history) stays in cwd — podcli stays project-scoped like git. |+| **Distribution** | **npm + bun only.** Thin wrapper package fetches the platform binary on install (codex-style). **No code signing, no brew/winget/curl\|sh/.exe.** |+| **Auto-update** | On launch: fast (~250ms, short-timeout) check against GitHub Releases. Newer → update then load. Offline/slow → proceed on current version (never blocks). Self-replace the managed binary in `~/.podcli/bin/`; if that's impossible, print the matching upgrade command (`npm i -g podcli` / `bun add -g podcli`). |+| **Update opt-out** | Persistent off switch: `podcli config set update.auto off` + `PODCLI_NO_UPDATE=1`. When off: no checks, runs installed version. `podcli update` still works on demand. |+| **AI features** | API key preferred → AI-CLI fallback → core works without. If a key is set, call the Claude/OpenAI API directly (self-contained); else shell to installed Claude/Codex CLI (today's behavior); else the video pipeline still works and AI features print how to enable them. |+| **Platforms** | macOS arm64, macOS x64, Linux x64, Linux arm64, Windows x64. |+| **First milestone** | **Thin vertical slice** — `process` pipeline only, fully hermetic, whisper.cpp, npm/bun, self-update, all 5 platforms. Studio / AI-API / MCP come after. |++---++## Target architecture++```+┌─ podcli (Go launcher, ~8MB, per-platform) ──────────────────────────┐+│ • on-launch self-update (GitHub Releases, throttle-free fast check) │+│ • first-run provisioning → global managed dir │+│ • subcommand routing: process/studio/thumbnails… → hermetic python │+│ studio render → hermetic node │+│ • config, version pinning, rollback │+└──────────────────────────────────────────────────────────────────────┘+ │ provisions (pinned versions)+ ▼+ Global managed dir (~/.local/share/podcli, etc.)+ bin/ podcli-<version> (the real engine binary, self-updatable)+ runtime/ cpython-standalone/ ffmpeg whisper.cpp (+ node/ later)+ models/ ggml-base-q5_1.bin … (fetched/cached)+ venv/ hermetic pip env for backend/ deps (opencv, Pillow, …)++ Per-project (cwd)/.podcli/+ knowledge/ output/ history/ presets/ cache/ (unchanged)+```++**Subcommand routing (MVP):** `process` and friends → `runtime/cpython/python backend/cli.py …` with all paths pointing at the hermetic runtime. The Go launcher sets `PYTHON`, `FFMPEG`, model paths, and env so `cli.py` never touches the system.++---++## Transcription swap (the keystone engine change)++Clean seam: `backend/services/transcription.py::transcribe_file()` returns a fixed dict (`segments`, word-level `words`, `duration`, `language`, speaker fields). Only the engine behind it changes.++- Replace `import whisper; model.transcribe(..., word_timestamps=True)` with a subprocess call to the vendored `whisper-cli` (whisper.cpp) emitting JSON, then map its output → the existing dict shape.+- **Validation risk to prove early:** whisper.cpp word-level timestamps must be good enough for the karaoke/word-highlight captions. Build a parity test (same clip, compare word timings old vs new) before committing.+- Diarization is already optional/off by default (Claude handles speakers; paste-transcript supports `Speaker (MM:SS)`), so it's not a blocker.+- Models: ship/fetch `ggml-base-q5_1` (~57MB) by default; allow `--model small/medium/large` to lazily fetch bigger GGUFs into `models/`.++---++## Roadmap++### Phase 0 — Foundation spike (de-risk everything)+- Go launcher skeleton: arg parse, subcommand passthrough to a hand-placed python.+- Managed-dir layout + OS-appropriate paths.+- Hermetic provisioning: download pinned **CPython standalone**, **static FFmpeg**, **whisper.cpp** binary + base-q5 model for the **current** platform; create hermetic venv; `pip install` backend deps into it.+- Prove `go run . process sample.mp4` produces a clip using **only** hermetic components (rename/hide system python+ffmpeg to verify).++### Phase 1 — whisper.cpp engine swap+- Reimplement `transcribe_file()` on whisper.cpp behind the existing dict contract.+- Word-timestamp parity test vs `openai-whisper` on a fixture; tune `--max-len`/token-timestamp flags.+- Remove `openai-whisper` from `requirements.txt`; confirm captions (karaoke/Hormozi/subtle) still render correctly.++### Phase 2 — Distribution + self-update (→ first installable release)+- CI matrix builds the Go launcher for all **5 targets**.+- **npm + bun wrapper package**: `postinstall` downloads the platform binary into `~/.podcli/bin/`; `bin` shim execs it. Publish to npm (bun consumes the same registry).+- GitHub Release per version carries: the 5 binaries + a **version manifest** pinning required runtime versions (so an update knows what to re-provision).+- Self-update: fast on-launch check, atomic self-replace of the managed binary, npm/bun fallback message, `PODCLI_NO_UPDATE` + `config set update.auto off`, `podcli update`, keep-previous-binary for `podcli rollback`.+- **Ship.** `npm i -g podcli` → `podcli process` works hermetic on all 5 platforms and auto-updates. ← *this is the MVP gate.*++### Phase 3 — Lazy tiers + studio+- Demote OpenCV face-crop to lazy (center-crop default offline; fetch opencv on first smart crop — the center-crop fallback already exists at `cli.py:621`).+- Lazy bigger Whisper models.+- **Studio**: provision hermetic **Node + Remotion + Chromium** on first `studio` use; route `studio` render through it.++### Phase 4 — AI goes native+- Port PodStack prompt files (`.claude/commands/*.md`) into the engine as direct **Claude API** calls.+- `podcli config set api-key …`; precedence: API key → installed Claude/Codex CLI → "enable AI" hint.+- Keep core pipeline fully functional without any AI.++### Phase 5 — MCP / web UI (or deprecate)+- Decide whether the MCP server still matters once AI is native via API, or it's only for "use podcli from inside Claude/Codex."+- If kept: `podcli serve` (MCP stdio) + `podcli ui` (web dashboard) provisioned on demand via hermetic Node.++---++## Risks / open questions++- **whisper.cpp timestamp quality** for word-highlight captions — *prove in Phase 1 before deleting PyTorch path.*+- **Hermetic Node + Chromium on Windows** for studio (Phase 3) — Remotion's Chromium download + headless render is the heaviest non-ML surface; expect platform-specific pain.+- **First-run download size/time** — set expectations with a clear progress UI; cache aggressively in the global dir.+- **npm self-update vs package-manager ownership** — managed-binary-in-`~/.podcli/bin` sidesteps it; fallback message covers the rest.+- **GPU acceleration** — whisper.cpp Metal (mac) is automatic; CUDA (linux/win) needs the right prebuilt — decide CPU-only baseline + optional CUDA fetch.+- **Versioning** — single version for launcher + manifest of pinned runtime versions; SemVer; changelog drives the "update available" line.+- **MCP/web UI fate** — genuinely open; resolve at Phase 5.++---++## Immediate next step++Start **Phase 0** on a branch: stand up the Go launcher + hermetic provisioning for the current platform (darwin/arm64) and get `process` running end-to-end against only hermetic components. That single spike validates the launcher, the managed-dir model, hermetic provisioning, and the whisper.cpp integration surface in one shot.diff --git a/podcli b/podcliindex 7eb8b18..829336f 100755--- a/podcli+++ b/podcli@@ -17,6 +17,25 @@ elsePYTHON="python3"fi+# ── Native CLI upgrade notice ──+# This in-repo bash launcher is superseded by the native `podcli` binary. Running+# the native CLI in this same directory auto-migrates this project's data on first+# run. Printed to stderr so command stdout (JSON, pipes) stays clean.+{+ U_ACCENT="\033[38;2;212;135;74m"+ U_BOLD="\033[1m"+ U_DIM="\033[2m"+ U_RESET="\033[0m"+ NATIVE_BIN="$(command -v podcli 2>/dev/null)"+ echo -e " ${U_BOLD}podcli now ships as a native CLI.${U_RESET} ${U_DIM}You're running the old in-repo launcher.${U_RESET}" >&2+ if [ -n "$NATIVE_BIN" ] && [ "$NATIVE_BIN" != "$0" ] && [ "$NATIVE_BIN" != "$SCRIPT_DIR/podcli" ]; then+ echo -e " Run ${U_ACCENT}podcli${U_RESET} in this folder instead — it auto-migrates this project's data on first run." >&2+ else+ echo -e " Install ${U_ACCENT}npm i -g podcli${U_RESET}, then run ${U_ACCENT}podcli${U_RESET} here — it auto-migrates this project's data on first run." >&2+ fi+ echo "" >&2+}+# ── PodStack slash commands → launch an AI agent ──CMD="$1"# Strip leading / or -- prefix (user might try /prep-episode, --prep-episode, or prep-episode)diff --git a/remotion/render-bookend.mjs b/remotion/render-bookend.mjsindex ee6c7df..2688079 100644--- a/remotion/render-bookend.mjs+++ b/remotion/render-bookend.mjs@@ -25,7 +25,13 @@ import { fileURLToPath } from "url";const __dirname = path.dirname(fileURLToPath(import.meta.url));const PROJECT_ROOT = path.resolve(__dirname, "..");-const CACHE_DIR = path.join(PROJECT_ROOT, ".podcli", "cache", "remotion-bundle");+// Share the (project-independent) composition bundle with render.mjs via+// PODCLI_CACHE_DIR so bookends reuse the prewarmed bundle instead of rebuilding+// into the runtime dir.+const CACHE_ROOT = process.env.PODCLI_CACHE_DIR+ ? path.resolve(process.env.PODCLI_CACHE_DIR)+ : path.join(PROJECT_ROOT, "data", "cache");+const CACHE_DIR = path.join(CACHE_ROOT, "remotion-bundle");const ENTRY_POINT = path.join(__dirname, "src", "index.ts");function parseArgs() {diff --git a/scripts/build-remotion.sh b/scripts/build-remotion.shnew file mode 100644index 0000000..aef6c3a--- /dev/null+++ b/scripts/build-remotion.sh@@ -0,0 +1,39 @@+#!/bin/sh+# Build the Remotion render bundle: the remotion/ project plus a production+# node_modules with only the render deps. Native bindings (@rspack, the Remotion+# compositor) are per-platform, so this MUST run on each target platform/arch in+# CI — the produced bundle is not portable across os/arch.+#+# Layout (extracted to the runtime dir): remotion/ + node_modules/ as siblings of+# backend/, so render.mjs resolves node_modules and the Python backend resolves+# runtime/remotion/render.mjs + runtime/node_modules.+#+# Usage: scripts/build-remotion.sh [out-dir] (default: dist/remotion-bundle)+set -e+here="$(cd "$(dirname "$0")/.." && pwd)"+out="${1:-$here/dist/remotion-bundle}"++rm -rf "$out"+mkdir -p "$out"+cp -R "$here/remotion" "$out/remotion"+cp "$here/tsconfig.json" "$out/tsconfig.json" 2>/dev/null || true++cat > "$out/package.json" <<'JSON'+{+ "name": "podcli-remotion-bundle",+ "private": true,+ "type": "module",+ "dependencies": {+ "@remotion/bundler": "^4.0.441",+ "@remotion/renderer": "^4.0.441",+ "remotion": "^4.0.441",+ "react": "^18.3.1",+ "react-dom": "^18.3.1",+ "@fontsource/dm-sans": "^5.2.8"+ }+}+JSON++cd "$out"+npm install --omit=dev --no-audit --no-fund --no-package-lock+echo "remotion bundle -> $out"diff --git a/scripts/build-studio.sh b/scripts/build-studio.shnew file mode 100644index 0000000..cd1fa48--- /dev/null+++ b/scripts/build-studio.sh@@ -0,0 +1,22 @@+#!/bin/sh+# Build the studio web-UI bundle: a single self-contained server (esbuild) plus+# the built SPA. Rendering is delegated to the Python backend at runtime, so the+# bundle needs no node_modules — only a Node runtime to execute it.+#+# Usage: scripts/build-studio.sh [out-dir] (default: dist/studio)+set -e+here="$(cd "$(dirname "$0")/.." && pwd)"+out="${1:-$here/dist/studio}"+cd "$here"++npm run build # tsc + vite -> dist/ui/web-server.js + dist/ui/public++rm -rf "$out"+mkdir -p "$out"+banner="import{createRequire as _cr}from'module';const require=_cr(import.meta.url);"+# Studio web-UI server + its built SPA.+node -e "require('esbuild').buildSync({entryPoints:['dist/ui/web-server.js'],bundle:true,platform:'node',format:'esm',outfile:'$out/web-server.mjs',banner:{js:\"$banner\"},logLevel:'error'})"+cp -r dist/ui/public "$out/public"+# MCP stdio server (the mcp__podcli__* tools Claude/Codex drive).+node -e "require('esbuild').buildSync({entryPoints:['dist/index.js'],bundle:true,platform:'node',format:'esm',outfile:'$out/mcp-server.mjs',banner:{js:\"$banner\"},logLevel:'error'})"+echo "studio + mcp bundle -> $out"diff --git a/src/config/paths.ts b/src/config/paths.tsindex 1535c02..25fac3e 100644--- a/src/config/paths.ts+++ b/src/config/paths.ts@@ -7,6 +7,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));const projectRoot = resolve(__dirname, "..", "..");const homeMarker = join(projectRoot, ".podcli-home");const dataDir = resolve(process.env.PODCLI_DATA || join(projectRoot, "data"));+const outputDir = resolve(process.env.PODCLI_OUTPUT || join(dataDir, "output"));function resolveHome(): string {if (process.env.PODCLI_HOME) {@@ -49,7 +50,7 @@ export const paths = {transcripts: join(dataDir, "cache", "transcripts"),packed: join(home, "packed"),working: join(dataDir, "working"),- output: join(dataDir, "output"),+ output: outputDir,logs: join(dataDir, "logs"),assets: join(home, "assets"),assetsRegistry: join(home, "assets", "registry.json"),@@ -60,7 +61,9 @@ export const paths = {corrections: join(home, "corrections.json"),thumbnailConfig: join(home, "thumbnail-config.json"),integrations: join(home, "integrations.json"),- pythonBackend: join(projectRoot, "backend", "main.py"),+ pythonBackend: process.env.PODCLI_BACKEND+ ? join(resolve(process.env.PODCLI_BACKEND), "main.py")+ : join(projectRoot, "backend", "main.py"),pythonPath: detectPython(),ffmpegPath: process.env.FFMPEG_PATH || "ffmpeg",ffprobePath: process.env.FFPROBE_PATH || "ffprobe",diff --git a/src/models/index.ts b/src/models/index.tsindex 5819c56..2c94a02 100644--- a/src/models/index.ts+++ b/src/models/index.ts@@ -2,7 +2,7 @@export interface TaskRequest {task_id: string;- task_type: "transcribe" | "parse_transcript" | "create_clip" | "batch_clips" | "analyze_energy" | "pack_transcript" | "detect_encoder" | "presets" | "ping" | "suggest_clips" | "generate_content" | "corrections" | "manage_integrations" | "run_integration_tool" | "manage_config";+ task_type: "transcribe" | "parse_transcript" | "create_clip" | "batch_clips" | "analyze_energy" | "pack_transcript" | "detect_encoder" | "presets" | "ping" | "suggest_clips" | "find_moment" | "generate_content" | "corrections" | "manage_integrations" | "run_integration_tool" | "manage_config";params: Record<string, unknown>;}diff --git a/src/ui/client/ClipDetail.tsx b/src/ui/client/ClipDetail.tsxindex f425a50..b4ed041 100644--- a/src/ui/client/ClipDetail.tsx+++ b/src/ui/client/ClipDetail.tsx@@ -83,8 +83,7 @@ export default function ClipDetail() {const tc = clip.thumbnail_config || {};const dirty = title !== clip.title || captionStyle !== clip.caption_style;- const file = basename(clip.output_path);- const previewUrl = `/api/preview/${file}?t=${bust}`;+ const previewUrl = `/api/clips/${clip.id}/preview?t=${bust}`;const source = thumbImage ? `Image · ${basename(thumbImage)}` : thumbTimestamp != null ? `Frame @ ${fmt(thumbTimestamp)}` : "Auto";const patch = (body: any) => api(`/clips/${clip.id}`, { method: "PATCH", body: JSON.stringify(body) });@@ -167,7 +166,7 @@ export default function ClipDetail() {<div style={{ display: "flex", justifyContent: "space-between", alignItems: "flex-end", gap: 16, marginTop: 8, flexWrap: "wrap" }}><h1 style={{ margin: 0 }}>{clip.title}</h1><div className="set-actions">- <a className="btn btn-ghost btn-sm" href={`/api/download/${file}`} download style={{ textDecoration: "none" }}>Download</a>+ <a className="btn btn-ghost btn-sm" href={`/api/clips/${clip.id}/download`} download style={{ textDecoration: "none" }}>Download</a><button className="btn btn-ghost btn-sm" onClick={reopen} disabled={busy !== null}>{busy === "reopen" ? <div className="spinner sm" /> : "Reopen in editor"}</button>{davinciOn && <button className="btn btn-ghost btn-sm" onClick={exportDavinci} disabled={busy !== null}>{busy === "davinci" ? <div className="spinner sm" /> : "Export for DaVinci"}</button>}<button className="btn btn-danger btn-sm" onClick={del} disabled={busy !== null}>{busy === "delete" ? <div className="spinner sm" /> : "Delete"}</button>diff --git a/src/ui/client/EpisodeWorkspace.jsx b/src/ui/client/EpisodeWorkspace.jsxindex e4ddf6a..edbf601 100644--- a/src/ui/client/EpisodeWorkspace.jsx+++ b/src/ui/client/EpisodeWorkspace.jsx@@ -531,6 +531,9 @@ const fmt = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(const [results, setResults] = useState([]);const [error, setError] = useState(null);const [previewFile, setPreviewFile] = useState(null);+ const [momentText, setMomentText] = useState('');+ const [findingMoment, setFindingMoment] = useState(false);+ const [momentNotice, setMomentNotice] = useState(null);const [retryIdx, setRetryIdx] = useState(null);const [retryJobId, setRetryJobId] = useState(null);@@ -902,6 +905,27 @@ const fmt = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(finally { setBrowsing(false); }}, []);+ const findMoment = async () => {+ const text = momentText.trim();+ if (!text || findingMoment) return;+ setFindingMoment(true); setError(null); setMomentNotice(null);+ try {+ const d = await api('/find-moment', { method: 'POST', body: JSON.stringify({ text }) });+ if (d.error) { setError(d.error); return; }+ if (!d.added) {+ setMomentNotice(d.found ? 'Those moments are already in your clips.' : "Couldn't find that moment — try different wording or a direct quote.");+ return;+ }+ // suggestions refresh via the SSE state-sync broadcast+ setMomentText('');+ setMomentNotice(`Added ${d.added} moment${d.added !== 1 ? 's' : ''}.`);+ } catch {+ setError('Moment search failed.');+ } finally {+ setFindingMoment(false);+ }+ };+const startExport = async () => {setPhase('exporting'); setResults([]);const sc = suggestions.filter((_, i) => !deselected.has(i));@@ -1485,6 +1509,30 @@ const fmt = (s) => `${Math.floor(s / 60)}:${String(Math.floor(s % 60)).padStart(</div>)}+ {/* Find a specific moment — paste a quote/description, AI locates it */}+ {(transcript || transcriptText) && phase !== 'parsing' && phase !== 'suggesting' && phase !== 'exporting' && (+ <div className="section" style={{ marginTop: 16 }}>+ <div className="section-label">Find a specific moment</div>+ <textarea+ className="input"+ rows={3}+ placeholder="Paste a quote or describe the moment(s) you want — the AI searches the transcript and adds them to your clips."+ value={momentText}+ onChange={(e) => { setMomentText(e.target.value); setMomentNotice(null); }}+ disabled={findingMoment}+ style={{ width: '100%', resize: 'vertical', fontFamily: 'inherit' }}+ />+ <div style={{ display: 'flex', alignItems: 'center', gap: 10, marginTop: 8 }}>+ <button className="btn btn-primary btn-sm" onClick={findMoment} disabled={!momentText.trim() || findingMoment}>+ {findingMoment+ ? <span style={{ display: 'flex', alignItems: 'center', gap: 6 }}><div className="spinner sm" />Searching{'…'}</span>+ : 'Find moments'}+ </button>+ {momentNotice && <span style={{ color: 'var(--text2)', fontSize: 13 }}>{momentNotice}</span>}+ </div>+ </div>+ )}+{/* Parsing */}{phase === 'parsing' && (<div className="fade-in" style={{ marginTop: 20 }}>diff --git a/src/ui/client/StudioHome.tsx b/src/ui/client/StudioHome.tsxindex 7182ff0..b386b52 100644--- a/src/ui/client/StudioHome.tsx+++ b/src/ui/client/StudioHome.tsx@@ -130,7 +130,7 @@ export default function StudioHome() {{thumb ? (<img className="clip-card-media" src={`/api/image?path=${encodeURIComponent(thumb)}`} alt="" />) : file ? (- <video className="clip-card-media" src={`/api/preview/${file}#t=0.1`} muted preload="metadata" playsInline />+ <video className="clip-card-media" src={`/api/clips/${c.id}/preview#t=0.1`} muted preload="metadata" playsInline />) : (<div className="clip-card-media empty">▶</div>)}diff --git a/src/ui/web-server.ts b/src/ui/web-server.tsindex 36b1212..fd9d3f8 100644--- a/src/ui/web-server.ts+++ b/src/ui/web-server.ts@@ -995,6 +995,52 @@ app.get("/api/preview/:filename", (req, res) => {streamVideo(req, res, filePath);});+// Clips now render into the user's working dir, not a single output root, so the+// library streams them by history id from wherever they live. The output_path+// recorded in clips.json IS the allowlist: only files podcli itself logged are+// servable, and only as regular files (symlinks resolved, extension checked).+async function serveClipById(+ req: Request,+ res: Response,+ id: string,+ mode: "preview" | "download",+) {+ const entry = await clipsHistory.findById(id);+ if (!entry || !entry.output_path) {+ res.status(404).json({ error: "Clip not found" });+ return;+ }+ let real: string;+ try {+ real = realpathSync(entry.output_path);+ } catch {+ res.status(404).json({ error: "File no longer exists" });+ return;+ }+ if (!statSync(real).isFile() || !/\.(mp4|mov|mkv|webm)$/i.test(real)) {+ res.status(400).json({ error: "Unsupported clip file" });+ return;+ }+ if (mode === "download") {+ res.download(real);+ return;+ }+ const mimeTypes: Record<string, string> = {+ ".webm": "video/webm",+ ".mov": "video/quicktime",+ ".mkv": "video/x-matroska",+ };+ streamVideo(req, res, real, mimeTypes[extname(real).toLowerCase()] || "video/mp4");+}++app.get("/api/clips/:id/preview", (req, res) => {+ void serveClipById(req, res, req.params.id, "preview");+});++app.get("/api/clips/:id/download", (req, res) => {+ void serveClipById(req, res, req.params.id, "download");+});+/*** GET /api/stream-source — Stream the source video for in-browser preview* Accepts ?path= query param (must be a file previously validated via /select-file or /upload)@@ -1746,13 +1792,11 @@ const knowledgeUpload = multer({await mkdir(paths.knowledge, { recursive: true });cb(null, paths.knowledge);},- filename: (_req, file, cb) => cb(null, file.originalname),+ filename: (_req, file, cb) => cb(null, basename(file.originalname)),}),fileFilter: (_req, file, cb) => {- if (- file.originalname.endsWith(".md") ||- file.originalname.endsWith(".txt")- ) {+ const name = basename(file.originalname);+ if (name.endsWith(".md") || name.endsWith(".txt")) {cb(null, true);} else {cb(new Error("Only .md and .txt files are allowed"));@@ -2063,6 +2107,8 @@ app.post("/api/claude-suggest", async (req, res) => {score: c.score,suggested_caption_style: c.suggested_caption_style || "hormozi",}));+ // Deselection is positional; replacing the list invalidates old indices.+ uiState.deselectedIndices = [];uiState.phase = "review";broadcastSSE("state-sync", uiState);}@@ -2076,6 +2122,77 @@ app.post("/api/claude-suggest", async (req, res) => {}});+// --- Find user-pasted moments (paste a description/quotes, AI locates them) ---++app.post("/api/find-moment", async (req, res) => {+ const text = typeof req.body?.text === "string" ? req.body.text.trim() : "";+ if (!text) {+ res.status(400).json({ error: "Paste a moment or description to search for." });+ return;+ }+ const segs = uiState.transcript?.segments;+ if (!segs || !Array.isArray(segs) || segs.length === 0) {+ res+ .status(400)+ .json({ error: "No transcript loaded. Transcribe or import one first." });+ return;+ }++ try {+ const existing = uiState.suggestions.map((s) => ({+ start_second: s.start_second,+ end_second: s.end_second,+ title: s.title,+ }));+ const result = await executor.execute<{ clips?: SuggestedClip[] }>(+ "find_moment",+ { text, segments: segs, existing_clips: existing, max_results: 8 },+ (event) =>+ broadcastSSE("job-update", { progress: event.percent, message: event.message }),+ );++ const found = result.data?.clips ?? [];+ // Append to existing suggestions, skipping anything at a range we already have.+ const seen = new Set(+ uiState.suggestions.map(+ (s) => `${Math.round(s.start_second * 10)}-${Math.round(s.end_second * 10)}`,+ ),+ );+ const added: SuggestedClip[] = [];+ for (const c of found) {+ const key = `${Math.round(c.start_second * 10)}-${Math.round(c.end_second * 10)}`;+ if (seen.has(key)) continue;+ seen.add(key);+ added.push({+ clip_id: `manual-${Date.now()}-${added.length}`,+ title: c.title,+ start_second: c.start_second,+ end_second: c.end_second,+ duration: c.duration ?? c.end_second - c.start_second,+ segments: c.segments,+ reasoning: c.reasoning ?? "",+ preview_text: c.preview_text ?? "",+ content_type: c.content_type,+ score: c.score,+ suggested_caption_style: c.suggested_caption_style || "hormozi",+ });+ }++ if (added.length > 0) {+ uiState.suggestions = [...uiState.suggestions, ...added];+ uiState.phase = "review";+ uiState.lastUpdated = Date.now();+ persistState();+ broadcastSSE("state-sync", uiState);+ }++ res.json({ clips: added, found: found.length, added: added.length });+ } catch (err: unknown) {+ const msg = errMsg(err);+ res.status(500).json({ error: `Moment search failed: ${msg.substring(0, 200)}` });+ }+});+// --- Per-clip content generation (titles, descriptions, tags) ---app.post("/api/generate-content", async (req, res) => {@@ -2374,7 +2491,10 @@ async function main() {res.sendFile(join(publicDir, "index.html"));});- app.listen(PORT, () => {+ // Bind to loopback by default — the studio serves local files (clips, assets,+ // source video) with no auth. Set PODCLI_HOST=0.0.0.0 to expose it on the LAN.+ const HOST = process.env.PODCLI_HOST || "127.0.0.1";+ app.listen(PORT, HOST, () => {log.info(`podcli running at http://localhost:${PORT}`);});}diff --git a/tests/parity/.gitignore b/tests/parity/.gitignorenew file mode 100644index 0000000..7ea24b7--- /dev/null+++ b/tests/parity/.gitignore@@ -0,0 +1,6 @@+# Real-audio fixtures and captured baselines may contain podcast content —+# never commit them. The committable parity surface is the synthetic transcript,+# the goldens (*.ass.expected), and the harness code.+local/+baseline/+candidate/diff --git a/tests/parity/README.md b/tests/parity/README.mdnew file mode 100644index 0000000..87ea258--- /dev/null+++ b/tests/parity/README.md@@ -0,0 +1,84 @@+# Parity harness — keeping every feature correct through the native-CLI migration++This harness is the safety net for `plans/native-cli.md` (Go launcher, hermetic+runtimes, **whisper.cpp** replacing openai-whisper/PyTorch). Its job: prove that+swapping the transcription engine and relocating the runtime does **not** change+what podcli produces.++## The correctness model: two layers split by a contract that already exists++The transcript JSON `{words, segments, ...}` is already a stable, multi-producer+contract (produced by `transcribe_file`, `parse_speaker_transcript`, raw JSON+import, **and** the on-disk cache; consumed by corrections, cropping, moment+selection, and captions). That seam lets correctness decompose into two layers+that are verified independently.++### Layer 1 — everything *downstream* of the transcript JSON+Moments → crop → captions → normalize → encode. **This code does not change** in+the migration; only the runtime relocates (system → hermetic). So the rule is+absolute: a fixed transcript must yield identical output. Any difference is a+runtime *pinning* bug, never a logic change.++- `transcript_synthetic.json` — neutral, no podcast content; packs the word-text+ edge cases (leading-space token, number+symbol, punctuation, apostrophe,+ whitespace-only token, zero-duration token, speaker change).+- `test_caption_parity.py` — renders all four caption styles from that transcript+ and diffs against committed goldens (`golden/*.ass.expected`). Also pins the+ **word-text normalization** the whisper.cpp boundary must reproduce exactly+ (the single highest-risk integration detail) and the 50ms zero-duration floor.++Run it (fast, no media, CI-friendly):++```+venv/bin/python3 -m pytest tests/parity/test_caption_parity.py -q+```++Intentionally update goldens after a deliberate change:++```+UPDATE_GOLDENS=1 venv/bin/python3 -m pytest tests/parity/test_caption_parity.py -q+```++### Layer 2 — the engine (`audio → transcript JSON`)+The only real change. Verified by comparing the new engine's output to a frozen+openai-whisper baseline, with **forgiving** tolerances — because the caption+pipeline already runs in production on evenly-spaced *synthetic* word timings+(`transcript_parser.py:306`), so absolute timestamp fidelity is a quality nicety,+not a correctness requirement.++1. Capture the baseline **now**, while openai-whisper still works. Drop a few+ short representative clips into `tests/parity/local/` (single speaker, two+ speakers, music-heavy, fast speech), then:++ ```+ venv/bin/python3 tests/parity/capture_baseline.py+ ```++ Writes `baseline/<stem>/` = transcript.json + metrics.json + captions per style.++2. Later, run whisper.cpp into `candidate/<stem>/transcript.json` and gate:++ ```+ venv/bin/python3 tests/parity/compare.py <stem>+ ```++ Checks WER and word-timestamp drift (median/p95) against thresholds+ (`PARITY_MAX_WER`, `PARITY_MAX_MEDIAN_DRIFT`, `PARITY_MAX_P95_DRIFT`). Nonzero+ exit = regression; wire it into CI as the swap gate.++## Why this makes "everything still works" tractable++- **Layer 1 is identical by construction** — pinned runtime + frozen-transcript+ goldens. The boring 80% can't drift silently.+- **Layer 2 is bounded against a floor the app already ships** — whisper.cpp only+ has to beat evenly-spaced timings, which it does trivially.+- **The cache protects existing work** — already-transcribed videos reuse their+ openai-whisper JSON, so they produce byte-identical output under the new binary.+- **Dual-engine release** (`--engine whisper-py`, planned) gives an instant+ real-world fallback while whisper.cpp proves itself.++## What is committed vs local++Committed: this README, `transcript_synthetic.json`, `golden/*.ass.expected`,+the harness scripts. **Never committed** (`.gitignore`): `local/` fixtures,+`baseline/`, `candidate/` — they can contain podcast content.diff --git a/tests/parity/capture_baseline.py b/tests/parity/capture_baseline.pynew file mode 100644index 0000000..2fe593e--- /dev/null+++ b/tests/parity/capture_baseline.py@@ -0,0 +1,110 @@+"""Layer-2 engine baseline capture.++Runs the CURRENT transcription engine (openai-whisper) on real-audio fixtures+and freezes its output as ground truth. When the engine is later swapped to+whisper.cpp, `compare.py` measures the candidate against this baseline with+explicit tolerances.++The baseline is the transcript JSON contract (`words` + `segments`) plus a+metrics summary and the captions rendered from those real words — i.e. exactly+the things whisper.cpp must reproduce.++Usage:+ venv/bin/python3 tests/parity/capture_baseline.py FIXTURE [FIXTURE ...]+ venv/bin/python3 tests/parity/capture_baseline.py # scans tests/parity/local/++Outputs (gitignored) under tests/parity/baseline/<stem>/:+ transcript.json full {words, segments, duration, language}+ metrics.json n_words, n_segments, duration, language, engine, model+ captions_<style>.ass captions rendered from the real transcript words++Capture this WHILE the current system still works — it is the frozen reference+everything else is measured against.+"""++import json+import os+import sys++HERE = os.path.dirname(os.path.abspath(__file__))+ROOT = os.path.abspath(os.path.join(HERE, "..", ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++LOCAL_DIR = os.path.join(HERE, "local")+BASELINE_DIR = os.path.join(HERE, "baseline")+MEDIA_EXTS = (".mp4", ".mov", ".mkv", ".wav", ".mp3", ".m4a", ".aac")+STYLES = ["hormozi", "karaoke", "subtle", "branded"]+MODEL = os.environ.get("PARITY_MODEL", "base")+++def _discover():+ if not os.path.isdir(LOCAL_DIR):+ return []+ return [+ os.path.join(LOCAL_DIR, f)+ for f in sorted(os.listdir(LOCAL_DIR))+ if f.lower().endswith(MEDIA_EXTS)+ ]+++def capture(media_path: str):+ from services.transcription import transcribe_file+ from services.caption_renderer import render_captions++ stem = os.path.splitext(os.path.basename(media_path))[0]+ out_dir = os.path.join(BASELINE_DIR, stem)+ os.makedirs(out_dir, exist_ok=True)++ print(f" transcribing {os.path.basename(media_path)} (model={MODEL}) ...")+ result = transcribe_file(+ file_path=media_path,+ model_size=MODEL,+ enable_diarization=False, # deterministic; diarization is optional/off by default+ )+ words = result.get("words", [])+ segments = result.get("segments", [])++ with open(os.path.join(out_dir, "transcript.json"), "w", encoding="utf-8") as f:+ json.dump(result, f, indent=2, ensure_ascii=False)++ metrics = {+ "engine": "openai-whisper",+ "model": MODEL,+ "n_words": len(words),+ "n_segments": len(segments),+ "duration": result.get("duration"),+ "language": result.get("language"),+ }+ with open(os.path.join(out_dir, "metrics.json"), "w", encoding="utf-8") as f:+ json.dump(metrics, f, indent=2)++ for style in STYLES:+ render_captions(words, style, os.path.join(out_dir, f"captions_{style}.ass"))++ print(f" -> {out_dir} ({len(words)} words, {len(segments)} segments)")+ return metrics+++def main(argv):+ fixtures = argv[1:] or _discover()+ if not fixtures:+ print(+ "No fixtures. Pass media paths, or drop clips into tests/parity/local/ .\n"+ "Use short representative clips (single speaker, two speakers, music-heavy, "+ "fast speech). They stay local — never committed.",+ file=sys.stderr,+ )+ return 1+ for media in fixtures:+ if not os.path.exists(media):+ print(f" skip (not found): {media}", file=sys.stderr)+ continue+ capture(media)+ print("\nBaseline captured. Compare a new engine later with tests/parity/compare.py")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main(sys.argv))diff --git a/tests/parity/compare.py b/tests/parity/compare.pynew file mode 100644index 0000000..063a9f3--- /dev/null+++ b/tests/parity/compare.py@@ -0,0 +1,129 @@+"""Compare a candidate transcription engine against the captured baseline.++Layer-2 gate: bounds whisper.cpp (or any new engine) against openai-whisper+ground truth on text accuracy and word-timestamp drift. The acceptance bar is+deliberately forgiving because the caption pipeline already runs in production+on evenly-spaced synthetic word timings (see transcript_parser.py) — absolute+timestamp fidelity is a quality nicety, not a correctness requirement.++Usage:+ venv/bin/python3 tests/parity/compare.py <stem>+ compares baseline/<stem>/transcript.json vs candidate/<stem>/transcript.json+ venv/bin/python3 tests/parity/compare.py <baseline.json> <candidate.json>++Exit code is nonzero if any threshold is exceeded — wire it into CI as the gate+for the whisper.cpp swap.+"""++import json+import os+import sys++HERE = os.path.dirname(os.path.abspath(__file__))++# Thresholds — tune against real fixtures, then lock in CI.+MAX_WER = float(os.environ.get("PARITY_MAX_WER", "0.08")) # 8% word error+MAX_MEDIAN_DRIFT = float(os.environ.get("PARITY_MAX_MEDIAN_DRIFT", "0.10")) # 100ms+MAX_P95_DRIFT = float(os.environ.get("PARITY_MAX_P95_DRIFT", "0.30")) # 300ms+++def _norm(w: str) -> str:+ return (w or "").strip().lower().strip(".,!?;:\"'")+++def _words(path: str):+ with open(path, encoding="utf-8") as f:+ data = json.load(f)+ return data.get("words", []) if isinstance(data, dict) else data+++def _wer(ref_tokens, hyp_tokens) -> float:+ """Word error rate via Levenshtein distance over token sequences."""+ n, m = len(ref_tokens), len(hyp_tokens)+ if n == 0:+ return 0.0 if m == 0 else 1.0+ prev = list(range(m + 1))+ for i in range(1, n + 1):+ cur = [i] + [0] * m+ for j in range(1, m + 1):+ cost = 0 if ref_tokens[i - 1] == hyp_tokens[j - 1] else 1+ cur[j] = min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost)+ prev = cur+ return prev[m] / n+++def _drift(ref, hyp):+ """Median / p95 abs start-time diff over the order-preserving common+ subsequence of matching word tokens. Words present in only one transcript+ are ignored for drift (they're counted by WER)."""+ rt = [_norm(w.get("word", "")) for w in ref]+ ht = [_norm(w.get("word", "")) for w in hyp]+ n, m = len(rt), len(ht)+ # LCS backtrace to align matching words by position.+ dp = [[0] * (m + 1) for _ in range(n + 1)]+ for i in range(1, n + 1):+ for j in range(1, m + 1):+ dp[i][j] = dp[i - 1][j - 1] + 1 if rt[i - 1] == ht[j - 1] else max(dp[i - 1][j], dp[i][j - 1])+ i, j, diffs = n, m, []+ while i > 0 and j > 0:+ if rt[i - 1] == ht[j - 1]:+ try:+ diffs.append(abs(float(ref[i - 1]["start"]) - float(hyp[j - 1]["start"])))+ except (KeyError, TypeError, ValueError):+ pass+ i, j = i - 1, j - 1+ elif dp[i - 1][j] >= dp[i][j - 1]:+ i -= 1+ else:+ j -= 1+ diffs.sort()+ if not diffs:+ return None, None, 0+ median = diffs[len(diffs) // 2]+ p95 = diffs[min(len(diffs) - 1, int(len(diffs) * 0.95))]+ return median, p95, len(diffs)+++def compare(baseline_path: str, candidate_path: str) -> bool:+ ref, hyp = _words(baseline_path), _words(candidate_path)+ wer = _wer([_norm(w.get("word", "")) for w in ref], [_norm(w.get("word", "")) for w in hyp])+ median, p95, matched = _drift(ref, hyp)++ print(f" baseline words: {len(ref)} candidate words: {len(hyp)}")+ print(f" WER: {wer:.3f} (max {MAX_WER})")+ if median is None:+ print(" drift: n/a (no aligned words)")+ else:+ print(f" drift median: {median:.3f}s (max {MAX_MEDIAN_DRIFT}) p95: {p95:.3f}s (max {MAX_P95_DRIFT}) aligned: {matched}")++ ok = wer <= MAX_WER+ if median is not None:+ ok = ok and median <= MAX_MEDIAN_DRIFT and p95 <= MAX_P95_DRIFT+ print(" RESULT: ", "PASS" if ok else "FAIL")+ return ok+++def _resolve(arg):+ cand = os.path.join(HERE, "candidate", arg, "transcript.json")+ base = os.path.join(HERE, "baseline", arg, "transcript.json")+ if os.path.exists(base) and os.path.exists(cand):+ return base, cand+ return arg, None+++def main(argv):+ if len(argv) == 2:+ base, cand = _resolve(argv[1])+ if cand is None:+ print(f"Need baseline/<stem> and candidate/<stem>, or two explicit paths.", file=sys.stderr)+ return 2+ elif len(argv) == 3:+ base, cand = argv[1], argv[2]+ else:+ print(__doc__)+ return 2+ return 0 if compare(base, cand) else 1+++if __name__ == "__main__":+ raise SystemExit(main(sys.argv))diff --git a/tests/parity/golden/branded.ass.expected b/tests/parity/golden/branded.ass.expectednew file mode 100644index 0000000..3181376--- /dev/null+++ b/tests/parity/golden/branded.ass.expected@@ -0,0 +1,52 @@+[Script Info]+Title: Podcast Clip Captions (Branded)+ScriptType: v4.00++PlayResX: 1080+PlayResY: 1920+WrapStyle: 0+ScaledBorderAndShadow: yes++[V4+ Styles]+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding+Style: BrandedNormal,Arial,80,&H00FFFFFF,&H00FFFFFF,&H90000000,&H00000000,-1,0,0,0,100,100,2,0,1,1,1,2,60,60,500,1++[Events]+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text+Dialogue: 0,0:00:00.00,0:00:00.34,BrandedNormal,,0,0,0,,{\an7\pos(240,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 145 0 b 153 0 160 7 160 15 l 160 85 b 160 93 153 100 145 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:00.00,0:00:00.34,BrandedNormal,,0,0,0,,{\an5\pos(320,1380)}The+Dialogue: 1,0:00:00.00,0:00:00.34,BrandedNormal,,0,0,0,,{\an5\pos(520,1380)}james+Dialogue: 1,0:00:00.00,0:00:00.34,BrandedNormal,,0,0,0,,{\an5\pos(740,1380)}webb+Dialogue: 0,0:00:00.34,0:00:00.72,BrandedNormal,,0,0,0,,{\an7\pos(400,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 225 0 b 233 0 240 7 240 15 l 240 85 b 240 93 233 100 225 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:00.34,0:00:00.72,BrandedNormal,,0,0,0,,{\an5\pos(320,1380)}The+Dialogue: 1,0:00:00.34,0:00:00.72,BrandedNormal,,0,0,0,,{\an5\pos(520,1380)}james+Dialogue: 1,0:00:00.34,0:00:00.72,BrandedNormal,,0,0,0,,{\an5\pos(740,1380)}webb+Dialogue: 0,0:00:00.72,0:00:01.05,BrandedNormal,,0,0,0,,{\an7\pos(640,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 185 0 b 193 0 200 7 200 15 l 200 85 b 200 93 193 100 185 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:00.72,0:00:01.05,BrandedNormal,,0,0,0,,{\an5\pos(320,1380)}The+Dialogue: 1,0:00:00.72,0:00:01.05,BrandedNormal,,0,0,0,,{\an5\pos(520,1380)}james+Dialogue: 1,0:00:00.72,0:00:01.05,BrandedNormal,,0,0,0,,{\an5\pos(740,1380)}webb+Dialogue: 0,0:00:01.05,0:00:01.62,BrandedNormal,,0,0,0,,{\an7\pos(160,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 385 0 b 393 0 400 7 400 15 l 400 85 b 400 93 393 100 385 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:01.05,0:00:01.62,BrandedNormal,,0,0,0,,{\an5\pos(360,1380)}Telescope+Dialogue: 1,0:00:01.05,0:00:01.62,BrandedNormal,,0,0,0,,{\an5\pos(660,1380)}cost+Dialogue: 1,0:00:01.05,0:00:01.62,BrandedNormal,,0,0,0,,{\an5\pos(840,1380)}$10+Dialogue: 0,0:00:01.62,0:00:01.95,BrandedNormal,,0,0,0,,{\an7\pos(560,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 185 0 b 193 0 200 7 200 15 l 200 85 b 200 93 193 100 185 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:01.62,0:00:01.95,BrandedNormal,,0,0,0,,{\an5\pos(360,1380)}Telescope+Dialogue: 1,0:00:01.62,0:00:01.95,BrandedNormal,,0,0,0,,{\an5\pos(660,1380)}cost+Dialogue: 1,0:00:01.62,0:00:01.95,BrandedNormal,,0,0,0,,{\an5\pos(840,1380)}$10+Dialogue: 0,0:00:01.95,0:00:02.40,BrandedNormal,,0,0,0,,{\an7\pos(760,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 145 0 b 153 0 160 7 160 15 l 160 85 b 160 93 153 100 145 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:01.95,0:00:02.40,BrandedNormal,,0,0,0,,{\an5\pos(360,1380)}Telescope+Dialogue: 1,0:00:01.95,0:00:02.40,BrandedNormal,,0,0,0,,{\an5\pos(660,1380)}cost+Dialogue: 1,0:00:01.95,0:00:02.40,BrandedNormal,,0,0,0,,{\an5\pos(840,1380)}$10+Dialogue: 0,0:00:02.40,0:00:03.10,BrandedNormal,,0,0,0,,{\an7\pos(120,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 345 0 b 353 0 360 7 360 15 l 360 85 b 360 93 353 100 345 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:02.40,0:00:03.10,BrandedNormal,,0,0,0,,{\an5\pos(300,1380)}Billion.+Dialogue: 1,0:00:02.40,0:00:03.10,BrandedNormal,,0,0,0,,{\an5\pos(620,1380)}wasn't+Dialogue: 1,0:00:02.40,0:00:03.10,BrandedNormal,,0,0,0,,{\an5\pos(860,1380)}that+Dialogue: 0,0:00:03.10,0:00:03.55,BrandedNormal,,0,0,0,,{\an7\pos(480,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 265 0 b 273 0 280 7 280 15 l 280 85 b 280 93 273 100 265 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:03.10,0:00:03.55,BrandedNormal,,0,0,0,,{\an5\pos(300,1380)}Billion.+Dialogue: 1,0:00:03.10,0:00:03.55,BrandedNormal,,0,0,0,,{\an5\pos(620,1380)}wasn't+Dialogue: 1,0:00:03.10,0:00:03.55,BrandedNormal,,0,0,0,,{\an5\pos(860,1380)}that+Dialogue: 0,0:00:03.55,0:00:03.60,BrandedNormal,,0,0,0,,{\an7\pos(760,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 185 0 b 193 0 200 7 200 15 l 200 85 b 200 93 193 100 185 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:03.55,0:00:03.60,BrandedNormal,,0,0,0,,{\an5\pos(300,1380)}Billion.+Dialogue: 1,0:00:03.55,0:00:03.60,BrandedNormal,,0,0,0,,{\an5\pos(620,1380)}wasn't+Dialogue: 1,0:00:03.55,0:00:03.60,BrandedNormal,,0,0,0,,{\an5\pos(860,1380)}that+Dialogue: 0,0:00:03.55,0:00:04.20,BrandedNormal,,0,0,0,,{\an7\pos(320,1330)\p1\c&H00000000&\bord0\shad0\1a&HFF&\t(0,80,\1a&H30&)}m 15 0 l 425 0 b 433 0 440 7 440 15 l 440 85 b 440 93 433 100 425 100 l 15 100 b 7 100 0 93 0 85 l 0 15 b 0 7 7 0 15 0{\p0}+Dialogue: 1,0:00:03.55,0:00:04.20,BrandedNormal,,0,0,0,,{\an5\pos(540,1380)}Expensive?diff --git a/tests/parity/golden/hormozi.ass.expected b/tests/parity/golden/hormozi.ass.expectednew file mode 100644index 0000000..2092e44--- /dev/null+++ b/tests/parity/golden/hormozi.ass.expected@@ -0,0 +1,18 @@+[Script Info]+Title: Podcast Clip Captions+ScriptType: v4.00++PlayResX: 1080+PlayResY: 1920+WrapStyle: 0+ScaledBorderAndShadow: yes++[V4+ Styles]+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding+Style: Default,Arial,80,&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,-1,0,0,0,100,100,0,0,3,0,0,2,40,40,180,1++[Events]+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text+Dialogue: 0,0:00:00.00,0:00:01.05,Default,,0,0,0,,{\c&H0000FFFF\2c&H00FFFFFF}{\kf34}THE {\kf37}JAMES {\kf33}WEBB+Dialogue: 0,0:00:01.05,0:00:02.40,Default,,0,0,0,,{\c&H0000FFFF\2c&H00FFFFFF}{\kf57}TELESCOPE {\kf32}COST {\kf44}$10+Dialogue: 0,0:00:02.40,0:00:03.60,Default,,0,0,0,,{\c&H0000FFFF\2c&H00FFFFFF}{\kf55}BILLION. {\kf44}WASN'T {\kf4}THAT+Dialogue: 0,0:00:03.55,0:00:04.20,Default,,0,0,0,,{\c&H0000FFFF\2c&H00FFFFFF}{\kf65}EXPENSIVE?diff --git a/tests/parity/golden/karaoke.ass.expected b/tests/parity/golden/karaoke.ass.expectednew file mode 100644index 0000000..c7d5337--- /dev/null+++ b/tests/parity/golden/karaoke.ass.expected@@ -0,0 +1,16 @@+[Script Info]+Title: Podcast Clip Captions+ScriptType: v4.00++PlayResX: 1080+PlayResY: 1920+WrapStyle: 0+ScaledBorderAndShadow: yes++[V4+ Styles]+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding+Style: Default,Arial,60,&H00808080,&H00808080,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,3,1,2,40,40,160,1++[Events]+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text+Dialogue: 0,0:00:00.00,0:00:01.95,Default,,0,0,0,,{\c&H00FFFFFF}{\2c&H00808080}{\kf34}The {\kf37}James {\kf33}Webb {\kf57}telescope {\kf32}cost+Dialogue: 0,0:00:01.95,0:00:04.20,Default,,0,0,0,,{\c&H00FFFFFF}{\2c&H00808080}{\kf44}$10 {\kf55}billion. {\kf44}Wasn't {\kf4}that {\kf65}expensive?diff --git a/tests/parity/golden/subtle.ass.expected b/tests/parity/golden/subtle.ass.expectednew file mode 100644index 0000000..85a143d--- /dev/null+++ b/tests/parity/golden/subtle.ass.expected@@ -0,0 +1,16 @@+[Script Info]+Title: Podcast Clip Captions+ScriptType: v4.00++PlayResX: 1080+PlayResY: 1920+WrapStyle: 0+ScaledBorderAndShadow: yes++[V4+ Styles]+Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding+Style: Default,Arial,52,&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,2,2,2,40,40,100,1++[Events]+Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text+Dialogue: 0,0:00:00.00,0:00:01.95,Default,,0,0,0,,The James Webb telescope cost+Dialogue: 0,0:00:01.95,0:00:04.20,Default,,0,0,0,,$10 billion. Wasn't that expensive?diff --git a/tests/parity/test_caption_parity.py b/tests/parity/test_caption_parity.pynew file mode 100644index 0000000..3af7a9c--- /dev/null+++ b/tests/parity/test_caption_parity.py@@ -0,0 +1,154 @@+"""Layer-1 caption parity: lock the deterministic, engine-independent surface.++Everything downstream of the transcript JSON contract (the `{words, segments}`+dict produced by transcribe_file / parse_speaker_transcript / JSON import /+cache) is pure code that does NOT change when we swap the transcription engine+or relocate the runtime. This test pins the most timestamp-sensitive part of+that surface — caption (ASS) generation — against committed goldens.++If a future change (whisper.cpp swap, hermetic runtime, a refactor) alters+caption output for a fixed transcript, this test fails. That is the whole point:+the engine may change, the contract's consumers may not — silently.++Regenerate goldens intentionally with: UPDATE_GOLDENS=1 pytest tests/parity/test_caption_parity.py+Goldens use the .ass.expected extension because *.ass is gitignored.+"""++import json+import os+import sys+import tempfile++import pytest++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++import services.caption_renderer as caption_renderer # noqa: E402+from services.caption_renderer import render_captions, _sanitize_words # noqa: E402++HERE = os.path.dirname(__file__)+GOLDEN_DIR = os.path.join(HERE, "golden")+TRANSCRIPT = os.path.join(HERE, "transcript_synthetic.json")+STYLES = ["hormozi", "karaoke", "subtle", "branded"]+++def _deterministic_text_widths(texts, font_name, font_size, bold, spacing=2):+ """A host-font-independent stand-in for _measure_text_widths.++ Real width measurement resolves the host's font via fc-match and freetype,+ so positions differ between macOS (Arial) and CI (DejaVu/Liberation) and the+ goldens can never match across machines. The parity harness exists to lock+ the engine-independent ASS pipeline (timing, styles, karaoke, position and+ pill geometry derived from widths) — not the host's typography — so we pin a+ deterministic width model and the goldens become reproducible everywhere.+ """+ widths = []+ for t in texts:+ n = len(t)+ if n == 0:+ widths.append(0)+ continue+ widths.append(round(n * font_size * 0.5) + spacing * max(0, n - 1))+ return widths+++def _load_words():+ with open(TRANSCRIPT, encoding="utf-8") as f:+ return json.load(f)["words"]+++def _render(style: str) -> str:+ words = _load_words()+ fd, out = tempfile.mkstemp(suffix=".ass")+ os.close(fd)+ try:+ render_captions(words, style, out, time_offset=0.0)+ with open(out, encoding="utf-8") as f:+ return f.read()+ finally:+ if os.path.exists(out):+ os.remove(out)++[email protected](autouse=True)+def _hermetic_render(monkeypatch):+ """Pin the two host-dependent inputs so goldens are reproducible everywhere.++ 1. Font name: caption_styles.DETECTED_FONT is resolved at import via fc-list,+ so it's "Arial" on macOS and "Liberation Sans" on CI's Ubuntu — and that+ name is written into the ASS Style line.+ 2. Text widths: see _deterministic_text_widths (affects the branded style's+ per-word positioning and pill geometry).+ """+ monkeypatch.setattr(caption_renderer, "_measure_text_widths", _deterministic_text_widths)++ real_get_style = caption_renderer.get_style++ def _pinned_get_style(name):+ style = dict(real_get_style(name))+ style["font_name"] = "Arial"+ return style++ monkeypatch.setattr(caption_renderer, "get_style", _pinned_get_style)++[email protected]("style", STYLES)+def test_caption_output_matches_golden(style):+ produced = _render(style)+ golden_path = os.path.join(GOLDEN_DIR, f"{style}.ass.expected")++ if os.environ.get("UPDATE_GOLDENS") == "1":+ os.makedirs(GOLDEN_DIR, exist_ok=True)+ with open(golden_path, "w", encoding="utf-8") as f:+ f.write(produced)+ pytest.skip(f"golden updated: {style}")++ assert os.path.exists(golden_path), (+ f"missing golden for {style}. Generate with UPDATE_GOLDENS=1."+ )+ with open(golden_path, encoding="utf-8") as f:+ expected = f.read()+ assert produced == expected, (+ f"caption output for '{style}' diverged from golden. "+ f"If this is an intended change, regenerate with UPDATE_GOLDENS=1."+ )+++def test_word_text_normalization():+ """The exact normalization the whisper.cpp boundary must reproduce.++ whisper.cpp emits leading-space token markers and can emit empty/whitespace+ tokens; corrections + caption spacing match on stripped word text. If the+ new engine's word text isn't normalized identically here, captions and+ apply_corrections() silently diverge. This is the single highest-risk+ integration detail in the engine swap.+ """+ words = _load_words()+ cleaned = _sanitize_words(words)+ texts = [w["word"] for w in cleaned]++ # leading space stripped+ assert texts[0] == "The"+ # whitespace-only token dropped entirely+ assert "" not in texts+ assert all(t.strip() == t and t for t in texts)+ # punctuation / apostrophe / number+symbol survive verbatim+ assert "billion." in texts+ assert "Wasn't" in texts+ assert "$10" in texts+ assert "expensive?" in texts+ # exactly one token (the whitespace-only one) was dropped+ assert len(cleaned) == len(words) - 1+++def test_zero_duration_word_gets_floor():+ """A token with end <= start must be widened to the 50ms floor, never+ crash or render a zero/negative-length event (a real whisper.cpp quirk)."""+ words = _load_words()+ cleaned = _sanitize_words(words)+ for w in cleaned:+ assert w["end"] > w["start"]+ assert (w["end"] - w["start"]) >= 0.05 - 1e-9diff --git a/tests/parity/transcript_synthetic.json b/tests/parity/transcript_synthetic.jsonnew file mode 100644index 0000000..e7377fc--- /dev/null+++ b/tests/parity/transcript_synthetic.json@@ -0,0 +1,22 @@+{+ "_comment": "Neutral synthetic transcript for Layer-1 caption parity. No personal/podcast content. Deliberately exercises the word-text edge cases most likely to diverge across transcription engines: a leading-space token marker, a number+symbol token, end-of-sentence punctuation, an apostrophe, a whitespace-only token (must be dropped), a zero-duration token (must get the 50ms floor), and a speaker change.",+ "segments": [+ {"id": 0, "start": 0.0, "end": 2.95, "text": "The James Webb telescope cost $10 billion.", "speaker": "SPEAKER_00"},+ {"id": 1, "start": 3.1, "end": 4.2, "text": "Wasn't that expensive?", "speaker": "SPEAKER_01"}+ ],+ "words": [+ {"word": " The", "start": 0.0, "end": 0.34, "speaker": "SPEAKER_00"},+ {"word": "James", "start": 0.34, "end": 0.72, "speaker": "SPEAKER_00"},+ {"word": "Webb", "start": 0.72, "end": 1.05, "speaker": "SPEAKER_00"},+ {"word": "telescope", "start": 1.05, "end": 1.62, "speaker": "SPEAKER_00"},+ {"word": "cost", "start": 1.62, "end": 1.95, "speaker": "SPEAKER_00"},+ {"word": "$10", "start": 1.95, "end": 2.4, "speaker": "SPEAKER_00"},+ {"word": "billion.", "start": 2.4, "end": 2.95, "speaker": "SPEAKER_00"},+ {"word": " ", "start": 2.95, "end": 2.95, "speaker": "SPEAKER_00"},+ {"word": "Wasn't", "start": 3.1, "end": 3.55, "speaker": "SPEAKER_01"},+ {"word": "that", "start": 3.55, "end": 3.55, "speaker": "SPEAKER_01"},+ {"word": "expensive?", "start": 3.55, "end": 4.2, "speaker": "SPEAKER_01"}+ ],+ "duration": 4.2,+ "language": "en"+}diff --git a/tests/test_config_bundle.py b/tests/test_config_bundle.pyindex 791b9e3..be5f61c 100644--- a/tests/test_config_bundle.py+++ b/tests/test_config_bundle.py@@ -83,6 +83,31 @@ class ConfigBundleTests(unittest.TestCase):self.assertTrue(registry["assets"][0]["path"].startswith(os.path.realpath(self.dst_home)))self.assertTrue(os.path.exists(registry["assets"][0]["path"]))+ def test_import_rewrites_preset_and_ui_state_asset_paths(self):+ # Regression: a preset/ui-state asset path stored as its literal (possibly+ # symlinked, e.g. macOS /var) value must be rewritten to the new home on+ # import — otherwise it leaks the source machine's path and breaks once the+ # source is gone. self.asset_file is the literal src path (under a tmpdir,+ # which is symlinked on macOS so raw != realpath — exactly the failure case).+ with open(os.path.join(self.src_home, "presets", "branded.json"), "w", encoding="utf-8") as f:+ json.dump({"caption_style": "branded", "logo_path": self.asset_file}, f)+ with open(os.path.join(self.src_home, "ui-state.json"), "w", encoding="utf-8") as f:+ json.dump({"settings": {"logoPath": self.asset_file}}, f)++ export_config(self.bundle, source_home=self.src_home)+ import_config(self.bundle, target_home=self.dst_home)++ home_real = os.path.realpath(self.dst_home)+ with open(os.path.join(self.dst_home, "presets", "branded.json"), encoding="utf-8") as f:+ preset = json.load(f)+ with open(os.path.join(self.dst_home, "ui-state.json"), encoding="utf-8") as f:+ ui = json.load(f)++ self.assertTrue(preset["logo_path"].startswith(home_real), preset["logo_path"])+ self.assertTrue(os.path.exists(preset["logo_path"]))+ self.assertTrue(ui["settings"]["logoPath"].startswith(home_real), ui["settings"]["logoPath"])+ self.assertNotIn(self.src_home, preset["logo_path"])+def test_import_restores_backup_on_failure(self):export_config(self.bundle, source_home=self.src_home)@@ -106,96 +131,173 @@ class ConfigBundleTests(unittest.TestCase):self.assertTrue(os.path.exists(keep_file))- def test_auto_migrate_skips_when_no_legacy_cache(self):- self.assertIsNone(auto_migrate_legacy_if_pending(quiet=True))+ # The native CLI keeps the brand brain + cache global; migration reads the+ # working dir (PODCLI_CWD) and imports it into the global home/cache.+ def _enter_migration(self, proj_root, global_home):+ import config.paths as paths_mod- def test_migrate_legacy_presets(self):- import shutil+ self._paths_mod = paths_mod+ self._saved_paths = {k: paths_mod.paths.get(k) for k in ("home", "cache", "project_root")}+ self._saved_cwd_env = os.environ.get("PODCLI_CWD")+ paths_mod.paths["home"] = global_home+ paths_mod.paths["cache"] = os.path.join(global_home, "data", "cache")+ # The backend install dir must be ignored by migration; point it elsewhere.+ paths_mod.paths["project_root"] = self.src_home+ os.environ["PODCLI_CWD"] = proj_root++ def _exit_migration(self):+ for key, value in self._saved_paths.items():+ if value is None:+ self._paths_mod.paths.pop(key, None)+ else:+ self._paths_mod.paths[key] = value+ if self._saved_cwd_env is None:+ os.environ.pop("PODCLI_CWD", None)+ else:+ os.environ["PODCLI_CWD"] = self._saved_cwd_env++ def test_auto_migrate_skips_when_no_legacy(self):+ empty_proj = os.path.join(os.path.dirname(self.bundle), "empty-proj")+ os.makedirs(empty_proj, exist_ok=True)+ self._enter_migration(empty_proj, self.dst_home)+ try:+ self.assertIsNone(auto_migrate_legacy_if_pending(quiet=True))+ finally:+ self._exit_migration()- import config.paths as paths_mod- from config_bundle import migrate_legacy_presets+ def test_migrate_legacy_cache(self):+ from config_bundle import migrate_legacy_cache as mlc- legacy_root = os.path.join(os.path.dirname(self.bundle), "legacy-presets-root")- legacy_presets = os.path.join(legacy_root, "presets")+ proj = os.path.join(os.path.dirname(self.bundle), "legacy-project")+ legacy = os.path.join(proj, ".podcli", "cache")+ os.makedirs(legacy, exist_ok=True)+ with open(os.path.join(legacy, "abc123.json"), "w", encoding="utf-8") as f:+ json.dump({"words": []}, f)++ self._enter_migration(proj, self.dst_home)+ try:+ summary = mlc(dry_run=False)+ target = os.path.join(self.dst_home, "data", "cache")+ self.assertEqual(summary["moved_json"], 1)+ self.assertTrue(os.path.exists(os.path.join(target, "abc123.json")))+ self.assertFalse(os.path.exists(os.path.join(legacy, "abc123.json")))+ finally:+ self._exit_migration()++ def test_status_reports_legacy_pending_without_migrating(self):+ proj = os.path.join(os.path.dirname(self.bundle), "legacy-status")+ legacy = os.path.join(proj, ".podcli", "cache")+ os.makedirs(legacy, exist_ok=True)+ stay = os.path.join(legacy, "stay.json")+ with open(stay, "w", encoding="utf-8") as f:+ json.dump({"words": []}, f)++ self._enter_migration(proj, self.dst_home)+ try:+ status = run_config_action("status")+ self.assertTrue(status.get("legacy_cache_pending"))+ self.assertTrue(os.path.exists(stay))+ finally:+ self._exit_migration()++ def test_migrate_legacy_top_presets(self):+ from config_bundle import migrate_legacy_presets as mlp++ proj = os.path.join(os.path.dirname(self.bundle), "legacy-presets-root")+ legacy_presets = os.path.join(proj, "presets")os.makedirs(legacy_presets, exist_ok=True)with open(os.path.join(legacy_presets, "myshow.json"), "w", encoding="utf-8") as f:json.dump({"caption_style": "branded"}, f)- old_root = paths_mod.paths["project_root"]- old_home = paths_mod.paths["home"]+ self._enter_migration(proj, self.dst_home)try:- paths_mod.paths["project_root"] = legacy_root- paths_mod.paths["home"] = self.dst_home+ summary = mlp(dry_run=False)target = os.path.join(self.dst_home, "presets")- os.makedirs(target, exist_ok=True)-- summary = migrate_legacy_presets(dry_run=False)self.assertEqual(summary["moved"], 1)self.assertTrue(os.path.exists(os.path.join(target, "myshow.json")))- self.assertFalse(os.path.exists(os.path.join(legacy_presets, "myshow.json")))finally:- paths_mod.paths["project_root"] = old_root- paths_mod.paths["home"] = old_home- shutil.rmtree(legacy_root, ignore_errors=True)+ self._exit_migration()- def test_status_does_not_migrate_legacy_cache(self):- import importlib- import config.paths as paths_mod- import config_bundle+ def test_migrate_legacy_home_imports_brand_brain(self):+ from config_bundle import migrate_legacy_home as mlh- legacy_root = os.path.join(os.path.dirname(self.bundle), "legacy-status")- legacy = os.path.join(legacy_root, ".podcli", "cache")- os.makedirs(legacy, exist_ok=True)- legacy_file = os.path.join(legacy, "stay.json")- with open(legacy_file, "w", encoding="utf-8") as f:- json.dump({"words": []}, f)+ proj = os.path.join(os.path.dirname(self.bundle), "legacy-home")+ os.makedirs(os.path.join(proj, ".podcli", "presets"), exist_ok=True)+ os.makedirs(os.path.join(proj, ".podcli", "knowledge"), exist_ok=True)+ with open(os.path.join(proj, ".podcli", "presets", "show.json"), "w", encoding="utf-8") as f:+ json.dump({"caption_style": "branded"}, f)+ with open(os.path.join(proj, ".podcli", "knowledge", "01-brand.md"), "w", encoding="utf-8") as f:+ f.write("# Brand\n")- old_root = paths_mod.paths["project_root"]+ empty_global = os.path.join(os.path.dirname(self.bundle), "empty-global")+ os.makedirs(empty_global, exist_ok=True)+ self._enter_migration(proj, empty_global)try:- paths_mod.paths["project_root"] = legacy_root- config_bundle.paths["project_root"] = legacy_root- status = run_config_action("status")- self.assertTrue(status.get("legacy_cache_pending"))- self.assertTrue(os.path.exists(legacy_file))+ summary = mlh(dry_run=False)+ self.assertTrue(summary["imported"])+ self.assertTrue(os.path.exists(os.path.join(empty_global, "presets", "show.json")))+ self.assertTrue(os.path.exists(os.path.join(empty_global, "knowledge", "01-brand.md")))finally:- paths_mod.paths["project_root"] = old_root- config_bundle.paths["project_root"] = old_root- import shutil- shutil.rmtree(legacy_root, ignore_errors=True)+ self._exit_migration()- def test_migrate_legacy_cache(self):- import shutil+ def test_migrate_legacy_home_skips_populated_global(self):+ from config_bundle import migrate_legacy_home as mlh- import config.paths as paths_mod- import config_bundle+ proj = os.path.join(os.path.dirname(self.bundle), "legacy-home-skip")+ os.makedirs(os.path.join(proj, ".podcli", "presets"), exist_ok=True)+ with open(os.path.join(proj, ".podcli", "presets", "show.json"), "w", encoding="utf-8") as f:+ json.dump({"a": 1}, f)- legacy_root = os.path.join(os.path.dirname(self.bundle), "legacy-project")- legacy = os.path.join(legacy_root, ".podcli", "cache")- os.makedirs(legacy, exist_ok=True)- legacy_file = os.path.join(legacy, "abc123.json")- with open(legacy_file, "w", encoding="utf-8") as f:+ # A global home that already holds managed content must not be clobbered.+ os.makedirs(os.path.join(self.dst_home, "presets"), exist_ok=True)+ with open(os.path.join(self.dst_home, "presets", "existing.json"), "w", encoding="utf-8") as f:+ json.dump({"keep": 1}, f)+ self._enter_migration(proj, self.dst_home)+ try:+ summary = mlh(dry_run=False)+ self.assertFalse(summary.get("imported"))+ self.assertTrue(summary.get("skipped_existing"))+ self.assertFalse(os.path.exists(os.path.join(self.dst_home, "presets", "show.json")))+ finally:+ self._exit_migration()++ def test_auto_migrate_from_old_project_dir(self):+ # Running `podcli` in an old ./podcli folder imports its brand brain, cache,+ # ancient top-level presets, and .env into the GLOBAL store. PODCLI_CWD is+ # the folder the user runs in; paths["home"]/["cache"] are the global targets.+ proj = os.path.join(os.path.dirname(self.bundle), "old-project")+ os.makedirs(os.path.join(proj, ".podcli", "presets"), exist_ok=True)+ os.makedirs(os.path.join(proj, ".podcli", "knowledge"), exist_ok=True)+ os.makedirs(os.path.join(proj, ".podcli", "cache"), exist_ok=True)+ os.makedirs(os.path.join(proj, "presets"), exist_ok=True)+ with open(os.path.join(proj, ".podcli", "presets", "show.json"), "w", encoding="utf-8") as f:+ json.dump({"caption_style": "branded"}, f)+ with open(os.path.join(proj, ".podcli", "knowledge", "01-brand.md"), "w", encoding="utf-8") as f:+ f.write("# Brand\n")+ with open(os.path.join(proj, ".podcli", "cache", "ep1.json"), "w", encoding="utf-8") as f:json.dump({"words": []}, f)-- old_root = paths_mod.paths["project_root"]- old_cache = paths_mod.paths["cache"]+ with open(os.path.join(proj, "presets", "ancient.json"), "w", encoding="utf-8") as f:+ json.dump({"old": 1}, f)+ with open(os.path.join(proj, ".env"), "w", encoding="utf-8") as f:+ f.write("OPENAI_API_KEY=sk-test\n")++ empty_global = os.path.join(os.path.dirname(self.bundle), "empty-global2")+ os.makedirs(empty_global, exist_ok=True)+ self._enter_migration(proj, empty_global)try:- paths_mod.paths["project_root"] = legacy_root- paths_mod.paths["cache"] = os.path.join(self.dst_home, "cache")- config_bundle.paths["project_root"] = legacy_root- config_bundle.paths["cache"] = paths_mod.paths["cache"]- target = paths_mod.paths["cache"]- os.makedirs(target, exist_ok=True)-- summary = migrate_legacy_cache(dry_run=False)+ summary = auto_migrate_legacy_if_pending(quiet=True)+ self.assertIsNotNone(summary)+ self.assertTrue(summary["home_migration"]["imported"])self.assertEqual(summary["moved_json"], 1)- self.assertTrue(os.path.exists(os.path.join(target, "abc123.json")))- self.assertFalse(os.path.exists(legacy_file))+ self.assertEqual(summary["presets_migration"]["moved"], 1)+ self.assertTrue(summary["env_migration"]["copied"])+ self.assertTrue(os.path.exists(os.path.join(empty_global, "presets", "show.json")))+ self.assertTrue(os.path.exists(os.path.join(empty_global, "presets", "ancient.json")))+ self.assertTrue(os.path.exists(os.path.join(empty_global, "knowledge", "01-brand.md")))+ self.assertTrue(os.path.exists(os.path.join(empty_global, "data", "cache", "ep1.json")))+ self.assertTrue(os.path.exists(os.path.join(empty_global, ".env")))finally:- paths_mod.paths["project_root"] = old_root- paths_mod.paths["cache"] = old_cache- config_bundle.paths["project_root"] = old_root- config_bundle.paths["cache"] = old_cache- shutil.rmtree(legacy_root, ignore_errors=True)+ self._exit_migration()def test_safe_extract_rejects_zip_slip(self):import zipfilediff --git a/tests/test_find_moments.py b/tests/test_find_moments.pynew file mode 100644index 0000000..b1d1fb2--- /dev/null+++ b/tests/test_find_moments.py@@ -0,0 +1,73 @@+"""find_moments_from_text: parse AI output into clip dicts, with the AI CLI mocked."""++import json+import os+import sys+import types+import unittest++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++from services import claude_suggest as cs++SEGMENTS = [+ {"start": 10.0, "end": 20.0, "text": "We talked about discipline and habits.", "speaker": "A"},+ {"start": 20.0, "end": 60.0, "text": "The moment I realized failure was the turning point.", "speaker": "B"},+]+++def _fake_run(**kwargs):+ payload = {+ "clips": [+ {+ "title": "The turning point",+ "start_second": 20.0,+ "end_second": 58.0,+ "segments": [{"start": 20.0, "end": 58.0}],+ "content_type": "guest_story",+ "scores": {"standalone": 5, "hook": 5, "relevance": 4, "quotability": 4},+ "quote": "Failure was the turning point",+ "why": "Directly matches the pasted moment",+ }+ ]+ }+ return types.SimpleNamespace(returncode=0, stdout=json.dumps(payload), stderr="")+++class FindMomentsTests(unittest.TestCase):+ def setUp(self):+ self._orig_candidates = cs._find_ai_cli_candidates+ self._orig_run = cs._run_ai_command+ cs._find_ai_cli_candidates = lambda: [("/usr/bin/claude", "claude")]+ cs._run_ai_command = lambda **kw: _fake_run(**kw)++ def tearDown(self):+ cs._find_ai_cli_candidates = self._orig_candidates+ cs._run_ai_command = self._orig_run++ def test_finds_and_shapes_moment(self):+ clips = cs.find_moments_from_text("the turning point", SEGMENTS, [])+ self.assertEqual(len(clips), 1)+ c = clips[0]+ self.assertEqual(c["start_second"], 20.0)+ self.assertEqual(c["end_second"], 58.0)+ self.assertEqual(c["title"], "The turning point")+ self.assertEqual(c["segments"], [{"start": 20.0, "end": 58.0}])+ self.assertTrue(c["suggested_caption_style"])+ self.assertGreater(c["score"], 0)++ def test_no_ai_cli_returns_empty(self):+ cs._find_ai_cli_candidates = lambda: []+ self.assertEqual(cs.find_moments_from_text("x", SEGMENTS, []), [])++ def test_progress_callback_invoked(self):+ seen = []+ cs.find_moments_from_text("x", SEGMENTS, [], progress_callback=lambda p, m: seen.append((p, m)))+ self.assertTrue(seen)+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_transcript_cache_engine.py b/tests/test_transcript_cache_engine.pynew file mode 100644index 0000000..53362b1--- /dev/null+++ b/tests/test_transcript_cache_engine.py@@ -0,0 +1,48 @@+import os+import sys+import unittest++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++from services import transcript_packer as tp+++class EngineNamespacedCacheTests(unittest.TestCase):+ def setUp(self):+ self._saved = os.environ.get("PODCLI_ENGINE")++ def tearDown(self):+ if self._saved is None:+ os.environ.pop("PODCLI_ENGINE", None)+ else:+ os.environ["PODCLI_ENGINE"] = self._saved++ def test_whisper_py_keeps_bare_path(self):+ for v in (None, "whisper-py", "WHISPER-PY"):+ if v is None:+ os.environ.pop("PODCLI_ENGINE", None)+ else:+ os.environ["PODCLI_ENGINE"] = v+ self.assertTrue(tp.transcript_json_path("abc123").endswith("abc123.json"))++ def test_whispercpp_is_namespaced(self):+ for v in ("whispercpp", "whisper-cpp", "whisper.cpp", "cpp"):+ os.environ["PODCLI_ENGINE"] = v+ self.assertTrue(+ tp.transcript_json_path("abc123").endswith("abc123-whispercpp.json"),+ f"engine {v!r} not namespaced",+ )++ def test_engines_do_not_collide(self):+ os.environ.pop("PODCLI_ENGINE", None)+ py = tp.transcript_json_path("abc123")+ os.environ["PODCLI_ENGINE"] = "whispercpp"+ cpp = tp.transcript_json_path("abc123")+ self.assertNotEqual(py, cpp)+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_transcription_engine.py b/tests/test_transcription_engine.pynew file mode 100644index 0000000..d6c03db--- /dev/null+++ b/tests/test_transcription_engine.py@@ -0,0 +1,67 @@+"""Engine selection: native installs auto-use whisper.cpp when openai-whisper+is absent, unless the user explicitly asked for the whisper-py engine."""++import os+import sys+import tempfile+import unittest++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++import services.transcription as tr+++class TranscriptionEngineTests(unittest.TestCase):+ def setUp(self):+ self._orig_wcpp = tr._transcribe_with_whispercpp+ self._orig_ready = tr._whispercpp_ready+ tr._transcribe_with_whispercpp = lambda *a, **k: {"engine": "whispercpp"}+ tr._whispercpp_ready = lambda size: True+ # Make `import whisper` fail to simulate a native (hermetic) install.+ self._had_whisper = sys.modules.get("whisper", "__absent__")+ sys.modules["whisper"] = None+ self._tmp = tempfile.NamedTemporaryFile(suffix=".wav", delete=False)+ self._tmp.write(b"x")+ self._tmp.close()+ self._saved_engine = os.environ.pop("PODCLI_ENGINE", None)++ def tearDown(self):+ tr._transcribe_with_whispercpp = self._orig_wcpp+ tr._whispercpp_ready = self._orig_ready+ if self._had_whisper == "__absent__":+ sys.modules.pop("whisper", None)+ else:+ sys.modules["whisper"] = self._had_whisper+ os.unlink(self._tmp.name)+ if self._saved_engine is None:+ os.environ.pop("PODCLI_ENGINE", None)+ else:+ os.environ["PODCLI_ENGINE"] = self._saved_engine++ def test_auto_falls_back_to_whispercpp(self):+ os.environ.pop("PODCLI_ENGINE", None)+ result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)+ self.assertEqual(result["engine"], "whispercpp")++ def test_explicit_whispercpp_uses_it(self):+ os.environ["PODCLI_ENGINE"] = "whispercpp"+ result = tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)+ self.assertEqual(result["engine"], "whispercpp")++ def test_explicit_whisper_py_still_errors(self):+ os.environ["PODCLI_ENGINE"] = "whisper-py"+ with self.assertRaises(RuntimeError):+ tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)++ def test_no_fallback_when_whispercpp_unavailable(self):+ os.environ.pop("PODCLI_ENGINE", None)+ tr._whispercpp_ready = lambda size: False+ with self.assertRaises(RuntimeError):+ tr.transcribe_file(self._tmp.name, model_size="base", enable_diarization=False)+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_whispercpp_adapter.py b/tests/test_whispercpp_adapter.pynew file mode 100644index 0000000..c1bb9ac--- /dev/null+++ b/tests/test_whispercpp_adapter.py@@ -0,0 +1,23 @@+import os+import sys+import unittest++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++from services.transcription_whispercpp import _tokens_to_words+++class WhisperCppAdapterTests(unittest.TestCase):+ def test_sentencepiece_marker_is_removed(self):+ words = _tokens_to_words([+ {"text": "▁hello", "offsets": {"from": 0, "to": 100}},+ {"text": "▁world", "offsets": {"from": 100, "to": 200}},+ ])+ self.assertEqual([w["word"] for w in words], ["hello", "world"])+++if __name__ == "__main__":+ unittest.main()diff --git a/tests/test_whispercpp_snap.py b/tests/test_whispercpp_snap.pynew file mode 100644index 0000000..9f09861--- /dev/null+++ b/tests/test_whispercpp_snap.py@@ -0,0 +1,73 @@+"""Energy-snap for whisper.cpp word timings: trailing words stranded in true+silence are pulled back into the voiced span, while words over speech are left+alone. (whisper.cpp sometimes stretches the final phrase across trailing+silence; this keeps captions in sync.)"""++import math+import os+import struct+import sys+import tempfile+import unittest+import wave++ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))+BACKEND_ROOT = os.path.join(ROOT, "backend")+if BACKEND_ROOT not in sys.path:+ sys.path.insert(0, BACKEND_ROOT)++from services.transcription_whispercpp import _snap_words_to_voiced, _voiced_intervals+++def _make_wav(path, voiced_s=1.0, silence_s=1.0, sr=16000):+ w = wave.open(path, "wb")+ w.setnchannels(1)+ w.setsampwidth(2)+ w.setframerate(sr)+ buf = bytearray()+ for i in range(int(sr * voiced_s)):+ buf += struct.pack("<h", int(8000 * math.sin(2 * math.pi * 200 * i / sr)))+ buf += b"\x00\x00" * int(sr * silence_s)+ w.writeframes(bytes(buf))+ w.close()+++class EnergySnapTests(unittest.TestCase):+ def setUp(self):+ self.wav = tempfile.mktemp(suffix=".wav")+ _make_wav(self.wav)++ def tearDown(self):+ if os.path.exists(self.wav):+ os.remove(self.wav)++ def test_voiced_interval_detected(self):+ iv = _voiced_intervals(self.wav)+ self.assertTrue(iv)+ self.assertAlmostEqual(iv[0][0], 0.0, delta=0.05)+ self.assertAlmostEqual(iv[-1][1], 1.0, delta=0.1)++ def test_trailing_word_pulled_out_of_silence(self):+ words = [+ {"word": "hello", "start": 0.1, "end": 0.5},+ {"word": "world", "start": 1.55, "end": 1.95},+ ]+ out = _snap_words_to_voiced(words, self.wav)+ self.assertEqual(out[0]["start"], 0.1) # word over speech untouched+ self.assertLessEqual(out[1]["start"], 1.2) # stranded word clamped back+ # a word clamped to the upper bound must keep positive duration+ for w in out:+ self.assertGreater(w["end"], w["start"])++ def test_all_silence_leaves_words_unchanged(self):+ silent = tempfile.mktemp(suffix=".wav")+ _make_wav(silent, voiced_s=0.0, silence_s=1.0)+ words = [{"word": "x", "start": 0.1, "end": 0.5}]+ try:+ self.assertEqual(_snap_words_to_voiced(words, silent), words)+ finally:+ os.remove(silent)+++if __name__ == "__main__":+ unittest.main()