diff --git a/.claude/skills/open-edit/scripts/preflight.sh b/.claude/skills/open-edit/scripts/preflight.sh
index 45a0c32..af18ed9 100755
--- a/.claude/skills/open-edit/scripts/preflight.sh
+++ b/.claude/skills/open-edit/scripts/preflight.sh
@@ -6,9 +6,12 @@
set -uo pipefail
# GUI-launched agents inherit a minimal PATH that commonly omits Homebrew. Add both standard
-# prefixes before probing node; preserve the caller's remaining PATH.
+# prefixes before probing node — but AFTER the caller's own PATH, never ahead of it. A Homebrew npm
+# keeps its own global directory, so an npx taken from there cannot see a CLI installed by whichever
+# npm the caller is using: it fetches a published copy and silently runs that instead of the one the
+# caller set up.
HOMEBREW_PATH_PREFIX="${OPEN_EDIT_HOMEBREW_PATH_PREFIX-/opt/homebrew/bin:/usr/local/bin}"
-export PATH="${HOMEBREW_PATH_PREFIX:+$HOMEBREW_PATH_PREFIX:}$PATH"
+export PATH="$PATH${HOMEBREW_PATH_PREFIX:+:$HOMEBREW_PATH_PREFIX}"
if ! command -v node >/dev/null 2>&1; then
MODE=""
diff --git a/.github/README.md b/.github/README.md
new file mode 100644
index 0000000..c2d087a
--- /dev/null
+++ b/.github/README.md
@@ -0,0 +1,173 @@
+
+
+
+
+
+
+
+Video editing for coding agents. Describe the edit; get the MP4.
+
+
+
+
+
+ Get started ·
+ Prompts ·
+ Examples ·
+ VEED
+
+
+OpenEdit is an open-source, agent-driven editing pipeline. There is no GUI and no timeline: you tell
+your coding agent what you want, and it transcribes, designs, renders and hands you the file.
+
+## Get started
+
+You need an Apple Silicon Mac (with Homebrew) or a Windows x64 PC, Git, Node 20 or newer, and one of
+Claude Code, Codex or Gemini CLI. From your project folder, install the skill into your agent:
+
+```sh
+npx skills add veedstudio/open-edit --skill open-edit
+```
+
+Then open the agent (`claude`, `codex` or `gemini`) and ask:
+
+```
+Add subtitles to my video clip.mp4
+```
+
+The first run sets itself up: it checks for Git, Node, pnpm and ffmpeg and names the command for
+anything missing (Homebrew or corepack on a Mac; on Windows the commands are printed for you to run,
+and ffmpeg is fetched into your user folder with no admin rights), asking before any global install;
+clones its runtime into `.open-edit/` inside your project and registers a session hook in the settings
+of Claude Code, Codex and Gemini CLI; downloads the renderer into your user's app-data folder; and asks
+once how you want speech transcribed. Hosted by VEED
+transcribes best (a veed.io account, [sign up](https://www.veed.io/signup) or
+[log in](https://www.veed.io/login); the free tier covers about ten minutes a month); WhisperX runs
+locally for free (needs `uv` or `pipx`; the first transcription downloads the model, about 2 GB for the
+fast tier and more for the better one; nothing leaves your machine); or bring your own service. When the
+run finishes you get the MP4 with subtitles burned in, a preview open in your browser, and the path to
+the file, which lives under `.open-edit/` in your project.
+
+/transcript.json`, and per-word timings are
+required: without them the caption reveals drift, so a transcript that has none is refused rather than
+rendered badly.
+
+## Requirements
+
+| | |
+| --- | --- |
+| Platform | Apple Silicon Mac or Windows x64 PC. Intel Macs are not supported: the renderer ships macOS-arm64 and windows-x64 only |
+| macOS | Built and tested on Tahoe 26.0. Nothing checks the version, so earlier releases may work, untested |
+| Windows | Windows 10 or newer (the installer extracts with the bundled `tar`). Git and Node via winget, pnpm via corepack or npm: preflight prints the exact commands and never runs them itself. ffmpeg is fetched into your user folder for you, no admin rights needed |
+| Linux | Planned; prioritisation depends on demand |
+| Agents | Claude Code, Codex or Gemini CLI. The installed skill prepares the runtime and loads its `AGENTS.md` instructions itself |
+
+## Scope and limitations
+
+V1 targets captions. Motion graphics, charts, and brandbook-matched styling render today, but are less
+exercised than captions and should be expected to have rough edges.
+
+Report defects through GitHub issues.
+
+## License
+
+The editor is licensed under Apache-2.0. The renderer binaries are distributed under PolyForm Shield
+1.0.0, which permits commercial use of the videos you produce with no payment to VEED. See `LICENSE`
+and `NOTICE` for the full terms.
+
+---
+
+OpenEdit · powered by VEED
diff --git a/.gitignore b/.gitignore
index 769ec82..0ee0940 100644
--- a/.gitignore
+++ b/.gitignore
@@ -51,3 +51,9 @@ __pycache__/
# Engine probe renders — regenerable output of the probe harness
internal/motion/probes/*/probe.mp4
.ffmpeg/
+# Compiled content — emitted in place by `node cli/scripts/build.mjs --content`. The packer does this
+# in its own copy of the tree; a working checkout stays .ts-only so nothing stale can shadow an edit.
+refs/html/**/*.js
+pipeline/**/*.js
+veed/args.js
+internal/packaging/out/
diff --git a/AGENTS.md b/AGENTS.md
index 0fcad36..0e261e9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -89,7 +89,11 @@ fast-path/refinement switch.
restores a single source track and levels whichever track it is given to the delivery loudness; this
is what a film needs instead.
- `veed/` — VEED-native transcription + login (one writer of `transcript.json`; real per-word timings), plus Fabric generation and video background removal on the same login. `npx @veedstudio/openedit-cli background-removal` reaches the live free VEED route by default, or fal's own `--fast` model when that variant is wanted; `npx @veedstudio/openedit-cli lipsync` (video + new audio -> re-lipsynced video) has no VEED-hosted route at all and always goes through fal. Both fal-charged paths still use the VEED login to host the local file for a URL, but the generation call itself bills the user's own fal key (the CLI's fal BYOK rail), never a VEED workspace. `npx @veedstudio/openedit-cli prep` — `meta.json` + `word-timings.json` + base frames (needs a transcript from any provider). `refs/` — `html/` refs + `tags.json` (v3, the RUNTIME INDEX — recipes only, facet taxonomy, `fit` = aspect SOT) + per-ref `recipe.md` (the prose recipe sheet a compiled recipe is derived from — the fast path runs the compiled module, never the sheet; the creative pass reads sheets as craft substrate and REMIX donors).
-- `config.ts` — all machine paths (ffmpeg / ffprobe / veed-engine). `docs/` — FLOW (orchestration) · recipe-format (the recipe law). Engine support matrix = the `feature-support.md` asset downloaded with the engine release into `.veed-engine/` (not vendored here).
+- `cli/src/config.ts` — the machine paths the CLI resolves (ffmpeg / ffprobe / the engine), and the two roots
+ it keeps apart: the CONTENT it reads (recipes, gates, brief — the package's own tree unless `OPEN_EDIT_ROOT`
+ names a directory that really carries `refs/tags.json`) and the WORKSPACE it writes (`runs/`, the recorded
+ provider choice). A checkout also has a top-level `config.ts` of its own, reading the same env vars, for the
+ substrate scripts that run outside the CLI. `docs/` — FLOW (orchestration) · recipe-format (the recipe law). Engine support matrix = the `feature-support.md` asset downloaded with the engine release into `.veed-engine/` (not vendored here).
## Hard rules (do not drift — these protect output quality)
- Recipe runs are **deterministic** — the generate-recipe command is the only writer of the final .wv document; never
diff --git a/NOTICE b/NOTICE
index d8b25a6..cddd860 100644
--- a/NOTICE
+++ b/NOTICE
@@ -18,6 +18,20 @@ The installer places a copy of those terms alongside the binary at
`.veed-engine/LICENSE-binary.md`. The canonical copy is `LICENSE-binary.md` in
the releases repository above.
+This project embeds woff2 subsets of two fonts in the login-success page, each
+licensed under the SIL Open Font License, Version 1.1
+(https://openfontlicense.org):
+
+ Inter — Copyright (c) 2016 The Inter Project Authors
+ (https://github.com/rsms/inter)
+
+ STIX Two Text — Copyright (c) 2001-2023 by the STI Pub Companies
+ (https://github.com/stipub/stixfonts)
+
+The full license text accompanies each upstream project at the URLs above.
+
+---
+
Transcription in this project is performed against the VEED service, which
requires a VEED account and credits. Use of that service is governed by VEED's
terms, separately from this project's license.
diff --git a/README.md b/README.md
index bf590a9..2afa28c 100644
--- a/README.md
+++ b/README.md
@@ -1,200 +1,282 @@
-
-
-
-
-
-
+# @veedstudio/openedit-cli
-Not the editor you rent, but the one you own.
+The Open Edit command-line tool: agent-driven video creation and editing,
+powered by VEED.
-
-
+The package carries the content it runs on — the recipe pool, the director's
+brief, the design substrate and the gates — so a fresh install can draw a style,
+build a document and gate it without cloning anything. The source is public at
+[veedstudio/open-edit](https://github.com/veedstudio/open-edit), whose README
+covers what Open Edit is and what it makes; this page is the command surface.
-
- Install ·
- Usage ·
- Examples ·
- VEED
-
+## Usage
-OpenEdit is an open-source, agent-driven editing pipeline that ships with VEED's HTML renderer — closed
-source, but free to use.
+```sh
+npx @veedstudio/openedit-cli --help
+```
-There is no GUI and no timeline. The pipeline is driven entirely through your coding agent — edit,
-cut, and reframe footage; layer motion graphics and visual elements; turn slides or websites into
-video; capture web pages; and pull in any [AI video/image generator](https://www.veed.io/tools/ai-video)
-or MCP server when it helps. Source video is optional: stills, slides, generated media, or pure
-motion graphics are enough when the brief calls for it. Be creative and fluid — try new ideas
-rather than collapsing every ask onto captions.
+## Commands
-OpenEdit edits footage. Supply your own source files, or ask it to generate a talking-head clip with
-[VEED Fabric](https://www.veed.io/ai/fabric-1-0) when you have none — that spends credits, and never
-without your approval.
+### login
-/transcript.json`. There is no default
+provider — the choice is the user's, recorded once with `--record`. Locally with
+WhisperX (free, offline, nothing billed anywhere):
-## Usage
-Open your coding agent. For example, with Claude Code:
```sh
-claude
+npx @veedstudio/openedit-cli transcribe video.mp4 [...] [--model medium] [--language de] [--force]
```
-then ask it:
-```
-Add subtitles to my video [VIDEO]
+A transcript already on disk is left alone (it may have been retimed onto an
+edit); `--force` transcribes it again.
+
+Or hosted by VEED (premium quality; requires the one-time `login`, and spends
+the workspace's VEED transcription credits — `--workspace ` names which,
+required only when the account has several):
+
+```sh
+npx @veedstudio/openedit-cli transcribe --provider veed video.mp4 [...]
```
-The agent will automatically transcribe your video, analyse the transcript, create a suitable design for your video, and then render it.
+`--record [--model ]` records the transcription
+provider choice in `.open-edit-prefs.json` instead of running anything.
-After 1-3 minutes, the agent will return your video with subtitles burned in, as well as launch a video previewer. It will also tell you where to find the final MP4.
+### whisper
-You can then ask the agent for subtitle amendments, for example:
+Map a Whisper-family JSON produced by your own service (WhisperX,
+openai-whisper, whisper-timestamped, mlx-whisper, whisper.cpp `-oj -ml 1`, or
+the OpenAI API's `verbose_json` with word granularity) into the same
+`runs//transcript.json`:
+```sh
+npx @veedstudio/openedit-cli whisper transcription.json media.mp4 [...] [--force]
```
-I don't like the yellow colour, make it darker
-Move the text up a bit
+Word timestamps are required; the media argument may be a video or an audio
+file.
-When he says "go buy it now", make sure the 'now' really stands out.
-```
+### prep
-You can also hand the agent a reference image to copy a style from:
+Probe the source canvas, synthesize `word-timings.json` from the transcript's
+real per-word times, and cut one base frame per beat (the transcript must
+already exist):
-```
-Add subtitles that look like this [IMG-REF], to my video [VIDEO]
+```sh
+npx @veedstudio/openedit-cli prep video.mp4 [...]
```
-## Examples
+### synth-timings
-Real outputs, each with the prompt that produced it. Click any example to watch it with sound.
+Even-split word reveal delays for a single beat window:
+```sh
+npx @veedstudio/openedit-cli synth-timings --start 1.2 --end 3.4 --words "A B C" [--out file.json]
```
-create viral subtitles with /open-edit and translate my video to 5 languages using VEED Lipsync 2.0 on Fal
+
+### generate / generate-set / sample-presenter
+
+Fabric generation — source footage from a script, when there is no video to
+caption. Generating spends TWO of the named workspace's allowances — AI
+Playground credits for the video and text-to-speech seconds for the voice — so
+it is two commands: the first quotes both and records the approval, the second
+spends exactly what was approved (no `--script` on the spend pass — the
+recorded, hashed script is what bills):
+
+```sh
+npx @veedstudio/openedit-cli generate --script "spoken words" --key my-run --workspace
+npx @veedstudio/openedit-cli generate --key my-run --yes
```
-One source clip, three languages, three caption styles — translated and re-lipsynced through
-[VEED's Lip Sync API](https://www.veed.io/tools/lip-sync-api):
+`--resume` collects a job already created and paid for; `--abandon `
+clears one abandoned charge record. `generate-set --shots shots.json` covers
+several shots under one approval, and `sample-presenter` proposes a
+deterministic character/voice pair for a run key (listing costs nothing).
+
+### background-removal / lipsync
-| Spanish | French | German |
-| --- | --- | --- |
-| [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/happy3-ES-078.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/remix-FR.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/happy2-DE-lowerthird.mp4) |
+Remove a video's background (VEED's free route by default; `--fast` uses a fal
+model billed to your own fal key), or re-lipsync a video to a new audio track
+(always fal-billed). Both use the VEED login only to host the local file:
+```sh
+npx @veedstudio/openedit-cli background-removal video.mp4 [--fast] [--mask-only] [--out ]
+npx @veedstudio/openedit-cli lipsync video.mp4 narration.mp3 [--out ]
```
-generate 3 viral hooks in Seedance 2.0 on Fal and create dynamic motion graphics using /open-edit
+
+The fal key comes from `FAL_KEY`, or `OPEN_EDIT_FAL_KEY_FILE` pointing at a
+file that holds it.
+
+### install-engine
+
+Download the veed render engine (checksum-verified, from its public GitHub
+releases) into the app-data dir, or upgrade an existing install:
+
+```sh
+npx @veedstudio/openedit-cli install-engine [weave-v]
```
-Three hooks generated with [Seedance](https://www.veed.io/tools/ai-video/seedance), three
-motion-graphic treatments:
+`VEED_ENGINE_BIN` overrides where the engine is looked for. The binary is
+licensed separately (PolyForm Shield); its license installs beside it.
+
+### install-ffmpeg / install-whisperx
-| | | |
-| --- | --- | --- |
-| [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/news-comic.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/chair-remix.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/makeup-happy-v2.mp4) |
+The other two installers. `install-ffmpeg` checks for a working FFmpeg first
+(`VEED_ENGINE_FFMPEG`, then PATH, then a previous install) and only downloads
+when nothing works — a checksum-verified static build into the app-data dir
+(the download route is Windows-only; macOS points at `brew install ffmpeg`).
+`install-whisperx` installs the local transcription provider into an isolated
+uv/pipx tool environment; it never touches the system Python.
+```sh
+npx @veedstudio/openedit-cli install-ffmpeg [--check|--force]
+npx @veedstudio/openedit-cli install-whisperx []
```
-use Figma MCP to study my BrandBook and create branded campaign graphics using /open-edit
+
+### mux-audio / mix-audio
+
+Put sound on a render. `mux-audio` lays a run's source audio (or `--audio
+`) onto its silent render, levelled to -14 LUFS / -1 dBTP (`--no-loudnorm`
+keeps the source level; the line it prints says which correction ran);
+`mix-audio` first builds one track from many pieces — narration, music,
+effects — per the run's mix spec, with music ducked under the voice:
+
+```sh
+npx @veedstudio/openedit-cli mix-audio runs/ # → runs//audio/mix.m4a
+npx @veedstudio/openedit-cli mux-audio runs/ --audio runs//audio/mix.m4a
```
-One brand book, three campaign cards:
+### wcag-pass
-| | | |
-| --- | --- | --- |
-| [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/race-card-1.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/race-card-2.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/race-card-4.mp4) |
+Contrast-audit a rendered run through the engine's bundled analyzer, and (with
+`--apply`) promote the remediated template after re-verifying it:
-## Renderer
+```sh
+npx @veedstudio/openedit-cli wcag-pass --run runs/ [--apply]
+```
+
+Needs the installed engine (`install-engine`). `WCAG_REMEDIATE` can point at a
+replacement remediation applier; by default the bundled one runs as its own
+plain-node process.
-Caption styles are authored in HTML and CSS. Rendering does not use a headless browser: there is no
-browser to install, launch, or keep alive for the duration of a render.
+### gates / expect-windows
-Internal benchmarks measured the renderer up to 2.2x faster than Chrome-driven renderers. These
-measurements are preliminary and not yet reproducible outside VEED; a documented benchmark and its
-methodology will follow.
+The whole gate chain — design → lint → verify → wcag → record → probe → mux —
+as one command over a run directory (run it outside any sandbox; rendering
+needs a real desktop session):
-The renderer is integrated but not required. Composition does not depend on it, so Chrome can be used
-as the render backend instead.
+```sh
+npx @veedstudio/openedit-cli gates runs/ [--doc ] [--audio ] [--no-loudnorm]
+```
-## Transcription
+`expect-windows` derives the `verify.expect` timing assertions from a
+document's own gates (`--write` stamps them into the manifest); the chain runs
+it automatically. The design and lint gates come from the content this package
+carries, so they run with no checkout; `OPEN_EDIT_ROOT` pointed at one replaces
+them with that checkout's.
-OpenEdit asks once which provider to use and records the answer at the runtime root
-(`.open-edit-prefs.json`); it does not ask again. Every provider writes the same file —
-`runs//transcript.json`, with real per-word timings — and nothing downstream can tell which one ran.
+### Editing and QA tools
-**VEED** — best quality, and the default workflow. Requires a VEED account; usage limits are your
-account's, and a free account covers about 10 minutes of transcription a month, beyond which it needs a
-[plan](https://www.veed.io/pricing). The audio track is uploaded and stored in order to transcribe it; the
-video is not uploaded. By default OpenEdit does not create a VEED project. The agent guides the one-time
-browser login and stores a refreshable token in the platform's per-user app-data directory.
+The remaining pipeline tools, each a direct port of its script:
```sh
-npx @veedstudio/openedit-cli login
-npx @veedstudio/openedit-cli transcribe --provider veed /path/to/video.mp4
+npx @veedstudio/openedit-cli concat-chapters --doc chapters/act-1 --doc chapters/act-2
+npx @veedstudio/openedit-cli concat-videos [--canvas WxH] [--fit letterbox|crop|open] [...]
+npx @veedstudio/openedit-cli cut-frames [--json] # frames at every shot boundary
+npx @veedstudio/openedit-cli scene-frames # stills for a clip with no beats
+npx @veedstudio/openedit-cli scoped-edit [--allow ]...
+npx @veedstudio/openedit-cli brand --file [--brief] [--check]
+npx @veedstudio/openedit-cli creative-log --for [--reject "…" --why "…"] [--brief]
```
-**WhisperX** — free, local and offline; nothing leaves your machine. Installed on request, and the first
-run also downloads a model. Runs on CPU by default, with two quality tiers; a CUDA-capable box can
-override via `OPEN_EDIT_WHISPERX_DEVICE` / `OPEN_EDIT_WHISPERX_COMPUTE`.
+The cut tools, for an edit made before captioning: measure where speech starts,
+stops and pauses; assemble the kept ranges of an EDL (edit decision list) in one
+encode with crossfaded joins, each range snapped to the frame grid; and move the
+per-word timings you already have onto that timeline instead of transcribing the
+cut again. `--gap` and `--crossfade` are milliseconds; the EDL is seconds.
```sh
-npx @veedstudio/openedit-cli install-whisperx # on request, once
-npx @veedstudio/openedit-cli transcribe /path/to/video.mp4 # --model medium for the better tier
+npx @veedstudio/openedit-cli speech-probe [--range a:b] [--gap 250] [--window 10] [--json]
+npx @veedstudio/openedit-cli apply-edl --edl edl.json --out cut.mp4 [--crossfade 40] [--crf 20]
+npx @veedstudio/openedit-cli retime-transcript --edl edl.json --out /runs/cut/transcript.json
```
-**Your own service** — produce a Whisper-family JSON however you like (WhisperX, openai-whisper,
-whisper-timestamped, mlx-whisper, the OpenAI API with `timestamp_granularities=["word"]`, or whisper.cpp
-`-oj`) and map it. No credentials pass through OpenEdit.
+The retimed transcript goes where `prep` reads, `runs//` under the runtime
+root, so `prep cut.mp4` finds it and the cut is never transcribed.
+
+### stills / preview
+
+`stills` fetches licensed pictures from Wikimedia Commons, recording each
+file's terms beside it (`search` / `show` / `save`). `preview` serves a
+read-only localhost page for a run — scrub the footage, follow the transcript,
+and the player swaps to the new render when it lands:
```sh
-npx @veedstudio/openedit-cli whisper transcription.json /path/to/video.mp4
+npx @veedstudio/openedit-cli stills search "berlin skyline" --limit 10
+npx @veedstudio/openedit-cli preview runs/
```
-Per-word timings are required whichever provider you use: without them the caption reveals drift out of
-sync with the audio, so a transcript that has none is refused rather than rendered badly.
+### init / readiness
-## Scope and limitations
+`init` is the workspace setup: it checks the machine dependencies (git, Node,
+pnpm, ffmpeg), clones the Open Edit runtime when the workspace isn't already a
+checkout, installs its pinned dependencies, and verifies the render engine.
+Bare `init` applies only safe, workspace-local setup; `--dry` reports without
+writing; `--auto-approve` also applies machine-global installs and clean
+updates, and is only for after a person has approved every reported action.
+Exit 10 means something is awaiting that approval; on success the workspace
+root is printed on stdout.
-V1 targets captions. Motion graphics, charts, and brandbook-matched styling render today, but are less
-exercised than captions and should be expected to have rough edges.
+```sh
+npx @veedstudio/openedit-cli init --dry --workspace
+npx @veedstudio/openedit-cli init --workspace
+```
-Report defects through GitHub issues.
+`readiness` reports what is present vs missing for a run — read-only, no
+network — and exits 1 when a blocking item is missing.
-## License
+## Configuration
-The editor is licensed under Apache-2.0. The renderer binaries are distributed under PolyForm Shield
-1.0.0, which permits commercial use of the videos you produce with no payment to VEED. See `LICENSE`
-and `NOTICE` for the full terms.
+| Environment variable | Effect |
+| --- | --- |
+| `VEED_ORIGIN` | Overrides the default `https://www.veed.io` origin. |
+| `OPENEDIT_STATE_DIR` | Overrides where login state is stored. |
+| `OPEN_EDIT_ROOT` | Where `runs//` outputs and `.open-edit-prefs.json` are written (default: the app-data directory below). Pointed at an Open Edit checkout it also replaces the bundled content, so the CLI runs that checkout's recipes and gates instead. |
+| `VEED_ENGINE_FFMPEG` / `VEED_ENGINE_FFPROBE` | ffmpeg/ffprobe binaries (default: `PATH`; ffprobe defaults beside a configured ffmpeg). |
+| `WHISPERX_BIN` / `WHISPERX_MODEL` | WhisperX binary and fallback model tier (defaults: `whisperx` on `PATH`, `small.en`). |
+| `OPEN_EDIT_WHISPERX_DEVICE` / `OPEN_EDIT_WHISPERX_COMPUTE` | WhisperX device/compute (defaults: `cpu`/`int8`). |
+
+Login state lives in the platform's per-user app-data directory:
+`~/Library/Application Support/veed-openedit` on macOS, `%APPDATA%\veed-openedit`
+on Windows, and `$XDG_CONFIG_HOME/veed-openedit` (default `~/.config/veed-openedit`)
+on Linux.
----
+## License
-OpenEdit · powered by VEED
+Apache-2.0. See the bundled `LICENSE` and `NOTICE` files.
diff --git a/SETUP.md b/SETUP.md
index f1fd34b..cdfb304 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -37,7 +37,7 @@ Init has three modes: bare applies safe local setup, `--dry` reports without wri
4. **A transcription provider** — the skill asks once and remembers the answer. Either
**VEED** (`npx @veedstudio/openedit-cli login`, one-time OAuth, ~30-day refreshable token; a free account
covers about 10 minutes a month) or **WhisperX** locally (`npx @veedstudio/openedit-cli install-whisperx`,
- free and offline). You can also point it at your own service. See `README.md`.
+ free and offline). You can also point it at your own service. See `.github/README.md`.
5. **VEED credits.** **VEED transcription consumes VEED credits** (WhisperX runs locally on your
machine; your own service is billed by whoever provides it). Separately, with no source video the skill can GENERATE a talking-head clip
(`npx @veedstudio/openedit-cli generate`), which spends a workspace's AI Playground credits. **Fabric reuses VEED
diff --git a/cli/scripts/build.mjs b/cli/scripts/build.mjs
new file mode 100644
index 0000000..824a11d
--- /dev/null
+++ b/cli/scripts/build.mjs
@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+// Builds the package: cli/src -> cli/dist, and with --content the content tree's .ts -> .js in place.
+//
+// Content is compiled ONLY when asked, because a checkout that carries both .ts and .js gets a stale
+// .js shadowing an edited .ts on the next run, silently. The packer asks for it in its own copy of
+// the tree; nobody needs it here.
+//
+// node cli/scripts/build.mjs [--content] [--root ]
+//
+// --root builds a DIFFERENT copy of the tree. The packer uses it to build its pristine export while
+// resolving tsc through this checkout's node_modules, which the export does not carry.
+import { chmodSync, cpSync, existsSync, mkdirSync, copyFileSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const rootFlag = process.argv.indexOf('--root');
+const ROOT = rootFlag === -1 ? fileURLToPath(new URL('../..', import.meta.url)) : resolve(process.argv[rootFlag + 1]);
+
+// Resolved through node rather than assumed at node_modules/.bin, so a temp copy of the tree with no
+// node_modules of its own still builds against the checkout that invoked it.
+const TSC = join(dirname(createRequire(import.meta.url).resolve('typescript/package.json')), 'bin', 'tsc');
+
+function tsc(project) {
+ const r = spawnSync(process.execPath, [TSC, '-p', join(ROOT, project)], { stdio: 'inherit', cwd: ROOT });
+ if (r.status !== 0) throw new Error(`build: tsc -p ${project} failed`);
+}
+
+/**
+ * Every ref in the runtime index must import and expose the generator shape. A recipe that throws on
+ * import, or that lost its default export in a refactor, is a run that fails at the last gate before
+ * the render — after the transcript, the frames and the style draw are all already paid for.
+ */
+async function assertRecipesLoad(root) {
+ const index = JSON.parse(readFileSync(join(root, 'refs', 'tags.json'), 'utf8'));
+ const refs = Array.isArray(index) ? index : index.refs;
+ // An index shape this cannot read must stop the build. Reading it as an empty pool would report
+ // success having checked nothing, which is the one outcome worse than a failure here.
+ if (!Array.isArray(refs) || refs.length === 0) {
+ throw new Error(`build: refs/tags.json under ${root} is not a runtime index this understands`);
+ }
+ for (const { id } of refs) {
+ const file = join(root, 'refs', 'html', id, 'recipe.js');
+ if (!existsSync(file)) throw new Error(`build: ${id}/recipe.js was not emitted`);
+ const mod = await import(pathToFileURL(file).href);
+ const recipe = mod.default;
+ if (!recipe || typeof recipe.generate !== 'function') throw new Error(`build: ${id}/recipe.js has no default export with a generate()`);
+ if (recipe.refId !== id) throw new Error(`build: ${id}/recipe.js declares refId ${JSON.stringify(recipe.refId)}`);
+ }
+ return refs.length;
+}
+
+tsc('cli/tsconfig.build.json');
+
+// The bin entry is executed directly by npm's shim, and tsc does not carry the mode across.
+chmodSync(join(ROOT, 'cli', 'dist', 'cli.js'), 0o755);
+
+// Static assets tsc does not know about: the OAuth landing page and the preview UI.
+mkdirSync(join(ROOT, 'cli', 'dist', 'veed'), { recursive: true });
+copyFileSync(join(ROOT, 'cli', 'src', 'veed', 'login-success.html'), join(ROOT, 'cli', 'dist', 'veed', 'login-success.html'));
+cpSync(join(ROOT, 'cli', 'src', 'preview', 'page'), join(ROOT, 'cli', 'dist', 'preview', 'page'), { recursive: true });
+
+if (process.argv.includes('--content')) {
+ tsc('tsconfig.content.json');
+ const n = await assertRecipesLoad(ROOT);
+ console.log(`build: cli/dist + content (${n} recipes load)`);
+} else {
+ console.log('build: cli/dist');
+}
diff --git a/cli/src/args.ts b/cli/src/args.ts
new file mode 100644
index 0000000..dc8a0be
--- /dev/null
+++ b/cli/src/args.ts
@@ -0,0 +1,65 @@
+// Strict flag parsing for every command that reads flags from a shell. node:util's
+// parseArgs is strict by default — an unrecognised flag, a flag missing its value, and
+// a stray positional are each an error — and callers may not turn that off: a lenient
+// parser silently mis-parses, which is exactly what this wrapper exists to stop. It
+// adds the one thing parseArgs does not: naming the valid flags, because "Unknown
+// option '--stile'" alone leaves someone guessing at the spelling of the one they meant.
+import { parseArgs, type ParseArgsConfig } from 'node:util';
+
+export function parseFlags(config: T & { strict?: never }) {
+ try {
+ return parseArgs(config);
+ } catch (cause) {
+ const flags = Object.keys(config.options ?? {}).sort().map((name) => `--${name}`);
+ const valid = flags.length > 0 ? `Valid flags: ${flags.join(' ')}` : 'This command takes no flags.';
+ throw new Error(`${(cause as Error).message}\n${valid}`, { cause });
+ }
+}
+
+// Named for what the value IS: "expected a number" without the value it found cannot be diagnosed from
+// the message alone, and this is the message a user reads instead of getting their result.
+export function describeValue(value: unknown): string {
+ if (value === undefined) return 'absent';
+ if (typeof value === 'string') return `the string ${JSON.stringify(value)}`;
+ if (typeof value === 'object') return value === null ? 'null' : JSON.stringify(value);
+ return String(value);
+}
+
+// --key and a session id each name a path segment under runs/, so both are fenced the same way: anything
+// that could climb out of the directory (a separator, a `..`, a leading dash) is refused rather than
+// normalised, because a silently relocated read or write is worse than an error.
+function assertSafeSegment(value: string, invalid: (v: string) => string): string {
+ if (!/^[A-Za-z0-9._-]+$/.test(value) || value === '.' || value === '..' || value.startsWith('-')) {
+ throw new Error(invalid(value));
+ }
+ return value;
+}
+
+export function assertSafeKey(key: string): string {
+ return assertSafeSegment(key, (k) =>
+ `invalid --key "${k}": use a single path segment of letters, digits, dot, dash or underscore (it names a directory under runs/)`,
+ );
+}
+
+export function assertSafeSessionId(sessionId: string): string {
+ return assertSafeSegment(sessionId, (id) =>
+ `invalid session id "${id}": use letters, digits, dot, dash or underscore (it names a charge record under runs//)`,
+ );
+}
+
+/**
+ * A numeric flag with a default, refused by name when it is not a usable number. An empty value
+ * (`--crf=`) is refused too: `Number('')` is 0, which would read as a selection nobody made.
+ */
+export function numberFlag(
+ flag: string,
+ raw: string | undefined,
+ fallback: number,
+ accept: (n: number) => boolean,
+ wants: string,
+): number {
+ if (raw === undefined) return fallback;
+ const n = raw.trim() === '' ? NaN : Number(raw);
+ if (!Number.isFinite(n) || !accept(n)) throw new Error(`--${flag} wants ${wants}, e.g. --${flag} ${fallback}`);
+ return n;
+}
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
new file mode 100644
index 0000000..af5bd04
--- /dev/null
+++ b/cli/src/cli.ts
@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { createRequire } from "node:module";
+import { login } from "./commands/login.ts";
+import { token } from "./commands/token.ts";
+import { transcribe } from "./commands/transcribe.ts";
+import { whisper } from "./commands/whisper.ts";
+import { prep } from "./commands/prep.ts";
+import { synthTimings } from "./commands/synth-timings.ts";
+import { generate } from "./commands/generate.ts";
+import { generateSet } from "./commands/generate-set.ts";
+import { samplePresenterCommand } from "./commands/sample-presenter.ts";
+import { backgroundRemoval } from "./commands/background-removal.ts";
+import { lipsync } from "./commands/lipsync.ts";
+import { installEngine } from "./commands/install-engine.ts";
+import { installFfmpeg } from "./commands/install-ffmpeg.ts";
+import { installWhisperx } from "./commands/install-whisperx.ts";
+import { muxAudio } from "./commands/mux-audio.ts";
+import { mixAudio } from "./commands/mix-audio.ts";
+import { wcagPass } from "./commands/wcag-pass.ts";
+import { gates } from "./commands/gates.ts";
+import { expectWindows } from "./commands/expect-windows.ts";
+import { generateRecipe } from "./commands/generate-recipe.ts";
+import { sampleStyleCommand } from "./commands/sample-style.ts";
+import { probeQaCommand } from "./commands/probe-qa.ts";
+import { scopedEdit } from "./commands/scoped-edit.ts";
+import { brandCommand } from "./commands/brand.ts";
+import { creativeLog } from "./commands/creative-log.ts";
+import { concatChapters } from "./commands/concat-chapters.ts";
+import { concatVideosCommand } from "./commands/concat-videos.ts";
+import { sceneFrames } from "./commands/scene-frames.ts";
+import { cutFrames } from "./commands/cut-frames.ts";
+import { speechProbe } from "./commands/speech-probe.ts";
+import { applyEdl } from "./commands/apply-edl.ts";
+import { retimeTranscript } from "./commands/retime-transcript.ts";
+import { stillsCommand } from "./commands/stills.ts";
+import { preview } from "./commands/preview.ts";
+import { main as initMain } from "./commands/init.ts";
+import { sessionStart } from "./commands/session-start.ts";
+import { readiness } from "./commands/readiness.ts";
+import { lint } from "./commands/lint.ts";
+import { designGate } from "./commands/design-gate.ts";
+import { contentRootCommand } from "./commands/content-root.ts";
+
+// package.json sits two levels above both src/ (dev via tsx) and dist/ (published build): the
+// package root is the repository root.
+const pkg = createRequire(import.meta.url)("../../package.json") as {
+ name: string;
+ version?: string;
+};
+
+const HELP = `Usage: openedit [options]
+
+Commands:
+ login Log in with VEED (opens a browser; --manual to paste the redirect instead)
+ token Print a valid VEED access token for a pipe, refreshing if stale; masked when printed
+ to a terminal (--path prints the store location)
+ transcribe Transcribe videos: WhisperX locally by default, or --provider veed for VEED's hosted
+ transcription (--record records the choice; --force redoes an existing transcript)
+ whisper Map a Whisper-family JSON your own service produced into runs//transcript.json (--force replaces one)
+ prep Probe canvas, synthesize word timings, and cut base frames for source videos
+ synth-timings Even-split word reveal delays for one beat window (the creative-pass fallback)
+ generate Fabric generation, two passes: --script quotes and records the approval; --yes spends it
+ generate-set One approval covering several shots (--shots shots.json)
+ sample-presenter Seeded, deterministic Fabric presenter proposal for a run key
+ background-removal Remove a video's background (free VEED route; --fast bills your own fal key)
+ lipsync Re-lipsync a video to new audio (bills your own fal key; VEED login only hosts the files)
+ install-engine Download and verify the render engine into the app-data dir (optional release tag)
+ install-ffmpeg Install FFmpeg if nothing works already: env override → PATH → app-data download (Windows)
+ install-whisperx Install WhisperX into an isolated uv/pipx environment (optional version pin)
+ mux-audio Mux a run's audio onto its silent render at delivery loudness (--audio ; --no-loudnorm)
+ mix-audio Build one soundtrack from a run's mix spec (narration/music/sfx, with ducking)
+ wcag-pass Contrast-audit a rendered run via the engine's analyzer (--apply promotes the remediation)
+ gates THE gate chain: design → lint → verify → wcag → record → probe → mux, one command
+ lint Run the engine-limit gate on one document (--json)
+ design-gate Read a run's documents back against its own design system (--doc , --json)
+ content-root Print the content tree this CLI resolves to (recipes, briefs, gates)
+ expect-windows Derive verify.expect timing assertions from a document's own gates (--write stamps them)
+ generate-recipe Run a workspace's compiled recipe for a sampled style, then drive the gate chain
+ sample-style Facet-scored, seeded style draw from the workspace's runtime index → style.json
+ probe-qa Frame QA of a recorded run vs its source footage
+ scoped-edit Prove an edit stayed inside its stated scope (baseline vs candidate .wv)
+ brand Validate a brand.json (--brief prints the design brief it implies)
+ creative-log Record accepted/rejected looks per footage, so a later pass knows what to avoid
+ concat-chapters Stream-copy a film's gated chapters into one deliverable
+ concat-videos Re-encode clips that disagree onto one canvas (--fit letterbox|crop|open)
+ scene-frames Stills for a clip with no beats
+ cut-frames Frames at every shot boundary (--json for the cut list)
+ speech-probe Measured speech onset, decay and safe cut gaps for a clip or a range (--json)
+ apply-edl Assemble the kept ranges of an EDL into one file, crossfading every join
+ retime-transcript Move existing per-word timings onto an EDL's timeline instead of transcribing again
+ stills Licensed stills from Wikimedia Commons: search / show / save (terms recorded with the file)
+ preview Localhost read-only preview of a run: scrub footage, follow the transcript, live-swap renders
+ init Workspace setup: check/install dependencies, clone the runtime, verify the engine
+ (--dry reports only; --auto-approve applies global installs after explicit user approval)
+ readiness Report what is present vs missing for a run (read-only, no network; exits 1 on a blocking miss)
+ session-start Agent SessionStart adapter: run init and print the context note (claude|codex|gemini)
+
+Options:
+ -v, --version Print the version and exit
+ -h, --help Show this help and exit
+`;
+
+// Commands own their flags, so only the command word is dispatched here; everything
+// after it goes to the command's own strict parser.
+export async function run(argv: string[]): Promise {
+ const [command, ...rest] = argv;
+
+ if (!command || command.startsWith("-")) {
+ let values: { version?: boolean; help?: boolean };
+ try {
+ ({ values } = parseArgs({
+ args: argv,
+ options: {
+ version: { type: "boolean", short: "v" },
+ help: { type: "boolean", short: "h" },
+ },
+ }));
+ } catch (error) {
+ console.error(error instanceof Error ? error.message : String(error));
+ console.error(HELP);
+ return 1;
+ }
+ if (values.version) {
+ // version is stamped at publish; absent on a dev checkout
+ console.log(pkg.version ?? "0.0.0-dev");
+ return 0;
+ }
+ console.log(HELP);
+ return 0;
+ }
+
+ try {
+ switch (command) {
+ case "login": {
+ const { values } = parseArgs({
+ args: rest,
+ options: { manual: { type: "boolean" } },
+ });
+ await login({ manual: values.manual });
+ return 0;
+ }
+ case "token": {
+ const { values } = parseArgs({
+ args: rest,
+ options: { path: { type: "boolean" } },
+ });
+ return await token({ path: values.path });
+ }
+ case "transcribe":
+ return await transcribe(rest);
+ case "whisper":
+ return await whisper(rest);
+ case "prep":
+ return await prep(rest);
+ case "synth-timings":
+ return synthTimings(rest);
+ case "generate":
+ return await generate(rest);
+ case "generate-set":
+ return await generateSet(rest);
+ case "sample-presenter":
+ return await samplePresenterCommand(rest);
+ case "background-removal":
+ return await backgroundRemoval(rest);
+ case "lipsync":
+ return await lipsync(rest);
+ case "install-engine":
+ return await installEngine(rest);
+ case "install-ffmpeg":
+ return await installFfmpeg(rest);
+ case "install-whisperx":
+ return await installWhisperx(rest);
+ case "mux-audio":
+ return muxAudio(rest);
+ case "mix-audio":
+ return mixAudio(rest);
+ case "wcag-pass":
+ return wcagPass(rest);
+ case "gates":
+ return gates(rest);
+ case "expect-windows":
+ return expectWindows(rest);
+ case "generate-recipe":
+ return await generateRecipe(rest);
+ case "sample-style":
+ return sampleStyleCommand(rest);
+ case "probe-qa":
+ return probeQaCommand(rest);
+ case "scoped-edit":
+ return scopedEdit(rest);
+ case "brand":
+ return brandCommand(rest);
+ case "creative-log":
+ return creativeLog(rest);
+ case "concat-chapters":
+ return concatChapters(rest);
+ case "concat-videos":
+ return await concatVideosCommand(rest);
+ case "scene-frames":
+ return sceneFrames(rest);
+ case "cut-frames":
+ return cutFrames(rest);
+ case "speech-probe":
+ return speechProbe(rest);
+ case "apply-edl":
+ return applyEdl(rest);
+ case "retime-transcript":
+ return retimeTranscript(rest);
+ case "stills":
+ return await stillsCommand(rest);
+ case "preview":
+ return await preview(rest);
+ case "init":
+ return await initMain(rest);
+ case "session-start":
+ return await sessionStart(rest);
+ case "readiness":
+ return readiness(rest);
+ case "lint":
+ return await lint(rest);
+ case "design-gate":
+ return await designGate(rest);
+ case "content-root":
+ return contentRootCommand(rest);
+ default:
+ console.error(`Unknown command: ${command}`);
+ console.error(HELP);
+ return 1;
+ }
+ } catch (error) {
+ console.error(error instanceof Error ? error.message : String(error));
+ return 1;
+ }
+}
+
+process.exitCode = await run(process.argv.slice(2));
diff --git a/cli/src/commands/apply-edl.ts b/cli/src/commands/apply-edl.ts
new file mode 100644
index 0000000..63fa8ba
--- /dev/null
+++ b/cli/src/commands/apply-edl.ts
@@ -0,0 +1,258 @@
+// Assemble an EDL's kept ranges into one file in a single encode.
+// An EDL (edit decision list) is the list of source intervals to keep, in order.
+//
+// openedit apply-edl --edl --out [--crossfade 40] [--crf 20]
+//
+// Joins are crossfaded, not butt-joined: a butt join clicks at the seam, and a crossfade needs one
+// encode over both sides of it. That is why this re-encodes instead of stream-copying like `concat-chapters`.
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { numberFlag, parseFlags } from '../args.ts';
+import { FFMPEG } from '../config.ts';
+import { loadEdl, snapRanges, sourceOrder, sourcePath, type SnappedRange } from '../edl.ts';
+import {
+ ASSUMED_COLOUR, audioDurationOf, colourTagsOf, probeDisplaySize, probeFrameRate, videoDurationOf,
+ type ColourReport, type ColourTags, type Display,
+} from '../probe.ts';
+
+const seconds = (t: number) => t.toFixed(6);
+const AUDIO_RATE = 48000;
+/** One AAC block at the lowest common source rate: the most a file's audio ends short of its picture by design. */
+const AAC_BLOCK_SEC = 1024 / 44100;
+
+/**
+ * Where each range's input is opened: every range is its OWN input, seeked to a whole second at least
+ * one second before it starts. One input shared by every range made the graph buffer whatever a
+ * reordered edit needed later. The seek is coarse on purpose: the graph's trim defines the edge, and
+ * the second of margin keeps that edge inside what was decoded.
+ */
+export function inputSeeks(ranges: SnappedRange[]): number[] {
+ return ranges.map((range) => Math.max(0, Math.floor(range.start) - 1));
+}
+
+/**
+ * One filter graph: trim every range out of its own input, put each on the same canvas, concat the
+ * video, and crossfade the audio by mixing fades rather than with `acrossfade`.
+ *
+ * The ranges arrive snapped to their source's frame grid, so each keeps a whole number of frames. The
+ * VIDEO trim edges sit half a frame before those instants: a frame's timestamp can land a few
+ * microseconds either side of k/fps once rounded to the container's timebase, and a boundary exactly on
+ * it would keep or drop that frame by luck. The AUDIO is cut on the instants themselves.
+ *
+ * Every segment but the last takes `crossfadeSec` of EXTRA audio from beyond its out-point, fades out
+ * over that tail, and is delayed to its place on the output timeline; the next segment fades in over
+ * the same window, and `amix` sums them without renormalising. Two linear fades sum to unity, so the
+ * sound that bleeds across a join is the room tone that genuinely followed the last kept frame. The
+ * last segment is padded to its snapped length, so the mix is exactly as long as the concatenated
+ * video even when the source's audio ends a few milliseconds before its last frame does.
+ */
+export function buildGraph(
+ ranges: SnappedRange[],
+ seeks: number[],
+ canvas: Display,
+ colour: ColourTags,
+ crossfadeSec: number,
+): { filter: string; videoLabel: string; audioLabel: string } {
+ const parts: string[] = [];
+ const scale =
+ `scale=${canvas.width}:${canvas.height}:force_original_aspect_ratio=decrease:flags=lanczos,` +
+ `pad=${canvas.width}:${canvas.height}:(ow-iw)/2:(oh-ih)/2,setsar=1`;
+
+ let offset = 0;
+ ranges.forEach((range, i) => {
+ const isLast = i === ranges.length - 1;
+ const start = range.start - seeks[i];
+ const end = range.end - seeks[i];
+ const length = range.end - range.start;
+ const halfFrame = 0.5 / range.fps;
+ parts.push(
+ `[${i}:v]trim=start=${seconds(Math.max(0, start - halfFrame))}:end=${seconds(end - halfFrame)},` +
+ `setpts=PTS-STARTPTS,${scale}[v${i}]`,
+ );
+ const audio = [
+ `atrim=start=${seconds(start)}:end=${seconds(isLast ? end : end + crossfadeSec)}`,
+ 'asetpts=PTS-STARTPTS',
+ `aformat=sample_rates=${AUDIO_RATE}:channel_layouts=stereo`,
+ ];
+ if (i > 0) audio.push(`afade=t=in:st=0:d=${seconds(crossfadeSec)}`);
+ if (isLast) audio.push(`apad=whole_len=${Math.round(length * AUDIO_RATE)}`);
+ else audio.push(`afade=t=out:st=${seconds(length)}:d=${seconds(crossfadeSec)}`);
+ // Delayed in SAMPLES: adelay's default unit is whole milliseconds, which is not a frame boundary.
+ const delay = Math.round(offset * AUDIO_RATE);
+ if (delay > 0) audio.push(`adelay=${delay}S:all=1`);
+ parts.push(`[${i}:a]${audio.join(',')}[a${i}]`);
+ offset += length;
+ });
+
+ // Colour is stamped as frame properties: the encoder takes its tags from the frames it is handed, and
+ // the -color_* output options are ignored on the ffmpeg builds this runs against.
+ parts.push(
+ `${ranges.map((_, i) => `[v${i}]`).join('')}concat=n=${ranges.length}:v=1:a=0,` +
+ `setparams=color_primaries=${colour.primaries}:color_trc=${colour.transfer}:colorspace=${colour.space}[vout]`,
+ );
+ parts.push(
+ ranges.length === 1
+ ? '[a0]anull[aout]'
+ : `${ranges.map((_, i) => `[a${i}]`).join('')}amix=inputs=${ranges.length}:normalize=0:dropout_transition=0[aout]`,
+ );
+
+ return { filter: parts.join(';'), videoLabel: '[vout]', audioLabel: '[aout]' };
+}
+
+const describeTags = (t: ColourTags) => `${t.primaries}/${t.transfer}/${t.space}`;
+const sameTags = (a: ColourTags, b: ColourTags) =>
+ a.primaries === b.primaries && a.transfer === b.transfer && a.space === b.space;
+
+/**
+ * One colour for the whole output, or a refusal: every source must agree, and a source that declares
+ * any axis the bt709 assumption would contradict (an HDR transfer, wide-gamut primaries) is never
+ * relabelled by having the rest assumed for it.
+ */
+export function decideColour(sources: { id: string; colour: ColourReport }[]): ColourReport {
+ for (const { id, colour } of sources) {
+ if (!colour.assumed) continue;
+ const contradicted = (Object.entries(colour.declared) as [keyof ColourTags, string][])
+ .filter(([axis, value]) => value !== ASSUMED_COLOUR[axis]);
+ if (contradicted.length > 0) {
+ throw new Error(
+ `source "${id}" declares ${contradicted.map(([axis, value]) => `${axis} ${value}`).join(' and ')} but not the rest — ` +
+ 'stamping bt709 over it would mislabel the picture. Tag the file completely before assembling.',
+ );
+ }
+ }
+ const first = sources[0];
+ for (const { id, colour } of sources.slice(1)) {
+ if (!sameTags(colour.tags, first.colour.tags)) {
+ throw new Error(
+ `sources disagree on colour: "${first.id}" is ${describeTags(first.colour.tags)} and "${id}" is ` +
+ `${describeTags(colour.tags)} — convert them to one colour space before assembling.`,
+ );
+ }
+ }
+ return first.colour;
+}
+
+export function applyEdl(argv: string[]): number {
+ const { values } = parseFlags({
+ args: argv,
+ options: {
+ edl: { type: 'string' },
+ out: { type: 'string' },
+ crossfade: { type: 'string' },
+ crf: { type: 'string' },
+ },
+ allowPositionals: false,
+ });
+ if (!values.edl || !values.out) {
+ throw new Error('usage: openedit apply-edl --edl --out [--crossfade , default 40] [--crf 20]');
+ }
+ const loaded = loadEdl(values.edl);
+ // ffmpeg reads `afade=d=0` as UNSET and falls back to its 44100-sample default — nearly a second per
+ // join, with no surplus trimmed to pay for it. A butt join would need its own flag.
+ const crossfadeMs = numberFlag('crossfade', values.crossfade, 40, (n) => n >= 1, 'at least 1 millisecond');
+ const crf = numberFlag('crf', values.crf, 20, (n) => n >= 0 && n <= 51, '0-51');
+ const crossfadeSec = crossfadeMs / 1000;
+
+ // Probed once per distinct source; the encode opens one input per RANGE (see inputSeeks).
+ const order = sourceOrder(loaded.edl.ranges);
+ const sources = new Map(order.map((id) => {
+ const path = sourcePath(loaded, id);
+ let duration: number;
+ try {
+ duration = audioDurationOf(path);
+ } catch (cause) {
+ // Every join borrows audio from beyond its out-point, so the audio's own length is what the
+ // guard below needs; the container's length would pass a file whose audio ends early or is absent.
+ throw new Error(`source "${id}": ${(cause as Error).message} — apply-edl assembles picture and sound together`, { cause });
+ }
+ return [id, { path, ...probeFrameRate(path), duration, video: videoDurationOf(path), colour: colourTagsOf(path) }];
+ }));
+ const sourceOf = (id: string) => sources.get(id)!;
+ // One frame rate for the whole output: the encode is forced to it, and a source at another rate would
+ // have frames dropped or doubled to fit without a word.
+ const first = sourceOf(order[0]);
+ for (const [id, source] of sources) {
+ if (Math.abs(source.fps - first.fps) > 1e-6) {
+ throw new Error(
+ `sources disagree on frame rate: "${order[0]}" runs at ${first.rate} fps and "${id}" at ${source.rate} — ` +
+ 'bring them to one rate first (concat-videos re-encodes to a common one).',
+ );
+ }
+ // The grid assumes every frame slot is filled; a slot the camera skipped inside a kept range moves
+ // every later frame a slot earlier against the sound, and nothing downstream can see it.
+ if (Math.abs(source.averageFps - source.fps) / source.fps > 0.005) {
+ console.warn(
+ `warning: source "${id}" is not constant frame rate (nominal ${source.rate}, average ${source.averageFps.toFixed(2)}) — ` +
+ 'a frame the camera skipped inside a kept range shifts the picture against the sound from there on.',
+ );
+ }
+ }
+ const ranges = snapRanges(loaded.edl.ranges, new Map(order.map((id) => [id, sourceOf(id).fps])));
+
+ ranges.forEach((range, index) => {
+ // A single range emits `anull`, not a crossfade, so it has no minimum beyond being non-empty.
+ if (ranges.length > 1 && range.end - range.start <= crossfadeSec) {
+ throw new Error(
+ `range ${index} of "${range.source}" is ${(range.end - range.start).toFixed(3)}s, no longer than the ` +
+ `${crossfadeMs}ms crossfade — shorten --crossfade or lengthen the range`,
+ );
+ }
+ const source = sourceOf(range.source);
+ // The picture's own length: a range past it plays every later range's picture early, and `trim`
+ // simply delivers fewer frames.
+ if (range.end > source.video + 1e-6) {
+ throw new Error(
+ `range ${index} of "${range.source}" ends at ${range.end.toFixed(3)}s but the source's picture is only ` +
+ `${source.video.toFixed(3)}s long. Move the out-point earlier.`,
+ );
+ }
+ const isLast = index === ranges.length - 1;
+ const needed = isLast ? range.end : range.end + crossfadeSec;
+ // The last range's audio may end short of its snapped end: the snap moves the edge up by less than
+ // a frame, and AAC stops on its own block grid rather than on the picture's. Within that the graph
+ // pads the sound to the picture; beyond it the out-point is genuinely past the recording.
+ const tolerated = isLast ? 1 / range.fps + AAC_BLOCK_SEC : 0;
+ if (needed > source.duration + tolerated + 1e-6) {
+ throw new Error(
+ isLast
+ ? `range ${index} of "${range.source}" ends at ${range.end.toFixed(3)}s but the source's audio is only ` +
+ `${source.duration.toFixed(3)}s long. Move the out-point earlier.`
+ : `range ${index} of "${range.source}" ends at ${range.end.toFixed(3)}s and its join needs ` +
+ `${crossfadeMs}ms more audio, but the source's audio is only ${source.duration.toFixed(3)}s long. ` +
+ 'Move the out-point earlier, reorder so this range is last, or lower --crossfade.',
+ );
+ }
+ });
+
+ const colour = decideColour(order.map((id) => ({ id, colour: sourceOf(id).colour })));
+ const assumedFor = order.filter((id) => sourceOf(id).colour.assumed);
+ const canvas = probeDisplaySize(first.path);
+ const seeks = inputSeeks(ranges);
+ const { filter, videoLabel, audioLabel } = buildGraph(ranges, seeks, canvas, colour.tags, crossfadeSec);
+
+ const outPath = resolve(values.out);
+ execFileSync(FFMPEG, [
+ '-nostdin', '-y', '-hide_banner', '-loglevel', 'error',
+ ...ranges.flatMap((range, i) => [...(seeks[i] > 0 ? ['-ss', String(seeks[i])] : []), '-i', sourceOf(range.source).path]),
+ '-filter_complex', filter,
+ '-map', videoLabel, '-map', audioLabel,
+ // -r pins the output to the source rate and gives the LAST frame a duration. Without it that frame
+ // reaches the muxer with none, the mp4 edit list ends a frame early, and players drop the frame.
+ '-r', first.rate,
+ '-c:v', 'libx264', '-preset', 'medium', '-crf', String(crf), '-pix_fmt', 'yuv420p',
+ '-c:a', 'aac', '-b:a', '192k', '-ar', '48000',
+ '-movflags', '+faststart',
+ outPath,
+ ], { stdio: ['ignore', 'inherit', 'inherit'] });
+
+ const kept = ranges.reduce((total, r) => total + (r.end - r.start), 0);
+ const joins = ranges.length - 1;
+ console.log(
+ `assembled ${ranges.length} range(s) from ${order.length} source(s) -> ${outPath}\n` +
+ ` ${kept.toFixed(3)}s kept, ${joins} crossfaded join(s) of ${crossfadeMs}ms; ${canvas.width}x${canvas.height}, ` +
+ `colour ${describeTags(colour.tags)}${assumedFor.length > 0 ? ` (assumed for ${assumedFor.map((id) => `"${id}"`).join(', ')}: no tags declared)` : ''}.\n` +
+ ' Each range is snapped to its source\'s frame grid, so the timeline is exactly the sum of the ' +
+ 'snapped ranges — a transcript retimed from the same EDL lands on the same instants.',
+ );
+ return 0;
+}
diff --git a/cli/src/commands/background-removal.ts b/cli/src/commands/background-removal.ts
new file mode 100644
index 0000000..bfc539a
--- /dev/null
+++ b/cli/src/commands/background-removal.ts
@@ -0,0 +1,283 @@
+// Video background removal, two ways:
+//
+// default the live VEED route (POST /v1/remove-background) — free, no credits are deducted,
+// authorized by a project's CAN_WRITE permission.
+// --fast the public fal model veed/video-background-removal/fast, reached the same way every other
+// generated asset in this repo reaches fal — the user's own key (cli/src/providers/fal.ts).
+// The live route has no fast variant, so this is the only way to get it. VEED login still
+// hosts the local file (so fal has a URL to fetch); the GENERATION call bills fal, not VEED.
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { type VeedHttp, unwrap } from '../veed/api.ts';
+import { getDefaultSpace, createProject } from '../veed/fabric-routes.ts';
+import { describeWorkspaceChoice, formatWorkspaceTable, resolveWorkspace } from '../veed/workspace.ts';
+import { uploadLocalAsset, readVideoBytes } from '../veed/asset-upload.ts';
+import { parseFlags } from '../args.ts';
+import { resolveVideoArg, runKeyOf } from '../resolve-video.ts';
+import { FFPROBE, runsDir } from '../config.ts';
+import { submitOnce, await_, download, firstUrl, falKey, completeJob, type Http as FalHttp } from '../providers/fal.ts';
+import { refreshingHttp } from '../veed/http.ts';
+import { resolveVeedToken } from '../veed/resolve-token.ts';
+
+export const FAL_BG_REMOVAL_FAST_MODEL = 'veed/video-background-removal/fast';
+
+// fal's own listed rate for this model (fal.ai/models/veed/video-background-removal/fast, fetched
+// 2026-08-19) — relayed as-is, not a VEED-derived constant, and not turned into a per-run dollar
+// estimate (fal prices by OUTPUT frame count, which isn't known until the job finishes).
+export const FAL_BG_REMOVAL_FAST_PRICE_NOTE =
+ '$0.012 per 30 frames with edge refinement on (default) / $0.008 per 30 frames with it off';
+
+export interface RemoveBackgroundStatusEntry {
+ workflowId: string;
+ projectId: string;
+ workspaceId?: string;
+ status: string;
+ result?: { url: string };
+}
+
+export async function startRemoveBackground(
+ http: VeedHttp,
+ args: { videoUrl: string; projectId: string; workspaceId?: string; duration?: number; maskOnly?: boolean },
+): Promise<{ workflowId: string }> {
+ return unwrap(
+ await http.postJson('/v1/remove-background', {
+ videoUrl: args.videoUrl,
+ projectId: args.projectId,
+ ...(args.workspaceId ? { workspaceId: args.workspaceId } : {}),
+ ...(args.duration !== undefined ? { duration: args.duration } : {}),
+ ...(args.maskOnly !== undefined ? { maskOnly: args.maskOnly } : {}),
+ }),
+ );
+}
+
+// Empty statuses[] is a valid "not found yet" response, not an error — the caller (pollRemoveBackground
+// below) treats "no matching entry" the same as any other still-pending state.
+export async function getRemoveBackgroundStatus(
+ http: VeedHttp,
+ args: { workflowId?: string; projectId?: string },
+): Promise {
+ const q = new URLSearchParams();
+ if (args.workflowId) q.set('workflowId', args.workflowId);
+ if (args.projectId) q.set('projectId', args.projectId);
+ const res = unwrap<{ statuses: RemoveBackgroundStatusEntry[] }>(
+ await http.getJson(`/v1/remove-background/status?${q.toString()}`),
+ );
+ return res.statuses.find((s) => !args.workflowId || s.workflowId === args.workflowId);
+}
+
+const TERMINAL_STATUSES = new Set(['COMPLETED', 'FAILED', 'CANCELED', 'UNKNOWN']);
+
+// This poll is a different animal from asset-upload's: a real video-processing job whose duration
+// scales with the source, so it mirrors fal.ts's await_() convention (a wall-clock deadline, a few
+// seconds between checks) rather than veed/poll.ts's fixed-interval convention.
+const STATUS_POLL_INTERVAL_MS = 3000;
+const STATUS_POLL_TIMEOUT_MS = 15 * 60_000;
+
+async function pollRemoveBackground(
+ http: VeedHttp,
+ args: { workflowId: string; projectId?: string },
+ sleep: (ms: number) => Promise,
+): Promise {
+ const deadline = Date.now() + STATUS_POLL_TIMEOUT_MS;
+ while (Date.now() < deadline) {
+ const entry = await getRemoveBackgroundStatus(http, args);
+ if (entry && TERMINAL_STATUSES.has(entry.status)) return entry;
+ await sleep(STATUS_POLL_INTERVAL_MS);
+ }
+ throw new Error(
+ `VEED: remove-background workflow ${args.workflowId} did not finish within ${STATUS_POLL_TIMEOUT_MS / 60_000} minutes`,
+ );
+}
+
+// Best-effort: ffprobe missing or the file being unreadable must not block the call. Duration is
+// reported to the route in default mode only — lipsync.ts reuses this same function.
+export function probeDurationSec(videoPath: string): number | undefined {
+ try {
+ const out = execFileSync(
+ FFPROBE,
+ ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', videoPath],
+ { stdio: ['ignore', 'pipe', 'ignore'] },
+ )
+ .toString()
+ .trim();
+ const dur = Number(out);
+ return Number.isFinite(dur) ? dur : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+export interface RemoveBackgroundDeps {
+ http: VeedHttp;
+ readVideoBytes: (videoPath: string) => Promise<{ bytes: Uint8Array; mimeType: string; extension: string }>;
+ sleep?: (ms: number) => Promise;
+ log?: (message: string) => void;
+ probeDuration?: (videoPath: string) => number | undefined;
+ falHttp?: FalHttp;
+ // The fal job ledger's directory. Defaults to runs/ (main() below); tests
+ // override it so they never write into this repo's own runs/ tree.
+ runDir?: string;
+ // Overrides fal.ts's await_() default (15 minutes) — tests use a short one rather than waiting out
+ // the real deadline.
+ falTimeoutMs?: number;
+}
+
+export interface RemoveBackgroundOptions {
+ videoPath: string;
+ outPath: string;
+ workspaceId?: string;
+ maskOnly?: boolean;
+ fast?: boolean;
+ refineForegroundEdges?: boolean;
+ falKey?: string;
+}
+
+export async function removeBackground(deps: RemoveBackgroundDeps, opts: RemoveBackgroundOptions): Promise {
+ if (opts.maskOnly && opts.fast) {
+ throw new Error('--mask-only has no equivalent on the fast fal model (veed/video-background-removal/fast) — drop one flag');
+ }
+ if (opts.workspaceId && opts.fast) {
+ throw new Error(
+ '--workspace has no effect on the fast fal model (veed/video-background-removal/fast) — the fal ' +
+ 'call is unscoped, billed to your own fal account, not a VEED workspace; drop one flag',
+ );
+ }
+
+ const { http } = deps;
+ const sleep = deps.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+ const log = deps.log ?? (() => {});
+ const probeDuration = deps.probeDuration ?? probeDurationSec;
+
+ const { bytes, mimeType, extension } = await deps.readVideoBytes(opts.videoPath);
+
+ if (opts.fast) {
+ const refine = opts.refineForegroundEdges ?? true;
+ // No per-run dollar estimate: fal prices by OUTPUT frame count, not known until the job finishes.
+ log(
+ `[fal] ${FAL_BG_REMOVAL_FAST_MODEL} bills YOUR OWN fal account, not any VEED workspace. ` +
+ `fal's listed rate: ${FAL_BG_REMOVAL_FAST_PRICE_NOTE}. This run: refine=${refine}.`,
+ );
+
+ // Unscoped: fal's own key authorizes the paid call, not a VEED project permission — VEED hosts the
+ // file so fal has a URL to fetch, and that hosting step is not billed either way.
+ const uploaded = await uploadLocalAsset({ http, sleep }, { bytes, mimeType, extension, assetType: 'VIDEO', group: 'srcVideo' });
+ log(`uploaded ${uploaded.assetId} for hosting only`);
+
+ const key = opts.falKey ?? falKey();
+ const runDir = deps.runDir ?? join(runsDir(), runKeyOf(opts.videoPath));
+ const input: Record = { video_url: uploaded.cdnUrl, refine_foreground_edges: refine };
+ const { job, reused } = await submitOnce(runDir, FAL_BG_REMOVAL_FAST_MODEL, input, { key, http: deps.falHttp, sleep });
+ if (reused) log(`[fal] this exact request is already in the ledger as ${job.requestId} — resuming it rather than buying it again`);
+ const result = await await_(job, { key, http: deps.falHttp, sleep, timeoutMs: deps.falTimeoutMs });
+ const url = firstUrl(result.payload);
+ if (!url) throw new Error(`fal returned no url for ${job.requestId}`);
+ await download(url, opts.outPath, deps.falHttp);
+ completeJob(runDir, FAL_BG_REMOVAL_FAST_MODEL, input);
+ log(`wrote ${opts.outPath}`);
+ return;
+ }
+
+ // default: the live, free VEED route. Scoped upload, because the route's own authorization is a
+ // project's CAN_WRITE permission — there is no billing workspace to protect from an unscoped call, but
+ // the project is what grants the request in the first place.
+ const duration = probeDuration(opts.videoPath);
+ let workspaceId = opts.workspaceId;
+ if (!workspaceId) {
+ const resolution = await resolveWorkspace({ http });
+ if (resolution.kind === 'must-choose') {
+ throw new Error(
+ 'VEED: this account has several workspaces — background removal runs inside a project scoped to ' +
+ `one of them, so it will not be picked for you. Re-run naming it, for example --workspace ${resolution.workspaces[0].id}:\n` +
+ `${formatWorkspaceTable(resolution.workspaces)}`,
+ );
+ }
+ workspaceId = resolution.workspace.id;
+ log(describeWorkspaceChoice(resolution.workspace, resolution.source));
+ }
+ const billedWorkspaceId: string = workspaceId;
+
+ const spaceId = await getDefaultSpace(http, billedWorkspaceId);
+ const projectId = await createProject(http, {
+ name: `background-removal-${runKeyOf(opts.videoPath)}`,
+ workspaceId: billedWorkspaceId,
+ spaceId,
+ });
+
+ const uploaded = await uploadLocalAsset({ http, sleep }, {
+ bytes, mimeType, extension, assetType: 'VIDEO', group: 'srcVideo', workspaceId: billedWorkspaceId, projectId,
+ });
+ log(`uploaded ${uploaded.assetId}`);
+
+ const started = await startRemoveBackground(http, {
+ videoUrl: uploaded.cdnUrl, projectId, workspaceId: billedWorkspaceId, duration, maskOnly: opts.maskOnly,
+ });
+ log(`remove-background workflow ${started.workflowId} — no VEED credits were charged for this run`);
+
+ const final = await pollRemoveBackground(http, { workflowId: started.workflowId, projectId }, sleep);
+ if (final.status !== 'COMPLETED' || !final.result?.url) {
+ throw new Error(`VEED: remove-background workflow ${started.workflowId} ended as ${final.status}`);
+ }
+
+ // The result URL may be short-lived, so it is downloaded immediately.
+ await download(final.result.url, opts.outPath, deps.falHttp);
+ log(`wrote ${opts.outPath}`);
+}
+
+function noTokenHelp(): void {
+ console.error(
+ [
+ 'No VEED login found. Log in with VEED:',
+ '',
+ ' npx @veedstudio/openedit-cli login',
+ '',
+ 'then re-run this command. The same login covers transcription, Fabric, and background removal',
+ '(both modes — --fast still uses it to host the local file, though the removal itself bills fal).',
+ ].join('\n'),
+ );
+}
+
+export async function backgroundRemoval(argv: string[]): Promise {
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: {
+ 'mask-only': { type: 'boolean' },
+ fast: { type: 'boolean' },
+ 'no-refine': { type: 'boolean' },
+ out: { type: 'string' },
+ workspace: { type: 'string' },
+ },
+ allowPositionals: true,
+ });
+ const [videoArg] = positionals;
+ if (!videoArg) {
+ console.error('usage: npx @veedstudio/openedit-cli background-removal [--mask-only] [--fast] [--no-refine] [--out ] [--workspace ]');
+ return 1;
+ }
+ const videoPath = resolveVideoArg(videoArg);
+ if (!existsSync(videoPath)) {
+ console.error(`video not found: ${videoPath}`);
+ return 1;
+ }
+ const outPath = values.out ?? join(runsDir(), runKeyOf(videoPath), 'background-removed.mp4');
+
+ const token = await resolveVeedToken();
+ if (!token) {
+ noTokenHelp();
+ return 1;
+ }
+ const http = refreshingHttp(async () => {
+ const t = await resolveVeedToken();
+ if (!t) throw new Error('VEED login expired mid-run — re-run: npx @veedstudio/openedit-cli login');
+ return t;
+ });
+
+ await removeBackground(
+ { http, readVideoBytes, log: (m) => console.log(`[bg-removal] ${m}`) },
+ {
+ videoPath, outPath, workspaceId: values.workspace, maskOnly: values['mask-only'], fast: values.fast,
+ refineForegroundEdges: values['no-refine'] ? false : undefined,
+ },
+ );
+ return 0;
+}
diff --git a/cli/src/commands/brand.ts b/cli/src/commands/brand.ts
new file mode 100644
index 0000000..d59b9b4
--- /dev/null
+++ b/cli/src/commands/brand.ts
@@ -0,0 +1,101 @@
+// The brand law, and the bone a SET of pieces shares.
+//
+// Every RACE-card brief in the launch session retyped the same block: the palette, the rule that white
+// and green carry everything and orange is a micro-accent only, the rule that type on a green plate is
+// the brand dark, where the mark sits, and the shared skeleton that made four cards read as one
+// campaign. Retyped four times, drifting each time, and the run that dropped the mark produced the
+// session's sharpest correction — the logo was not the one from the brandbook.
+//
+// brand.ts --file --brief # the law as prompt-ready prose
+// brand.ts --file --check # validate it before a run spends a render on it
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, dirname, isAbsolute, join } from 'node:path';
+import { parseFlags } from '../args.ts';
+
+export interface Brand {
+ name: string;
+ /** role → hex. Roles are the point: "ink"/"accent"/"ground" survive a palette swap, "#96FF1A" does not. */
+ palette: Record;
+ /** Sentences that constrain how the palette may be spent. These are what a design pass gets wrong. */
+ colourLaw?: string[];
+ type?: { display?: string; body?: string; notes?: string };
+ /** A mark is a FILE, never a redrawing. `asset` is resolved relative to the brand file. */
+ logo?: { asset?: string; placement?: string; never?: string };
+ /** Present when several pieces are made together and must read as one campaign. */
+ set?: { shared: string[]; varies?: string[] };
+}
+
+export interface Problem { field: string; message: string }
+
+const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
+
+export function validate(brand: Brand, baseDir: string): Problem[] {
+ const out: Problem[] = [];
+ if (!brand.name?.trim()) out.push({ field: 'name', message: 'a brand with no name cannot be reported back to the user' });
+ const roles = Object.entries(brand.palette ?? {});
+ if (!roles.length) out.push({ field: 'palette', message: 'no palette — the design pass would invent one' });
+ for (const [role, hex] of roles) {
+ if (!HEX.test(hex)) out.push({ field: `palette.${role}`, message: `"${hex}" is not a hex colour` });
+ if (/^#?[0-9a-f]{3,6}$/i.test(role)) {
+ out.push({ field: `palette.${role}`, message: 'the KEY must be a role ("ink", "accent", "ground"), not the colour again — a role survives a palette swap' });
+ }
+ }
+ // The corpus's asset-fidelity class is 17 records: a mark drawn by hand instead of taken from the
+ // file the user supplied. A brand that names an asset which is not there invites exactly that.
+ if (brand.logo?.asset) {
+ const p = isAbsolute(brand.logo.asset) ? brand.logo.asset : join(baseDir, brand.logo.asset);
+ if (!existsSync(p)) out.push({ field: 'logo.asset', message: `${brand.logo.asset} does not exist — a design pass told to use a missing mark draws its own` });
+ }
+ if (brand.set && !brand.set.shared?.length) {
+ out.push({ field: 'set.shared', message: 'a set with nothing shared is not a set — name the bone every piece keeps' });
+ }
+ return out;
+}
+
+export function briefFor(brand: Brand, baseDir: string): string {
+ const lines: string[] = [`THE BRAND — ${brand.name}. It is the design authority; on any collision with a direction, it wins.`];
+ lines.push(` Palette (role → value, spend them by ROLE):`);
+ for (const [role, hex] of Object.entries(brand.palette ?? {})) lines.push(` ${role}: ${hex}`);
+ if (brand.colourLaw?.length) {
+ lines.push(` Colour law — these are constraints, not suggestions:`);
+ for (const l of brand.colourLaw) lines.push(` · ${l}`);
+ }
+ if (brand.type) {
+ const t = [brand.type.display && `display ${brand.type.display}`, brand.type.body && `body ${brand.type.body}`]
+ .filter(Boolean).join(' · ');
+ if (t) lines.push(` Type: ${t}`);
+ if (brand.type.notes) lines.push(` ${brand.type.notes}`);
+ }
+ if (brand.logo) {
+ const p = brand.logo.asset
+ ? (isAbsolute(brand.logo.asset) ? brand.logo.asset : resolve(baseDir, brand.logo.asset))
+ : undefined;
+ lines.push(` Mark: ${p ? `USE THE FILE at ${p} — never redraw it, never crop it out of a raster` : 'no asset supplied'}`);
+ if (brand.logo.placement) lines.push(` Placement: ${brand.logo.placement}`);
+ if (brand.logo.never) lines.push(` Never: ${brand.logo.never}`);
+ }
+ if (brand.set) {
+ lines.push(` THE SHARED BONE — every piece in this set keeps these, so the set reads as one campaign:`);
+ for (const s of brand.set.shared) lines.push(` · ${s}`);
+ if (brand.set.varies?.length) {
+ lines.push(` What differs between pieces: ${brand.set.varies.join(', ')}. Compositions differ; the bone does not.`);
+ }
+ }
+ return lines.join('\n');
+}
+
+export function brandCommand(argv: string[]): number {
+ const { values } = parseFlags({
+ args: argv,
+ options: { file: { type: 'string' }, brief: { type: 'boolean' }, check: { type: 'boolean' } },
+ });
+ if (!values.file) { console.error('usage: openedit brand --file [--brief] [--check]'); return 2; }
+ const path = resolve(values.file);
+ const brand = JSON.parse(readFileSync(path, 'utf8')) as Brand;
+ const problems = validate(brand, dirname(path));
+ if (values.brief && !problems.length) { console.log(briefFor(brand, dirname(path))); return 0; }
+ for (const p of problems) console.error(`BRAND[${p.field}] ${p.message}`);
+ if (problems.length) { console.error(`brand: ${problems.length} problem(s)`); return 1; }
+ console.log('brand: valid');
+ return 0;
+}
diff --git a/cli/src/commands/concat-chapters.ts b/cli/src/commands/concat-chapters.ts
new file mode 100644
index 0000000..82bdb45
--- /dev/null
+++ b/cli/src/commands/concat-chapters.ts
@@ -0,0 +1,115 @@
+// Chapters into a film.
+//
+// A long piece is authored one document per chapter, because one `.wv` holding twelve minutes is a
+// document nobody can gate, fix or re-render in part. Each chapter goes through the gate chain and
+// lands its own `out.mp4` — and then nothing joined them WITHOUT TRANSCODING. The gate chain says it
+// runs "design → lint → verify → record → probe → mux"; that is true of a chapter and stops there.
+//
+// `concat-videos.ts` also joins mp4s, and is the wrong tool here: it exists for generated clips that
+// disagree — different shapes, some without audio — so it re-encodes onto one canvas and normalises the
+// frame rate. Engine renders agree by construction, and a twelve-minute film must not be transcoded
+// once per assembly, nor have its fps resampled.
+//
+// The concat demuxer copies streams rather than re-encoding, which is what keeps a twelve-minute film
+// from being transcoded once per assembly. It requires every part to share codec parameters — the
+// engine renders them identically and `mux-audio.ts` encodes aac for all of them, so they do. That
+// requirement is checked rather than assumed: a mismatch here produces a file that plays for one
+// chapter and then glitches, which is the kind of defect nobody sees until the whole thing is watched.
+import { execFileSync } from 'node:child_process';
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve } from 'node:path';
+import { parseFlags } from '../args.ts';
+import { FFMPEG, FFPROBE } from '../config.ts';
+
+/** The demuxer's list format. Single quotes in a path are escaped the way ffmpeg expects. */
+export function concatList(parts: string[]): string {
+ if (!parts.length) throw new Error('concat: no chapters given');
+ return parts.map((p) => `file '${resolve(p).replace(/'/g, "'\\''")}'`).join('\n') + '\n';
+}
+
+export interface StreamShape {
+ codec: string;
+ width: number;
+ height: number;
+ fps: string;
+ audioCodec: string;
+ sampleRate: string;
+ channels: number;
+}
+
+export function shapeOf(file: string): StreamShape {
+ const out = execFileSync(FFPROBE, [
+ '-v', 'error', '-show_entries',
+ 'stream=codec_name,codec_type,width,height,r_frame_rate,sample_rate,channels',
+ '-of', 'json', file,
+ ], { encoding: 'utf8' });
+ const streams = (JSON.parse(out) as { streams: Record[] }).streams;
+ const v = streams.find((s) => s.codec_type === 'video') ?? {};
+ const a = streams.find((s) => s.codec_type === 'audio') ?? {};
+ return {
+ codec: String(v.codec_name ?? ''),
+ width: Number(v.width ?? 0),
+ height: Number(v.height ?? 0),
+ fps: String(v.r_frame_rate ?? ''),
+ audioCodec: String(a.codec_name ?? ''),
+ sampleRate: String(a.sample_rate ?? ''),
+ channels: Number(a.channels ?? 0),
+ };
+}
+
+/** What differs between two parts, in words a person can act on. */
+export function shapeDiff(a: StreamShape, b: StreamShape): string[] {
+ const out: string[] = [];
+ if (a.codec !== b.codec) out.push(`video codec ${a.codec} vs ${b.codec}`);
+ if (a.width !== b.width || a.height !== b.height) out.push(`canvas ${a.width}x${a.height} vs ${b.width}x${b.height}`);
+ if (a.fps !== b.fps) out.push(`fps ${a.fps} vs ${b.fps}`);
+ if (a.audioCodec !== b.audioCodec) out.push(`audio codec ${a.audioCodec || 'none'} vs ${b.audioCodec || 'none'}`);
+ if (a.sampleRate !== b.sampleRate) out.push(`sample rate ${a.sampleRate} vs ${b.sampleRate}`);
+ if (a.channels !== b.channels) out.push(`channels ${a.channels} vs ${b.channels}`);
+ return out;
+}
+
+export function concat(parts: string[], outPath: string, listPath: string): string {
+ for (const p of parts) if (!existsSync(p)) throw new Error(`concat: no such chapter render — ${p}`);
+ const shapes = parts.map(shapeOf);
+ for (let i = 1; i < shapes.length; i++) {
+ const d = shapeDiff(shapes[0], shapes[i]);
+ if (d.length) {
+ throw new Error(
+ `concat: ${parts[i]} does not match ${parts[0]} — ${d.join(', ')}. Copying streams needs them ` +
+ 'identical; re-render the odd chapter at the film\'s canvas and fps rather than transcoding here.',
+ );
+ }
+ }
+ mkdirSync(dirname(listPath), { recursive: true });
+ writeFileSync(listPath, concatList(parts));
+ mkdirSync(dirname(outPath), { recursive: true });
+ execFileSync(FFMPEG, [
+ '-y', '-hide_banner', '-loglevel', 'error',
+ '-f', 'concat', '-safe', '0', '-i', listPath,
+ '-c', 'copy', '-movflags', '+faststart', outPath,
+ ]);
+ return outPath;
+}
+
+export function concatChapters(argv: string[]): number {
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: { doc: { type: 'string', multiple: true }, out: { type: 'string' } },
+ allowPositionals: true,
+ });
+ const [runDir] = positionals;
+ const docs = (values.doc as string[] | undefined) ?? [];
+ if (!runDir || !docs.length) {
+ console.error('usage: openedit concat-chapters --doc chapters/act-1 --doc chapters/act-2 [...] [--out final/out.mp4]');
+ return 2;
+ }
+ // Order is the order the flags were given. Deriving it from a directory listing would put act-10
+ // before act-2, and a film whose chapters play in the wrong order is not a failure anyone notices
+ // in a gate.
+ const parts = docs.map((d) => join(runDir, d, 'out.mp4'));
+ const out = join(runDir, values.out ?? 'final/out.mp4');
+ concat(parts, out, join(runDir, 'final', 'concat.txt'));
+ console.log(`concat: ${parts.length} chapters → ${out}`);
+ return 0;
+}
diff --git a/cli/src/commands/concat-videos.ts b/cli/src/commands/concat-videos.ts
new file mode 100644
index 0000000..cb6abe6
--- /dev/null
+++ b/cli/src/commands/concat-videos.ts
@@ -0,0 +1,250 @@
+// Joins several clips into one, end to end.
+//
+// openedit concat-videos [...]
+// openedit concat-videos --canvas 1080x1920 --fit crop
+// openedit concat-videos --fit open [...]
+//
+// Generated clips do NOT share a canvas: a Fabric still decides its own aspect, so a portrait presenter
+// and a landscape one produce different dimensions. ffmpeg's concat demuxer refuses that outright, and
+// the stream-copy path people reach for first fails with a size-mismatch that reads like a codec problem.
+// So this re-encodes every input onto one canvas, and a clip whose aspect differs from that canvas has to
+// lose something: --fit letterbox (the default) pads it and keeps the whole frame behind black bars;
+// --fit crop fills the canvas and cuts the overflow; --fit open decides nothing in code and instead
+// reports which clips differ, so the agent can reframe each shot itself. Re-encoding is the price of
+// accepting mixed inputs at all.
+//
+// The canvas defaults to the LARGEST input by area, so the sharpest clip keeps its resolution and the
+// others are upscaled to meet it rather than everything collapsing to the smallest.
+import { parseFlags } from '../args.ts';
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { promisify } from 'node:util';
+import { FFMPEG, FFPROBE } from '../config.ts';
+
+const run = promisify(execFile);
+
+export interface Size {
+ width: number;
+ height: number;
+}
+
+// letterbox pads a mismatched clip (keeps all framing); crop fills the canvas (cuts the overflow); open
+// runs no encode and reports the mismatches for the agent to reframe by hand.
+export type FitMode = 'letterbox' | 'crop' | 'open';
+
+// Only these two reach the encoder — open never does, so the filter graph does not model it.
+type EncodeFit = 'letterbox' | 'crop';
+
+// Two aspects count as the same shape when they are within this FRACTION of each other — relative, so
+// the threshold means the same thing in portrait and landscape. Even-dimension rounding moves a ratio by
+// well under this, while a visibly different frame exceeds it.
+const ASPECT_TOLERANCE = 0.01;
+
+export function aspectOf(size: Size): number {
+ return size.width / size.height;
+}
+
+// Even dimensions: yuv420p chroma is subsampled 2x, and an odd width or height makes the encoder fail
+// with a message that says nothing about the real cause.
+export function evenSize(size: Size): Size {
+ return { width: Math.max(2, size.width - (size.width % 2)), height: Math.max(2, size.height - (size.height % 2)) };
+}
+
+export function largestByArea(sizes: Size[]): Size {
+ if (sizes.length === 0) throw new Error('no inputs to size a canvas from');
+ return evenSize(sizes.reduce((a, b) => (b.width * b.height > a.width * a.height ? b : a)));
+}
+
+export function parseCanvas(text: string): Size {
+ const m = /^(\d+)x(\d+)$/.exec(text.trim());
+ if (!m) throw new Error(`--canvas expects WIDTHxHEIGHT, got "${text}"`);
+ return evenSize({ width: Number(m[1]), height: Number(m[2]) });
+}
+
+export function parseFit(text: string | undefined): FitMode {
+ if (text === undefined) return 'letterbox';
+ if (text === 'letterbox' || text === 'crop' || text === 'open') return text;
+ throw new Error(`--fit expects letterbox, crop or open, got "${text}"`);
+}
+
+export interface AspectReport {
+ size: Size;
+ matchesCanvas: boolean;
+}
+
+// Which clips differ in shape from the canvas — the ones a fit strategy actually acts on. A clip that
+// already matches gets the same result from crop or letterbox, so only these are worth reporting.
+export function aspectReport(sizes: Size[], canvas: Size): AspectReport[] {
+ const target = aspectOf(canvas);
+ return sizes.map((size) => ({
+ size,
+ matchesCanvas: Math.abs(aspectOf(size) - target) <= target * ASPECT_TOLERANCE,
+ }));
+}
+
+// One filter chain per input: fit or fill the canvas, force a common timebase and pixel aspect. setsar
+// stops a clip with a non-square pixel aspect from concatenating at the wrong shape; a clip that already
+// matches the canvas is unaffected by either shape (nothing to pad or crop).
+// Per-input audio facts the concat needs: whether the clip HAS an audio track, and how long it runs so a
+// silent stand-in can be cut to match when it does not.
+export interface AudioTrack {
+ hasAudio: boolean;
+ duration: number;
+}
+
+export interface InputMeta extends AudioTrack {
+ size: Size;
+}
+
+export function filterGraph(canvas: Size, fit: EncodeFit, audio: AudioTrack[]): string {
+ const { width: W, height: H } = canvas;
+ // crop scales to COVER then cuts; letterbox scales to FIT then pads. Without force_original_aspect_ratio
+ // ffmpeg stretches and every face goes oval.
+ const shape = fit === 'crop'
+ ? `scale=${W}:${H}:force_original_aspect_ratio=increase:flags=lanczos,crop=${W}:${H}`
+ : `scale=${W}:${H}:force_original_aspect_ratio=decrease:flags=lanczos,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2:color=black`;
+ const parts: string[] = [];
+ audio.forEach((track, i) => {
+ parts.push(`[${i}:v]${shape},setsar=1,fps=30[v${i}]`);
+ // A clip with no audio track cannot be mapped as [i:a]; ffmpeg aborts the whole concat with an opaque
+ // "Stream specifier :a matches no streams". Synthesise silence of the clip's own length instead, so
+ // concat's a=1 always has a stream and a silent motion-graphics shot joins like any other.
+ parts.push(track.hasAudio
+ ? `[${i}:a]aresample=48000,asetpts=N/SR/TB[a${i}]`
+ : `anullsrc=r=48000:cl=stereo,atrim=duration=${track.duration},asetpts=N/SR/TB[a${i}]`);
+ });
+ const count = audio.length;
+ const streams = Array.from({ length: count }, (_, i) => `[v${i}][a${i}]`).join('');
+ parts.push(`${streams}concat=n=${count}:v=1:a=1[v][a]`);
+ return parts.join(';');
+}
+
+export function ffmpegArgs(inputs: string[], out: string, canvas: Size, fit: EncodeFit, audio: AudioTrack[]): string[] {
+ return [
+ '-loglevel', 'error', '-y',
+ ...inputs.flatMap((i) => ['-i', i]),
+ '-filter_complex', filterGraph(canvas, fit, audio),
+ '-map', '[v]', '-map', '[a]',
+ '-c:v', 'libx264', '-crf', '18', '-preset', 'medium', '-pix_fmt', 'yuv420p',
+ '-c:a', 'aac', '-b:a', '192k',
+ '-movflags', '+faststart',
+ out,
+ ];
+}
+
+export async function probeSize(file: string): Promise {
+ const { stdout } = await run(FFPROBE, [
+ '-v', 'error', '-select_streams', 'v:0',
+ '-show_entries', 'stream=width,height', '-of', 'csv=p=0:s=x', file,
+ ]);
+ const [width, height] = stdout.trim().split('x').map(Number);
+ if (!width || !height) throw new Error(`could not read the dimensions of ${file}`);
+ return { width, height };
+}
+
+// One probe for everything the encode path needs: video size, whether an audio track is present, and the
+// container duration (used only to size synthesised silence for an audio-less clip).
+export async function probeInput(file: string): Promise {
+ const { stdout } = await run(FFPROBE, [
+ '-v', 'error',
+ '-show_entries', 'stream=codec_type,width,height:format=duration',
+ '-of', 'json', file,
+ ]);
+ const data = JSON.parse(stdout) as {
+ streams?: { codec_type?: string; width?: number; height?: number }[];
+ format?: { duration?: string };
+ };
+ const streams = data.streams ?? [];
+ const video = streams.find((s) => s.codec_type === 'video');
+ if (!video?.width || !video?.height) throw new Error(`could not read the dimensions of ${file}`);
+ const duration = Number(data.format?.duration);
+ if (!Number.isFinite(duration)) throw new Error(`could not read the duration of ${file}`);
+ return {
+ size: { width: video.width, height: video.height },
+ hasAudio: streams.some((s) => s.codec_type === 'audio'),
+ duration,
+ };
+}
+
+export interface ConcatOptions {
+ canvas?: Size;
+ fit?: EncodeFit;
+}
+
+// Shared by the encode and report paths so the "clip not found" message lives in exactly one place.
+function assertClipsExist(inputs: string[]): void {
+ const missing = inputs.filter((i) => !existsSync(i));
+ if (missing.length > 0) throw new Error(`clip not found:\n ${missing.join('\n ')}`);
+}
+
+export async function concatVideos(inputs: string[], out: string, opts: ConcatOptions = {}): Promise {
+ if (inputs.length < 2) throw new Error('concat needs at least two clips; one clip is already the answer');
+ assertClipsExist(inputs);
+ // Every input is probed now — the audio plan (present vs silent, and each clip's length) is needed even
+ // when --canvas pins the size, so there is nothing to skip.
+ const metas = await Promise.all(inputs.map(probeInput));
+ const target = opts.canvas ?? largestByArea(metas.map((m) => m.size));
+ await run(FFMPEG, ffmpegArgs(inputs, out, target, opts.fit ?? 'letterbox', metas));
+ return target;
+}
+
+// The report path, a sibling to concatVideos that encodes nothing: probe, choose the canvas, and say which
+// clips differ in shape — the --fit open answer, exported so it is testable without a subprocess.
+export async function reportAspects(inputs: string[], canvas?: Size): Promise<{ canvas: Size; report: AspectReport[] }> {
+ assertClipsExist(inputs);
+ const sizes = await Promise.all(inputs.map(probeSize));
+ const target = canvas ?? largestByArea(sizes);
+ return { canvas: target, report: aspectReport(sizes, target) };
+}
+
+// Prints the --fit open report: the chosen canvas, then each clip's shape against it. The report is in
+// input order, so the clip path is taken by position.
+function printAspectReport(inputs: string[], canvas: Size, report: AspectReport[]): void {
+ console.log(`[concat] canvas ${canvas.width}x${canvas.height} (aspect ${aspectOf(canvas).toFixed(3)})`);
+ report.forEach((r, i) => {
+ const tag = r.matchesCanvas ? 'matches ' : 'MISMATCH';
+ console.log(` ${tag} ${r.size.width}x${r.size.height} (${aspectOf(r.size).toFixed(3)}) ${inputs[i]}`);
+ });
+ const off = report.filter((r) => !r.matchesCanvas).length;
+ console.log(
+ off === 0
+ ? '[concat] every clip already matches the canvas — --fit letterbox or crop will both join cleanly.'
+ : `[concat] ${off}/${report.length} clips differ from the canvas aspect — reframe them per shot, ` +
+ 'or fall back to --fit crop (fills, cuts overflow) or --fit letterbox (pads, keeps all framing).',
+ );
+}
+
+export async function concatVideosCommand(argv: string[]): Promise {
+ // Strict, with the clip paths as positionals: a mistyped --canvas or --fit must not silently fall
+ // through and be treated as one of the files to join.
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: { canvas: { type: 'string' }, fit: { type: 'string' } },
+ allowPositionals: true,
+ });
+ const canvas = values.canvas === undefined ? undefined : parseCanvas(values.canvas);
+ const fit = parseFit(values.fit);
+
+ if (fit === 'open') {
+ // open reports on the inputs and writes nothing, so every positional is a clip — there is no out path.
+ const clips = positionals;
+ if (clips.length < 2) {
+ console.error('usage: openedit concat-videos --fit open [...]');
+ return 1;
+ }
+ const { canvas: target, report } = await reportAspects(clips, canvas);
+ printAspectReport(clips, target, report);
+ return 0;
+ }
+
+ const [out, ...inputs] = positionals;
+ if (!out || inputs.length < 2) {
+ console.error(
+ 'usage: openedit concat-videos [--canvas WxH] [--fit letterbox|crop] [...]',
+ );
+ return 1;
+ }
+ const used = await concatVideos(inputs, out, { canvas, fit });
+ console.log(`[concat] ${inputs.length} clips → ${out} at ${used.width}x${used.height} (--fit ${fit})`);
+ return 0;
+}
diff --git a/cli/src/commands/content-root.ts b/cli/src/commands/content-root.ts
new file mode 100644
index 0000000..9742839
--- /dev/null
+++ b/cli/src/commands/content-root.ts
@@ -0,0 +1,13 @@
+import { contentRoot } from "../config.ts";
+
+// Where the recipes, briefs and gates this CLI will use actually live — the installed package, or a
+// checkout when OPEN_EDIT_ROOT points at one. Printed rather than inferred because "which content
+// answered" is the first question when a run picks a style nobody expected.
+export function contentRootCommand(argv: string[]): number {
+ if (argv.length) {
+ console.error("usage: openedit content-root");
+ return 2;
+ }
+ console.log(contentRoot());
+ return 0;
+}
diff --git a/cli/src/commands/creative-log.ts b/cli/src/commands/creative-log.ts
new file mode 100644
index 0000000..fd52845
--- /dev/null
+++ b/cli/src/commands/creative-log.ts
@@ -0,0 +1,145 @@
+// What has already been tried on a piece of footage, and why the accepted version was accepted.
+//
+// The launch session carried both by hand. Every creative brief it wrote ended with an "ALREADY TRIED
+// ON THIS CLIP AND REJECTED" list and, once something landed, a sentence naming why: "the colours
+// worked with the background rather than fighting it, it was graphic, bright and punchy, and the
+// typefaces were interestingly chosen." That worked — the later rounds genuinely diverged — but it
+// lived in the orchestrator's context, which means it was retyped for every agent and erased by the
+// first compaction. Three rounds of "you approached them all the same way" came from exactly that.
+//
+// The log is keyed by the SOURCE VIDEO, not the run: rounds two, three and four of a treatment are
+// different run dirs on the same footage, and it is the footage that accumulates history.
+//
+// creative-log.ts --for --reject "" --why ""
+// creative-log.ts --for --accept "" --why ""
+// creative-log.ts --for --brief # the accumulated history, ready to paste
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { parseFlags } from '../args.ts';
+import { workspaceRoot } from '../config.ts';
+
+export interface Attempt { what: string; why: string }
+export interface CreativeLog {
+ source: string;
+ rejected: Attempt[];
+ /** The last accepted look. A later acceptance replaces it; the rejections only ever accumulate. */
+ accepted?: Attempt;
+}
+
+// Overridable so a test never writes into the real one. The suite once deleted the production log on
+// every run — the artifact whose whole purpose is surviving a compaction did not survive `pnpm test`.
+const LOG_PATH = process.env.OPEN_EDIT_CREATIVE_LOG ?? join(workspaceRoot(), 'runs', '.creative-log.json');
+
+type Store = Record;
+
+let corrupt = false;
+
+function load(): Store {
+ corrupt = false;
+ if (!existsSync(LOG_PATH)) return {};
+ try {
+ return JSON.parse(readFileSync(LOG_PATH, 'utf8')) as Store;
+ } catch {
+ // Reading through a corrupt log is fine — history is a helper, not a gate. Writing through it is
+ // not: the empty fallback would erase the reject/accept history of every clip on the machine.
+ corrupt = true;
+ return {};
+ }
+}
+
+function save(store: Store): void {
+ mkdirSync(dirname(LOG_PATH), { recursive: true });
+ if (corrupt && existsSync(LOG_PATH)) {
+ let dest = LOG_PATH.replace(/\.json$/, '.corrupt.json');
+ let n = 1;
+ while (existsSync(dest)) dest = LOG_PATH.replace(/\.json$/, `.corrupt.${n++}.json`);
+ renameSync(LOG_PATH, dest);
+ process.stderr.write(`[creative-log] the log could not be parsed and was kept at ${dest}; starting a new one\n`);
+ corrupt = false;
+ }
+ writeFileSync(LOG_PATH, JSON.stringify(store, null, 2) + '\n');
+}
+
+export function logFor(source: string, store: Store = load()): CreativeLog {
+ const key = resolve(source);
+ return store[key] ?? { source: key, rejected: [] };
+}
+
+export function reject(source: string, what: string, why: string): CreativeLog {
+ const store = load();
+ const log = logFor(source, store);
+ // The same attempt reported twice is one attempt; a re-run should not inflate the history.
+ if (!log.rejected.some((r) => r.what === what)) log.rejected.push({ what, why });
+ store[log.source] = log;
+ save(store);
+ return log;
+}
+
+export function accept(source: string, what: string, why: string): CreativeLog {
+ const store = load();
+ const log = logFor(source, store);
+ log.accepted = { what, why };
+ store[log.source] = log;
+ save(store);
+ return log;
+}
+
+/**
+ * The history as prompt-ready prose. Empty when nothing has been tried, so a first round carries no
+ * ceremony — and a design pass never has to be told that the list is empty.
+ */
+export function briefFor(source: string): string {
+ const log = logFor(source);
+ const parts: string[] = [];
+ if (log.accepted) {
+ parts.push(
+ `WHAT THE CLIENT ACCEPTED ON THIS FOOTAGE, AND WHY — this is the bar, not a thing to copy:\n` +
+ ` ${log.accepted.what}\n Why it landed: ${log.accepted.why}`,
+ );
+ }
+ if (log.rejected.length) {
+ parts.push(
+ `ALREADY TRIED ON THIS FOOTAGE AND REJECTED — do not land on any of these again:\n` +
+ log.rejected.map((r) => ` · ${r.what}${r.why ? ` — rejected because ${r.why}` : ''}`).join('\n'),
+ );
+ }
+ return parts.join('\n\n');
+}
+
+export function creativeLog(argv: string[]): number {
+ const { values } = parseFlags({
+ args: argv,
+ options: {
+ for: { type: 'string' },
+ reject: { type: 'string' },
+ accept: { type: 'string' },
+ why: { type: 'string' },
+ brief: { type: 'boolean' },
+ },
+ });
+ const source = values.for;
+ if (!source) {
+ console.error('usage: openedit creative-log --for [--reject "" --why ""] [--accept "" --why ""] [--brief]');
+ return 2;
+ }
+ if (values.brief) {
+ const text = briefFor(source);
+ console.log(text || '(nothing tried on this footage yet)');
+ return 0;
+ }
+ if (values.reject === undefined && values.accept === undefined) {
+ console.error('nothing to record: pass --reject, --accept, or --brief');
+ return 2;
+ }
+ // A rejection with no reason is the part that stops being useful three rounds later, when nobody
+ // remembers whether the look was wrong or merely early.
+ if (!values.why) {
+ console.error('--why is required: a list of rejected looks with no reasons cannot tell a later pass what to avoid');
+ return 2;
+ }
+ const log = values.accept !== undefined
+ ? accept(source, values.accept, values.why)
+ : reject(source, values.reject!, values.why);
+ console.log(`[creative-log] ${values.accept !== undefined ? 'accepted' : 'rejected'} recorded — ${log.rejected.length} rejection(s) on file for this footage`);
+ return 0;
+}
diff --git a/cli/src/commands/cut-frames.ts b/cli/src/commands/cut-frames.ts
new file mode 100644
index 0000000..0f349ce
--- /dev/null
+++ b/cli/src/commands/cut-frames.ts
@@ -0,0 +1,197 @@
+// The frames a uniform grid never looks at.
+//
+// node --import tsx pipeline/scripts/cut-frames.ts [--out ] [--json] [--threshold 0.15]
+// [--after 3] [--no-sheets]
+//
+// WHY THIS EXISTS. A run sampled its deliverable at 1.2, 3.8, 9.5, 15.0 and 21.5 seconds and called
+// the composite clean. Its cuts were at 1.83, 5.29, 8.58, 10.75, 14.25, 19.54 and 20.67 — not one
+// sample was within four tenths of a cut, and the defect it was looking for lives ONLY at a cut: the
+// matted speaker lagged the background by a few frames, so for an instant a person from the previous
+// shot stood in front of the next one. Evenly spaced frames are the wrong frames. A cut is where two
+// layers can disagree, where a caption can survive a shot it was never meant to cross, and where a
+// generated take shows its seams — so those are the frames to pull.
+//
+// Detection is ffmpeg's own scene score, and the frames come out as a contact sheet per cut: the last
+// frame BEFORE it and the first few after, so a layer that arrives late is visible as itself rather
+// than inferred.
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, existsSync, statSync, copyFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { parseFlags } from '../args.ts';
+import { FFMPEG, FFPROBE } from '../config.ts';
+import { probeFps } from '../probe.ts';
+
+export interface Cut { tSec: number; score: number }
+
+export function durationOf(video: string): number {
+ const read = (entry: string) => execFileSync(FFPROBE, [
+ '-v', 'error', '-select_streams', 'v:0', '-show_entries', entry, '-of', 'default=nw=1:nk=1', video,
+ ], { encoding: 'utf8' }).trim();
+ // A container with no format duration prints `N/A`, which reads as NaN — and every tile time then
+ // fails `t < durationSec`, so the tool wrote no sheets at all and still exited 0 saying "LOOK at the
+ // strips". The video stream carries its own duration when the container does not.
+ for (const entry of ['format=duration', 'stream=duration']) {
+ const v = Number(read(entry));
+ if (Number.isFinite(v) && v > 0) return v;
+ }
+ throw new Error(`${video}: ffprobe reports no usable duration — a cut cannot be placed in a clip of unknown length`);
+}
+
+/** ffmpeg's metadata printer, as time/score pairs in time order. It deduplicates nothing. */
+export function parseSceneMetadata(out: string): Cut[] {
+ const raw: Cut[] = [];
+ let pending: number | null = null;
+ for (const line of out.split('\n')) {
+ const t = line.match(/pts_time:([\d.]+)/);
+ if (t) { pending = Number(t[1]); continue; }
+ const s = line.match(/scene_score=([\d.]+)/);
+ if (s && pending !== null) { raw.push({ tSec: pending, score: Number(s[1]) }); pending = null; }
+ }
+ return raw.sort((a, b) => a.tSec - b.tSec);
+}
+
+/**
+ * Detections within two frames of each other are one cut seen twice — a dissolve scores on several
+ * consecutive frames — so the strongest score of a run is kept at the time of its FIRST detection.
+ *
+ * The window slides from the most recent detection, not from the start of the run: measuring it from
+ * the start split a four-frame dissolve into three cuts. But sliding alone is transitively closed, so
+ * a strobe, a whip pan or `--threshold 0` produced an unbroken chain and the WHOLE CLIP reported as
+ * one cut, swallowing every real boundary inside it. A run is therefore also capped.
+ *
+ * The cap is in SECONDS, because a dissolve is half a second whatever the frame rate is. Counted in
+ * frames, one 0.5 s cross-dissolve came back as one cut at 24 fps, two at 30 and three at 60 — the
+ * same edit, three answers, because the footage was shot faster.
+ */
+export function mergeAdjacent(cuts: Cut[], fps: number, maxRunSec = 0.5): Cut[] {
+ const merged: Cut[] = [];
+ // The window slides from the most recent DETECTION while the reported time stays at the first one:
+ // a dissolve scores on a run of consecutive frames, and measuring the gap from the start of the run
+ // instead split a four-frame dissolve into three cuts.
+ let lastSeen = -Infinity;
+ for (const c of cuts) {
+ const last = merged[merged.length - 1];
+ const withinGap = last !== undefined && c.tSec - lastSeen < 2 / fps;
+ const withinRun = last !== undefined && c.tSec - last.tSec < maxRunSec + 0.5 / fps;
+ if (withinGap && withinRun) {
+ if (c.score > last.score) merged[merged.length - 1] = { tSec: last.tSec, score: c.score };
+ } else merged.push(c);
+ lastSeen = c.tSec;
+ }
+ return merged;
+}
+
+/** The frame before the cut, then `after` frames from it — sampled at frame centres, clamped to the clip. */
+export function tileTimes(cut: Cut, fps: number, durationSec: number, after: number): number[] {
+ return [-1, ...Array.from({ length: Math.max(0, after) }, (_, k) => k)]
+ .map((k) => cut.tSec + (k + 0.5) / fps)
+ .filter((t) => t >= 0 && t < durationSec);
+}
+
+/** Every shot boundary, by scene score. */
+export function cutsIn(video: string, threshold = 0.15): Cut[] {
+ const out = execFileSync(FFMPEG, [
+ '-v', 'error', '-i', video,
+ '-filter_complex', `select='gt(scene,${threshold})',metadata=print:file=-`,
+ '-an', '-f', 'null', '-',
+ ], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+ return mergeAdjacent(parseSceneMetadata(out), probeFps(video));
+}
+
+/**
+ * One contact sheet per cut: the frame before it and `after` frames from it on.
+ *
+ * The sheet is the deliverable of this tool. A number in a report ("7 cuts detected") is not
+ * something anyone can be wrong in front of; a strip showing the same hand in two positions is.
+ */
+export function sheetsForCuts(
+ video: string,
+ cuts: Cut[],
+ outDir: string,
+ o: { after?: number; width?: number } = {},
+): string[] {
+ const after = o.after ?? 3;
+ const width = o.width ?? 320;
+ const fps = probeFps(video);
+ const dur = durationOf(video);
+ mkdirSync(outDir, { recursive: true });
+
+ const sheets: string[] = [];
+ cuts.forEach((cut, i) => {
+ const stem = `cut${String(i + 1).padStart(2, '0')}`;
+ const tiles = tileTimes(cut, fps, dur, after).map((t, k) => {
+ const p = join(outDir, `${stem}-${k}.png`);
+ execFileSync(FFMPEG, ['-y', '-v', 'error', '-ss', String(t), '-i', video,
+ '-frames:v', '1', '-vf', `scale=${width}:-1`, p]);
+ // A seek past the end of the video stream exits 0 and writes nothing, so the file's existence
+ // is not evidence that a frame came out of it.
+ return existsSync(p) && statSync(p).size > 0 ? p : undefined;
+ }).filter((p): p is string => p !== undefined);
+
+ if (!tiles.length) return;
+ const sheet = join(outDir, `${stem}.png`);
+ // hstack takes two inputs at the minimum; a cut in the last frames of the clip can leave one.
+ if (tiles.length === 1) copyFileSync(tiles[0], sheet);
+ else {
+ execFileSync(FFMPEG, ['-y', '-v', 'error',
+ ...tiles.flatMap((t) => ['-i', t]),
+ '-filter_complex', `hstack=inputs=${tiles.length}`, '-frames:v', '1', sheet]);
+ }
+ sheets.push(sheet);
+ });
+ return sheets;
+}
+
+export function cutFrames(argv: string[]): number {
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: {
+ out: { type: 'string' },
+ json: { type: 'boolean' },
+ threshold: { type: 'string' },
+ after: { type: 'string' },
+ 'no-sheets': { type: 'boolean' },
+ },
+ allowPositionals: true,
+ });
+ const [video] = positionals;
+ if (!video || !existsSync(video)) {
+ console.error('usage: openedit cut-frames [--out ] [--json] [--threshold 0.15] [--after 3] [--no-sheets]');
+ return 2;
+ }
+
+ const num = (name: string, raw: string | undefined, min: number, max: number): number | undefined => {
+ if (raw === undefined) return undefined;
+ const v = Number(raw);
+ if (!Number.isFinite(v) || v < min || v > max) {
+ console.error(`--${name} must be a number between ${min} and ${max}, got "${raw}"`);
+ throw new RangeError('cut-frames: bad flag value');
+ }
+ return v;
+ };
+ // A threshold of 0 fires on every frame and turns the whole clip into one merged run.
+ let cuts, fps, sheets;
+ try {
+ cuts = cutsIn(video, num('threshold', values.threshold, 0.01, 1));
+ fps = probeFps(video);
+ var outDir = values.out ?? join(process.cwd(), 'qa', `cuts-${basename(video).replace(/\.\w+$/, '')}`);
+ sheets = values['no-sheets'] ? [] : sheetsForCuts(video, cuts, outDir, {
+ after: num('after', values.after, 0, 32),
+ });
+ } catch (e) {
+ if (e instanceof RangeError) return 2;
+ throw e;
+ }
+
+ if (values.json) {
+ console.log(JSON.stringify({ video, fps, cuts, sheets }, null, 2));
+ } else {
+ console.log(`${cuts.length} cut(s) at ${fps} fps`);
+ for (const [i, c] of cuts.entries()) {
+ console.log(` cut ${i + 1}: ${c.tSec.toFixed(3)}s (frame ${Math.round(c.tSec * fps)}) score ${c.score.toFixed(3)}`);
+ }
+ if (sheets.length) console.log(`\nOne strip per cut — the frame before it, then the frames after — in ${outDir}`);
+ console.log('LOOK at the strips. A layer that changes on a different frame from the rest of the picture is the defect these frames exist to show.');
+ }
+ return 0;
+}
diff --git a/cli/src/commands/design-gate.ts b/cli/src/commands/design-gate.ts
new file mode 100644
index 0000000..c375100
--- /dev/null
+++ b/cli/src/commands/design-gate.ts
@@ -0,0 +1,44 @@
+import { parseFlags } from "../args.ts";
+import { contentRoot } from "../config.ts";
+import { loadDesignGate, type GateFinding } from "../gates/content-gates.ts";
+
+// A run's authored documents read back against its own design system. Same gate the workspace script
+// runs; loaded from content so a published install needs no checkout and no tsx.
+export async function designGate(argv: string[]): Promise {
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: { json: { type: "boolean" }, doc: { type: "string" } },
+ allowPositionals: true,
+ });
+ const [runDir] = positionals;
+ if (!runDir) {
+ console.error("usage: openedit design-gate [--doc ] [--json]");
+ return 2;
+ }
+
+ const gate = await loadDesignGate(contentRoot());
+ const { findings, documents } = gate(runDir, { doc: values.doc });
+ const errors = findings.filter((f) => f.severity === "error").length;
+ if (values.json) {
+ console.log(JSON.stringify(findings, null, 2));
+ } else {
+ // Findings repeat across documents; one line per distinct message with a count reads better than
+ // the same tracking error printed 217 times.
+ const seen = new Map();
+ for (const f of findings) {
+ const key = `${f.rule}|${f.message}`;
+ const entry = seen.get(key);
+ if (entry) entry.n++;
+ else seen.set(key, { f, n: 1 });
+ }
+ for (const { f, n } of seen.values()) {
+ const repeats = n > 1 ? `+${n - 1} more` : "";
+ const inner = [f.file, repeats].filter(Boolean).join(" ");
+ console.log(`${f.severity.toUpperCase()}[${f.rule}] ${f.message}${inner ? ` (${inner})` : ""}`);
+ }
+ console.log(errors
+ ? `design-gate: ${errors} error(s) across ${documents} document(s)`
+ : `design-gate: clean (${documents} document(s), ${findings.length} warning(s))`);
+ }
+ return errors ? 1 : 0;
+}
diff --git a/cli/src/commands/expect-windows.ts b/cli/src/commands/expect-windows.ts
new file mode 100644
index 0000000..b9fe8e1
--- /dev/null
+++ b/cli/src/commands/expect-windows.ts
@@ -0,0 +1,209 @@
+// Turn the document's own gate timings into assertions `--verify` can fail on.
+//
+// The engine already accepts a `verify.expect` block in the manifest — "this element must be visible
+// from 2.1s to 3.4s" — and it has gone essentially unused, because writing the list by hand for forty
+// cues is nobody's idea of a good time. The document already states every window, so the list can be
+// derived rather than written.
+//
+// This closes the corpus's largest class. `timing-offset` is 30 recorded corrections — a reveal
+// that starts late, a beat that holds too long, a caption still up when the next one arrives — and
+// none of them are visible to `--verify` today, because verify checks what IS drawn and every one of
+// these documents draws something. An expectation is what makes "drawn at the wrong time" a failure.
+//
+// expect-windows.ts [--write] [--tolerance-ms 40]
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseFlags } from '../args.ts';
+
+export interface Expectation {
+ element: string;
+ visible: boolean;
+ from: number;
+ to: number;
+}
+
+/** ms from a CSS time token. */
+function ms(tok: string | undefined): number | undefined {
+ const m = tok?.trim().match(/^(-?[\d.]+)(ms|s)$/);
+ if (!m) return undefined;
+ return m[2] === 's' ? Number(m[1]) * 1000 : Number(m[1]);
+}
+
+function keyframeNames(css: string): Map {
+ const out = new Map();
+ const re = /@keyframes\s+([\w-]+)\s*\{/g;
+ let m: RegExpExecArray | null;
+ while ((m = re.exec(css))) {
+ let depth = 1, i = re.lastIndex;
+ while (i < css.length && depth > 0) {
+ if (css[i] === '{') depth++;
+ else if (css[i] === '}') depth--;
+ i++;
+ }
+ out.set(m[1], css.slice(re.lastIndex, i - 1));
+ }
+ return out;
+}
+
+/**
+ * Every element with an id whose gate holds it visible across a window, as an assertion.
+ *
+ * A gate is a keyframes block that ENDS hidden (`100% { opacity: 0 }`) — the cue-window idiom. The
+ * assertion is sampled INSIDE the window by `toleranceMs` at each end, because an assertion that
+ * straddles the flip instant tests the engine's rounding rather than the design's timing.
+ */
+/** Tags that never wrap anything, so they never open a level. */
+const VOID = new Set(['br', 'img', 'source', 'track', 'input', 'meta', 'link', 'hr', 'area', 'base', 'col', 'embed', 'wbr']);
+
+/**
+ * Every id-carrying element with its TRUE inner html.
+ *
+ * A non-greedy `([\s\S]*?)<\/\1>` stops at the first closing tag of the same name, which for a div
+ * holding a div is the inner one. The leftover text then read as the parent's own ink, so the
+ * "skip elements with no ink of their own" guard never fired and the gate emitted assertions that
+ * FAIL on documents which render perfectly — 18 of them across this repository's own accepted corpus.
+ */
+export function elementsWithId(wv: string): { open: string; attrs: string; id: string; inner: string }[] {
+ const out: { open: string; attrs: string; id: string; inner: string }[] = [];
+ // Blanked rather than removed, so every offset and line number downstream stays true. A commented-out
+ // element is not in the document, and asserting on its id fails a render that is perfectly correct.
+ wv = wv.replace(//g, (m) => ' '.repeat(m.length));
+ const tagRe = /<(\/?)([a-zA-Z][\w-]*)((?:"[^"]*"|'[^']*'|[^>"'])*)>/g;
+ const opens: { name: string; attrs: string; id?: string; innerStart: number; openTag: string }[] = [];
+ let m: RegExpExecArray | null;
+ while ((m = tagRe.exec(wv))) {
+ const [whole, slash, name, attrs] = m;
+ const lower = name.toLowerCase();
+ if (VOID.has(lower)) continue;
+ if (slash) {
+ // Close the most recent open of this name; unbalanced markup simply yields nothing for it.
+ for (let i = opens.length - 1; i >= 0; i--) {
+ if (opens[i].name !== lower) continue;
+ const o = opens.splice(i, 1)[0];
+ if (o.id) out.push({ open: o.openTag, attrs: o.attrs, id: o.id, inner: wv.slice(o.innerStart, m.index) });
+ break;
+ }
+ continue;
+ }
+ if (/\/\s*$/.test(attrs)) continue; // self-closing
+ opens.push({
+ name: lower,
+ attrs,
+ id: attrs.match(/\bid="([^"]+)"/)?.[1],
+ innerStart: m.index + whole.length,
+ openTag: whole,
+ });
+ }
+ return out;
+}
+
+export function expectationsFor(wv: string, durationMs: number, toleranceMs = 40): Expectation[] {
+ const css = wv.match(/]*>([\s\S]*?)<\/style>/gi)?.join('\n') ?? '';
+ const frames = keyframeNames(css);
+ const closing = new Set(
+ [...frames].filter(([, body]) => /(?:\b100%|\bto)\s*\{[^}]*opacity\s*:\s*0(?![.\d])/.test(body)).map(([n]) => n),
+ );
+
+ // class → the closing gate it names, and any timing the rule itself fixes.
+ const gated = new Map();
+ for (const m of css.replace(/\/\*[\s\S]*?\*\//g, '').matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+ const sel = m[1].trim().split('\n').pop()!.trim();
+ const body = m[2];
+ if (sel.startsWith('@') || sel.includes('%')) continue;
+ const cls = sel.match(/^\.([\w-]+)$/)?.[1];
+ if (!cls) continue;
+ const short = body.match(/animation\s*:\s*([^;]+)/)?.[1];
+ const name = short?.trim().split(/\s+/)[0] ?? body.match(/animation-name\s*:\s*([\w-]+)/)?.[1];
+ if (!name || !closing.has(name)) continue;
+ const times = (short ?? '').replace(name, '').trim().split(/\s+/).map(ms).filter((v): v is number => v !== undefined);
+ gated.set(cls, {
+ dur: times[0] ?? ms(body.match(/animation-duration\s*:\s*([^;]+)/)?.[1]),
+ delay: times[1] ?? ms(body.match(/animation-delay\s*:\s*([^;]+)/)?.[1]),
+ });
+ }
+
+ // The slowest ENTRANCE in the document — an animation that ends visible rather than hidden. Every
+ // gate's assertion waits it out, because until it finishes the content inside the gate is mid-fade.
+ let entranceMs = 0;
+ for (const [name, body] of frames) {
+ if (closing.has(name)) continue;
+ if (!/opacity/.test(body)) continue;
+ for (const m of css.matchAll(new RegExp(`animation\\s*:\\s*${name}([^;}]*)`, 'g'))) {
+ const times = m[1].trim().split(/\s+/).map(ms).filter((v): v is number => v !== undefined);
+ if (times.length) entranceMs = Math.max(entranceMs, (times[0] ?? 0) + (times[1] ?? 0));
+ }
+ }
+
+ const out: Expectation[] = [];
+ for (const el of elementsWithId(wv)) {
+ const tag = [el.open] as unknown as RegExpMatchArray;
+ (tag as unknown as string[])[1] = el.attrs.match(/class="([^"]*)"/)?.[1] ?? '';
+ const id = el.id;
+ const inner = el.inner;
+ // `expect-visible` measures the ink of the element ITSELF. When the words live in child spans —
+ // the cue/word structure the brief prescribes and every recipe emits — the parent has no ink of
+ // its own and the assertion fails on a document that renders perfectly. Verified on engine 0.8.0
+ // (`tests/expect-visible-nested.test.ts`), so those elements are skipped rather than asserted wrongly.
+ const ownText = inner.replace(/<(\w+)[^>]*>[\s\S]*?<\/\1>/g, '').replace(/<[^>]*>/g, '').trim();
+ if (!ownText) continue;
+ const style = tag[0].match(/style=(?:"([^"]*)"|'([^']*)')/i)?.slice(1).find((v) => v !== undefined) ?? '';
+ for (const cls of String(tag[1]).split(/\s+/).filter(Boolean)) {
+ const g = gated.get(cls);
+ if (!g) continue;
+ const short = style.match(/animation\s*:\s*([^;"]+)/)?.[1];
+ const times = (short ?? '').trim().split(/\s+/).map(ms).filter((v): v is number => v !== undefined);
+ const dur = times[0] ?? ms(style.match(/animation-duration\s*:\s*([^;"]+)/)?.[1]) ?? g.dur;
+ const delay = times[1] ?? ms(style.match(/animation-delay\s*:\s*([^;"]+)/)?.[1]) ?? g.delay ?? 0;
+ if (dur === undefined) continue;
+ // The gate opening is not the moment the content is ON SCREEN. Inside it, words are still
+ // entering — at 40ms into a 380ms rise the glyph is at about a tenth of its opacity, and an
+ // assertion there tests the entrance rather than the timing it exists to check. Start after the
+ // slowest entrance in the document has finished.
+ const from = delay + Math.max(toleranceMs, entranceMs + toleranceMs);
+ const to = Math.min(delay + dur - toleranceMs, durationMs - toleranceMs);
+ // A window too short to sample inside proves nothing; asserting on it would only be noise.
+ if (to <= from) continue;
+ out.push({ element: id, visible: true, from: Number((from / 1000).toFixed(3)), to: Number((to / 1000).toFixed(3)) });
+ break;
+ }
+ }
+ return out;
+}
+
+export function expectWindows(argv: string[], opts: { quiet?: boolean } = {}): number {
+ // The gate chain derives silently; a human invocation prints what it derived.
+ const say = opts.quiet ? () => {} : console.log;
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: { write: { type: 'boolean' }, 'tolerance-ms': { type: 'string' }, doc: { type: 'string' } },
+ allowPositionals: true,
+ });
+ const dir = positionals[0];
+ if (!dir) { console.error('usage: openedit expect-windows [--doc final] [--write] [--tolerance-ms 40]'); return 2; }
+ // A film has one document per chapter. Hardcoding `final` made the gate chain's own --doc flag a
+ // lie: it reached lint and the engine and stopped here, on a path that does not exist.
+ const doc = (values.doc as string | undefined) ?? 'final';
+ const mfPath = join(dir, doc, 'manifest.json');
+ const mf = JSON.parse(readFileSync(mfPath, 'utf8')) as { render: { duration: number }; verify?: { derivedBy?: string; expect: Expectation[] } };
+ const wv = readFileSync(join(dir, doc, 'template.wv'), 'utf8');
+ const tol = Number(values['tolerance-ms'] ?? 40);
+ if (!Number.isFinite(tol) || tol < 0) {
+ console.error(`--tolerance-ms must be a non-negative number, got "${values['tolerance-ms']}"`);
+ return 2;
+ }
+ const expect = expectationsFor(wv, mf.render.duration * 1000, tol);
+
+ if (!expect.length) { say('expect-windows: no gated elements with ids — nothing to assert'); return 0; }
+ if (values.write) {
+ // Stamped so a later run can tell its own work from a block somebody wrote on purpose. Without
+ // this the gate chain saw any `verify` block as authored and kept a document gated against the
+ // timings of an earlier render.
+ mf.verify = { derivedBy: 'expect-windows', expect };
+ writeFileSync(mfPath, JSON.stringify(mf, null, 2) + '\n');
+ say(`expect-windows: wrote ${expect.length} expectation(s) into ${mfPath} — --verify now fails when a cue is off screen inside its own window`);
+ } else {
+ say(JSON.stringify({ verify: { expect } }, null, 2));
+ say(`\nexpect-windows: ${expect.length} expectation(s); pass --write to put them in the manifest`);
+ }
+ return 0;
+}
diff --git a/cli/src/commands/gates.ts b/cli/src/commands/gates.ts
new file mode 100644
index 0000000..72eda38
--- /dev/null
+++ b/cli/src/commands/gates.ts
@@ -0,0 +1,191 @@
+// THE GATE CHAIN, as one command.
+//
+// openedit gates [--doc ] [--audio ] [--no-mux] [--no-loudnorm] [--no-probe] [--no-expect] [--no-design] [--no-wcag]
+//
+// design → lint → --verify → WCAG → --record → probe-qa → mux. Stops at the first failure and names it.
+// RUN OUTSIDE ANY SANDBOX: --verify and --record need a real desktop session (the window-server on macOS).
+//
+// --no-probe the run has no source footage to diff frames against
+// --no-mux the run has no soundtrack to restore (the silent render is copied to out.mp4, so the
+// deliverable path is the same on every path)
+// --no-expect skip deriving `verify.expect` from the document's own gates. Do not reach for this to
+// make a failure go away: an expect-visible failure means a cue is off screen inside the
+// window the document itself declares, which is a real defect no other gate can see.
+// --no-design the run has no design/system.json — true only of a compiled-recipe run, where the
+// recipe IS the system. An authored run without one is the defect this gate exists for.
+import { spawnSync } from 'node:child_process';
+import { copyFileSync, existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { contentRoot, engineBinPath, engineEnv, workspaceRoot } from '../config.ts';
+import { tsxImportUrl } from '../ts-runtime.ts';
+import { expectWindows } from './expect-windows.ts';
+import { probeQaCommand } from './probe-qa.ts';
+import { muxAudio } from './mux-audio.ts';
+import { wcagPass } from './wcag-pass.ts';
+
+const usage = 'usage: openedit gates [--doc ] [--audio ] [--no-mux] [--no-loudnorm] [--no-probe] [--no-expect] [--no-design] [--no-wcag]';
+
+class GateExit extends Error {
+ constructor(readonly code: number, msg = '') { super(msg); }
+}
+const die = (msg: string, code: number): never => { throw new GateExit(code, msg); };
+const fail = (name: string): never =>
+ die(`gates: FAILED at ${name} — fix that, then re-run the gate chain`, 1);
+
+export function gates(argv: string[]): number {
+ try {
+ run(argv);
+ return 0;
+ } catch (error) {
+ if (error instanceof GateExit) {
+ if (error.message) console.error(error.message);
+ return error.code;
+ }
+ throw error;
+ }
+}
+
+// The design and lint gates are CONTENT: they enforce the design substrate's own rules (the design
+// system, the engine-limit lints the substrate is written against), co-versioned with the recipes
+// they govern. A published install carries them compiled, so they run as plain node; a checkout
+// carries only .ts and needs tsx. Same script, same arguments, either way.
+function runContentGate(script: string, args: string[]): boolean {
+ const root = contentRoot();
+ const compiled = join(root, `${script}.js`);
+ const source = join(root, `${script}.ts`);
+ const path = existsSync(compiled) ? compiled : source;
+ if (!existsSync(path)) {
+ die(`gates: ${script} not found under ${root} — the content root carries no gates; point OPEN_EDIT_ROOT at an Open Edit checkout or reinstall the package`, 2);
+ }
+ const runtime = path.endsWith('.js') ? [path] : ['--import', tsxImportUrl(root), path];
+ return spawnSync(process.execPath, [...runtime, ...args], { stdio: 'inherit', cwd: workspaceRoot() }).status === 0;
+}
+
+// cwd is the workspace root so the engine finds its data/font-cache seed there — the same place
+// every other run artifact anchors.
+const runEngine = (args: string[]) =>
+ spawnSync(engineBinPath(), args, { stdio: 'inherit', env: engineEnv(), cwd: workspaceRoot() }).status === 0;
+
+function run(argv: string[]): void {
+ const [dir, ...rest] = argv;
+ if (!dir) die(usage, 2);
+
+ let noLoudnorm = false;
+
+ let noMux = false;
+ let noProbe = false;
+ let noExpect = false;
+ let noDesign = false;
+ let noWcag = false;
+ // Which document under the run this call gates. A captioned clip has one; a film has one per
+ // chapter, and hardcoding `final` was why a seven-chapter run found no route through here.
+ let doc = 'final';
+ // Whether --doc was actually GIVEN, which is a different question from which document is gated. The
+ // default is `final`, so passing it on unconditionally told design-gate every run was one chapter of
+ // a longer piece — and the declared-but-unused check, which only fires on a whole run, never ran at
+ // all through this chain.
+ let docGiven = false;
+ // A built soundtrack rather than the source clip's track — a film has one, a captioned clip does not.
+ let audio = '';
+ while (rest.length > 0) {
+ const flag = rest.shift();
+ switch (flag) {
+ // `--doc final` is the default written out, not a request to gate one chapter of many.
+ case '--doc': {
+ const value = rest.shift();
+ if (!value) die('--doc needs a subdirectory', 2);
+ doc = value!;
+ if (doc !== 'final') docGiven = true;
+ break;
+ }
+ case '--audio': {
+ const value = rest.shift();
+ if (!value) die('--audio needs a file', 2);
+ audio = value!;
+ break;
+ }
+ case '--no-mux': noMux = true; break;
+ case '--no-loudnorm': noLoudnorm = true; break;
+ case '--no-probe': noProbe = true; break;
+ case '--no-expect': noExpect = true; break;
+ case '--no-design': noDesign = true; break;
+ case '--no-wcag': noWcag = true; break;
+ default:
+ die(`gates: unknown flag ${flag}`, 2);
+ }
+ }
+
+ // A flag that cannot take effect is worse than one that is refused, and the complaint belongs here:
+ // downstream it would print only after design, lint, verify, record and probe-qa had already run.
+ if (noMux && noLoudnorm) console.warn('gates: --no-loudnorm has no effect with --no-mux — nothing is muxed');
+
+ const final = join(dir!, doc);
+ const tpl = join(final, 'template.wv');
+
+ if (!existsSync(tpl)) die(`gates: no ${tpl} — author the document first`, 2);
+ if (!existsSync(join(final, 'manifest.json'))) {
+ die(`gates: no ${join(final, 'manifest.json')} — the render block is required`, 2);
+ }
+
+ if (!noDesign) {
+ console.log('gates: design');
+ const args = docGiven ? [dir!, '--doc', doc] : [dir!];
+ if (!runContentGate('pipeline/scripts/design-gate', args)) fail('design');
+ }
+
+ console.log('gates: lint');
+ if (!runContentGate('pipeline/scripts/lint-template', [tpl])) fail('lint');
+
+ // Derive the timing assertions from the document's own gates, unless the manifest already carries a
+ // hand-written set. Without them --verify only checks what IS drawn; with them it also checks WHEN.
+ // `--write` stamps what it derived, so a re-run can replace its own work and leave a hand-written block
+ // alone. Without the stamp the guard saw any `verify` block as authored and every later run gated the
+ // document against the timings of an earlier one.
+ const manifest = readFileSync(join(final, 'manifest.json'), 'utf8');
+ if (!noExpect && (!manifest.includes('"verify"') || manifest.includes('"derivedBy"'))) {
+ if (expectWindows([dir!, '--doc', doc, '--write'], { quiet: true }) !== 0) fail('expect-windows');
+ }
+
+ console.log('gates: verify');
+ if (!runEngine([final, '--verify'])) fail('--verify');
+
+ // Contrast is a REPORT, not a verdict. wcag-pass exits 1 only when the engine is missing or below the
+ // version floor that carries the analyzer, or when the pass itself crashes,
+ // and its own documentation calls that an environment problem rather than a design failure — so it is
+ // said out loud and the run continues to a deliverable rather than dying without one.
+ //
+ // It reads /final and takes no document argument, so it has nothing to say about a chapter of a
+ // longer piece. Running it anyway would either abort on a directory that is not there or, worse, report
+ // on a document this invocation never touched.
+ if (!noWcag) {
+ if (doc !== 'final') {
+ console.log(`gates: wcag skipped — it reads ${dir}/final and this run gates ${doc}; check contrast on the assembled film`);
+ } else {
+ console.log('gates: wcag');
+ if (wcagPass(['--run', dir!]) !== 0) {
+ console.error('gates: wcag could not run (engine missing, below the version floor, or crashed) — contrast is UNCHECKED for this render');
+ }
+ }
+ }
+
+ console.log('gates: record');
+ if (!runEngine([final, '--progress-output', '--record', join(final, 'out.silent.mp4')])) fail('--record');
+
+ if (!noProbe) {
+ console.log('gates: probe-qa');
+ if (probeQaCommand([dir!, '--doc', doc]) !== 0) fail('probe-qa');
+ } else {
+ console.log('gates: probe-qa skipped (no source footage to diff against)');
+ }
+
+ if (!noMux) {
+ console.log('gates: mux');
+ const muxArgs = [dir!, '--doc', doc, ...(audio ? ['--audio', audio] : []), ...(noLoudnorm ? ['--no-loudnorm'] : [])];
+ if (muxAudio(muxArgs) !== 0) fail('mux');
+ } else {
+ copyFileSync(join(final, 'out.silent.mp4'), join(final, 'out.mp4'));
+ console.log('gates: no soundtrack to restore — silent render copied to out.mp4');
+ }
+
+ console.log(`gates: clean → ${join(final, 'out.mp4')}`);
+}
diff --git a/cli/src/commands/generate-recipe.ts b/cli/src/commands/generate-recipe.ts
new file mode 100644
index 0000000..964b2b6
--- /dev/null
+++ b/cli/src/commands/generate-recipe.ts
@@ -0,0 +1,211 @@
+// Recipe runner — the fast path's DESIGN + RENDER for recipe-backed picks. Loads the compiled recipe for the
+// run's sampled ref (refs/html//recipe.ts), generates runs//final/{template.wv,
+// manifest.json} deterministically (zero tokens), then optionally drives the full gate chain:
+// lint → --verify (mechanical ladder fix loop) → --record → probe-qa. Run OUTSIDE any sandbox when
+// passing --verify/--record (the engine needs the window-server).
+// openedit generate-recipe --run [--verify] [--record] [--module ]
+// --module runs a specific recipe module (standalone runs — no style.json needed — or a CUSTOMISED
+// copy). Never edit a library recipe (refs/html//recipe.ts) for one run: copy it to the scratchpad,
+// rewrite its relative lib import to the absolute pipeline/recipes/lib.ts path, edit the copy, pass it here.
+// Exit: 0 done · 1 a gate failed (lint error, verify after the fix cycles, record, or probe FAIL) ·
+// 2 usage, or a refused input (a --module that does not exist, a style.json pointing outside the
+// recipe library) · 3 no compiled recipe for the sampled ref (caller runs the from-scratch inline pass).
+import { parseFlags } from '../args.ts';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join, resolve, sep } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { wcagPass } from './wcag-pass.ts';
+import { contentRoot, engineBinPath, engineEnv, workspaceRoot } from '../config.ts';
+import { probeRun } from './probe-qa.ts';
+import { readStylePick } from './sample-style.ts';
+import { compiledGeneratorRelPath, generatorRelPath, type RecipeGenerator, type RunMeta } from '../recipes-contract.ts';
+import type { WordTimings } from '../prep/synth-word-timings.ts';
+import { reexecFailureReason, reexecWithStripTypes, tsxImportUrl } from '../ts-runtime.ts';
+
+const MAX_FIX_CYCLES = 2;
+
+// --verify's bounds failures name a beat-scoped caption element. Id shapes vary per recipe
+// (#b3p1l2, #b3p1, #b3l2, #b3l1r2, …) but all are `b` + letter+digit segments; the runner
+// passes the EXACT id as a demotion key and each recipe maps it to its own ladder scope via
+// demotionFor. Anything else failing means a generator bug — report, never improvise.
+function boundsLineIds(verifyOut: string): string[] {
+ return [...verifyOut.matchAll(/FAIL\[bounds\] #(b\d+(?:[a-z]+\d*)*)\b/g)].map((m) => m[1]);
+}
+
+export async function generateRecipe(argv: string[]): Promise {
+ // Strict: an unknown flag is an error, never a no-op. This script once accepted --style, ignored it,
+ // and re-rendered the previously sampled ref — printing the OLD id while looking like it had worked.
+ // A flag that changes nothing must say so rather than let a run look like it obeyed.
+ const { values } = parseFlags({
+ args: argv,
+ options: {
+ run: { type: 'string' },
+ module: { type: 'string' },
+ record: { type: 'boolean' },
+ verify: { type: 'boolean' },
+ wcag: { type: 'boolean' },
+ 'wcag-apply': { type: 'boolean' },
+ 'progress-output': { type: 'boolean' },
+ },
+ });
+ const runArg = values.run;
+ if (!runArg) {
+ console.error('usage: openedit generate-recipe --run [--verify] [--record] [--wcag] [--wcag-apply] [--module ]');
+ return 2;
+ }
+ const runDir = resolve(runArg);
+ const doRecord = values.record ?? false;
+ const doVerify = (values.verify ?? false) || doRecord; // record only ever happens on a clean verify
+ // --wcag: opt-in WCAG AA contrast pass between verify and record (DEFAULT on
+ // the creative faces, which run the gates by hand — see the skill; opt-in
+ // here so the recipe fast path stays byte-identical until asked). It runs
+ // DETECT-ONLY: it audits real rendered contrast + emits contrast-statistics.json
+ // and reports, but changes nothing. It only makes sense inside the gate
+ // chain — bare --wcag would run without a rendered final/ to audit.
+ // --wcag-apply implies --wcag and runs the pass in APPLY mode (remediate +
+ // promote a remediated final/template.wv on measured improvement).
+ const doWcagApply = values['wcag-apply'] ?? false;
+ const doWcag = (values.wcag ?? false) || doWcagApply;
+ if (doWcag && !doVerify) {
+ console.error('[generate-recipe] --wcag requires --verify or --record (the WCAG pass runs after a clean verify)');
+ return 2;
+ }
+
+ // --module needs no style.json (independent/standalone runs); the sampled-ref path requires it.
+ const moduleOverride = values.module;
+ let modPath: string;
+ if (moduleOverride) {
+ modPath = resolve(moduleOverride);
+ if (!existsSync(modPath)) { console.error(`[generate-recipe] --module ${modPath} does not exist`); return 2; }
+ console.log(`[generate-recipe] module ${modPath}`);
+ } else {
+ const style = readStylePick(runDir);
+ const compiled = join(contentRoot(), compiledGeneratorRelPath(style.refId));
+ modPath = existsSync(compiled) ? compiled : join(contentRoot(), generatorRelPath(style.refId));
+ // Last line before import(): whatever style.json said, a library module lives under refs/html/.
+ // --module is exempt by design — an explicit operator path (the scratchpad copy) is the point.
+ const libraryRoot = join(contentRoot(), 'refs', 'html') + sep;
+ if (!modPath.startsWith(libraryRoot)) {
+ console.error(`[generate-recipe] refusing to load ${modPath}: outside ${libraryRoot}`);
+ return 2;
+ }
+ if (!style.hasRecipe || !existsSync(modPath)) {
+ console.error(`[generate-recipe] no compiled recipe for "${style.refId}" (${modPath}) — run the from-scratch inline pass (SKILL: DESIGN + RENDER variant B)`);
+ return 3;
+ }
+ }
+ // Recipe modules are workspace TypeScript. Try the load, then retry under the stripping flag,
+ // rather than grading the runtime by version.
+ let recipe: RecipeGenerator;
+ try {
+ recipe = (await import(pathToFileURL(modPath).href)).default as RecipeGenerator;
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code !== 'ERR_UNKNOWN_FILE_EXTENSION') throw e;
+ // Node never strips types inside node_modules, on any version and under any flag, so re-running
+ // an installed package's own .ts walks into the same wall a second time. Where the compiled
+ // module ships beside the source — every ref in the pool — name it instead of retrying.
+ const compiled = modPath.replace(/\.ts$/, '.js');
+ if (compiled !== modPath && existsSync(compiled)) {
+ console.error(`[generate-recipe] ${modPath} is TypeScript this Node cannot load — pass --module ${compiled}, the compiled module beside it`);
+ return 2;
+ }
+ const outcome = reexecWithStripTypes();
+ if (outcome.kind === 'ran') return outcome.code;
+ console.error(`[generate-recipe] cannot load the recipe module ${modPath}: ${reexecFailureReason(outcome)}`);
+ return 2;
+ }
+ const meta = JSON.parse(readFileSync(join(runDir, 'meta.json'), 'utf8')) as RunMeta;
+ const timings = JSON.parse(readFileSync(join(runDir, 'word-timings.json'), 'utf8')) as WordTimings;
+
+ const finalDir = join(runDir, 'final');
+ mkdirSync(finalDir, { recursive: true });
+ const demote: Record = {};
+ const tplPath = join(finalDir, 'template.wv');
+ const manifestPath = join(finalDir, 'manifest.json');
+ const write = () => {
+ const out = recipe.generate(meta, timings, { demote });
+ writeFileSync(tplPath, out.wv);
+ writeFileSync(manifestPath, out.manifest);
+ };
+ write();
+ console.log(`[generate-recipe] ${recipe.refId}: ${timings.beats.length} beats → ${tplPath}`);
+
+ // Gate 1 — LINT (pure, no engine; runs on every generate): a generated document violating engine
+ // limits is a generator bug — fix the recipe module (or lib), never the output.
+ // The manifest is written seven lines up, and three rules are decidable only with it — a run that
+ // lints without it is running a strictly weaker gate than the shell path, silently.
+ // The lint rules live in the workspace (substrate-owned, next to the recipes they govern);
+ // --json hands back the same findings the old in-process import returned.
+ const lint = (): { severity: string; rule: string; message: string }[] => {
+ const base = join(contentRoot(), 'pipeline', 'scripts', 'lint-template');
+ const lintPath = existsSync(`${base}.js`) ? `${base}.js` : `${base}.ts`;
+ if (!existsSync(lintPath)) throw new Error(`[generate-recipe] ${lintPath} not found — the content root carries no gates; point OPEN_EDIT_ROOT at an Open Edit checkout or reinstall the package`);
+ const runtime = lintPath.endsWith('.js') ? [lintPath] : ['--import', tsxImportUrl(contentRoot()), lintPath];
+ const r = spawnSync(process.execPath, [...runtime, tplPath, '--json'], { encoding: 'utf8', cwd: workspaceRoot() });
+ if (r.error || r.stdout === null) throw new Error(`[generate-recipe] lint could not run: ${r.error?.message ?? 'no output'}`);
+ return JSON.parse(r.stdout);
+ };
+ const findings = lint();
+ for (const x of findings) console.log(`${x.severity.toUpperCase()}[${x.rule}] ${x.message}`);
+ if (findings.some((x) => x.severity === 'error')) {
+ console.error('[generate-recipe] lint failed — fix the recipe module, never the generated document');
+ return 1;
+ }
+ if (!doVerify) return 0;
+
+ // Folder mode discovers template.wv (engine >= 0.7.1) and picks up manifest.json alongside it.
+ for (let cycle = 0; ; cycle++) {
+ const r = spawnSync(engineBinPath(), [finalDir, '--verify'], { encoding: 'utf8', env: engineEnv(), cwd: workspaceRoot() });
+ if (r.error) { console.error(`[generate-recipe] cannot run ${engineBinPath()}: ${r.error.message}`); return 1; }
+ const out = `${r.stdout ?? ''}${r.stderr ?? ''}`;
+ if (r.status === 0) { console.log(`[generate-recipe] verify clean (exit 0)${cycle ? ` after ${cycle} fix cycle(s)` : ''}`); break; }
+ const lineIds = boundsLineIds(out);
+ if (r.status !== 1 || !lineIds.length || cycle >= MAX_FIX_CYCLES) {
+ console.error(out.trim());
+ console.error(`[generate-recipe] verify failed (exit ${r.status})${lineIds.length ? '' : ' — no mechanical fix applies (not a bounds failure on a caption line)'}`);
+ return 1;
+ }
+ // one row per failing element per cycle: --verify names the element once per offending frame
+ for (const key of new Set(lineIds)) demote[key] = (demote[key] ?? 0) + 1;
+ console.log(`[generate-recipe] FAIL[bounds] → ladder step down: ${lineIds.join(', ')} (cycle ${cycle + 1}/${MAX_FIX_CYCLES})`);
+ write();
+ }
+
+ // The ladder loop regenerates on demotion — re-check the final document (errors only; warns shown above).
+ if (Object.keys(demote).length && lint().some((x) => x.severity === 'error')) {
+ console.error('[generate-recipe] lint failed after ladder demotion — generator bug; report, never hand-edit');
+ return 1;
+ }
+
+ // Gate 3.5 — WCAG: audit real rendered contrast + emit contrast-statistics.json,
+ // then report. DETECT-ONLY: status 'attention' lists every low-contrast
+ // selector but changes nothing — record still consumes the verified final/.
+ if (doWcag) {
+ // Exit 1 is tooling (engine missing or below the analyzer floor) — the same hard fail as before.
+ if (wcagPass(['--run', runDir, ...(doWcagApply ? ['--apply'] : [])]) !== 0) return 1;
+ }
+
+ if (doRecord) {
+ const outMp4 = join(finalDir, 'out.silent.mp4');
+ const r = spawnSync(engineBinPath(), [finalDir, '--progress-output', '--record', outMp4], { stdio: 'inherit', env: engineEnv(), cwd: workspaceRoot() });
+ if (r.status !== 0) { console.error(`[generate-recipe] record failed (exit ${r.status})`); return 1; }
+ console.log(`[generate-recipe] recorded ${outMp4}`);
+
+ // Gate 4 — PROBE: mechanical frame QA vs the source (the defects --verify can't see: dead-air
+ // mid-beat, unreadable ink). FAIL → do NOT redesign and do NOT auto-re-render; report honestly
+ // and offer a --seed/--style re-run. Warns are FYI — mention them and proceed.
+ const probes = probeRun(runDir);
+ for (const p of probes.filter((x) => x.verdict !== 'pass')) {
+ console.log(`[probe-qa] beat ${p.beat} ${p.probe}@${p.tSec}s ink=${p.inkPct}% contrast=${p.contrast ?? '-'} ${p.verdict.toUpperCase()}${p.notes.length ? ' — ' + p.notes.join('; ') : ''}`);
+ }
+ const probeFails = probes.filter((x) => x.verdict === 'fail');
+ if (probeFails.length) {
+ console.error(`[generate-recipe] probe-qa: ${probeFails.length} FAIL — report honestly; offer a --seed/--style re-run`);
+ return 1;
+ }
+ console.log(`[generate-recipe] probe-qa clean (${probes.filter((x) => x.verdict === 'warn').length} warn)`);
+ }
+ return 0;
+}
+
diff --git a/cli/src/commands/generate-set.ts b/cli/src/commands/generate-set.ts
new file mode 100644
index 0000000..28e80f6
--- /dev/null
+++ b/cli/src/commands/generate-set.ts
@@ -0,0 +1,278 @@
+// One approval covering SEVERAL shots.
+//
+// npx @veedstudio/openedit-cli generate-set --shots shots.json --key poem --workspace
+// npx @veedstudio/openedit-cli generate-set --key poem --yes
+//
+// A set is a layer over the single-shot engine, not a replacement for it. Every guarantee generate.ts
+// already provides is per-KEY — the charge record that survives a create which timed out, --resume,
+// --abandon, the refusal to buy the same script twice — so each shot runs under its own derived key
+// (`poem-1`, `poem-2`, …) and keeps all of them, unchanged and independent. A shot that fails leaves the
+// shots already paid for alone.
+//
+// What the set adds is the ONE thing a user should not have to do N times: approve. The set approval is
+// the authorisation; the per-shot approvals it writes are its expansion, not a second question. That is
+// why the set is hashed as a whole — reorder the shots, edit one line, swap one image, and the approval
+// no longer covers what is about to be bought.
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { estimateRange, estimateTotalCredits } from '../veed/fabric.ts';
+import {
+ assertNonEmptyScript, type GenerateDeps, type PendingConfirmation, pendingPathFor, run, runDirFor,
+ scriptHash,
+} from './generate.ts';
+import {
+ DEFAULT_VOICE_RATES_PATH, parseVoiceRates, rateRange, resolveRate, SEEDED_RATES, type VoiceRates,
+} from '../veed/voice-rates.ts';
+
+export interface Shot {
+ // Names the run directory for this shot, so a failure points at something a person can act on.
+ id: string;
+ script: string;
+ character?: string;
+ image?: string;
+ voice?: string;
+}
+
+export interface SetApproval {
+ shots: Shot[];
+ // Over the WHOLE set: order included, because two shots swapped is a different video.
+ setSha256: string;
+ workspaceId: string;
+ workspaceNamed: boolean;
+ estimatedCredits: number;
+ approvedAt: number;
+}
+
+export function setPathFor(key: string): string {
+ return join(runDirFor(key), '.fabric-pending-set.json');
+}
+
+// The key a shot runs under. Derived, never taken from input, so a shot id cannot escape the run dir.
+export function shotKey(setKey: string, id: string): string {
+ return `${setKey}-${id}`;
+}
+
+export function hashSet(shots: Shot[]): string {
+ const canonical = JSON.stringify(
+ shots.map((s) => ({ id: s.id, script: s.script, character: s.character ?? null, image: s.image ?? null, voice: s.voice ?? null })),
+ );
+ return createHash('sha256').update(canonical).digest('hex');
+}
+
+export function parseShots(raw: string): Shot[] {
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(raw);
+ } catch (e) {
+ throw new Error(`the shots file is not valid JSON: ${e instanceof Error ? e.message : e}`);
+ }
+ if (!Array.isArray(parsed) || parsed.length === 0) throw new Error('the shots file must be a non-empty array');
+
+ const seen = new Set();
+ return parsed.map((entry, i) => {
+ const s = entry as Partial;
+ const id = s.id ?? String(i + 1);
+ if (!/^[A-Za-z0-9._-]+$/.test(id)) throw new Error(`shot ${i + 1}: id "${id}" must be letters, digits, dot, dash or underscore`);
+ if (seen.has(id)) throw new Error(`shot ${i + 1}: duplicate id "${id}" — ids name run directories, so they must differ`);
+ seen.add(id);
+ if (s.character && s.image) throw new Error(`shot ${id}: give a character or an image, not both`);
+ return {
+ id,
+ script: assertNonEmptyScript(String(s.script ?? '')),
+ ...(s.character ? { character: s.character } : {}),
+ ...(s.image ? { image: s.image } : {}),
+ ...(s.voice ? { voice: s.voice } : {}),
+ };
+ });
+}
+
+// Priced shot by shot at each shot's own voice rate, then summed — a set can mix a measured voice with an
+// unmeasured one, and averaging them would quote a figure that is right for neither. `low`/`high` are the
+// spread across known speaking rates, carried so the approval can say how firm the total is.
+export function estimateSet(
+ shots: Shot[],
+ defaults: { voice: string } = { voice: '' },
+ rates: VoiceRates = SEEDED_RATES,
+): { credits: number; low: number; high: number; allMeasured: boolean } {
+ const spread = rateRange(rates);
+ let credits = 0;
+ let low = 0;
+ let high = 0;
+ let allMeasured = true;
+ for (const shot of shots) {
+ const { charsPerSecond, samples } = resolveRate(shot.voice ?? defaults.voice, rates);
+ if (samples === null) allMeasured = false;
+ // Each shot is a separate generation, so its speech rounds up to its own whole minute — priced per
+ // shot and summed, never as one pooled duration.
+ credits += estimateTotalCredits(shot.script, charsPerSecond);
+ const range = estimateRange(shot.script, spread);
+ low += range.low;
+ high += range.high;
+ }
+ return { credits, low, high, allMeasured };
+}
+
+// Every way a stored set approval can fail to cover what is about to be spent. Each is a refusal, never
+// a warning: the whole point of the record is that nobody is billed for something they did not see.
+export function assertCovers(approval: SetApproval, shots: Shot[], nowMs: number, maxAgeMs: number): void {
+ if (hashSet(shots) !== approval.setSha256) {
+ throw new Error(
+ 'refusing to spend: the shots no longer match the set that was approved — a script, an image, an ' +
+ 'order or a voice has changed. Nothing spent. Re-run the confirm pass and approve the new figure.',
+ );
+ }
+ // Guard the timestamp before doing arithmetic on it — a missing/non-finite approvedAt makes `age` NaN,
+ // and the age-based message would otherwise read "NaN minutes old", which names no actionable reason.
+ if (!Number.isFinite(approval.approvedAt)) {
+ throw new Error(
+ 'refusing to spend: the approval has no valid timestamp — the pending set record is corrupt. ' +
+ 'Nothing spent. Re-run the confirm pass and approve a fresh figure.',
+ );
+ }
+ const age = nowMs - approval.approvedAt;
+ if (age < 0 || age > maxAgeMs) {
+ throw new Error(
+ `refusing to spend: the approval is ${Math.round(age / 60_000)} minutes old. Nothing spent. ` +
+ 'Re-run the confirm pass and approve a fresh figure.',
+ );
+ }
+}
+
+// Expands the ONE approval into the per-shot approval each run consumes. These files are not a second
+// question — they are what the answer already given means, written where the single-shot engine reads it.
+export function pendingForShot(
+ approval: SetApproval,
+ shot: Shot,
+ defaults: { character: string; voice: string },
+ rates: VoiceRates = SEEDED_RATES,
+): PendingConfirmation {
+ const voiceId = shot.voice ?? defaults.voice;
+ // The SAME rate the single-shot engine will re-derive when it re-confirms this pending. Priced any
+ // other way, its "you approved N but the quote is now M" guard fires on every shot of every set.
+ const { charsPerSecond } = resolveRate(voiceId, rates);
+ return {
+ script: shot.script,
+ scriptSha256: scriptHash(shot.script),
+ characterId: shot.character ?? defaults.character,
+ ...(shot.image ? { image: shot.image } : {}),
+ voiceId,
+ workspaceId: approval.workspaceId,
+ workspaceNamed: approval.workspaceNamed,
+ estimatedCredits: estimateTotalCredits(shot.script, charsPerSecond),
+ approvedAt: approval.approvedAt,
+ };
+}
+
+export interface SetResult {
+ status: 'confirmed' | 'generated' | 'no-token' | 'workspace-required';
+ credits?: number;
+ clips?: string[];
+}
+
+export async function runSet(
+ args: { key: string; shots?: Shot[]; workspace?: string; yes: boolean; character: string; voice: string },
+ deps: GenerateDeps,
+ maxAgeMs = 60 * 60_000,
+): Promise {
+ const log = deps.log ?? ((m: string) => console.log(m));
+ // Both default the same way generate.ts does, so a set and a single shot agree about time.
+ const now = deps.now ?? Date.now;
+ const setPath = setPathFor(args.key);
+ // The same learned rates the single-shot engine reads, so a set and a shot quote the same script alike.
+ const rates = parseVoiceRates(await deps.readState(DEFAULT_VOICE_RATES_PATH));
+
+ if (!args.yes) {
+ if (!args.shots) throw new Error('the confirm pass needs --shots ');
+ const shots = args.shots;
+ const { credits, low, high, allMeasured } = estimateSet(shots, { voice: args.voice }, rates);
+
+ // One block, one figure, one yes. The per-shot lines are there so nobody approves a total without
+ // seeing what makes it up.
+ log(
+ [
+ `[fabric] ${shots.length} shots in one approval`,
+ ...shots.map((s) => {
+ const who = s.image ? `your image (${s.image})` : (s.character ?? args.character);
+ const { charsPerSecond, samples } = resolveRate(s.voice ?? args.voice, rates);
+ const basis = samples === null ? 'estimated rate' : `${samples} run${samples === 1 ? '' : 's'} of this voice`;
+ return ` ${s.id.padEnd(10)} ~${estimateTotalCredits(s.script, charsPerSecond)} credits · ${s.script.length} chars · ${who} · ${basis}`;
+ }),
+ ` ${'TOTAL'.padEnd(10)} ~${credits} AI Playground credits`,
+ // Cost follows the finished DURATION, and speaking rate decides that. Where a voice has never been
+ // measured the total is a lean-slow guess, so the spread it could land in is stated rather than
+ // implied by a tilde.
+ ...(allMeasured
+ ? []
+ : [` ${''.padEnd(10)} some voices here have never been measured — expect ${low}-${high} credits`]),
+ ].join('\n'),
+ );
+
+ // Written only after the block is printed: an approval that exists before the user has seen what it
+ // covers is an approval for nothing.
+ const approval: SetApproval = {
+ shots,
+ setSha256: hashSet(shots),
+ workspaceId: args.workspace ?? '',
+ workspaceNamed: Boolean(args.workspace),
+ estimatedCredits: credits,
+ approvedAt: now(),
+ };
+ await deps.writeState(setPath, `${JSON.stringify(approval, null, 2)}\n`);
+ log(`\nNothing spent. To approve ${credits} credits and generate all ${shots.length}, run exactly:\n\n npx @veedstudio/openedit-cli generate-set --key ${args.key} --yes\n`);
+ return { status: 'confirmed', credits };
+ }
+
+ const raw = await deps.readState(setPath);
+ if (raw === null) {
+ throw new Error(
+ `no approved set for --key ${args.key}. Run the confirm pass first (it spends nothing):\n` +
+ ` npx @veedstudio/openedit-cli generate-set --shots --key ${args.key}`,
+ );
+ }
+ const approval = JSON.parse(raw) as SetApproval;
+ assertCovers(approval, approval.shots, now(), maxAgeMs);
+
+ const clips: string[] = [];
+ for (const shot of approval.shots) {
+ const key = shotKey(args.key, shot.id);
+ // The set approval, expanded where the single-shot engine looks for it. Everything below this line
+ // is the existing per-shot path, with every guarantee it already had.
+ await deps.writeState(
+ pendingPathFor(key),
+ `${JSON.stringify(pendingForShot(approval, shot, { character: args.character, voice: args.voice }, rates), null, 2)}\n`,
+ );
+ log(`[fabric] shot ${shot.id} →`);
+ const result = await run(
+ { key, character: args.character, voice: args.voice, workspace: approval.workspaceId, yes: true, resume: false },
+ deps,
+ );
+ if (result.status !== 'generated') return { status: result.status as SetResult['status'], clips };
+ clips.push(join(runDirFor(key), `${key}.mp4`));
+ }
+
+ // Spent: the approval is gone, so one yes buys one set — the same rule a single shot follows.
+ await deps.removeState(setPath);
+ log(`\n[fabric] ${clips.length} clips generated. Join them with:\n node --import tsx pipeline/scripts/concat-videos.ts ${join(runDirFor(args.key), `${args.key}.mp4`)} ${clips.join(' ')}`);
+ return { status: 'generated', clips };
+}
+
+export async function generateSet(argv: string[]): Promise {
+ const { parseArgs, realDeps } = await import('./generate.ts');
+ const at = argv.indexOf('--shots');
+ if (at !== -1 && (at + 1 >= argv.length || argv[at + 1].startsWith('--'))) {
+ throw new Error('flag --shots requires a value: the path to a shots JSON file');
+ }
+ const shotsFile = at === -1 ? undefined : argv[at + 1];
+ // --shots is handled here and removed; everything left is handed to the single-shot parser, which is
+ // strict and will name any other unknown flag.
+ const rest = at === -1 ? argv : [...argv.slice(0, at), ...argv.slice(at + 2)];
+ // parseArgs wants a script on a confirm pass and REFUSES one alongside --yes; a set keeps its
+ // scripts in the shots file, so the placeholder is supplied only where the parser insists on it.
+ const spending = rest.includes('--yes');
+ const args = parseArgs(spending || rest.includes('--script') ? rest : [...rest, '--script', 'set']);
+ const shots = shotsFile ? parseShots(await readFile(shotsFile, 'utf8')) : undefined;
+ const result = await runSet({ ...args, shots }, realDeps());
+ if (result.status === 'workspace-required' || result.status === 'no-token') return 1;
+ return 0;
+}
diff --git a/cli/src/commands/generate.ts b/cli/src/commands/generate.ts
new file mode 100644
index 0000000..1d768fd
--- /dev/null
+++ b/cli/src/commands/generate.ts
@@ -0,0 +1,1179 @@
+// Generate source footage with VEED Fabric when the user has no video to caption.
+//
+// 1. Log in once: npx @veedstudio/openedit-cli login (same token as transcription — no MCP connector)
+// 2. Confirm cost: npx @veedstudio/openedit-cli generate --script "..." --key my-run --workspace ws-id
+// 3. Spend + make: npx @veedstudio/openedit-cli generate --key my-run --yes (NO --script here)
+// 4. If 3 broke: npx @veedstudio/openedit-cli generate --key my-run --resume (collects, spends nothing)
+// 5. If 3 vanished: npx @veedstudio/openedit-cli generate --key my-run --abandon (clears one record)
+//
+// Which workspace pays is the user's decision: with no --workspace and no remembered choice the confirm
+// pass stops and prints every workspace with its balance. A remembered choice (veed/.veed-workspace.json) is
+// not a confirmed one, so the spend pass refuses until the command names the workspace, and refuses a
+// different one from the approval. A run that spends reports what it was approved for, plus what the balance
+// did, into runs//.fabric-spend-.json.
+//
+// Confirm and spend are two separate processes. The confirm pass writes the approved script + its SHA-256,
+// ids, workspace and quoted credits to runs//.fabric-pending.json; the spend pass spends THAT and takes
+// no --script (re-typing it is how billed words drift from priced ones). It refuses if the fresh estimate
+// exceeds the approved figure, the recorded script no longer matches its hash, or the approval is over an
+// hour old; a spent approval is deleted so one "yes" buys one video.
+//
+// Nothing takes an exclusive lock, because concurrent runs are normal: every attempt writes its OWN
+// runs//.fabric-charge-.json. It is written BEFORE the create call (phase 'charging') and
+// updated with the job id after (phase 'charged'), because a create that times out or 502s has still moved
+// the money and only a record written first can say so. Before charging, a run stands down if another is
+// charging now, is already paid for (--resume collects it), or was orphaned (--abandon clears that one
+// record). See veed/charge-records.ts.
+//
+// Writes runs//.mp4, whose filename must derive back to via runKeyOf (resolve-video.ts, the
+// rule go.ts and prep.ts share). The default run only ever CONFIRMS, since generation spends real credits.
+// The flow lives in run() with HTTP client, token, download and file write injected (like orchestrate.ts's
+// transcribeWithVeed) so the spend gate is testable offline; main() supplies the real ones.
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { runsDir } from '../config.ts';
+import { runKeyOf } from '../resolve-video.ts';
+import { assertSafeKey, assertSafeSessionId, describeValue, parseFlags } from '../args.ts';
+import {
+ chargeFileName, classifyChargeRecords, parseChargeRecord, sessionIdOfChargeFile,
+ type ChargeRecord, type ChargeVerdict,
+} from '../veed/charge-records.ts';
+import {
+ awaitVideo, CHARS_PER_SECOND, confirmVideo, createVideo, curatedVoiceFor, estimateRange,
+ estimateTotalCredits, framingOf, FabricJobFailedError, getAllowances, listCharacters,
+ type Allowances, type ImageSource,
+} from '../veed/fabric.ts';
+import type { VeedHttp } from '../veed/api.ts';
+import { refreshingHttp } from '../veed/http.ts';
+import { resolveVeedToken } from '../veed/resolve-token.ts';
+import {
+ conservativeRate, DEFAULT_VOICE_RATES_PATH, parseVoiceRates, rateFor, rateRange, serializeVoiceRates,
+ withObservation,
+} from '../veed/voice-rates.ts';
+import { DEFAULT_WORKSPACE_PATH, parseWorkspaceChoice, serializeWorkspaceChoice } from '../veed/workspace-store.ts';
+import {
+ allUnpriced, describeChoice, formatWorkspaceTable, listWorkspacesWithCredits, resolveWorkspace,
+ type WorkspaceCredits,
+} from '../veed/workspace.ts';
+
+// Defaults so a caller who supplies only --script gets a sensible 9:16 talking head. Character choice is how
+// portrait framing is selected (no aspectRatio parameter); character-15 verifiably renders 480x864.
+const DEFAULT_CHARACTER = 'character-15';
+// Only reached when the character is not a known preset.
+const DEFAULT_VOICE = 'kOvUpYLYS0rKGldsKcD1'; // Maeve, English (Ireland)
+
+// A URL is fetched by VEED; anything else is a path on this machine. Deciding here keeps the rule in one
+// place rather than in both passes.
+export function imageSourceFrom(ref: string | undefined): ImageSource | undefined {
+ if (!ref) return undefined;
+ return /^https?:\/\//i.test(ref) ? { kind: 'url', url: ref } : { kind: 'file', path: ref };
+}
+
+export interface Args {
+ // Absent on the spend pass: --yes takes the script from the approval on disk, so priced words are billed words.
+ script?: string;
+ key: string;
+ character: string;
+ // The user's own still — a URL or a local path — used INSTEAD of a preset character.
+ image?: string;
+ voice: string;
+ workspace?: string;
+ yes: boolean;
+ resume: boolean;
+ // The session whose charge record is to be resolved. Names ONE record, never a whole run's state.
+ abandon?: string;
+ // Spend despite an allowance reading that says it cannot cover this (a reading can be wrong).
+ // Never bypasses the approval itself.
+ ignoreBalance?: boolean;
+}
+
+// What pass 1 records under runs// and pass 2 is allowed to spend. The hash pins the exact words the
+// quote was for; approvedAt bounds how long a quote is honoured.
+export interface PendingConfirmation {
+ script: string;
+ scriptSha256: string;
+ characterId: string;
+ // Present only when the user brought their own still; part of the approval, since swapping it between the
+ // passes would generate something nobody said yes to.
+ image?: string;
+ voiceId: string;
+ workspaceId: string;
+ // True only when the user named the workspace on the approving invocation; a cached choice is confirmed
+ // before it bills, not assumed.
+ workspaceNamed: boolean;
+ estimatedCredits: number;
+ approvedAt: number;
+}
+
+// The audit trail for a run that spent something. Unlike the two files above it is never deleted: it is the
+// only durable answer to "what did this cost, and out of whose credits?".
+export interface SpendRecord {
+ jobId: string;
+ workspaceId: string;
+ workspaceName: string;
+ // Our own estimate, and the figure the user approved. VEED quotes no per-job price.
+ estimatedCredits: number;
+ // What the credits bought, kept so a paid run doubles as a calibration sample (only the finished video
+ // says how many seconds a script really took). Optional for records written before this field existed.
+ scriptChars?: number;
+ durationSeconds?: number;
+ // What the quote was built from, so the report can name the gap rather than the reader inferring it.
+ assumedCharsPerSecond?: number;
+ // The workspace balance delta, kept ONLY when it corroborates the quote closely enough to be quoted back;
+ // null when the balance could not be read, did not move, or moved by an amount no single run explains.
+ chargedCredits: number | null;
+ // The same delta, unfiltered: a WORKSPACE-level observation (a teammate or the web app moves it too),
+ // never a claim about this run — it is what a user takes to VEED support when the figures disagree.
+ observedWorkspaceDelta?: number | null;
+ // The balance read immediately before the charge, kept so a --resume in a LATER process can still measure
+ // what the job took: without it an interrupted run can never say more than its estimate.
+ balanceBefore: number | null;
+ at: number;
+}
+
+const PENDING_FILE = '.fabric-pending.json';
+const SPEND_PREFIX = '.fabric-spend-';
+const SPEND_SUFFIX = '.json';
+// An approval goes stale after an hour: past that the user has moved on, and server pricing may have moved
+// with them. Re-confirming is free; being billed for a quote nobody is still looking at is not.
+const PENDING_TTL_MS = 60 * 60_000;
+// Runs AFTER the credits are spent, so a stalled CDN connection must not hang forever on paid-for work:
+// generous enough for the whole transfer, finite so the process always ends. Same budget as veed/http.ts.
+const DOWNLOAD_TIMEOUT_MS = 15 * 60_000;
+
+// A server-side `failed` verdict costs nothing (VEED does not charge a failed job), so a run re-submits a
+// fresh job rather than surrendering to a transient backend hiccup. The waits below sit BETWEEN attempts, so
+// three attempts wait twice; the last value is sticky if the array is ever shorter than the attempts.
+const MAX_GENERATION_ATTEMPTS = 3;
+const GENERATION_RETRY_BACKOFF_MS = [10_000, 20_000];
+
+// Matched on the code, never the message beside it: "Insufficient funds" is display copy and can be reworded.
+const INSUFFICIENT_CREDITS_CODE = 'insufficient_credits';
+
+function isTerminalGenerationFailure(e: FabricJobFailedError): boolean {
+ return e.code === INSUFFICIENT_CREDITS_CODE;
+}
+
+export function scriptHash(script: string): string {
+ return createHash('sha256').update(script, 'utf8').digest('hex');
+}
+
+export function runDirFor(key: string): string {
+ return join(runsDir(), assertSafeKey(key));
+}
+
+export function pendingPathFor(key: string): string {
+ return join(runDirFor(key), PENDING_FILE);
+}
+
+export function chargePathFor(key: string, sessionId: string): string {
+ return join(runDirFor(key), chargeFileName(assertSafeSessionId(sessionId)));
+}
+
+// Per ATTEMPT, like the charge record: a singleton file let a second run of the same key destroy the first's
+// only account of what it cost. --resume knows which session's record it has to complete.
+export function spendPathFor(key: string, sessionId: string): string {
+ return join(runDirFor(key), `${SPEND_PREFIX}${assertSafeSessionId(sessionId)}${SPEND_SUFFIX}`);
+}
+
+// The run-directory guards live in args.ts, shared with every entry point that names one; re-exported
+// here because this module's callers and the docs address them through it.
+export { assertSafeKey, assertSafeSessionId };
+
+const OPTIONS = {
+ script: { type: 'string' },
+ key: { type: 'string' },
+ character: { type: 'string' },
+ image: { type: 'string' },
+ voice: { type: 'string' },
+ workspace: { type: 'string' },
+ abandon: { type: 'string' },
+ yes: { type: 'boolean' },
+ resume: { type: 'boolean' },
+ // Balance is evidence, not truth (a reading can be wrong), so this downgrades that reading from a
+ // refusal to a warning. Overrides nothing else — the approval still has to exist, match, and be fresh.
+ 'ignore-balance': { type: 'boolean' },
+} as const;
+
+const USAGE = [
+ 'usage: npx @veedstudio/openedit-cli generate --script "spoken words" --workspace [--key ] [--character ] [--voice ]',
+ ' npx @veedstudio/openedit-cli generate --key --yes (spends the cost the confirm pass above quoted)',
+ ' npx @veedstudio/openedit-cli generate --key --resume (collects a job already created and paid for)',
+ ' npx @veedstudio/openedit-cli generate --key --abandon (clears one abandoned charge record)',
+].join('\n');
+
+const SCRIPT_WITH_YES = [
+ '--script cannot be combined with --yes.',
+ '--yes spends the confirmation you already approved, which is recorded under runs//.fabric-pending.json;',
+ 're-typing the script is exactly how the billed words drift away from the priced ones. Confirm first:',
+ ' npx @veedstudio/openedit-cli generate --script "spoken words" --key ',
+ 'then spend what it quoted:',
+ ' npx @veedstudio/openedit-cli generate --key --yes',
+].join('\n');
+
+// The four modes are mutually exclusive by construction; checked in parseArgs AND in run(), which is a
+// public entry point of its own.
+function assertFlagCombination(args: { script?: string; yes: boolean; resume: boolean; abandon?: string }): void {
+ if (args.yes && args.script !== undefined) throw new Error(SCRIPT_WITH_YES);
+ if (args.resume && (args.yes || args.script !== undefined)) {
+ throw new Error(
+ '--resume takes neither --script nor --yes: it downloads a job that was already created and paid for, ' +
+ 'and spends nothing.',
+ );
+ }
+ if (args.abandon !== undefined && (args.yes || args.resume || args.script !== undefined)) {
+ throw new Error(
+ '--abandon takes no --script, --yes or --resume: it only resolves one abandoned charge record, and ' +
+ 'spends nothing.',
+ );
+ }
+ if (!args.yes && !args.resume && args.abandon === undefined && args.script === undefined) throw new Error(USAGE);
+}
+
+// An unexpanded shell variable (`--script "$SCRIPT"` with `$SCRIPT` unset) parses as `--script ""`, which
+// would be quoted for a video with nothing to say and then billed by --yes. Validated in parseArgs like
+// --key, not in assertFlagCombination, which only compares flags against each other.
+export function assertNonEmptyScript(script: string): string {
+ if (script.trim() === '') {
+ throw new Error(
+ `--script must not be empty or whitespace-only (got ${JSON.stringify(script)}). This is usually a ` +
+ 'shell variable that failed to expand, e.g. --script "$SCRIPT" with $SCRIPT unset.',
+ );
+ }
+ return script;
+}
+
+export function parseArgs(argv: string[]): Args {
+ const result: Partial = {
+ key: 'generated',
+ character: DEFAULT_CHARACTER,
+ yes: false,
+ resume: false,
+ };
+
+ const { values } = parseFlags({ args: argv, options: OPTIONS });
+
+ if (values.script !== undefined) result.script = assertNonEmptyScript(values.script);
+ if (values.key !== undefined) result.key = values.key;
+ if (values.character !== undefined) result.character = values.character;
+ if (values.image !== undefined) result.image = values.image;
+ // Otherwise the face brings its own, so a male preset never reads in a female voice.
+ result.voice = values.voice ?? curatedVoiceFor(result.character as string) ?? DEFAULT_VOICE;
+ if (values.workspace !== undefined) result.workspace = values.workspace;
+ if (values.abandon !== undefined) result.abandon = assertSafeSessionId(values.abandon);
+ result.yes = values.yes ?? false;
+ result.resume = values.resume ?? false;
+ result.ignoreBalance = values['ignore-balance'] ?? false;
+
+ assertFlagCombination(result as Args);
+ assertSafeKey(result.key as string);
+
+ return result as Args;
+}
+
+export interface GenerateDeps {
+ // A currently-valid access token, or null when there is no usable login. Called again per request, so a
+ // long poll survives the token expiring mid-run.
+ resolveAccessToken: () => Promise;
+ connect: (getToken: () => Promise) => Promise;
+ download: (url: string) => Promise;
+ // Only for a user's LOCAL image; injected so the spend path stays testable without touching a disk.
+ readFileBytes?: (path: string) => Promise;
+ writeOutput: (path: string, bytes: Uint8Array) => Promise;
+ // The small JSON state files under runs// (approval, charge records, spend trail); injected so the
+ // spend gate stays testable without touching the filesystem.
+ readState: (path: string) => Promise;
+ writeState: (path: string, text: string) => Promise;
+ removeState: (path: string) => Promise;
+ // File names in a run directory (empty when absent): charge records are per-attempt, so finding the OTHER
+ // attempts means listing the directory rather than reading one known path.
+ listState: (dir: string) => Promise;
+ // Who this process is, stamped into the record it writes so another run can ask whether it is still there.
+ // One process charges at most once, so its session id is also its attempt id.
+ sessionId: string;
+ pid: number;
+ host: string;
+ // Only meaningful for a pid on THIS host; injected so both branches of the liveness rule are drivable.
+ isAlive: (pid: number) => boolean;
+ sleep: (ms: number) => Promise;
+ now?: () => number;
+ log?: (message: string) => void;
+}
+
+export type RunResult =
+ | { status: 'no-token' }
+ // Nobody has said which workspace to bill, so the run stops having spent nothing and shows the choices.
+ | { status: 'workspace-required'; workspaces: WorkspaceCredits[] }
+ | { status: 'confirmed'; credits: number }
+ | { status: 'generated'; path: string; bytes: number }
+ | { status: 'abandoned'; sessionId: string };
+
+function refusePending(path: string, detail: string): never {
+ throw new Error(
+ `refusing to spend: ${path} ${detail}. Nothing spent.\n` +
+ 'That file is left where it is so it can be inspected; re-run the confirm pass and approve the cost it ' +
+ 'prints.',
+ );
+}
+
+// The approval crossed a process boundary as JSON, so every field is an untrusted claim. Unchecked, a
+// missing timestamp reads back as `nowMs - undefined` = NaN and passes BOTH the `> TTL` and `< 0` checks
+// silently; refusal names the offending field, because "malformed" is not something a user can act on.
+function assertPendingShape(value: unknown, path: string): PendingConfirmation {
+ if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+ refusePending(path, `holds ${describeValue(value)}, which is not a JSON object`);
+ }
+ const record = value as Record;
+ for (const field of ['script', 'scriptSha256', 'characterId', 'voiceId', 'workspaceId'] as const) {
+ const held = record[field];
+ if (typeof held !== 'string' || held === '') {
+ refusePending(path, `has ${field} = ${describeValue(held)}, not a non-empty string`);
+ }
+ }
+ if (typeof record.workspaceNamed !== 'boolean') {
+ refusePending(path, `has workspaceNamed = ${describeValue(record.workspaceNamed)}, not a boolean`);
+ }
+ // Finite, because 1e999 is legal JSON that reads back as Infinity: an infinite approved figure caps
+ // nothing, and an infinite timestamp is never stale.
+ for (const field of ['estimatedCredits', 'approvedAt'] as const) {
+ const held = record[field];
+ if (typeof held !== 'number' || !Number.isFinite(held)) {
+ refusePending(path, `has ${field} = ${describeValue(held)}, not a finite number`);
+ }
+ }
+ if ((record.estimatedCredits as number) < 0) {
+ refusePending(path, `has estimatedCredits = ${record.estimatedCredits}, which is not a cost anyone approved`);
+ }
+ return value as PendingConfirmation;
+}
+
+// Reads back what pass 1 approved. Everything here is local: a bad approval is refused before a single
+// byte reaches VEED, let alone a charge.
+async function loadPending(
+ deps: GenerateDeps, path: string, key: string, nowMs: number,
+): Promise {
+ const raw = await deps.readState(path);
+ if (raw === null) {
+ throw new Error(
+ `no approved confirmation for --key ${key}. Run the confirm pass first (it spends nothing):\n` +
+ ` npx @veedstudio/openedit-cli generate --script "spoken words" --key ${key}\n` +
+ 'then re-run this command once you have approved the cost it prints.',
+ );
+ }
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(raw);
+ } catch {
+ throw new Error(`refusing to spend: ${path} is not readable JSON; re-run the confirm pass`);
+ }
+ const record = assertPendingShape(parsed, path);
+ // The hash pins the exact words the quote was for: a record edited after approval buys something the
+ // user was never shown a price for.
+ if (scriptHash(record.script) !== record.scriptSha256) {
+ throw new Error(
+ `refusing to spend: the script in ${path} does not match the hash recorded when the cost was approved.\n` +
+ 'Re-run the confirm pass and approve the cost it prints.',
+ );
+ }
+ const ageMs = nowMs - record.approvedAt;
+ if (ageMs > PENDING_TTL_MS || ageMs < 0) {
+ const age = ageMs < 0 ? 'timestamped in the future' : `${Math.round(ageMs / 60_000)} minutes old`;
+ throw new Error(
+ `refusing to spend: that approval is ${age} (limit ${PENDING_TTL_MS / 60_000} minutes).\n` +
+ 'Re-run the confirm pass to see the current cost and approve it again.',
+ );
+ }
+ return record;
+}
+
+// --- charge records: what the OTHER attempts at this key say about whether it may be charged again ---
+
+// One record as found on disk. A null `record` is a file that could not be parsed, which is refused rather
+// than skipped: guessing its phase would guess whether money moved.
+interface ScannedCharge {
+ sessionId: string;
+ record: ChargeRecord | null;
+}
+
+// Every attempt but our own. Our own record is excluded because a run must never stand down for itself.
+async function scanChargeRecords(deps: GenerateDeps, key: string): Promise {
+ const dir = runDirFor(key);
+ const found: ScannedCharge[] = [];
+ for (const name of await deps.listState(dir)) {
+ const sessionId = sessionIdOfChargeFile(name);
+ if (sessionId === null || sessionId === deps.sessionId) continue;
+ const raw = await deps.readState(join(dir, name));
+ // Gone between the listing and the read: the owner resolved it, which is the one race that is safe.
+ if (raw === null) continue;
+ found.push({ sessionId, record: parseChargeRecord(raw) });
+ }
+ return found;
+}
+
+function verdictsOf(scanned: ScannedCharge[], deps: GenerateDeps, nowMs: number): ChargeVerdict[] {
+ return classifyChargeRecords(
+ scanned.flatMap((s) => (s.record ? [s.record] : [])),
+ { host: deps.host, now: nowMs, isAlive: deps.isAlive },
+ );
+}
+
+// Paid first, then a live charge, then an orphan: all three refuse, and this only decides which one the user
+// is told about — the most actionable one.
+const BLOCKER_ORDER = ['paid', 'charging', 'orphaned'] as const;
+
+function blockingVerdict(verdicts: ChargeVerdict[]): ChargeVerdict | undefined {
+ for (const state of BLOCKER_ORDER) {
+ const hit = verdicts.find((v) => v.state === state);
+ if (hit) return hit;
+ }
+ return undefined;
+}
+
+function unreadableRecordMessage(sessionId: string, key: string): string {
+ return (
+ `refusing to spend: the charge record for session ${sessionId} under --key ${key} cannot be read, so it ` +
+ 'cannot be ruled out that this run was already charged. Nothing spent.\n' +
+ 'Check the workspace for a recent charge, then clear that one record:\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --abandon ${sessionId}`
+ );
+}
+
+function blockerMessage(v: ChargeVerdict, key: string): string {
+ const started = new Date(v.startedAt).toISOString();
+ if (v.state === 'paid') {
+ return (
+ `refusing to spend: session ${v.sessionId} has already paid for Fabric job ${v.jobId} under --key ${key}. ` +
+ 'Nothing spent.\n' +
+ 'Collect that job instead — it charges nothing:\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --resume`
+ );
+ }
+ if (v.state === 'charging') {
+ return (
+ `refusing to spend: session ${v.sessionId} (pid ${v.pid} on ${v.host}) is charging --key ${key} right ` +
+ `now, since ${started}. Nothing spent.\n` +
+ 'Let it finish; if it is interrupted, its video is collected without paying again:\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --resume`
+ );
+ }
+ return (
+ `refusing to spend: session ${v.sessionId} (pid ${v.pid} on ${v.host}) started charging --key ${key} at ` +
+ `${started} and never came back, so VEED MAY already have charged for it — and no job id was ever ` +
+ 'recorded, so nothing here can collect it. Nothing spent.\n' +
+ 'Check that workspace for a video and a charge from around then before paying again. Once you have, ' +
+ 'clear that one record (it releases nothing else):\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --abandon ${v.sessionId}`
+ );
+}
+
+// The pre-flight scan: a charge already in flight, already paid or possibly-landed all stop the run before
+// anything reaches the server.
+function assertNoBlockingCharge(scanned: ScannedCharge[], deps: GenerateDeps, key: string, nowMs: number): void {
+ const unreadable = scanned.find((s) => s.record === null);
+ if (unreadable) throw new Error(unreadableRecordMessage(unreadable.sessionId, key));
+ const blocker = blockingVerdict(verdictsOf(scanned, deps, nowMs));
+ if (blocker) throw new Error(blockerMessage(blocker, key));
+}
+
+// Ties are broken on the session id so that two records stamped in the same millisecond still yield to the
+// SAME one in both processes; without that, a symmetric race can stand both runs down or neither.
+function startedBefore(other: ChargeVerdict, ours: ChargeRecord): boolean {
+ if (other.startedAt !== ours.startedAt) return other.startedAt < ours.startedAt;
+ return other.sessionId < ours.sessionId;
+}
+
+// Write our record, then look again: no mutex, so the record is on disk before the charge, a rival that got
+// there first is visible, and the earlier startedAt decides. A record written only after a successful
+// create would make this impossible.
+async function acquireChargeSlot(deps: GenerateDeps, key: string, nowMs: number): Promise {
+ const record: ChargeRecord = {
+ sessionId: deps.sessionId, pid: deps.pid, host: deps.host, startedAt: nowMs, phase: 'charging',
+ };
+ const path = chargePathFor(key, deps.sessionId);
+ await deps.writeState(path, `${JSON.stringify(record, null, 2)}\n`);
+
+ const rescanned = await scanChargeRecords(deps, key);
+ const unreadable = rescanned.find((s) => s.record === null);
+ if (unreadable) {
+ await deps.removeState(path);
+ throw new Error(unreadableRecordMessage(unreadable.sessionId, key));
+ }
+ const verdicts = verdictsOf(rescanned, deps, nowMs);
+ // A rival that started LATER is not a blocker: it can see us, and it is the one that stands down.
+ const blocker = blockingVerdict(verdicts.filter((v) => v.state !== 'charging' || startedBefore(v, record)));
+ if (blocker) {
+ await deps.removeState(path);
+ if (blocker.state !== 'charging') throw new Error(blockerMessage(blocker, key));
+ throw new Error(
+ `refusing to spend: session ${blocker.sessionId} started charging --key ${key} first ` +
+ `(${new Date(blocker.startedAt).toISOString()}), so this run stood down rather than buy the same ` +
+ 'script twice. Nothing spent.\n' +
+ 'Collect that run\'s video when it finishes — it charges nothing:\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --resume`,
+ );
+ }
+ return record;
+}
+
+// The attempt is over: the record stays as an account of what happened, and constrains nothing further.
+async function resolveChargeRecord(
+ deps: GenerateDeps, key: string, sessionId: string, at: number,
+): Promise {
+ const path = chargePathFor(key, sessionId);
+ const raw = await deps.readState(path);
+ const record = raw === null ? null : parseChargeRecord(raw);
+ // Nothing legible to resolve, so leave nothing legible behind either.
+ if (!record) {
+ await deps.removeState(path);
+ return;
+ }
+ await deps.writeState(path, `${JSON.stringify({ ...record, resolvedAt: at }, null, 2)}\n`);
+}
+
+// The counterpart for --resume: the job a charge record says this key has ALREADY been charged for.
+async function loadResumableJob(
+ deps: GenerateDeps, key: string, nowMs: number,
+): Promise<{ jobId: string; sessionId: string }> {
+ const scanned = await scanChargeRecords(deps, key);
+ const verdicts = verdictsOf(scanned, deps, nowMs);
+ // The newest, because a key charged more than once (each time on its own fresh approval) is resumed to its
+ // most recent job.
+ const paid = verdicts.filter((v) => v.state === 'paid').sort((a, b) => b.startedAt - a.startedAt)[0];
+ if (paid?.jobId) return { jobId: paid.jobId, sessionId: paid.sessionId };
+
+ const stranded = verdicts.find((v) => v.state === 'orphaned' || v.state === 'charging');
+ if (stranded) {
+ throw new Error(
+ `no in-flight Fabric job recorded for --key ${key}: session ${stranded.sessionId} started a charge at ` +
+ `${new Date(stranded.startedAt).toISOString()} but never recorded a job id, so there is nothing to poll.\n` +
+ 'Check the workspace before paying again, then clear that record:\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --abandon ${stranded.sessionId}`,
+ );
+ }
+ throw new Error(
+ `no in-flight Fabric job recorded for --key ${key} (looked for a charge record in ${runDirFor(key)}).\n` +
+ 'There is nothing to resume: either the job already downloaded, or it was never created.',
+ );
+}
+
+// Purely local, and deliberately narrow: it resolves the ONE record it is given and leaves every other
+// attempt, and every other run, exactly as it was.
+async function abandonChargeRecord(
+ deps: GenerateDeps, key: string, sessionId: string, nowMs: number, log: (m: string) => void,
+): Promise {
+ const path = chargePathFor(key, sessionId);
+ if (await deps.readState(path) === null) {
+ throw new Error(
+ `no charge record for session ${sessionId} under --key ${key} (looked in ${path}). Nothing to abandon.`,
+ );
+ }
+ await resolveChargeRecord(deps, key, sessionId, nowMs);
+ log(
+ `[fabric] charge record ${sessionId} abandoned; --key ${key} is free to take a fresh approval. If that ` +
+ 'attempt did charge, those credits are gone — this only unblocks the key.',
+ );
+ return { status: 'abandoned', sessionId };
+}
+
+// Where the workspace to bill came from. `flag` is the only source that updates the stored choice: it is the
+// only one where the user just named a workspace.
+type WorkspaceSource = 'approval' | 'flag' | 'stored';
+
+// Purely local, and deliberately without a fallback: an unanswered question stops the run (see run()) rather
+// than being answered on the user's behalf.
+async function resolveWorkspaceChoice(
+ args: Args, deps: GenerateDeps, pending: PendingConfirmation | undefined,
+): Promise<{ id: string; source: WorkspaceSource } | null> {
+ if (pending) {
+ // The approval binds script, figure AND workspace together; a flag naming a different one contradicts
+ // it, and honouring either side silently bills a choice the user did not make twice.
+ if (args.workspace && args.workspace !== pending.workspaceId) {
+ throw new Error(
+ `refusing to spend: the approval on disk bills ${pending.workspaceId}, but --workspace names ` +
+ `${args.workspace}. Nothing spent.\n` +
+ `Drop the flag to spend from ${pending.workspaceId}, or re-run the confirm pass against ` +
+ `${args.workspace} and approve what it quotes.`,
+ );
+ }
+ return { id: pending.workspaceId, source: 'approval' };
+ }
+ if (args.workspace) return { id: args.workspace, source: 'flag' };
+ const stored = parseWorkspaceChoice(await deps.readState(DEFAULT_WORKSPACE_PATH));
+ if (stored) return { id: stored.workspaceId, source: 'stored' };
+ return null;
+}
+
+// ASYMMETRIC because the directions are not equally believable: VEED charges at or under quote, so a delta
+// below it is ordinary rounding (generous floor), while a delta above it is likely a concurrent run, not a
+// bigger charge (tight ceiling). The 20/5 split comes from a real run — quoted 24, charged 22 (8.3% under) —
+// which the old symmetric 5% band discarded. Do not re-tighten the lower bound without re-reading that data.
+const LOWER_BAND_RATIO = 0.80;
+const UPPER_BAND_RATIO = 1.05;
+// 20% of a small quote can be a fraction of a credit (e.g. 2.4 on a quote of 3), which integer billing can
+// never land on exactly; the absolute floor keeps small quotes measurable at all.
+const BAND_SLACK_CREDITS = 1;
+
+// What a workspace delta is worth as corroboration: measured (close enough to quote back), unmeasured
+// (unreadable, non-positive, or below the floor), or ambiguous (above the ceiling — overcharge or a
+// concurrent run, indistinguishable). `delta` rides on all three because it is an observation in its own
+// right; discarding it on the ambiguous branch withheld the one measured number the user needs to go check.
+type ChargeAssessment =
+ | { kind: 'measured'; delta: number }
+ | { kind: 'unmeasured'; delta: number | null }
+ | { kind: 'ambiguous'; delta: number };
+
+function assessCharge(before: number | null, after: number | null, quoted: number): ChargeAssessment {
+ if (before === null || after === null) return { kind: 'unmeasured', delta: null };
+ const delta = before - after;
+ // A balance that did not move (or moved the wrong way) corroborates nothing, regardless of the band.
+ if (delta <= 0) return { kind: 'unmeasured', delta };
+ const lower = Math.min(quoted - BAND_SLACK_CREDITS, quoted * LOWER_BAND_RATIO);
+ const upper = Math.max(quoted + BAND_SLACK_CREDITS, quoted * UPPER_BAND_RATIO);
+ if (delta < lower) return { kind: 'unmeasured', delta };
+ if (delta > upper) return { kind: 'ambiguous', delta };
+ return { kind: 'measured', delta };
+}
+
+// For reporting, never gating: an unreadable allowance degrades the report to an estimate rather than
+// failing a paid-for run, and is never treated as an empty one (which would refuse an affordable run).
+async function readAllowances(client: VeedHttp, workspaceId: string): Promise {
+ try {
+ return await getAllowances(client, workspaceId);
+ } catch {
+ return null;
+ }
+}
+
+async function readBalance(client: VeedHttp, workspaceId: string): Promise {
+ return (await readAllowances(client, workspaceId))?.aiPlaygroundCredits ?? null;
+}
+
+// Name + balance for the workspace about to be billed, so the user reads it before approving anything. The
+// name is cosmetic, so a listing failure must not stop a run the user has already directed.
+async function describeFraming(client: VeedHttp, characterId: string): Promise {
+ let listed;
+ try {
+ listed = (await listCharacters(client)).find((c) => c.id === characterId);
+ } catch {
+ listed = undefined;
+ }
+ if (!listed) return `unknown — ${characterId} is not in the live character listing, so its shape cannot be stated`;
+ return framingOf(listed) === 'portrait' ? 'portrait 9:16' : 'landscape 16:9';
+}
+
+export async function run(args: Args, deps: GenerateDeps): Promise {
+ const log = deps.log ?? ((m: string) => console.log(m));
+ // Re-checked here as well as in parseArgs: run() is a public entry point and the key ends up in a path.
+ const key = assertSafeKey(args.key);
+ assertFlagCombination(args);
+ // Same reasoning as the key: a caller of run() that never went through parseArgs (every test here included)
+ // must not be able to reach confirm_fabric_video with nothing to say.
+ if (args.script !== undefined) assertNonEmptyScript(args.script);
+ const now = deps.now ?? Date.now;
+ const pendingPath = pendingPathFor(key);
+
+ // Spends nothing and asks the server nothing, so it answers before the login is even resolved.
+ if (args.abandon !== undefined) {
+ return await abandonChargeRecord(deps, key, assertSafeSessionId(args.abandon), now(), log);
+ }
+
+ // Pass 2 and --resume read their whole request off disk BEFORE anything touches the network.
+ if (args.yes) assertNoBlockingCharge(await scanChargeRecords(deps, key), deps, key, now());
+ const pending = args.yes ? await loadPending(deps, pendingPath, key, now()) : undefined;
+ const resuming = args.resume ? await loadResumableJob(deps, key, now()) : undefined;
+
+ const token = await deps.resolveAccessToken();
+ if (!token) return { status: 'no-token' };
+
+ const client = await deps.connect(async () => {
+ const fresh = await deps.resolveAccessToken();
+ if (!fresh) throw new Error('VEED login is no longer valid; run: npx @veedstudio/openedit-cli login');
+ return fresh;
+ });
+
+ // --resume never confirms and never creates: the video is already bought, this only collects it.
+ if (resuming) {
+ log(`[fabric] resuming job ${resuming.jobId} — it is already paid for, nothing further will be charged`);
+ try {
+ return await collect(client, resuming.jobId, key, resuming.sessionId, deps, log);
+ } finally {
+ // The charge report is unconditional, and the run that was interrupted never got to make it. The
+ // record to close is that SESSION's, not the key's: another attempt's trail is not this run's to touch.
+ await completeSpendRecord(client, key, resuming.sessionId, deps, log);
+ }
+ }
+
+ // Which workspace pays is the user's decision. With no flag and no remembered choice the run stops here,
+ // before the first billable thought, and shows them what there is to choose from.
+ const choice = await resolveWorkspaceChoice(args, deps, pending);
+ if (!choice) {
+ const workspaces = await listWorkspacesWithCredits(client);
+ log(
+ [
+ '[fabric] Fabric bills a workspace and none has been chosen, so nothing has been done and nothing spent.',
+ '',
+ formatWorkspaceTable(workspaces),
+ '',
+ 'Re-run naming the workspace to spend from, for example:',
+ ` npx @veedstudio/openedit-cli generate --script "spoken words" --key ${key} --workspace ${workspaces[0].id}`,
+ 'That choice is remembered, so this is asked once and not every session.',
+ ].join('\n'),
+ );
+ return { status: 'workspace-required', workspaces };
+ }
+
+ const workspaceId = choice.id;
+ // An account with no workspaces has nothing to bill; checked here where the workspace is chosen, so it
+ // fails once with a useful message rather than later, one call at a time.
+ const resolution = await resolveWorkspace({ http: client, explicit: workspaceId });
+ if (resolution.kind === 'must-choose') throw new Error('internal error: a workspace was already chosen');
+ const workspace = resolution.workspace;
+ log(`[fabric] ${describeChoice(workspace, resolution.source)}`);
+ // The spend pass is the last moment at which a workspace nobody ever named can still be questioned, and
+ // the CLI cannot hold a conversation — so naming it on this invocation IS the acknowledgement.
+ if (pending && !pending.workspaceNamed && args.workspace !== workspaceId) {
+ throw new Error(
+ `refusing to spend: ${workspace.name} (${workspaceId}) is remembered from an earlier session, and ` +
+ 'nobody has confirmed it for this charge. Nothing spent.\n' +
+ `It has ${workspace.credits === null ? 'an unreadable balance' : `${workspace.credits} credits`}. ` +
+ 'Confirm it by naming it:\n' +
+ ` npx @veedstudio/openedit-cli generate --key ${key} --yes --workspace ${workspaceId}\n` +
+ 'To bill a different workspace, re-run the confirm pass with that --workspace.',
+ );
+ }
+
+ // Only an explicit flag records a decision; a run that inherited its workspace has not made one.
+ const workspaceNamed = choice.source === 'flag';
+ if (choice.source === 'stored') {
+ log(
+ `[fabric] ${workspaceId} is remembered from an earlier session, not chosen for this run — the spend ` +
+ 'pass below names it again, which is where that choice gets confirmed.',
+ );
+ }
+ if (workspaceNamed) {
+ await deps.writeState(
+ DEFAULT_WORKSPACE_PATH,
+ serializeWorkspaceChoice({ workspaceId, workspaceName: workspace.name, chosenAt: now() }),
+ );
+ }
+
+ // Pass 1 builds the request from the flags; pass 2 rebuilds it from the approval, so the script is typed
+ // exactly once and cannot drift between the price the user saw and the one they are charged.
+ const script = pending?.script ?? (args.script as string);
+ const voiceId = pending?.voiceId ?? args.voice;
+
+ // Resolved BEFORE the confirmation, because it is what prices it: confirmVideo quotes at this rate, so
+ // the figure in the approval block and the figure the estimate line explains are the same number.
+ const rates = parseVoiceRates(await deps.readState(DEFAULT_VOICE_RATES_PATH));
+ const known = rateFor(voiceId, rates);
+ const rate = known?.charsPerSecond ?? conservativeRate(rates);
+ const range = estimateRange(script, rateRange(rates));
+
+ const req = {
+ script,
+ voiceId,
+ characterId: pending?.characterId ?? args.character,
+ image: imageSourceFrom(pending?.image ?? args.image),
+ workspaceId,
+ // Already resolved above; passing it spares confirmVideo a duplicate workspace listing.
+ workspaceName: workspace.name,
+ charsPerSecond: rate,
+ };
+ log(
+ known
+ ? `[fabric] local estimate ~${estimateTotalCredits(script, rate)} credits (${script.length} chars at ${rate} chars/second, measured over ${known.samples} run${known.samples === 1 ? '' : 's'} of this voice)`
+ : `[fabric] local estimate ~${estimateTotalCredits(script, rate)} credits (${script.length} chars). This voice has never been measured, and speaking rate decides the length: expect ${range.low}-${range.high} credits.`,
+ );
+ // The confirmation ALWAYS runs, and always before create_fabric_video below — it is what the user is
+ // shown to approve. Nothing between here and the `if (!args.yes)` gate may spend.
+ const confirmation = await confirmVideo(client, req);
+ // One approval covers the script, the presenter, the voice, the framing AND the cost, so all five are in
+ // the block it is given against: the script and the framing lost their own gates, not their visibility.
+ log(
+ [
+ '[fabric] confirmation',
+ ` character ${confirmation.characterName} (${confirmation.characterId})`,
+ ` voice ${confirmation.voiceName}`,
+ ` framing ${await describeFraming(client, req.characterId)}`,
+ ` workspace ${confirmation.workspaceName}`,
+ ` cost ~${confirmation.estimatedCredits} AI Playground credits`,
+ // The speech synthesis and Fabric One Lipsync are two debits on the one credit allowance; the figure
+ // above is their sum, so the user sees the whole spend rather than half of it.
+ " (covers both the speech synthesis and Fabric One Lipsync — one allowance, one figure)",
+ // An unmeasured voice gets the spread it could land in, not a single figure dressed as a
+ // measurement. The point number above already leans slow; this says how wide the uncertainty is.
+ ...(known ? [] : [` (estimated: this voice has never been measured, expect ${range.low}-${range.high})`]),
+ ` script ${script.length} chars, exactly as they will be spoken:`,
+ ...script.split('\n').map((line) => ` ${line}`),
+ ].join('\n'),
+ );
+
+ // A workspace that cannot cover the quote is a stop, not a prompt to look elsewhere: a richer workspace
+ // bills money nobody offered. Checked on BOTH passes, each with its own freshly-read balance (it can move
+ // between them); refusing on the CONFIRM pass means no unaffordable approval is ever written. An UNREADABLE
+ // balance is not evidence of insufficiency, so it proceeds and lets the server refuse.
+ if (workspace.credits !== null && workspace.credits < confirmation.estimatedCredits && args.ignoreBalance) {
+ log(
+ `[fabric] WARNING: ${workspace.name} reports ${workspace.credits} credits against a ~${confirmation.estimatedCredits} ` +
+ 'credit quote, and --ignore-balance says to spend anyway. If the report is right this fails at VEED, ' +
+ 'having charged nothing; if it is wrong, this charges normally.',
+ );
+ } else if (workspace.credits !== null && workspace.credits < confirmation.estimatedCredits) {
+ throw new Error(
+ `refusing to spend: ${workspace.name} (${workspaceId}) has ${workspace.credits} credits, but this ` +
+ `costs ${confirmation.estimatedCredits}. Nothing spent.\n` +
+ 'Top that workspace up, shorten the script, or re-confirm naming a different --workspace — this will ' +
+ 'not switch workspaces on your behalf.',
+ );
+ }
+
+ if (!pending) {
+ const record: PendingConfirmation = {
+ script,
+ scriptSha256: scriptHash(script),
+ characterId: req.characterId,
+ ...(args.image ? { image: args.image } : {}),
+ voiceId: req.voiceId,
+ workspaceId,
+ workspaceNamed,
+ estimatedCredits: confirmation.estimatedCredits,
+ approvedAt: now(),
+ };
+ await deps.writeState(pendingPath, `${JSON.stringify(record, null, 2)}\n`);
+ // An unnamed workspace carries its own flag into the command, so approving the cost and confirming the
+ // workspace are the same keystroke rather than two questions.
+ const spendCommand = ` npx @veedstudio/openedit-cli generate --key ${key} --yes` +
+ (workspaceNamed ? '' : ` --workspace ${workspaceId}`);
+ log(
+ `\nNothing spent. To approve ${confirmation.estimatedCredits} credits and generate, run exactly:\n\n` +
+ `${spendCommand}\n\n` +
+ 'That re-uses the confirmation above — do not re-type --script.',
+ );
+ return { status: 'confirmed', credits: confirmation.estimatedCredits };
+ }
+
+ // The cap: the server may not charge more than the figure the user actually saw and approved. A cheaper
+ // quote is fine — being billed LESS than approved needs no second look.
+ if (confirmation.estimatedCredits > pending.estimatedCredits) {
+ throw new Error(
+ `refusing to spend: you approved ${pending.estimatedCredits} credits, but the server now quotes ` +
+ `${confirmation.estimatedCredits}. Nothing spent.\n` +
+ 'Re-run the confirm pass to see the new cost and approve it explicitly.',
+ );
+ }
+
+ // --- everything past this line spends real credits ---
+ let lastFailure: FabricJobFailedError | undefined;
+ for (let attempt = 0; attempt < MAX_GENERATION_ATTEMPTS; attempt++) {
+ if (attempt > 0) {
+ const waitMs = GENERATION_RETRY_BACKOFF_MS[Math.min(attempt - 1, GENERATION_RETRY_BACKOFF_MS.length - 1)];
+ log(`[fabric] retry ${attempt + 1}/${MAX_GENERATION_ATTEMPTS} in ${Math.round(waitMs / 1000)}s (reason=${lastFailure?.reason ?? 'unknown'})`);
+ await deps.sleep(waitMs);
+ }
+
+ // VEED exposes no per-job charge, so the balance either side of the create call is all there is — and it
+ // is only ever a WORKSPACE observation; the quote above is the figure this run reports. Read per attempt
+ // so each attempt's record stands on its own.
+ const balanceBefore = await readBalance(client, workspaceId);
+ // Written BEFORE the charging call, deliberately: a create that times out, 502s or returns a truncated
+ // body has still moved the money, and a record written afterwards would not exist to say so (buying twice).
+ // A retry runs under a per-attempt session id so its charge/spend files sit BESIDE the failed attempt's,
+ // never on top of them — and so scanChargeRecords (which excludes the acquiring session's own record)
+ // still excludes THIS attempt. Only acquireChargeSlot reads deps.sessionId; the rest take it explicitly.
+ const attemptDeps: GenerateDeps = attempt === 0
+ ? deps
+ : { ...deps, sessionId: `${deps.sessionId}-r${attempt}` };
+ const charge = await acquireChargeSlot(attemptDeps, key, now());
+ const chargePath = chargePathFor(key, charge.sessionId);
+ const job = await createVideo(client, req, { readFileBytes: deps.readFileBytes });
+ // Now the charge is known to have landed AND has an id: the record can name the job --resume needs.
+ await deps.writeState(chargePath, `${JSON.stringify({ ...charge, phase: 'charged', jobId: job.jobId }, null, 2)}\n`);
+ // Closing balance taken HERE, not after the download: the balance is workspace-global, so the minutes of
+ // polling and downloading would let other spends land inside the measurement. Whether VEED debits at create
+ // or completion is unknown, so this reading is preferred only when it moved, with the post-download one as fallback.
+ const balanceAtCreate = await readBalance(client, workspaceId);
+ // The approval is consumed at the FIRST create and never re-read: the retries re-submit the same in-memory
+ // request, so a "yes" left on disk could only ever buy a SECOND, unrelated video. After the attempts are
+ // exhausted the run throws and a fresh confirm pass is required.
+ if (attempt === 0) await deps.removeState(pendingPath);
+ log(`[fabric] job ${job.jobId} started${job.durationSeconds ? ` (${job.durationSeconds.toFixed(1)}s of video)` : ''}`);
+ log(`[fabric] recorded at ${chargePath} — if this run is interrupted, collect it without paying again:\n npx @veedstudio/openedit-cli generate --key ${key} --resume`);
+
+ const spend: SpendRecord = {
+ jobId: job.jobId,
+ workspaceId,
+ workspaceName: workspace.name,
+ estimatedCredits: confirmation.estimatedCredits,
+ scriptChars: confirmation.script.length,
+ durationSeconds: job.durationSeconds,
+ assumedCharsPerSecond: rate,
+ chargedCredits: null,
+ observedWorkspaceDelta: null,
+ balanceBefore,
+ at: now(),
+ };
+ const spendPath = spendPathFor(key, charge.sessionId);
+ // Written at the charge and again below with the observed figure: a run that dies mid-download still spent
+ // the credits, and an audit trail that only appears on success hides the cases worth auditing.
+ await deps.writeState(spendPath, `${JSON.stringify(spend, null, 2)}\n`);
+
+ // Closes this attempt's charge audit against the balance. Only reached for a job that was actually
+ // charged — a success, or a timeout/transport failure whose credits are gone and which --resume collects.
+ const finalizeCharge = async (): Promise => {
+ let balanceAfter = balanceAtCreate;
+ let assessment = assessCharge(balanceBefore, balanceAtCreate, confirmation.estimatedCredits);
+ // The tight reading is credible only when it already CORROBORATES the quote; anything less — nothing
+ // moved, or only PART of the charge had landed — needs the completion read, the last chance to see a
+ // debit that settles late. The speech synthesis debits a couple of credits at create while the clip's
+ // credits settle at completion, so the early delta is routinely positive but far below the quote;
+ // stopping there would report that partial figure as "nothing credible" while the full charge settled
+ // unseen. 'ambiguous' is left alone: the early delta is already above the quote, and waiting only lets
+ // more concurrent movement pile onto a reading that is already untrustworthy.
+ if (assessment.kind === 'unmeasured') {
+ balanceAfter = await readBalance(client, workspaceId);
+ assessment = assessCharge(balanceBefore, balanceAfter, confirmation.estimatedCredits);
+ }
+ spend.chargedCredits = assessment.kind === 'measured' ? assessment.delta : null;
+ spend.observedWorkspaceDelta = assessment.delta;
+ reportCharge(log, spend, assessment, balanceAfter);
+ if (spend.durationSeconds && spend.scriptChars) {
+ // The next quote for this voice is built from what this one actually did.
+ await deps.writeState(
+ DEFAULT_VOICE_RATES_PATH,
+ serializeVoiceRates(withObservation(rates, req.voiceId, spend.scriptChars / spend.durationSeconds)),
+ );
+ }
+ await deps.writeState(spendPath, `${JSON.stringify(spend, null, 2)}\n`);
+ log(`[fabric] spend recorded at ${spendPath}`);
+ };
+
+ try {
+ const result = await collect(client, job.jobId, key, charge.sessionId, deps, log);
+ await finalizeCharge();
+ return result;
+ } catch (e) {
+ // Closed against the balances actually read: a zero asserted here would deny the synthesis debit.
+ await finalizeCharge();
+ if (e instanceof FabricJobFailedError) {
+ lastFailure = e;
+ // A timeout may already have consumed what it billed for; a refusal did not.
+ if (e.timedOut || isTerminalGenerationFailure(e)) throw e;
+ continue;
+ }
+ // Transport and client-side timeouts may still be finishing on a paid job, so --resume collects them.
+ throw e;
+ }
+ }
+ // All attempts returned the server's `failed` verdict without one that a re-submit could fix.
+ throw lastFailure ?? new Error(`Fabric generation failed after ${MAX_GENERATION_ATTEMPTS} attempts`);
+}
+
+// Saying nothing about cost is never acceptable, nor is a number the run cannot stand behind. VEED gives no
+// per-job figure, so the leading number is OUR estimate (labelled as one), and the workspace-global balance
+// delta is offered as corroboration, named a workspace movement, never "charged N". The user always gets a
+// number AND how much to trust it.
+function reportCharge(
+ log: (m: string) => void, spend: SpendRecord, assessment: ChargeAssessment, balanceAfter: number | null,
+): void {
+ const workspace = `${spend.workspaceName} (${spend.workspaceId})`;
+ // Printed on EVERY run that can measure, not only where the delta agrees: an estimate that was wrong
+ // is exactly the case this line explains, so hiding it there would hide it when it matters most.
+ if (spend.durationSeconds && spend.scriptChars) {
+ const observed = spend.scriptChars / spend.durationSeconds;
+ log(
+ `[fabric] this run measured ${observed.toFixed(1)} characters/second` +
+ (assessment.delta ? ` and ${(assessment.delta / spend.durationSeconds).toFixed(2)} credits/second` : '') +
+ `. The estimate assumed ${spend.assumedCharsPerSecond ?? CHARS_PER_SECOND}; speaking rate is a ` +
+ 'property of the voice, and it is what decides how long — and so how expensive — a script is.',
+ );
+ }
+ log(
+ `[fabric] this run was approved for an estimated ${spend.estimatedCredits} credits against ${workspace} — ` +
+ 'that figure is our own estimate from the script length, not a price VEED quoted. VEED exposes no ' +
+ 'per-job cost, so the balance movement below is the only measurement of what was actually charged.',
+ );
+ const left = balanceAfter === null ? '' : `, ${balanceAfter} left`;
+ if (assessment.kind === 'measured') {
+ log(
+ `[fabric] that workspace's balance moved ${assessment.delta} credits over the run${left}, which ` +
+ 'corroborates the estimate. It is a workspace-wide movement rather than this run\'s charge: anything ' +
+ 'else billing the same workspace moves it too.',
+ );
+ return;
+ }
+ if (assessment.kind === 'ambiguous') {
+ log(
+ `[fabric] that workspace's balance moved ${assessment.delta} credits over the run${left} — more than ` +
+ `the ${spend.estimatedCredits}-credit estimate, so it is recorded as an observed workspace movement ` +
+ 'and not as this run\'s charge. The likeliest cause is our estimate running low — a voice slower ' +
+ 'than assumed makes a longer video — and a concurrent run billing the same workspace is the other. ' +
+ 'The measured rate above says which.',
+ );
+ return;
+ }
+ // Deliberately covers all three ways a delta says nothing — unread, unmoved, moved too little — because
+ // claiming the balance "could not be read" when it read perfectly and sat still is its own small lie.
+ log(
+ `[fabric] the balance either side gives nothing credible to corroborate that with (it could not be read, ` +
+ `did not move, or moved too little to stand for the estimate), so this is our estimate and not ` +
+ `the amount charged: ~${spend.estimatedCredits} credits from ${workspace}`,
+ );
+}
+
+// Closes the audit trail a charged-but-interrupted run left open: it names the workspace that was billed, so
+// the balance can be read against it without asking the user anything a second time.
+async function completeSpendRecord(
+ client: VeedHttp, key: string, sessionId: string, deps: GenerateDeps, log: (m: string) => void,
+): Promise {
+ const path = spendPathFor(key, sessionId);
+ const raw = await deps.readState(path);
+ let spend: SpendRecord | null = null;
+ try {
+ if (raw !== null) spend = JSON.parse(raw) as SpendRecord;
+ } catch {
+ spend = null;
+ }
+ if (!spend || typeof spend.workspaceId !== 'string') {
+ log(`[fabric] no usable spend record at ${path}, so this run cannot say what the job cost`);
+ return;
+ }
+
+ // A resume COMPLETES a record, never re-decides one: the balance it could read now reflects every other
+ // spend against this workspace since, so re-running the assessment would replace the one real measurement
+ // with an artefact of that drift.
+ if (typeof spend.chargedCredits === 'number' && Number.isFinite(spend.chargedCredits)) {
+ reportCharge(log, spend, { kind: 'measured', delta: spend.chargedCredits }, null);
+ return;
+ }
+
+ const resolved = await resolveWorkspace({ http: client, explicit: spend.workspaceId });
+ const workspace = resolved.kind === 'resolved'
+ ? resolved.workspace
+ : { id: spend.workspaceId, name: spend.workspaceName, credits: null };
+ const assessment = assessCharge(spend.balanceBefore ?? null, workspace.credits, spend.estimatedCredits);
+ spend.chargedCredits = assessment.kind === 'measured' ? assessment.delta : null;
+ spend.observedWorkspaceDelta = assessment.delta;
+ reportCharge(log, spend, assessment, workspace.credits);
+ await deps.writeState(path, `${JSON.stringify(spend, null, 2)}\n`);
+ log(`[fabric] spend recorded at ${path}`);
+}
+
+// Poll an EXISTING job (paid for already) and land the file. Shared by the spend pass and --resume, so both
+// clean up the same state and neither can reach create_fabric_video from here.
+async function collect(
+ client: VeedHttp, jobId: string, key: string, sessionId: string, deps: GenerateDeps,
+ log: (m: string) => void,
+): Promise {
+ const now = deps.now ?? Date.now;
+ let url: string;
+ try {
+ url = await awaitVideo(client, jobId, {
+ sleep: deps.sleep,
+ now: deps.now,
+ onProgress: (attempt, status) => log(`[fabric] poll ${attempt + 1}: ${status}`),
+ });
+ } catch (e) {
+ // A job the server declared failed is terminal and (unlike a timeout) was not charged: resolving its
+ // charge record frees the run to re-submit under a fresh slot, which a lingering record would block
+ // forever. Every other failure may still finish server-side, so its record stays for --resume to collect.
+ if (e instanceof FabricJobFailedError) await resolveChargeRecord(deps, key, sessionId, now());
+ throw e;
+ }
+
+ const bytes = await deps.download(url);
+ // The filename must derive back to `key` via runKeyOf (as go.ts and prep.ts do), or this run silently
+ // collides with whatever run that filename would derive to.
+ const out = join(runsDir(), key, `${key}.mp4`);
+ if (runKeyOf(out) !== key) {
+ throw new Error(`internal error: runKeyOf(${out}) !== "${key}" — refusing to write a colliding run`);
+ }
+ await deps.writeOutput(out, bytes);
+ // A downloaded job is no longer in flight; the approval that bought it was already spent at the charge.
+ await resolveChargeRecord(deps, key, sessionId, now());
+ log(`[fabric] wrote ${out} (${(bytes.length / 1e6).toFixed(1)} MB)`);
+ return { status: 'generated', path: out, bytes: bytes.length };
+}
+
+function noTokenHelp(): void {
+ console.error(
+ [
+ 'No VEED login found. Log in with VEED:',
+ '',
+ ' npx @veedstudio/openedit-cli login',
+ '',
+ 'It opens your browser once and stores a refreshable token, owner-only, in the',
+ "CLI's app-data directory (npx @veedstudio/openedit-cli token --path prints where).",
+ '',
+ 'The same login covers both transcription and Fabric generation.',
+ ].join('\n'),
+ );
+}
+
+export function realDeps(): GenerateDeps {
+ return {
+ resolveAccessToken: resolveVeedToken,
+ // Resolved per request, so a token refresh mid-poll is picked up without reconnecting.
+ connect: async (getToken) => refreshingHttp(getToken),
+ readFileBytes: async (path) => new Uint8Array(await readFile(path)),
+ download: async (url) => {
+ const res = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+ if (!res.ok) throw new Error(`download ${url} -> ${res.status}`);
+ return new Uint8Array(await res.arrayBuffer());
+ },
+ writeOutput: async (path, bytes) => {
+ await mkdir(dirname(path), { recursive: true });
+ await writeFile(path, bytes);
+ },
+ readState: async (path) => {
+ try {
+ return await readFile(path, 'utf8');
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code === 'ENOENT') return null;
+ throw e;
+ }
+ },
+ writeState: async (path, text) => {
+ await mkdir(dirname(path), { recursive: true });
+ await writeFile(path, text, { mode: 0o600 });
+ },
+ removeState: (path) => rm(path, { force: true }),
+ listState: async (dir) => {
+ try {
+ return await readdir(dir);
+ } catch (e) {
+ if ((e as NodeJS.ErrnoException).code === 'ENOENT') return [];
+ throw e;
+ }
+ },
+ // One id per process, and a process charges at most once, so this identifies the attempt as well.
+ sessionId: randomUUID(),
+ pid: process.pid,
+ host: hostname(),
+ // Signal 0 checks for the process without touching it; EPERM means it exists and simply is not ours.
+ isAlive: (pid) => {
+ try {
+ process.kill(pid, 0);
+ return true;
+ } catch (e) {
+ return (e as NodeJS.ErrnoException).code === 'EPERM';
+ }
+ },
+ sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+ now: Date.now,
+ };
+}
+
+export async function generate(argv: string[]): Promise {
+ const args = parseArgs(argv);
+ const result = await run(args, realDeps());
+ if (result.status === 'no-token') {
+ noTokenHelp();
+ return 1;
+ }
+ // run() has already printed the workspaces and the exact command to re-run with; a non-zero exit keeps a
+ // caller that chains commands from treating "nobody chose" as "done".
+ if (result.status === 'workspace-required') return 1;
+ return 0;
+}
diff --git a/cli/src/commands/init.ts b/cli/src/commands/init.ts
new file mode 100644
index 0000000..831e8c2
--- /dev/null
+++ b/cli/src/commands/init.ts
@@ -0,0 +1,677 @@
+// @ts-nocheck — a faithful port of the skill's preflight.mjs, kept line-for-line where possible;
+// its behavior is pinned by tests/init.test.ts, not by types.
+//
+// Open Edit's single setup entrypoint.
+//
+// openedit init Apply workspace-local setup; report global installs and updates.
+// openedit init --dry Report only; never write.
+// openedit init --auto-approve Apply everything, including global installs and clean updates. The
+// orchestrating agent may use this only after explicit user approval.
+//
+// Project hooks (the SessionStart entries in the workspace's agent configs) are installed here too,
+// invoking this package's session-start command — the installed skill is SKILL.md alone.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { resolveLatestEngineTag } from '../engine-release.ts';
+import {
+ engineBinaryName,
+ engineInstallDir,
+ ffmpegInstallDir,
+ findOnPath,
+ installHint,
+ isCmdShim,
+ isEngineRunnable,
+ platformKey,
+ unsupportedMessage,
+} from '../platform.ts';
+import { installProjectHooks } from '../project-hooks.ts';
+
+export interface ExecResult {
+ status: number | null;
+ stdout?: string | Buffer | null;
+ stderr?: string | Buffer | null;
+ error?: Error;
+}
+
+const DEFAULT_REPOSITORY = 'https://github.com/veedstudio/open-edit.git';
+const DEFAULT_REF = 'main';
+// Floor, not a pin: any newer pnpm is accepted. Must equal the repository package.json's
+// `packageManager`; init runs in a CONSUMER's project, so reading that field at runtime would find
+// their package.json, not the repo's. tests/init.test.ts holds the two together instead.
+const MIN_PNPM = '10.16.1';
+// 0.10.2 is the first release with `--verify=` (the safe-zone family the skill's SAFE-ZONE CHECK
+// runs); the Windows asset arrived in 0.9.0 and the WCAG analyzer in 0.8.0. The floor is checked before
+// the release API, so a stale engine is caught even when that API is unreachable or rate-limited.
+const MIN_ENGINE = '0.10.2';
+
+
+const USAGE = `usage: openedit init [--dry|--auto-approve]
+ [--workspace ] [--repository ] [--ref ]
+
+Bare init applies only workspace-local first-time setup. --dry never writes.
+--auto-approve installs missing machine dependencies and applies all clean updates; use it only
+after the user has explicitly approved every action reported by --dry.`;
+
+class PreflightError extends Error {}
+
+export function defaultDeps() {
+ return {
+ os: process.platform,
+ arch: process.arch,
+ env: process.env,
+ exec: (cmd, args, opts = {}) => spawnSync(cmd, args, { encoding: 'utf8', ...opts }),
+ fetch: (...args) => fetch(...args),
+ err: (line) => process.stderr.write(`${line}\n`),
+ out: (line) => process.stdout.write(`${line}\n`),
+ };
+}
+
+export async function main(argv, overrides = {}) {
+ const deps = { ...defaultDeps(), ...overrides };
+ try {
+ return await run(argv, deps);
+ } catch (error) {
+ if (error instanceof PreflightError) {
+ deps.err(`preflight: ERROR — ${error.message}`);
+ return 1;
+ }
+ throw error;
+ }
+}
+
+async function run(argv, deps) {
+ const { env } = deps;
+ const isWin = deps.os === 'win32';
+ const say = (msg) => deps.err(`preflight: ${msg}`);
+ const die = (msg) => {
+ throw new PreflightError(msg);
+ };
+ let needsApproval = false;
+ let failed = false;
+ const needApproval = (msg) => {
+ needsApproval = true;
+ say(`APPROVAL REQUIRED — ${msg}`);
+ };
+
+ // GUI-launched agents inherit a minimal PATH that commonly omits Homebrew. Add both standard
+ // prefixes before probing brew, Node, pnpm, FFmpeg or Git — BEHIND the caller's own PATH, never
+ // ahead of it. This PATH also carries the nested `npx @veedstudio/openedit-cli` calls below, and an
+ // npm whose global directory is not the caller's resolves a published copy of this CLI instead of
+ // the one now running: a different version doing the install.
+ if (deps.os === 'darwin') {
+ const prefix = 'OPEN_EDIT_HOMEBREW_PATH_PREFIX' in env
+ ? env.OPEN_EDIT_HOMEBREW_PATH_PREFIX
+ : '/opt/homebrew/bin:/usr/local/bin';
+ if (prefix) env.PATH = env.PATH ? `${env.PATH}:${prefix}` : prefix;
+ }
+
+ const which = deps.which ?? ((cmd) => findOnPath(cmd, env, deps.os));
+ const have = (cmd) => Boolean(which(cmd));
+ const exec = (cmd, args, opts = {}) => deps.exec(cmd, args, opts);
+ // pnpm and npm install as .cmd shims on Windows, which Node refuses to exec directly — the
+ // classic win32 port bug. Route those through cmd.exe with every token quoted.
+ const execTool = (cmd, args, opts = {}) => {
+ const resolved = which(cmd) ?? cmd;
+ // A corepack-managed pnpm fetches its version on first use and PROMPTS before doing so. stdio is
+ // piped here, so nobody can answer and the probe fails instead of reporting a version.
+ const withEnv = { env: { ...env, COREPACK_ENABLE_DOWNLOAD_PROMPT: '0' }, ...opts };
+ if (isCmdShim(resolved)) {
+ const line = [resolved, ...args].map((a) => `"${a}"`).join(' ');
+ return deps.exec('cmd.exe', ['/d', '/s', '/c', `"${line}"`], { ...withEnv, windowsVerbatimArguments: true });
+ }
+ return deps.exec(resolved, args, withEnv);
+ };
+ const out = (result) => (result.stdout ?? '').toString().trim();
+ const ok = (result) => !result.error && result.status === 0;
+
+ // Numeric core only: a prerelease segment (10.17.0-beta.1) made Number() NaN, which reported a
+ // NEWER tool as missing and proposed the floor over it. A prerelease of the floor now passes.
+ const versionAtLeast = (candidate, floor) => {
+ if (!candidate) return false;
+ const core = (v) => String(v).trim().replace(/^v/, '').split(/[-+]/)[0].split('.');
+ const a = core(candidate);
+ const b = core(floor);
+ for (let i = 0; i < Math.max(a.length, b.length); i++) {
+ const x = Number(a[i] ?? 0);
+ const y = Number(b[i] ?? 0);
+ if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+ if (x !== y) return x > y;
+ }
+ return true;
+ };
+ // pnpm >=10 self-switches to a project's pinned `packageManager`, so the binary on PATH is not the
+ // one that installs. Ask what this pnpm becomes in a scratch project carrying the same pin.
+ const pnpmSelfSwitchesToFloor = () => {
+ let dir = null;
+ try {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'open-edit-pnpm-'));
+ fs.writeFileSync(
+ path.join(dir, 'package.json'),
+ JSON.stringify({ name: 'open-edit-pnpm-probe', private: true, packageManager: `pnpm@${MIN_PNPM}` }),
+ );
+ return versionAtLeast(out(execTool('pnpm', ['--version'], { cwd: dir })), MIN_PNPM);
+ } catch {
+ return false; // offline, or a pnpm that cannot fetch its pin — treat as not satisfied
+ } finally {
+ if (dir) { try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* scratch dir */ } }
+ }
+ };
+ const pnpmOk = () => versionAtLeast(out(execTool('pnpm', ['--version'])), MIN_PNPM)
+ || pnpmSelfSwitchesToFloor();
+ // native expands Windows 8.3 short names (RUNNER~1), so OPEN_EDIT_ROOT is the path a user recognises.
+ const resolveDir = (p) => {
+ try {
+ const real = fs.realpathSync.native(p);
+ return fs.statSync(real).isDirectory() ? real : null;
+ } catch {
+ return null;
+ }
+ };
+
+ let mode = 'apply';
+ let workspaceArg = '';
+ let repositoryArg = '';
+ let refArg = '';
+ const args = [...argv];
+ while (args.length > 0) {
+ const arg = args.shift();
+ switch (arg) {
+ case '--dry': mode = 'dry'; break;
+ case '--auto-approve': mode = 'auto'; break;
+ case '--workspace':
+ if (args.length === 0) die('--workspace requires a path');
+ workspaceArg = args.shift();
+ break;
+ case '--repository':
+ if (args.length === 0) die('--repository requires a URL or local path');
+ repositoryArg = args.shift();
+ break;
+ case '--ref':
+ if (args.length === 0) die('--ref requires a branch');
+ refArg = args.shift();
+ break;
+ case '-h':
+ case '--help':
+ deps.err(USAGE);
+ return 0;
+ default:
+ deps.err(USAGE);
+ die(`unknown argument: ${arg}`);
+ }
+ }
+ for (const value of [workspaceArg, repositoryArg, refArg]) {
+ if (/[\n\r]/.test(value)) die('arguments may not contain newlines');
+ }
+
+ let workspace;
+ if (workspaceArg) {
+ workspace = resolveDir(workspaceArg) ?? die(`workspace does not exist: ${workspaceArg}`);
+ } else {
+ const top = exec('git', ['rev-parse', '--show-toplevel']);
+ workspace = (ok(top) && resolveDir(out(top))) || fs.realpathSync.native(process.cwd());
+ }
+ if (repositoryArg && fs.existsSync(repositoryArg) && fs.statSync(repositoryArg).isDirectory()) {
+ repositoryArg = resolveDir(repositoryArg) ?? die('repository path does not exist');
+ }
+
+ if (!platformKey(deps.os, deps.arch)) die(unsupportedMessage(deps.os, deps.arch));
+
+ const container = path.join(workspace, '.open-edit');
+ const managedRoot = path.join(container, 'runtime');
+ let root = managedRoot;
+ let rootKind = 'missing';
+ let recorded = { repository: '', ref: '', commit: '' };
+
+ // The markers that make a tree an Open Edit runtime. A refusal names the one that was missing:
+ // "not a valid checkout" alone leaves whoever hits it — in CI, on a machine they cannot open —
+ // with a verdict and no evidence. This package ships three of the four, so the lockfile is what
+ // tells an installed copy of the CLI apart from a runtime to reuse in place; it cannot come along
+ // by accident, because npm drops a pnpm/yarn lockfile from every pack even when `files` names it
+ // outright (measured).
+ const CHECKOUT_MARKERS = [
+ 'package.json',
+ 'pnpm-lock.yaml',
+ path.join('pipeline', 'scripts', 'preflight.sh'),
+ path.join('refs', 'tags.json'),
+ ];
+ const missingCheckoutMarker = (candidate) => {
+ try {
+ // existsSync answers false for an unreadable directory as readily as for an absent file, so the
+ // permissions are checked on their own — otherwise a locked tree is reported as a missing file.
+ fs.accessSync(candidate, fs.constants.R_OK | fs.constants.X_OK);
+ return CHECKOUT_MARKERS.find((marker) => !fs.existsSync(path.join(candidate, marker))) ?? '';
+ } catch (error) {
+ return `readable contents (${error?.message ?? String(error)})`;
+ }
+ };
+ const isOpenEditCheckout = (candidate) => missingCheckoutMarker(candidate) === '';
+
+ const statePathFor = (dir) => {
+ const result = exec('git', ['-C', dir, 'rev-parse', '--absolute-git-dir']);
+ return ok(result) ? path.join(out(result), 'open-edit-preflight-state') : null;
+ };
+ const stateGet = (file, key) => {
+ const result = exec('git', ['config', '--file', file, '--get', `preflight.${key}`]);
+ return ok(result) ? out(result) : '';
+ };
+ const writeState = (dir, source, branch, commit) => {
+ const file = statePathFor(dir) ?? die(`cannot locate Git metadata for ${dir}`);
+ for (const [key, value] of [['schema', '1'], ['repository', source], ['ref', branch], ['installedCommit', commit]]) {
+ exec('git', ['config', '--file', file, `preflight.${key}`, value]);
+ }
+ };
+
+ const discoverRuntime = () => {
+ if (isOpenEditCheckout(workspace) && ok(exec('git', ['-C', workspace, 'rev-parse', '--is-inside-work-tree']))) {
+ root = workspace;
+ rootKind = 'reused';
+ return;
+ }
+ if (!fs.existsSync(managedRoot)) return;
+ if (!fs.statSync(managedRoot).isDirectory()) die(`managed runtime path is not a directory: ${managedRoot}`);
+ const strayMarker = missingCheckoutMarker(managedRoot);
+ if (strayMarker) die(`refusing unexpected contents at ${managedRoot} — no ${strayMarker}`);
+ const statePath = statePathFor(managedRoot) ?? die('managed runtime is not a Git checkout');
+ if (!fs.existsSync(statePath)) die('managed runtime has no completed-clone receipt');
+ if (stateGet(statePath, 'schema') !== '1') die('managed runtime has an unsupported receipt');
+ recorded = {
+ repository: stateGet(statePath, 'repository'),
+ ref: stateGet(statePath, 'ref'),
+ commit: stateGet(statePath, 'installedCommit'),
+ };
+ if (!recorded.repository || !recorded.ref || !recorded.commit) die('managed runtime receipt is incomplete');
+ const origin = out(exec('git', ['-C', managedRoot, 'remote', 'get-url', 'origin']));
+ const head = out(exec('git', ['-C', managedRoot, 'rev-parse', 'HEAD']));
+ if (origin !== recorded.repository) die('runtime origin differs from its receipt');
+ if (head !== recorded.commit) die('runtime HEAD differs from its managed revision; inspect it before continuing');
+ if (repositoryArg && repositoryArg !== recorded.repository) die('--repository conflicts with the managed runtime');
+ if (refArg && refArg !== recorded.ref) die('--ref conflicts with the managed runtime');
+ root = managedRoot;
+ rootKind = 'managed';
+ };
+
+ discoverRuntime();
+
+ // SessionStart hooks for the agent harnesses, written into the WORKSPACE's agent configs. Advisory,
+ // like setup always treated them: a hook problem must not block a run. Owned here rather than by
+ // the skill so an installed skill is SKILL.md alone.
+ if (mode === 'dry') {
+ say('WOULD APPLY LOCALLY — SessionStart hooks in the workspace agent configs (.claude/.codex/.gemini)');
+ } else {
+ try {
+ installProjectHooks(workspace, (line) => say(line));
+ } catch (error) {
+ say(`could not install project hooks automatically (${error?.message ?? error}); the agent must preserve existing settings and add them manually`);
+ }
+ }
+
+ // Say which code is about to run, and warn when a local checkout is being bypassed. WORKSPACE is only
+ // reused when it IS an Open Edit checkout; otherwise everything below runs from a clone of
+ // DEFAULT_REF, so pointing --workspace at the wrong directory silently runs different code.
+ if (rootKind === 'reused') {
+ say(`reusing the local checkout at ${root}`);
+ } else {
+ say(`workspace ${workspace} will use a managed clone at ${managedRoot}`);
+ // Pointing --workspace elsewhere while standing in a checkout silently runs DIFFERENT code —
+ // the note the skill-bundled setup used to key on its own install location.
+ const invokedTop = exec('git', ['rev-parse', '--show-toplevel']);
+ const invokedFrom = ok(invokedTop) ? resolveDir(out(invokedTop)) : null;
+ if (invokedFrom && isOpenEditCheckout(invokedFrom) && invokedFrom !== workspace) {
+ say(`NOTE: this command ran from the checkout ${invokedFrom}, which will NOT be used.`);
+ say(` To run that code instead, pass --workspace ${invokedFrom}`);
+ }
+ }
+
+ let repository;
+ let ref;
+ if (rootKind === 'managed') {
+ repository = recorded.repository;
+ ref = recorded.ref;
+ } else {
+ repository = repositoryArg || DEFAULT_REPOSITORY;
+ ref = refArg || DEFAULT_REF;
+ }
+
+ // Duplicates config.ts's resolution rather than importing it, so the check runs against the
+ // INJECTED env: env override → app-data install → legacy workspace .ffmpeg/ → PATH.
+ const localFfmpegOk = () => [path.join(ffmpegInstallDir(deps.os, env), 'bin'), path.join(root, '.ffmpeg', 'bin')]
+ .some((bin) => ['ffmpeg', 'ffprobe'].every((n) => fs.existsSync(path.join(bin, isWin ? `${n}.exe` : n))));
+ const ffmpegOk = () =>
+ (have(env.VEED_ENGINE_FFMPEG || 'ffmpeg') && have(env.VEED_ENGINE_FFPROBE || 'ffprobe')) || localFfmpegOk();
+ // A platform question: the no-admin download route exists on Windows only (macOS has brew).
+ const ffmpegHasLocalRoute = () => isWin;
+ const installFfmpegLocally = () => {
+ // stderr is inherited, so the installer's own diagnostics reach the user directly.
+ const r = execTool('npx', ['--yes', '@veedstudio/openedit-cli', 'install-ffmpeg'], { stdio: ['ignore', 2, 2] });
+ if (!ok(r)) {
+ say(`local FFmpeg install failed: ${r.error?.message ?? `exited ${r.status}`}`);
+ failed = true;
+ }
+ };
+ const installBrewFormula = (formula) => {
+ if (!have('brew')) {
+ say(`Homebrew is required to install ${formula}; install Homebrew first`);
+ failed = true;
+ return;
+ }
+ if (!ok(execTool('brew', ['install', formula], { stdio: ['ignore', 2, 2] }))) failed = true;
+ };
+
+ // Kept at this scope so the post-clone FFmpeg step can clear its entry and retract the approval.
+ let globalsMissing = { git: false, node: false, pnpm: false, ffmpeg: false };
+
+ const handleGlobalDependencies = () => {
+ const missing = {
+ git: !have('git'),
+ node: !have('node'),
+ pnpm: !pnpmOk(),
+ ffmpeg: !ffmpegOk(),
+ };
+ globalsMissing = missing;
+ if (missing.git) needApproval(`install Git globally: ${installHint('git', deps.os)}`);
+ if (missing.node) needApproval(`install Node globally: ${installHint('node', deps.os)}`);
+ // corepack avoids owning a global package, but resolves its version from the CWD project and
+ // writes shims into Node's own bin dir, which a system-wide Node does not allow. Both commands
+ // are printed because either can be the one that works on a given machine.
+ if (missing.pnpm) {
+ needApproval(`install pnpm ${MIN_PNPM} or newer globally: ${have('corepack')
+ ? 'corepack enable pnpm (or npm install --global pnpm@latest)'
+ : 'npm install --global pnpm@latest'}`);
+ }
+ if (missing.ffmpeg) {
+ needApproval(`install FFmpeg globally: ${installHint('ffmpeg', deps.os)}`);
+ if (ffmpegHasLocalRoute()) {
+ say('FFmpeg can instead be installed to the app-data dir, which needs no admin rights: npx @veedstudio/openedit-cli install-ffmpeg');
+ }
+ }
+
+ if (isWin && Object.values(missing).some(Boolean)) {
+ // winget needs an interactive first run and its PATH edits never reach an already-running
+ // process, so Windows GLOBAL installs stay manual: report, and keep the approval pending even
+ // under --auto-approve rather than half-applying it.
+ if (!have('winget')) say('no winget on this machine — install from git-scm.com, nodejs.org, and gyan.dev (FFmpeg) instead');
+ // FFmpeg is the exception — handleLocalFfmpeg() applies the no-admin route.
+ if (missing.git || missing.node || missing.pnpm) {
+ say('Windows installs are manual in v1 — run the commands above, then re-run preflight from a NEW terminal (PATH changes need a fresh shell)');
+ }
+ return;
+ }
+ if (mode !== 'auto') return;
+ needsApproval = false;
+ if (missing.git) installBrewFormula('git');
+ if (missing.node) installBrewFormula('node');
+ if (missing.ffmpeg) installBrewFormula('ffmpeg');
+ if (missing.pnpm) {
+ // corepack enable only writes shims; which pnpm they resolve to comes from the CWD project's
+ // own packageManager, which is the consumer's and may be below the floor or absent. A zero exit
+ // is therefore not proof, and treating it as one skipped the npm fallback that would have
+ // fixed it — leaving preflight to die a step later with nothing left to try.
+ const viaCorepack = have('corepack')
+ && ok(execTool('corepack', ['enable', 'pnpm'], { stdio: ['ignore', 2, 2] }))
+ && pnpmOk();
+ if (!viaCorepack) {
+ if (!have('npm')) {
+ say('npm is unavailable after installing Node');
+ failed = true;
+ return;
+ }
+ if (!ok(execTool('npm', ['install', '--global', 'pnpm@latest'], { stdio: ['ignore', 2, 2] }))) failed = true;
+ }
+ }
+ if (!have('git') || !have('node') || !pnpmOk() || !ffmpegOk()) failed = true;
+ };
+
+ handleGlobalDependencies();
+ if (failed) die('one or more approved global dependency installs failed');
+
+ // The installer ships in this package, so the no-admin route needs no clone.
+ const handleLocalFfmpeg = () => {
+ if (!ffmpegHasLocalRoute() || !globalsMissing.ffmpeg || ffmpegOk()) return;
+ if (mode === 'dry') {
+ say('WOULD APPLY LOCALLY — npx @veedstudio/openedit-cli install-ffmpeg');
+ return;
+ }
+ // Bare init performs this: it is workspace-local and needs no elevation, so only GLOBAL installs
+ // wait for approval.
+ say('installing FFmpeg into the app-data dir (no admin rights needed)');
+ installFfmpegLocally();
+ if (!ffmpegOk()) return;
+ globalsMissing.ffmpeg = false;
+ // Safe because only the global installs approve before here; renderer and runtime come later.
+ if (!Object.values(globalsMissing).some(Boolean)) needsApproval = false;
+ };
+
+ handleLocalFfmpeg();
+ if (failed) die('the local FFmpeg install failed');
+
+ const cloneRuntime = () => {
+ if (rootKind !== 'missing') return;
+ if (!have('git')) {
+ say('runtime clone is waiting for Git');
+ return;
+ }
+ if (mode === 'dry') {
+ say(`WOULD APPLY LOCALLY — full clone ${repository} (${ref}) to ${managedRoot}`);
+ return;
+ }
+ fs.mkdirSync(container, { recursive: true });
+ let staging;
+ try {
+ staging = fs.mkdtempSync(path.join(container, '.preflight.'));
+ } catch {
+ die('cannot create clone staging directory');
+ }
+ try {
+ say(`cloning ${repository} (${ref}) to ${managedRoot}`);
+ const cloned = path.join(staging, 'runtime');
+ if (!ok(exec('git', ['clone', '--single-branch', '--branch', ref, '--', repository, cloned], { stdio: ['ignore', 2, 2] }))) die('clone failed');
+ // Names the repository and ref, never the staging path: the finally below deletes that before
+ // the error surfaces, and a directory the reader cannot open is not evidence.
+ const cloneMarker = missingCheckoutMarker(cloned);
+ if (cloneMarker) die(`cloned repository is not a valid Open Edit checkout — ${repository} (${ref}) has no ${cloneMarker}`);
+ const commitR = exec('git', ['-C', cloned, 'rev-parse', 'HEAD']);
+ if (!ok(commitR)) die('cannot resolve cloned revision');
+ const originR = exec('git', ['-C', cloned, 'remote', 'get-url', 'origin']);
+ if (!ok(originR)) die('cannot resolve cloned origin');
+ const commit = out(commitR);
+ const origin = out(originR);
+ writeState(cloned, origin, ref, commit);
+ if (fs.existsSync(managedRoot)) die('runtime appeared while cloning; refusing to overwrite it');
+ fs.renameSync(cloned, managedRoot);
+ if (ok(exec('git', ['-C', workspace, 'rev-parse', '--is-inside-work-tree']))) {
+ let exclude = out(exec('git', ['-C', workspace, 'rev-parse', '--git-path', 'info/exclude']));
+ if (!path.isAbsolute(exclude)) exclude = path.join(workspace, exclude);
+ const existing = fs.existsSync(exclude) ? fs.readFileSync(exclude, 'utf8') : '';
+ if (!existing.split(/\r?\n/).includes('.open-edit/')) fs.appendFileSync(exclude, '\n.open-edit/\n');
+ }
+ root = managedRoot;
+ rootKind = 'managed';
+ recorded = { repository: origin, ref, commit };
+ say(`runtime cloned at ${commit}`);
+ } finally {
+ fs.rmSync(staging, { recursive: true, force: true });
+ }
+ };
+
+ cloneRuntime();
+
+ // `pnpm list` costs about 850ms, almost all of it pnpm's own boot, and this predicate is asked twice
+ // in one init — once to decide whether to install, once again in the readiness summary. The answer
+ // cannot change between those two calls unless install ran, which clears the memo itself.
+ let depsReady: boolean | undefined;
+ const repoDepsReady = () => (depsReady ??= computeRepoDepsReady());
+
+ const computeRepoDepsReady = () => {
+ const tsx = path.join(root, 'node_modules', '.bin', 'tsx');
+ if (isWin) {
+ // pnpm writes .CMD shims on Windows, and there is no exec bit to test
+ if (!fs.existsSync(`${tsx}.CMD`) && !fs.existsSync(`${tsx}.cmd`)) return false;
+ } else {
+ try {
+ fs.accessSync(tsx, fs.constants.X_OK);
+ } catch {
+ return false;
+ }
+ }
+ const modulesYaml = path.join(root, 'node_modules', '.modules.yaml');
+ if (!fs.existsSync(modulesYaml)) return false;
+ const recordedPnpm = fs.readFileSync(modulesYaml, 'utf8').split(/\r?\n/)
+ .map((line) => line.match(/^packageManager:\s*pnpm@([^\s"']*)/)?.[1])
+ .find(Boolean) ?? '';
+ return versionAtLeast(recordedPnpm, MIN_PNPM) && ok(execTool('pnpm', ['list', '--depth', '0'], { cwd: root }));
+ };
+
+ const handleRepoDeps = () => {
+ if (rootKind === 'missing') return;
+ if (repoDepsReady()) {
+ say('repository dependencies — ready');
+ return;
+ }
+ if (!have('node') || !pnpmOk()) {
+ say('repository dependencies are waiting for approved Node/pnpm installation');
+ return;
+ }
+ if (mode === 'dry') {
+ say(`WOULD APPLY LOCALLY — pnpm install --frozen-lockfile in ${root}`);
+ return;
+ }
+ say(`installing repository dependencies in ${root}`);
+ if (!ok(execTool('pnpm', ['install', '--frozen-lockfile'], { cwd: root, stdio: ['ignore', 2, 2] }))) die('repository dependency installation failed');
+ depsReady = undefined; // install changed the answer
+ if (!repoDepsReady()) die('repository dependency validation failed after install');
+ };
+
+ handleRepoDeps();
+
+ const enginePath = () => env.VEED_ENGINE_BIN || path.join(engineInstallDir(deps.os, env), engineBinaryName(deps.os));
+ const latestEngineVersion = async () => {
+ // No route answering means no update prompt, never a failed run — the floor check above already
+ // catches a stale engine without asking anyone what the newest one is.
+ const { tag } = await resolveLatestEngineTag(deps.fetch, 10_000);
+ return tag.replace(/^weave-v/, ''); // upstream tag format is weave-v
+ };
+ // The binary prints `weave-viewer-cli `; a run that fails or prints nothing reads as ''.
+ const engineVersion = (bin) => {
+ const result = exec(bin, ['--version']);
+ return result.error ? '' : ((result.stdout ?? '').toString().trim().split(/\s+/)[1] ?? '');
+ };
+ // The installer lives in the published CLI, not the runtime checkout; execTool routes npx
+ // through cmd.exe on Windows (it installs as a .cmd shim there).
+ const installEngine = () => ok(execTool('npx', ['--yes', '@veedstudio/openedit-cli', 'install-engine'], { stdio: ['ignore', 2, 2] }));
+
+ // RE-READ and enforce, after any install: one that exits 0 without raising the
+ // version (download failed softly, or the published release is still older than
+ // the floor) would otherwise be reported as ready, and the run would die inside
+ // the WCAG pass on an unknown flag instead.
+ const assertEngineFloor = (engine) => {
+ const installed = engineVersion(engine);
+ if (!versionAtLeast(installed, MIN_ENGINE)) {
+ die(`renderer is ${installed || 'unreadable'} after installing, below the required ${MIN_ENGINE} — the safe-zone check and the WCAG pass cannot run`);
+ }
+ say(`renderer ${installed} — meets the ${MIN_ENGINE} floor`);
+ };
+
+ const handleRenderer = async () => {
+ if (rootKind === 'missing') return;
+ const engine = enginePath();
+ if (!isEngineRunnable(engine, deps.os)) {
+ if (mode === 'dry') {
+ say(`WOULD APPLY LOCALLY — install the renderer in ${engineInstallDir(deps.os, env)}`);
+ return;
+ }
+ say('installing the renderer locally');
+ if (!installEngine()) die('renderer installation failed');
+ // A FIRST install answers to the same floor as an update: nothing downstream
+ // re-checks it, so an engine laid down below the floor would be reported ready.
+ assertEngineFloor(engine);
+ return;
+ }
+ const installed = engineVersion(engine);
+ // The FLOOR is checked before freshness: an engine below it cannot run the WCAG
+ // pass at all, and that must be said even when the release API is unreachable.
+ // An UNREADABLE version counts as below it — nothing downstream can tell the two
+ // apart, so treating it as "unknown, carry on" only defers the failure.
+ if (!versionAtLeast(installed, MIN_ENGINE)) {
+ if (mode !== 'auto') {
+ needApproval(`update renderer from ${installed || 'an unreadable version'} to at least ${MIN_ENGINE} (the safe-zone check needs --verify=, the WCAG pass its bundled analyzer)`);
+ return;
+ }
+ if (!installEngine()) die('approved renderer update failed');
+ assertEngineFloor(engine);
+ needsApproval = false;
+ return;
+ }
+ const latest = await latestEngineVersion();
+ if (!installed || !latest) {
+ say('renderer freshness — offline or indeterminate');
+ return;
+ }
+ if (installed === latest) {
+ say(`renderer ${installed} — current`);
+ return;
+ }
+ if (!versionAtLeast(latest, installed)) {
+ say(`renderer ${installed} is newer than published ${latest}`);
+ return;
+ }
+ needApproval(`update renderer from ${installed} to ${latest}`);
+ if (mode === 'auto') {
+ needsApproval = false;
+ if (!installEngine()) die('approved renderer update failed');
+ }
+ };
+
+ await handleRenderer();
+
+ const handleRuntimeUpdate = () => {
+ if (rootKind !== 'managed') return;
+ const remote = exec('git', ['ls-remote', '--exit-code', repository, `refs/heads/${ref}`]);
+ const remoteCommit = ok(remote) ? (out(remote).split(/\s+/)[0] ?? '') : '';
+ if (!remoteCommit) {
+ say('runtime freshness — offline or indeterminate');
+ return;
+ }
+ const localCommit = out(exec('git', ['-C', root, 'rev-parse', 'HEAD']));
+ if (localCommit === remoteCommit) {
+ say(`runtime ${localCommit} — current`);
+ return;
+ }
+ if (out(exec('git', ['-C', root, 'status', '--porcelain']))) {
+ say('UPDATE AVAILABLE — runtime has local changes; leaving it untouched');
+ return;
+ }
+ needApproval(`fast-forward runtime from ${localCommit} to ${remoteCommit} (${repository} ${ref})`);
+ if (mode === 'auto') {
+ needsApproval = false;
+ if (!ok(exec('git', ['-C', root, 'fetch', 'origin', `refs/heads/${ref}:refs/remotes/origin/${ref}`], { stdio: ['ignore', 2, 2] }))) die('approved runtime fetch failed');
+ if (!ok(exec('git', ['-C', root, 'merge-base', '--is-ancestor', localCommit, remoteCommit]))) die('remote update is not a fast-forward');
+ if (!ok(exec('git', ['-C', root, 'merge', '--ff-only', remoteCommit], { stdio: ['ignore', 2, 2] }))) die('approved runtime update failed');
+ writeState(root, repository, ref, remoteCommit);
+ }
+ };
+
+ handleRuntimeUpdate();
+
+ if (rootKind === 'missing') {
+ say('runtime is not ready');
+ } else if (repoDepsReady() && isEngineRunnable(enginePath(), deps.os)) {
+ say(`ready — OPEN_EDIT_ROOT=${root}`);
+ } else if (needsApproval) {
+ say('local setup is incomplete because an approved prerequisite is missing');
+ } else {
+ // Nothing is awaiting approval: the outstanding work is the WOULD APPLY LOCALLY list above, which
+ // bare preflight performs itself. Saying "approval" here sent agents looking for a user to ask.
+ say('not ready yet — run bare preflight (no --dry) to apply the local setup listed above');
+ }
+
+ if (needsApproval) {
+ say('run with --auto-approve only after the user approves every action above');
+ return 10;
+ }
+ if (failed) return 1;
+ deps.out(root);
+ return 0;
+}
+
diff --git a/cli/src/commands/install-engine.ts b/cli/src/commands/install-engine.ts
new file mode 100644
index 0000000..95ca2c1
--- /dev/null
+++ b/cli/src/commands/install-engine.ts
@@ -0,0 +1,123 @@
+// Install veed-engine-cli by downloading the release directly from GitHub (no package manager).
+// Fetches the platform's archive + its .sha256 + the feature-support.md asset, verifies the checksum,
+// and extracts everything into the app-data engine dir. The orchestrator asks the user before running.
+// The upstream release assets keep their original names (weave-viewer-cli-*, weave-v* tags);
+// the extracted binary is renamed locally to veed-engine-cli (.exe on Windows).
+//
+// openedit install-engine # install/upgrade to the latest release
+// openedit install-engine weave-v0.9.0 # pin a specific tag (upstream tag format)
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { engineDir } from '../config.ts';
+import { ENGINE_RELEASES_REPO as REPO, resolveLatestEngineTag } from '../engine-release.ts';
+import { ENGINE_ASSETS, engineBinaryName, platformKey, probeVersion, unsupportedMessage } from '../platform.ts';
+
+const say = (msg: string) => console.log(`install-engine: ${msg}`);
+
+class InstallError extends Error {}
+const die = (msg: string): never => { throw new InstallError(msg); };
+
+const fetchOk = async (url: string, timeoutMs: number) => {
+ const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
+ if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+ return res;
+};
+
+const download = async (url: string, dest: string, timeoutMs: number) => {
+ const res = await fetchOk(url, timeoutMs);
+ fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()));
+};
+
+export async function installEngine(argv: string[]): Promise {
+ try {
+ await install(argv[0] ?? '');
+ return 0;
+ } catch (error) {
+ if (error instanceof InstallError) {
+ console.error(`install-engine: ${error.message}`);
+ return 1;
+ }
+ throw error;
+ }
+}
+
+async function install(tagArg: string): Promise {
+ // Platform gate — only these assets are published; fail loudly elsewhere rather than installing a
+ // binary that can't exec.
+ const key = platformKey();
+ if (!key) die(`${unsupportedMessage()} — see the published assets at ${REPO}.`);
+ const { archive: ARCHIVE, upstreamBin: UPSTREAM_BIN } = ENGINE_ASSETS[key!];
+ const DEST = engineDir();
+ const LOCAL_BIN = engineBinaryName();
+
+ // Resolve the tag to install (arg overrides; else the latest release)
+ let tag = tagArg;
+ if (!tag) {
+ const latest = await resolveLatestEngineTag();
+ tag = latest.tag;
+ if (!tag) die(`could not resolve a release tag — ${latest.failures.join('; ')}`);
+ // A fallback that worked still spent a metered API call. Naming the route that was skipped is
+ // how a permanently blocked one gets noticed instead of quietly costing budget every run.
+ if (latest.failures.length > 0) say(`note — ${latest.failures.join('; ')}`);
+ }
+
+ const base = `https://github.com/${REPO}/releases/download/${tag}`;
+ say(`installing ${tag} (${ARCHIVE}) → ${DEST}`);
+
+ // Download archive + checksum + feature-support.md into a scratch dir
+ const work = fs.mkdtempSync(path.join(os.tmpdir(), 'veed-engine-'));
+ try {
+ try {
+ await download(`${base}/${ARCHIVE}`, path.join(work, ARCHIVE), 120_000);
+ await download(`${base}/${ARCHIVE}.sha256`, path.join(work, `${ARCHIVE}.sha256`), 30_000);
+ } catch (error) {
+ die(`download failed for ${tag}: ${(error as Error).message}`);
+ }
+ // feature-support.md is auxiliary (the support matrix) — don't abort the install if a release omits it.
+ await download(`${base}/feature-support.md`, path.join(work, 'feature-support.md'), 30_000)
+ .catch(() => say(`note — no feature-support.md asset on ${tag}; skipping it.`));
+ // The binary is licensed separately from this package (PolyForm Shield, not Apache-2.0) and the archive
+ // does not carry its terms, so fetch them from the release tag and install them next to the binary —
+ // whoever ends up with the engine should also end up with its license. Repo file, not a release asset.
+ await download(`https://raw.githubusercontent.com/${REPO}/${tag}/LICENSE-binary.md`, path.join(work, 'LICENSE-binary.md'), 30_000)
+ .catch(() => say(`note — could not fetch the engine license for ${tag}; it is at https://github.com/${REPO}/blob/main/LICENSE-binary.md`));
+
+ // Verify the checksum (the sidecar is ` `)
+ say('verifying sha256…');
+ const expected = fs.readFileSync(path.join(work, `${ARCHIVE}.sha256`), 'utf8').trim().split(/\s+/)[0]?.toLowerCase();
+ const actual = createHash('sha256').update(fs.readFileSync(path.join(work, ARCHIVE))).digest('hex');
+ if (!expected || expected !== actual) die(`sha256 mismatch for ${ARCHIVE}: expected ${expected ?? '(none)'}, got ${actual}`);
+
+ // Extract into a clean engine dir (replace any prior install atomically-ish), then rename the
+ // binary from its upstream name to the local one. System tar is bsdtar on macOS and Windows 10+,
+ // which auto-detects both gzip and zip. On Windows pin the System32 binary: under Git Bash the
+ // PATH resolves MSYS tar (GNU, no zip support) ahead of it.
+ const tarBin = (() => {
+ if (process.platform !== 'win32') return 'tar';
+ const sys = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe');
+ return fs.existsSync(sys) ? sys : 'tar';
+ })();
+ fs.rmSync(DEST, { recursive: true, force: true });
+ fs.mkdirSync(DEST, { recursive: true });
+ const tar = spawnSync(tarBin, ['-xf', path.join(work, ARCHIVE), '-C', DEST], { stdio: 'inherit' });
+ if (tar.error && (tar.error as NodeJS.ErrnoException).code === 'ENOENT') die('system tar is required to extract the engine archive (it ships with macOS and Windows 10+).');
+ if (tar.status !== 0) die(`extraction failed for ${ARCHIVE}.`);
+ fs.renameSync(path.join(DEST, UPSTREAM_BIN), path.join(DEST, LOCAL_BIN));
+ for (const extra of ['feature-support.md', 'LICENSE-binary.md']) {
+ // copy, not rename: the scratch dir can sit on another volume than the app-data dir
+ if (fs.existsSync(path.join(work, extra))) fs.copyFileSync(path.join(work, extra), path.join(DEST, extra));
+ }
+ } finally {
+ fs.rmSync(work, { recursive: true, force: true });
+ }
+
+ // Verify the binary actually runs (catches a wrong-arch download or an unexpected archive layout)
+ const bin = path.join(engineDir(), engineBinaryName());
+ const { banner, failure } = probeVersion(bin);
+ if (!banner) die(`ERROR — installed ${bin} but it did not run: ${failure}`);
+ say(`installed ${banner}`);
+ say(`VEED_ENGINE_BIN → ${bin}`);
+}
diff --git a/cli/src/commands/install-ffmpeg.ts b/cli/src/commands/install-ffmpeg.ts
new file mode 100644
index 0000000..bacdc6a
--- /dev/null
+++ b/cli/src/commands/install-ffmpeg.ts
@@ -0,0 +1,167 @@
+// Install FFmpeg for machines where the global install needs rights the user does not have.
+// Checks for a working install first (env override, then PATH, then a previous app-data install)
+// and only downloads when nothing works. Downloads a static build plus its .sha256, verifies the
+// checksum, and extracts ffmpeg/ffprobe into the app-data dir — never a working directory, which
+// a plugin host may not have.
+//
+// WINDOWS ONLY for the download, deliberately: macOS already has a no-admin route in
+// `brew install ffmpeg`, so a missing install points there rather than putting a second binary on disk.
+//
+// Usage:
+// npx @veedstudio/openedit-cli install-ffmpeg # install if nothing works already
+// npx @veedstudio/openedit-cli install-ffmpeg --check # report what is installed; write nothing
+// npx @veedstudio/openedit-cli install-ffmpeg --force # install/upgrade the app-data copy regardless
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ffmpegDir } from '../config.ts';
+import { FFMPEG_PROBE, findOnPath, installHint, probeVersion } from '../platform.ts';
+
+// Gyan's builds are the ones the FFmpeg project itself links for Windows.
+const BASE = 'https://www.gyan.dev/ffmpeg/builds';
+const ARCHIVE = 'ffmpeg-release-essentials.zip';
+
+const say = (msg: string) => console.log(`install-ffmpeg: ${msg}`);
+// Throws rather than exiting, so the caller's finally still removes the ~100 MB scratch dir.
+class InstallError extends Error {}
+const die = (msg: string): never => {
+ throw new InstallError(msg);
+};
+
+const exeName = (name: string) => (process.platform === 'win32' ? `${name}.exe` : name);
+const appDataBin = () => path.join(ffmpegDir(), 'bin');
+const appDataInstalled = () => ['ffmpeg', 'ffprobe'].every((n) => fs.existsSync(path.join(appDataBin(), exeName(n))));
+
+const versionBanner = (bin: string): string => probeVersion(bin, FFMPEG_PROBE).banner;
+
+// Where a run of the pipeline would actually find ffmpeg: the same order config.ts resolves in.
+const existing = (): { where: string; bin: string } | null => {
+ const env = process.env.VEED_ENGINE_FFMPEG;
+ if (env && versionBanner(env)) return { where: 'VEED_ENGINE_FFMPEG', bin: env };
+ if (appDataInstalled()) return { where: 'app-data install', bin: path.join(appDataBin(), exeName('ffmpeg')) };
+ const onPath = findOnPath('ffmpeg');
+ if (onPath && findOnPath('ffprobe')) return { where: 'PATH', bin: onPath };
+ return null;
+};
+
+const fetchOk = async (url: string, timeoutMs: number) => {
+ const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), redirect: 'follow' });
+ if (!res.ok) throw new Error(`HTTP ${res.status} for ${url}`);
+ return res;
+};
+
+async function install(): Promise {
+ const DEST = ffmpegDir();
+ const version = await fetchOk(`${BASE}/release-version`, 30_000)
+ .then((r) => r.text())
+ .then((t) => t.trim())
+ .catch(() => '');
+ say(`installing FFmpeg ${version || '(current release)'} → ${DEST}`);
+
+ const work = fs.mkdtempSync(path.join(os.tmpdir(), 'open-edit-ffmpeg-'));
+ const staged = `${DEST}.new`;
+ try {
+ const zip = path.join(work, ARCHIVE);
+ try {
+ const res = await fetchOk(`${BASE}/${ARCHIVE}`, 600_000);
+ fs.writeFileSync(zip, Buffer.from(await res.arrayBuffer()));
+ } catch (error) {
+ die(`download failed: ${(error as Error).message}`);
+ }
+
+ // The published sidecar tracks the same rolling archive, so a mismatch means the release rotated
+ // mid-download (or the bytes are wrong); either way, refuse rather than install unverified.
+ say('verifying sha256…');
+ const expected = await fetchOk(`${BASE}/${ARCHIVE}.sha256`, 30_000)
+ .then((r) => r.text())
+ .then((t) => t.trim().split(/\s+/)[0]?.toLowerCase())
+ .catch(() => '');
+ if (!expected) die('could not fetch the published sha256; refusing to install unverified bytes.');
+ const actual = createHash('sha256').update(fs.readFileSync(zip)).digest('hex');
+ if (expected !== actual) die(`sha256 mismatch: expected ${expected}, got ${actual}. Re-run to pick up the current release.`);
+
+ // System tar is bsdtar on Windows 10+, which reads zip. Under Git Bash the PATH resolves MSYS tar
+ // (GNU, no zip support) first, so pin the System32 copy.
+ const sys = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'tar.exe');
+ const tarBin = fs.existsSync(sys) ? sys : 'tar';
+ const unpacked = path.join(work, 'x');
+ fs.mkdirSync(unpacked, { recursive: true });
+ const tar = spawnSync(tarBin, ['-xf', zip, '-C', unpacked], { stdio: 'inherit' });
+ if ((tar.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT') die('system tar is required to extract the archive (it ships with Windows 10+).');
+ if (tar.status !== 0) die('extraction failed.');
+
+ // The archive nests everything under ffmpeg--essentials_build/; flatten so the layout
+ // stays stable across releases and config.ts can hardcode one path.
+ const top = fs.readdirSync(unpacked).map((d) => path.join(unpacked, d)).find((d) => fs.statSync(d).isDirectory());
+ const srcBin = top && path.join(top, 'bin');
+ if (!srcBin || !fs.existsSync(srcBin)) die('unexpected archive layout: no bin/ directory inside.');
+
+ // Build the replacement completely BEFORE touching the existing install: a half-removed dir
+ // would leave the machine with no FFmpeg at all, having had a working one a moment earlier.
+ fs.rmSync(staged, { recursive: true, force: true });
+ fs.mkdirSync(path.join(staged, 'bin'), { recursive: true });
+ for (const file of fs.readdirSync(srcBin as string)) fs.copyFileSync(path.join(srcBin as string, file), path.join(staged, 'bin', file));
+ for (const extra of ['LICENSE', 'README.txt']) {
+ const from = top && path.join(top, extra);
+ if (from && fs.existsSync(from)) fs.copyFileSync(from, path.join(staged, extra));
+ }
+
+ // Swap. Windows refuses to rename a directory holding a running binary, so an upgrade attempted
+ // while a render is using ffmpeg.exe fails here — with the previous install still intact.
+ const previous = `${DEST}.old`;
+ fs.rmSync(previous, { recursive: true, force: true });
+ try {
+ fs.mkdirSync(path.dirname(DEST), { recursive: true });
+ if (fs.existsSync(DEST)) fs.renameSync(DEST, previous);
+ fs.renameSync(staged, DEST);
+ } catch (error) {
+ if (!fs.existsSync(DEST) && fs.existsSync(previous)) fs.renameSync(previous, DEST); // put it back
+ die(`could not replace ${DEST}: ${(error as Error).message}. Close anything using ffmpeg.exe and re-run.`);
+ }
+ fs.rmSync(previous, { recursive: true, force: true });
+ } finally {
+ fs.rmSync(work, { recursive: true, force: true });
+ fs.rmSync(staged, { recursive: true, force: true });
+ }
+
+ if (!appDataInstalled()) die(`installed but ${appDataBin()} is missing ffmpeg/ffprobe.`);
+ const bin = path.join(appDataBin(), exeName('ffmpeg'));
+ const { banner, failure } = probeVersion(bin, FFMPEG_PROBE);
+ if (!banner) die(`installed ${bin} but it did not run: ${failure}`);
+ say(`installed ${banner}`);
+ say('every command finds it automatically; no env vars needed');
+}
+
+export async function installFfmpeg(args: string[]): Promise {
+ try {
+ if (args.includes('--check')) {
+ const found = existing();
+ if (!found) {
+ say(`not installed (no env override, nothing on PATH, nothing in ${appDataBin()})`);
+ return 1;
+ }
+ say(`installed via ${found.where} — ${versionBanner(found.bin) || 'present but not runnable'}`);
+ say(`→ ${found.bin}`);
+ return 0;
+ }
+
+ if (!args.includes('--force')) {
+ const found = existing();
+ if (found) {
+ say(`already installed via ${found.where} — ${found.bin}; nothing to do (--force reinstalls the app-data copy)`);
+ return 0;
+ }
+ }
+
+ if (process.platform !== 'win32') {
+ die(`the download route covers Windows only; run \`${installHint('ffmpeg')}\`, which needs no admin rights either.`);
+ }
+ await install();
+ return 0;
+ } catch (error) {
+ console.error(`install-ffmpeg: ${error instanceof InstallError ? error.message : ((error as Error).stack ?? error)}`);
+ return 1;
+ }
+}
diff --git a/cli/src/commands/install-whisperx.ts b/cli/src/commands/install-whisperx.ts
new file mode 100644
index 0000000..839e90b
--- /dev/null
+++ b/cli/src/commands/install-whisperx.ts
@@ -0,0 +1,124 @@
+// Install WhisperX, the local and free transcription provider (the transcribe command). NOT run as a
+// side effect of anything: the orchestrator asks the user first, because this pulls in PyTorch and the
+// first transcription then downloads model weights — around 2 GB of disk for the fastest tier, more
+// for medium.
+//
+// Usage:
+// npx @veedstudio/openedit-cli install-whisperx # install (or report an existing install)
+// npx @veedstudio/openedit-cli install-whisperx 3.4.3 # pin a version
+//
+// Removing it: `uv tool uninstall whisperx` (or `pipx uninstall whisperx`) takes out the tool and its
+// dependencies. Downloaded weights live on in ~/.cache/huggingface and ~/.cache/torch, which other tools
+// share — prune those per model directory, never wholesale.
+//
+// Installs into an isolated tool environment — uv first, pipx second — which uv/pipx manage in their
+// own per-user location, so nothing here depends on a working directory. It deliberately never runs
+// `pip install` against the system Python: on a packaged or system interpreter that is either blocked
+// outright (PEP 668) or, worse, succeeds and contaminates the environment.
+import { spawnSync, type SpawnSyncOptions } from 'node:child_process';
+import fs from 'node:fs';
+import { findOnPath, installHint, isCmdShim, whisperxSupported } from '../platform.ts';
+
+const say = (msg: string) => console.log(`install-whisperx: ${msg}`);
+const warn = (msg: string) => console.error(`install-whisperx: ${msg}`);
+
+export async function installWhisperx(args: string[]): Promise {
+ const version = args[0] ?? '';
+ const spec = `whisperx${version ? `==${version}` : ''}`;
+
+ // The interpreter is pinned because on Python 3.14 the resolver produces an install whose
+ // `whisperx --help` works but whose first real transcription dies importing pyannote.audio, since
+ // torchaudio 2.9 removed list_audio_backends(). 3.12 resolves a working set.
+ const python = 'OPEN_EDIT_WHISPERX_PYTHON' in process.env ? process.env.OPEN_EDIT_WHISPERX_PYTHON! : '3.12';
+
+ // Platform guard — matching the rest of the runtime. On both supported platforms CTranslate2 defaults
+ // to CPU here; a CUDA-capable box can override the device via the transcribe command's env knobs.
+ if (!whisperxSupported()) {
+ warn(`unsupported platform ${process.platform}/${process.arch} — this runtime supports macOS arm64 and Windows x64.`);
+ return 1;
+ }
+
+ const which = (cmd: string) => findOnPath(cmd);
+ // pipx installs as a .cmd shim on some Windows setups; Node refuses to exec those directly.
+ const run = (cmd: string, runArgs: string[], opts: SpawnSyncOptions = {}) => {
+ const resolved = which(cmd) ?? cmd;
+ if (isCmdShim(resolved)) {
+ const line = [resolved, ...runArgs].map((a) => `"${a}"`).join(' ');
+ return spawnSync('cmd.exe', ['/d', '/s', '/c', `"${line}"`], { stdio: 'inherit', ...opts, windowsVerbatimArguments: true });
+ }
+ return spawnSync(resolved, runArgs, { stdio: 'inherit', ...opts });
+ };
+
+ const existing = which('whisperx');
+ if (existing) {
+ say(`whisperx is already installed at ${existing}`);
+ return 0;
+ }
+
+ if (which('uv')) {
+ say(`installing ${spec} with uv on Python ${python} (isolated tool environment)`);
+ if (run('uv', ['tool', 'install', '--python', python, spec]).status !== 0) return 1;
+ } else if (which('pipx')) {
+ say(`installing ${spec} with pipx on Python ${python} (isolated tool environment)`);
+ if (run('pipx', ['install', '--python', `python${python}`, spec]).status !== 0
+ && run('pipx', ['install', spec]).status !== 0) return 1;
+ } else {
+ console.error(`install-whisperx: neither uv nor pipx is available, and this command will not install into the system
+Python. Install one of them first, then re-run:
+
+ ${installHint('uv')} # recommended
+ ${installHint('pipx')}
+
+Or choose VEED transcription instead, which needs no local install.`);
+ return 1;
+ }
+
+ // An installer that exits 0 without a working binary is the failure mode worth catching here: a half
+ // state would otherwise be discovered mid-render.
+ const installed = which('whisperx');
+ if (!installed) {
+ warn('the install reported success but whisperx is not on PATH.');
+ warn('If uv or pipx installed it elsewhere, add its bin dir to PATH or set WHISPERX_BIN.');
+ return 1;
+ }
+ if (spawnSync(installed, ['--help'], { stdio: 'ignore' }).status !== 0) {
+ warn('whisperx is on PATH but does not run (--help failed).');
+ return 1;
+ }
+
+ // --help alone is not proof: it parses arguments before importing the alignment stack, so a broken
+ // dependency set passes it and fails on the first real transcription instead. Import the package with
+ // the interpreter from the installed script's own shebang, which works for uv and pipx alike. On
+ // Windows the entry point is an .exe launcher with no shebang, so the check is skipped there.
+ let wxPython = '';
+ if (process.platform !== 'win32') {
+ try {
+ const shebang = fs.readFileSync(installed, 'utf8').split('\n', 1)[0] ?? '';
+ if (shebang.startsWith('#!')) wxPython = shebang.slice(2).trim().split(/\s+/)[0] ?? '';
+ } catch {
+ wxPython = '';
+ }
+ }
+ let interpreterUsable = false;
+ if (wxPython) {
+ try {
+ fs.accessSync(wxPython, fs.constants.X_OK);
+ interpreterUsable = true;
+ } catch {
+ interpreterUsable = false;
+ }
+ }
+ if (interpreterUsable) {
+ if (spawnSync(wxPython, ['-c', 'import whisperx'], { stdio: 'ignore' }).status !== 0) {
+ warn('whisperx installed but cannot be imported — its dependency set is broken.');
+ warn('Retry pinned to another interpreter, e.g. OPEN_EDIT_WHISPERX_PYTHON=3.11 npx @veedstudio/openedit-cli install-whisperx');
+ return 1;
+ }
+ } else {
+ warn('note — could not locate the interpreter to verify the import; skipping that check.');
+ }
+
+ say(`ready — ${installed}`);
+ console.log('The first transcription downloads model weights, and alignment runs on CPU; expect it to be slow.');
+ return 0;
+}
diff --git a/cli/src/commands/lint.ts b/cli/src/commands/lint.ts
new file mode 100644
index 0000000..f35e9bc
--- /dev/null
+++ b/cli/src/commands/lint.ts
@@ -0,0 +1,34 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseFlags } from "../args.ts";
+import { contentRoot } from "../config.ts";
+import { loadLintGate, type RenderFacts } from "../gates/content-gates.ts";
+
+// The mechanical engine-limit gate, run against the content tree this CLI ships with. The rules are
+// content — they change with the substrate they police — so they are loaded, never reimplemented here.
+export async function lint(argv: string[]): Promise {
+ const { values, positionals } = parseFlags({ args: argv, options: { json: { type: "boolean" } }, allowPositionals: true });
+ const [file] = positionals;
+ if (!file) {
+ console.error("usage: openedit lint [--json]");
+ return 2;
+ }
+
+ // The manifest sits next to the document; without it the timing rules cannot run.
+ let render: RenderFacts | undefined;
+ try {
+ const manifest = join(dirname(file), "manifest.json");
+ if (existsSync(manifest)) render = JSON.parse(readFileSync(manifest, "utf8")).render;
+ } catch { /* a malformed manifest is the renderer's error to report, not this gate's */ }
+
+ const lintTemplate = await loadLintGate(contentRoot());
+ const findings = lintTemplate(readFileSync(file, "utf8"), render);
+ const errors = findings.filter((f) => f.severity === "error").length;
+ if (values.json) {
+ console.log(JSON.stringify(findings, null, 2));
+ } else {
+ for (const f of findings) console.log(`${f.severity.toUpperCase()}[${f.rule}] ${f.message}`);
+ console.log(errors ? `lint: ${errors} error(s), ${findings.length - errors} warning(s)` : `lint: clean (${findings.length} warning(s))`);
+ }
+ return errors ? 1 : 0;
+}
diff --git a/cli/src/commands/lipsync.ts b/cli/src/commands/lipsync.ts
new file mode 100644
index 0000000..04f8483
--- /dev/null
+++ b/cli/src/commands/lipsync.ts
@@ -0,0 +1,132 @@
+// Lipsync (video + new audio -> re-lipsynced video), via the public fal model veed/lipsync/v2 — the
+// user's own key, the same rail every other generated asset in this repo reaches fal through
+// (cli/src/providers/fal.ts). There is no live VEED route for this model to fall back to, unlike
+// background-removal.ts's default mode. VEED login still hosts the local video + audio (so fal has URLs to fetch); the
+// GENERATION call bills fal, not VEED.
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { type VeedHttp } from '../veed/api.ts';
+import { uploadLocalAsset, readVideoBytes } from '../veed/asset-upload.ts';
+import { parseFlags } from '../args.ts';
+import { resolveVideoArg, runKeyOf } from '../resolve-video.ts';
+import { runsDir } from '../config.ts';
+import { submitOnce, await_, download, firstUrl, falKey, completeJob, type Http as FalHttp } from '../providers/fal.ts';
+import { refreshingHttp } from '../veed/http.ts';
+import { resolveVeedToken } from '../veed/resolve-token.ts';
+
+export const FAL_LIPSYNC_V2_MODEL = 'veed/lipsync/v2';
+
+// fal's own listed rate for this model (fal.ai/models/veed/lipsync/v2, fetched 2026-08-19) — relayed
+// as-is, not a VEED-derived constant, and not turned into a per-run dollar estimate (fal prices by
+// OUTPUT seconds, not known until the job finishes).
+export const FAL_LIPSYNC_V2_PRICE_PER_SECOND = 0.07;
+
+export interface LipsyncDeps {
+ http: VeedHttp;
+ readVideoBytes: (videoPath: string) => Promise<{ bytes: Uint8Array; mimeType: string; extension: string }>;
+ readAudioBytes: (audioPath: string) => Promise<{ bytes: Uint8Array; mimeType: string; extension: string }>;
+ sleep?: (ms: number) => Promise;
+ log?: (message: string) => void;
+ falHttp?: FalHttp;
+ runDir?: string;
+ // Overrides fal.ts's await_() default (15 minutes) — tests use a short one rather than waiting out
+ // the real deadline.
+ falTimeoutMs?: number;
+}
+
+export interface LipsyncOptions {
+ videoPath: string;
+ audioPath: string;
+ outPath: string;
+ falKey?: string;
+}
+
+export async function runLipsync(deps: LipsyncDeps, opts: LipsyncOptions): Promise {
+ const { http } = deps;
+ const sleep = deps.sleep ?? ((ms: number) => new Promise((r) => setTimeout(r, ms)));
+ const log = deps.log ?? (() => {});
+
+ // No per-run dollar estimate: fal prices by OUTPUT seconds, not known until the job finishes.
+ log(`[fal] ${FAL_LIPSYNC_V2_MODEL} bills YOUR OWN fal account, not any VEED workspace. fal's listed rate: $${FAL_LIPSYNC_V2_PRICE_PER_SECOND} per second of output video.`);
+
+ const [video, audio] = await Promise.all([deps.readVideoBytes(opts.videoPath), deps.readAudioBytes(opts.audioPath)]);
+
+ // Unscoped: fal's own key authorizes the paid call, not a VEED project permission — VEED hosts the
+ // files so fal has URLs to fetch, and that hosting step is not billed either way. Concurrent: the two
+ // uploads are independent, so there is no reason to pay for one's poll loop before starting the other.
+ const [uploadedVideo, uploadedAudio] = await Promise.all([
+ uploadLocalAsset({ http, sleep }, { bytes: video.bytes, mimeType: video.mimeType, extension: video.extension, assetType: 'VIDEO', group: 'srcVideo' }),
+ uploadLocalAsset({ http, sleep }, { bytes: audio.bytes, mimeType: audio.mimeType, extension: audio.extension, assetType: 'AUDIO', group: 'srcVideo' }),
+ ]);
+ log(`uploaded video ${uploadedVideo.assetId} and audio ${uploadedAudio.assetId} for hosting only`);
+
+ const key = opts.falKey ?? falKey();
+ const runDir = deps.runDir ?? join(runsDir(), runKeyOf(opts.videoPath));
+ const input: Record = { video_url: uploadedVideo.cdnUrl, audio_url: uploadedAudio.cdnUrl };
+ const { job, reused } = await submitOnce(runDir, FAL_LIPSYNC_V2_MODEL, input, { key, http: deps.falHttp, sleep });
+ if (reused) log(`[fal] this exact request is already in the ledger as ${job.requestId} — resuming it rather than buying it again`);
+ const result = await await_(job, { key, http: deps.falHttp, sleep, timeoutMs: deps.falTimeoutMs });
+ const url = firstUrl(result.payload);
+ if (!url) throw new Error(`fal returned no url for ${job.requestId}`);
+ await download(url, opts.outPath, deps.falHttp);
+ completeJob(runDir, FAL_LIPSYNC_V2_MODEL, input);
+ log(`wrote ${opts.outPath}`);
+}
+
+async function readAudioBytes(audioPath: string): Promise<{ bytes: Uint8Array; mimeType: string; extension: string }> {
+ const bytes = await readFile(audioPath);
+ const ext = (extname(audioPath).slice(1) || 'mp3').toLowerCase();
+ const mimeType = ext === 'wav' ? 'audio/wav' : ext === 'm4a' ? 'audio/mp4' : 'audio/mpeg';
+ return { bytes, mimeType, extension: ext };
+}
+
+function noTokenHelp(): void {
+ console.error(
+ [
+ 'No VEED login found. Log in with VEED:',
+ '',
+ ' npx @veedstudio/openedit-cli login',
+ '',
+ 'then re-run this command. The login only hosts the local video/audio; lipsync itself bills fal.',
+ ].join('\n'),
+ );
+}
+
+export async function lipsync(argv: string[]): Promise {
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: { out: { type: 'string' } },
+ allowPositionals: true,
+ });
+ const [videoArg, audioArg] = positionals;
+ if (!videoArg || !audioArg) {
+ console.error('usage: npx @veedstudio/openedit-cli lipsync [--out ]');
+ return 1;
+ }
+ const videoPath = resolveVideoArg(videoArg);
+ const audioPath = resolveVideoArg(audioArg);
+ const missing = [videoPath, audioPath].filter((p) => !existsSync(p));
+ if (missing.length > 0) {
+ console.error(missing.map((p) => `not found: ${p}`).join('\n'));
+ return 1;
+ }
+ const outPath = values.out ?? join(runsDir(), runKeyOf(videoPath), 'lipsync.mp4');
+
+ const token = await resolveVeedToken();
+ if (!token) {
+ noTokenHelp();
+ return 1;
+ }
+ const http = refreshingHttp(async () => {
+ const t = await resolveVeedToken();
+ if (!t) throw new Error('VEED login expired mid-run — re-run: npx @veedstudio/openedit-cli login');
+ return t;
+ });
+
+ await runLipsync(
+ { http, readVideoBytes, readAudioBytes, log: (m) => console.log(`[lipsync] ${m}`) },
+ { videoPath, audioPath, outPath },
+ );
+ return 0;
+}
diff --git a/cli/src/commands/login.ts b/cli/src/commands/login.ts
new file mode 100644
index 0000000..88a4e59
--- /dev/null
+++ b/cli/src/commands/login.ts
@@ -0,0 +1,187 @@
+// Interactive "log in with VEED": opens a browser, catches the redirect on a
+// localhost loopback, exchanges the code (PKCE) for tokens, and stores them in
+// the CLI state dir for the other commands to use.
+//
+// Run: openedit login [--manual]
+// Env: VEED_ORIGIN optionally overrides the default https://www.veed.io origin.
+import { openUrl } from '../open-url.ts';
+import { createServer } from 'node:http';
+import { createInterface } from 'node:readline/promises';
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { clientPath, stateDir } from '../config.ts';
+import { VEED_ORIGIN as ORIGIN } from '../veed/api.ts';
+import { loginSuccessPage } from '../veed/login-page.ts';
+import { buildAuthorizeUrl, makePkcePair, OAUTH_SCOPE } from '../veed/oauth.ts';
+import { DEFAULT_TOKEN_PATH as TOKEN_PATH, writeTokenFileAtomically } from '../veed/token-store.ts';
+
+const CLIENT_PATH = clientPath();
+const LOOPBACK_PORT = 8977;
+const REDIRECT_URI = `http://127.0.0.1:${LOOPBACK_PORT}/callback`;
+
+interface Discovery {
+ authorization_endpoint: string;
+ token_endpoint: string;
+ registration_endpoint: string;
+}
+
+async function discover(): Promise {
+ const res = await fetch(`${ORIGIN}/.well-known/oauth-authorization-server`);
+ if (!res.ok) throw new Error(`discovery failed: ${res.status}`);
+ return (await res.json()) as Discovery;
+}
+
+// Register this client once (Dynamic Client Registration) and cache the id,
+// keyed by origin: a client registered on prod is meaningless on dev.
+async function getClientId(discovery: Discovery): Promise {
+ try {
+ const cached = JSON.parse(await readFile(CLIENT_PATH, 'utf8')) as {
+ clientId?: string;
+ origin?: string;
+ };
+ if (cached.clientId && cached.origin === ORIGIN) return cached.clientId;
+ } catch {
+ /* not registered yet */
+ }
+ const res = await fetch(discovery.registration_endpoint, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify({
+ client_name: 'open-editor (local)',
+ redirect_uris: [REDIRECT_URI],
+ grant_types: ['authorization_code', 'refresh_token'],
+ response_types: ['code'],
+ token_endpoint_auth_method: 'none',
+ scope: OAUTH_SCOPE,
+ }),
+ });
+ if (!res.ok) throw new Error(`client registration failed: ${res.status} ${(await res.text()).slice(0, 300)}`);
+ const reg = (await res.json()) as { client_id: string };
+ await writeFile(CLIENT_PATH, JSON.stringify({ clientId: reg.client_id, origin: ORIGIN }, null, 2));
+ return reg.client_id;
+}
+
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+// Serve one redirect: resolve with the auth code once VEED sends the user back.
+function catchRedirect(expectedState: string): Promise {
+ return new Promise((resolve, reject) => {
+ const timer = setTimeout(() => {
+ server.close();
+ reject(new Error('login timed out after 5 minutes; re-run openedit login'));
+ }, LOGIN_TIMEOUT_MS);
+ // Don't let the pending timer keep the process alive after a successful login.
+ timer.unref();
+ const server = createServer(async (req, res) => {
+ const url = new URL(req.url ?? '/', REDIRECT_URI);
+ if (url.pathname !== '/callback') {
+ res.writeHead(404).end();
+ return;
+ }
+ const code = url.searchParams.get('code');
+ const state = url.searchParams.get('state');
+ if (!code || state !== expectedState) {
+ res.writeHead(400, { 'content-type': 'text/plain' }).end('Login failed; return to the terminal.');
+ server.close();
+ reject(new Error('login redirect missing code or state mismatch'));
+ return;
+ }
+ res
+ .writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+ .end(await loginSuccessPage());
+ server.close();
+ resolve(code);
+ });
+ server.listen(LOOPBACK_PORT, '127.0.0.1');
+ server.on('error', reject);
+ });
+}
+
+// Manual mode: no browser + no loopback. Print the URL, take the redirect
+// pasted back (full localhost URL or the bare ?code=...). Lets an agent drive
+// the flow with its own browser, or a human log in on another device.
+async function readCodeFromStdin(expectedState: string): Promise {
+ console.log(
+ 'Open the URL above (any browser logged into VEED). It will redirect to a\n' +
+ 'localhost address that will not load — that is expected. Copy that final\n' +
+ 'redirected URL (or its code=...&state=... query) and paste it here:',
+ );
+ const rl = createInterface({ input: process.stdin, output: process.stdout });
+ const answer = (await rl.question('> ')).trim();
+ rl.close();
+ let code: string | null = null;
+ let state: string | null = expectedState;
+ try {
+ const u = new URL(answer);
+ code = u.searchParams.get('code');
+ state = u.searchParams.get('state');
+ } catch {
+ // Not a URL: read it as the redirect's query string, which must still carry the state. Taking a
+ // bare code and assuming the state would accept an authorization code from anyone who could get
+ // it pasted here — the one thing the state parameter exists to prevent.
+ const query = new URLSearchParams(answer.replace(/^[?#]/, ''));
+ code = query.get('code');
+ state = query.get('state');
+ }
+ if (!code || state !== expectedState) {
+ throw new Error('the pasted redirect must carry both code and state, and the state must match the one this login started');
+ }
+ return code;
+}
+
+export async function login(opts: { manual?: boolean } = {}): Promise {
+ // The atomic token write renames within this dir, so it must exist first.
+ await mkdir(stateDir(), { recursive: true });
+ const discovery = await discover();
+ const clientId = await getClientId(discovery);
+ const { verifier, challenge } = makePkcePair();
+ const state = randomBytes(16).toString('base64url');
+
+ const authorizeUrl = buildAuthorizeUrl({
+ authorizationEndpoint: discovery.authorization_endpoint,
+ clientId,
+ redirectUri: REDIRECT_URI,
+ challenge,
+ state,
+ });
+
+ // --manual (or VEED_LOGIN_MANUAL=1) is the no-reachable-browser fallback: print
+ // the URL, no browser auto-open, no loopback; complete via a pasted redirect.
+ const manual = opts.manual || process.env.VEED_LOGIN_MANUAL === '1';
+ console.log(`Log in with VEED:\n ${authorizeUrl}\n`);
+ let code: string;
+ if (manual) {
+ code = await readCodeFromStdin(state);
+ } else {
+ console.log('Opening your browser (pass --manual to paste the redirect instead)...');
+ openUrl(authorizeUrl);
+ code = await catchRedirect(state);
+ }
+ const res = await fetch(discovery.token_endpoint, {
+ method: 'POST',
+ headers: { 'content-type': 'application/x-www-form-urlencoded' },
+ body: new URLSearchParams({
+ grant_type: 'authorization_code',
+ code,
+ redirect_uri: REDIRECT_URI,
+ client_id: clientId,
+ code_verifier: verifier,
+ }),
+ });
+ if (!res.ok) throw new Error(`token exchange failed: ${res.status} ${(await res.text()).slice(0, 300)}`);
+ const token = (await res.json()) as {
+ access_token: string;
+ refresh_token?: string;
+ expires_in: number;
+ };
+
+ await writeTokenFileAtomically(TOKEN_PATH, {
+ accessToken: token.access_token,
+ refreshToken: token.refresh_token ?? null,
+ expiresAt: Date.now() + token.expires_in * 1000,
+ origin: ORIGIN,
+ clientId,
+ tokenEndpoint: discovery.token_endpoint,
+ });
+ console.log(`Logged in. Token stored at ${TOKEN_PATH}`);
+}
diff --git a/cli/src/commands/mix-audio.ts b/cli/src/commands/mix-audio.ts
new file mode 100644
index 0000000..0068e6b
--- /dev/null
+++ b/cli/src/commands/mix-audio.ts
@@ -0,0 +1,168 @@
+// One soundtrack out of many pieces.
+//
+// `mux-audio.ts` restores the SOURCE audio of a clip onto its render, which is the whole audio story a
+// captioned run has. A film is not that: a 12-minute documentary carried 66 narration takes, 11 sound
+// effects and 6 music cues, and nothing in this repository could put them together — no `amix`, no
+// `adelay`, no concat anywhere. So the run hand-wrote its own, once, and threw it away.
+//
+// This takes a spec and produces the mixed track. Every piece states WHERE it starts and how loud it
+// sits; music that has to live under narration says so and is ducked by the narration itself rather
+// than by a gain somebody guessed at.
+//
+// openedit mix-audio [--spec audio/mix.json] [--out audio/mix.m4a]
+import { execFileSync } from 'node:child_process';
+import { readFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { parseFlags } from '../args.ts';
+import { FFMPEG } from '../config.ts';
+
+export interface Track {
+ /** Relative to the run dir, or absolute. */
+ path: string;
+ /** When it starts, in seconds on the film's timeline. */
+ atSec: number;
+ /** Level in dB. 0 leaves it alone; negative is quieter. */
+ gainDb?: number;
+ fadeInSec?: number;
+ fadeOutSec?: number;
+ /** Where this piece sits. `voice` is the bus everything else can duck under. */
+ role?: 'voice' | 'music' | 'sfx' | 'ambience';
+ /** Music under narration. Ducked by the voice bus, not by a guessed gain. */
+ duck?: boolean;
+}
+
+export interface MixSpec {
+ /** The film's length. Anything past it is trimmed, so one long cue cannot extend the deliverable. */
+ durationSec: number;
+ tracks: Track[];
+}
+
+function label(i: number): string {
+ return `a${i}`;
+}
+
+/**
+ * The filtergraph, built as a string so it can be read and tested without running ffmpeg.
+ *
+ * `adelay` needs a value per channel, `amix` with `normalize=0` keeps levels where the spec put them
+ * (its default divides every input by the input count, which is why a mix built without it comes out
+ * mysteriously quiet), and `apad` plus `atrim` fix the total length so a short mix does not shorten
+ * the film.
+ */
+export function filtergraph(spec: MixSpec): { graph: string; out: string } {
+ if (!spec.tracks.length) throw new Error('mix-audio: the spec has no tracks');
+ if (!Number.isFinite(spec.durationSec) || spec.durationSec <= 0) {
+ throw new Error(`mix-audio: durationSec must be a positive number, got ${spec.durationSec}`);
+ }
+ const parts: string[] = [];
+ const voices: string[] = [];
+ const ducked: string[] = [];
+ const plain: string[] = [];
+
+ spec.tracks.forEach((t, i) => {
+ if (!Number.isFinite(t.atSec) || t.atSec < 0) {
+ throw new Error(`mix-audio: "${t.path}" starts at ${t.atSec}s — a start must be a non-negative number`);
+ }
+ const ms = Math.round(t.atSec * 1000);
+ const chain = [`[${i}:a]aresample=48000`, `adelay=${ms}|${ms}`];
+ if (t.gainDb) chain.push(`volume=${t.gainDb}dB`);
+ if (t.fadeInSec) chain.push(`afade=t=in:st=${t.atSec}:d=${t.fadeInSec}`);
+ if (t.fadeOutSec) {
+ // Measured from the END of the film, because a cue's own length is not knowable from the spec.
+ const at = Math.max(0, spec.durationSec - t.fadeOutSec);
+ chain.push(`afade=t=out:st=${at}:d=${t.fadeOutSec}`);
+ }
+ const l = label(i);
+ parts.push(`${chain.join(',')}[${l}]`);
+ if (t.role === 'voice') voices.push(l);
+ else if (t.duck) ducked.push(l);
+ else plain.push(l);
+ });
+
+ if (ducked.length && !voices.length) {
+ throw new Error('mix-audio: a track asks to be ducked, but no track is marked role "voice" to duck it');
+ }
+
+ let voiceBus = '';
+ if (voices.length) {
+ voiceBus = 'vox';
+ parts.push(voices.length === 1
+ ? `[${voices[0]}]anull[${voiceBus}]`
+ : `${voices.map((l) => `[${l}]`).join('')}amix=inputs=${voices.length}:normalize=0[${voiceBus}]`);
+ }
+
+ const beds: string[] = [];
+ if (ducked.length) {
+ // The narration itself opens the gap. A threshold high enough to ignore room tone, a slow release
+ // so the bed does not pump between words.
+ //
+ // THE THRESHOLD IS ABSOLUTE, so how deep the bed dips is set by how loud the VOICE is, not by the
+ // gap between them. Measured against the same bed: a voice at -3dB pulls the mix down 1.4dB, at
+ // -12dB 0.8dB, and at -24dB not at all — below the threshold nothing ducks. Level the narration
+ // before mixing, or set its gain so it actually crosses; a quiet take silently gets no ducking.
+ // The key is padded to the film's length. `sidechaincompress` ends its OUTPUT when the sidechain
+ // ends, so an unpadded key truncated the bed at the last word — measured at -91dB against -33dB
+ // for the same music one second later. Music dying when narration stops is the exact opposite of
+ // what ducking is for.
+ parts.push(`[${voiceBus}]asplit=2[vmix][vkeyraw]`);
+ parts.push(`[vkeyraw]apad=whole_dur=${spec.durationSec}[vkey]`);
+ const bed = ducked.length === 1 ? ducked[0] : 'beds';
+ if (ducked.length > 1) parts.push(`${ducked.map((l) => `[${l}]`).join('')}amix=inputs=${ducked.length}:normalize=0[beds]`);
+ parts.push(`[${bed}][vkey]sidechaincompress=threshold=0.03:ratio=8:attack=20:release=600[duckedbed]`);
+ beds.push('duckedbed', 'vmix');
+ } else if (voiceBus) {
+ beds.push(voiceBus);
+ }
+ beds.push(...plain);
+
+ // `apad` with no bound pads FOREVER, and `atrim` downstream does not always close the graph — a
+ // review's fifty-track stress spec ran ffmpeg for an hour without finishing. Pad to the film's own
+ // length instead, so the padding ends on its own and `atrim` only ever has to cut.
+ const out = 'mix';
+ const tail = `apad=whole_dur=${spec.durationSec},atrim=0:${spec.durationSec},asetpts=N/SR/TB[${out}]`;
+ parts.push(beds.length === 1
+ ? `[${beds[0]}]${tail}`
+ : `${beds.map((l) => `[${l}]`).join('')}amix=inputs=${beds.length}:normalize=0,${tail}`);
+
+ return { graph: parts.join(';'), out };
+}
+
+export function mix(runDir: string, specPath: string, outPath: string): string {
+ const spec = JSON.parse(readFileSync(specPath, 'utf8')) as MixSpec;
+ const resolve = (p: string) => (isAbsolute(p) ? p : join(runDir, p));
+ for (const t of spec.tracks) {
+ if (!existsSync(resolve(t.path))) throw new Error(`mix-audio: no such track — ${t.path}`);
+ }
+ const { graph, out } = filtergraph(spec);
+ const args = ['-y', '-hide_banner', '-loglevel', 'error'];
+ for (const t of spec.tracks) args.push('-i', resolve(t.path));
+ args.push('-filter_complex', graph, '-map', `[${out}]`, '-c:a', 'aac', '-b:a', '192k', outPath);
+ mkdirSync(dirname(outPath), { recursive: true });
+ execFileSync(FFMPEG, args);
+ return outPath;
+}
+
+export function mixAudio(argv: string[]): number {
+ const { values, positionals } = parseFlags({
+ args: argv,
+ options: { spec: { type: 'string' }, out: { type: 'string' }, 'print-graph': { type: 'boolean' } },
+ allowPositionals: true,
+ });
+ const [runDir] = positionals;
+ if (!runDir) {
+ console.error('usage: openedit mix-audio [--spec audio/mix.json] [--out audio/mix.m4a] [--print-graph]');
+ return 2;
+ }
+ const specPath = join(runDir, values.spec ?? 'audio/mix.json');
+ if (!existsSync(specPath)) {
+ console.error(`mix-audio: no spec at ${specPath} — it lists each track with its path, atSec, gainDb and role`);
+ return 2;
+ }
+ if (values['print-graph']) {
+ console.log(filtergraph(JSON.parse(readFileSync(specPath, 'utf8')) as MixSpec).graph);
+ return 0;
+ }
+ const out = mix(runDir, specPath, join(runDir, values.out ?? 'audio/mix.m4a'));
+ console.log(`mix-audio: ${out}`);
+ return 0;
+}
diff --git a/cli/src/commands/mux-audio.ts b/cli/src/commands/mux-audio.ts
new file mode 100644
index 0000000..92f95ca
--- /dev/null
+++ b/cli/src/commands/mux-audio.ts
@@ -0,0 +1,231 @@
+// MUX AUDIO — restore the soundtrack. veed-engine-cli renders video only; this muxes the original audio
+// onto the clean silent render, levelled to the delivery target. Deterministic; ffmpeg only, no sandbox exit needed.
+//
+// openedit mux-audio [--doc final] [--audio ] [--no-loudnorm]
+// Audio comes from --audio when given, else from /meta.json's source video. Muxes
+// //out.silent.mp4 -> out.mp4, where defaults to final.
+// VEED_ENGINE_FFMPEG ffmpeg (default: ffmpeg on PATH)
+import { execFileSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { FFMPEG, FFPROBE } from '../config.ts';
+import { hasAudioStream } from '../probe.ts';
+
+class MuxError extends Error {
+ constructor(msg: string, readonly code: number) { super(msg); }
+}
+const fail = (msg: string, code: number): never => { throw new MuxError(msg, code); };
+
+export function muxAudio(argv: string[]): number {
+ try {
+ run(argv);
+ return 0;
+ } catch (error) {
+ if (error instanceof MuxError) {
+ if (error.message) console.error(error.message);
+ return error.code;
+ }
+ throw error;
+ }
+}
+
+function run(argv: string[]): void {
+ const [dir, ...rest] = argv;
+ if (!dir) fail('usage: openedit mux-audio [--doc final] [--audio ] [--no-loudnorm]', 2);
+ // A film gates and delivers one chapter at a time, and its audio is a built mix rather than the
+ // source clip's track — hardcoding both was why the chain's own --doc flag stopped at the engine.
+ let doc = 'final';
+ let audio = '';
+ let normalise = true;
+ while (rest.length > 0) {
+ const flag = rest.shift();
+ switch (flag) {
+ case '--doc': doc = rest.shift() ?? fail('--doc needs a subdirectory', 2); break;
+ case '--audio': audio = rest.shift() ?? fail('--audio needs a file', 2); break;
+ case '--no-loudnorm': normalise = false; break;
+ default: fail(`mux-audio: unknown flag ${flag}`, 2);
+ }
+ }
+
+ const silent = join(dir!, doc, 'out.silent.mp4');
+ const outPath = join(dir!, doc, 'out.mp4');
+ if (!existsSync(silent)) fail(`mux: missing ${silent} (render first)`, 1);
+
+ // The audio is either a track that was BUILT for this run (a mix of narration, music and effects) or
+ // the source clip's own. Only the second needs meta.json — a run with no footage has none, and
+ // requiring it was why the footage-free path failed at its last gate.
+ let src: string;
+ if (audio) {
+ src = audio;
+ if (!existsSync(src)) fail(`mux: no audio at ${src}`, 1);
+ } else {
+ const metaPath = join(dir!, 'meta.json');
+ if (!existsSync(metaPath)) fail(`mux: no ${metaPath} and no --audio — say which track to lay on`, 2);
+ const videoPath = (JSON.parse(readFileSync(metaPath, 'utf8')) as { videoPath?: string }).videoPath ?? '';
+ if (!videoPath || !existsSync(videoPath)) fail(`mux: could not resolve source video from ${metaPath}`, 1);
+ src = videoPath;
+ }
+
+ const probe = (args: string[]) => {
+ try {
+ return execFileSync(FFPROBE, args, { encoding: 'utf8' }).trim();
+ } catch {
+ return '';
+ }
+ };
+
+ // -map 1:a:0? tolerates a source with no audio track (out.mp4 then == silent render).
+ // Write to a tmp name and rename: out.mp4 is watched live by the preview server, so its
+ // existence must mean completeness (a moov-less in-progress file plays as broken "done").
+ // +faststart keeps moov up front (the engine records it that way; default muxing would move it
+ // to the tail, making the deliverable start slower anywhere without Range support).
+ const tmp = join(dir!, doc, 'out.tmp.mp4');
+ // The PICTURE decides the length. `-shortest` let a built mix truncate the film — a 2s track over a
+ // 6s render wrote a 2s deliverable and exited 0, which destroys work without saying so.
+ const vdur = probe(['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=duration', '-of', 'csv=p=0', silent])
+ || probe(['-v', 'error', '-show_entries', 'format=duration', '-of', 'csv=p=0', silent]);
+ if (!vdur) fail(`mux: could not read the duration of ${silent}`, 1);
+
+ // Camera audio commonly lands several decibels under the delivery target and plays quieter than its
+ // neighbours in a feed; the track is re-encoded here anyway, so the correction costs one measurement
+ // pass. --no-loudnorm keeps the source level for one chapter of a longer piece, whose level belongs
+ // to the whole film.
+ const hasAudio = hasAudioStream(src);
+ // A source video with no track is a silent film and muxes as-is; a track the user NAMED with no
+ // audio in it is a mistake, and a silent deliverable that exits 0 would pass the whole gate chain.
+ if (audio && !hasAudio) fail(`mux: ${src} has no audio stream — nothing to lay on the render`, 1);
+ let loudness: Loudnorm;
+ if (!normalise) loudness = { mode: 'none', filter: null, why: 'not requested' };
+ else if (!hasAudio) loudness = { mode: 'none', filter: null, why: 'the source has no audio track — nothing to normalise' };
+ else loudness = loudnormFilter(src);
+ if (normalise && loudness.mode !== 'measured') {
+ console.log(`mux: loudness ${loudness.mode === 'dynamic' ? 'corrected dynamically' : 'left as recorded'} — ${loudness.why}`);
+ }
+
+ try {
+ execFileSync(FFMPEG, [
+ '-y', '-hide_banner', '-loglevel', 'error', '-i', silent, '-i', src,
+ '-map', '0:v:0', '-map', '1:a:0?', '-c:v', 'copy',
+ ...(loudness.filter ? ['-af', loudness.filter] : []),
+ // 48 kHz on every path: loudnorm works at 192 kHz and would otherwise hand the encoder 96 kHz,
+ // and a chapter muxed with --no-loudnorm must not differ in rate from its neighbours.
+ '-c:a', 'aac', '-ar', '48000', '-t', vdur, '-movflags', '+faststart', tmp,
+ ], { stdio: ['ignore', 'inherit', 'inherit'] });
+ } catch {
+ fail('', 1);
+ }
+ renameSync(tmp, outPath);
+ // Say which correction actually ran: a line that claims -14 LUFS after a fallback is a lie the
+ // deliverable cannot be checked against without re-measuring it.
+ const said: Record = {
+ measured: ` (normalised to ${LOUDNORM_I} LUFS)`,
+ dynamic: ' (dynamic loudness correction — see above)',
+ none: hasAudio ? '' : ' (no audio track in the source)',
+ };
+ console.log(`mux: wrote ${outPath}${said[loudness.mode]}`);
+}
+
+// The delivery target this pipeline aims at: -14 LUFS integrated, -1 dBTP true peak, 11 LU range.
+// It is the level the major social platforms have converged on for upload normalisation; a platform
+// that moves its own target moves these, so they are constants to revisit, not physical facts.
+export const LOUDNORM_I = -14;
+export const LOUDNORM_TP = -1;
+export const LOUDNORM_LRA = 11;
+
+const TARGET = `loudnorm=I=${LOUDNORM_I}:TP=${LOUDNORM_TP}:LRA=${LOUDNORM_LRA}`;
+
+/**
+ * `measured`: a linear gain computed from a measurement pass — the only mode that is a plain level
+ * change. `dynamic`: loudnorm's per-window normaliser, which pumps on speech, so it is a different
+ * processing decision and is named as one. `none`: nothing applied; `why` says what stopped it.
+ */
+export type Loudnorm =
+ | { mode: 'measured'; filter: string }
+ | { mode: 'dynamic'; filter: string; why: string }
+ | { mode: 'none'; filter: null; why: string };
+
+export interface LoudnormMeasurement {
+ input_i: number;
+ input_tp: number;
+ input_lra: number;
+ input_thresh: number;
+ target_offset: number;
+}
+
+/**
+ * The JSON summary loudnorm prints, out of the rest of ffmpeg's stderr. Anchored on the block's own
+ * first key: a warning printed after it that happens to contain a brace would otherwise shift a
+ * last-brace slice and lose the measurement. Null when there is no summary or it does not parse.
+ */
+export function parseLoudnormSummary(stderr: string): Record | null {
+ const anchor = stderr.lastIndexOf('"input_i"');
+ const open = anchor === -1 ? -1 : stderr.lastIndexOf('{', anchor);
+ const close = open === -1 ? -1 : stderr.indexOf('}', anchor);
+ if (open === -1 || close === -1) return null;
+ try {
+ return JSON.parse(stderr.slice(open, close + 1)) as Record;
+ } catch {
+ return null;
+ }
+}
+
+/**
+ * What loudnorm will actually do with a measurement, mirroring its own gate: the linear mode applies
+ * only when the gain that reaches the target keeps the true peak under the ceiling, the loudness range
+ * is within the limit, and neither the level nor the range measured as exactly zero (a constant level
+ * reports a range of 0 LU);
+ * otherwise ffmpeg runs its dynamic normaliser without saying so, and the report has to say it instead.
+ * (An input under three seconds takes loudnorm's own peak-limited linear gain whatever is passed.)
+ */
+export function decideLoudnorm(measured: LoudnormMeasurement): Loudnorm {
+ const { input_i: i, input_tp: tp, input_lra: lra, input_thresh: thresh, target_offset: offset } = measured;
+ const withMeasurement = `${TARGET}:measured_I=${i}:measured_TP=${tp}:measured_LRA=${lra}:measured_thresh=${thresh}:offset=${offset}`;
+ const gain = LOUDNORM_I - i;
+ const peakAfter = tp + gain;
+ const reasons: string[] = [];
+ if (peakAfter > LOUDNORM_TP) {
+ reasons.push(`a linear gain of ${gain >= 0 ? '+' : ''}${gain.toFixed(1)} dB would put the true peak at ${peakAfter.toFixed(1)} dBTP (limit ${LOUDNORM_TP})`);
+ }
+ if (lra > LOUDNORM_LRA) reasons.push(`the loudness range is ${lra.toFixed(1)} LU (limit ${LOUDNORM_LRA})`);
+ if (lra === 0) reasons.push('the loudness range measured as 0 LU (a constant level), which the linear mode refuses');
+ else if (i === 0) reasons.push('the integrated loudness measured as exactly 0 LUFS, which the linear mode refuses');
+ if (reasons.length > 0) return { mode: 'dynamic', filter: `${withMeasurement}:linear=false`, why: reasons.join('; ') };
+ return { mode: 'measured', filter: `${withMeasurement}:linear=true` };
+}
+
+const unmeasured = (why: string): Loudnorm => ({ mode: 'dynamic', filter: TARGET, why });
+
+export function loudnormFilter(source: string): Loudnorm {
+ // spawnSync, not execFileSync: the measurement is printed to STDERR, and execFileSync only hands
+ // stderr back on a throw, so a successful pass would silently lose it.
+ const measure = spawnSync(FFMPEG, [
+ '-hide_banner', '-nostats', '-i', source, '-af', `${TARGET}:print_format=json`, '-vn', '-f', 'null', '-',
+ ], { encoding: 'utf8' });
+
+ if (measure.error) return { filter: null, mode: 'none', why: `ffmpeg could not run: ${measure.error.message}` };
+ const stderr = measure.stderr ?? '';
+ // A non-zero exit still prints the input dump, and a file's own metadata tags land on that same
+ // stderr — so the summary is never read after a failure, only ffmpeg's last line is quoted.
+ if (measure.status !== 0) {
+ const last = stderr.trim().split('\n').pop() ?? '';
+ return unmeasured(`the measurement pass exited ${measure.status}${last ? `: ${last}` : ''}`);
+ }
+
+ const summary = parseLoudnormSummary(stderr);
+ if (!summary) return unmeasured('the measurement pass printed no readable summary');
+
+ // Present is not the same as usable: a silent track reports every key, with -inf in some of them.
+ // The filter is built from these coerced numbers, never from the summary's strings, so "" or " "
+ // cannot interpolate as an empty argument.
+ const needed = ['input_i', 'input_tp', 'input_lra', 'input_thresh', 'target_offset'] as const;
+ const values = needed.map((key) => Number(summary[key]));
+ if (values.some((v) => !Number.isFinite(v))) {
+ return {
+ filter: null,
+ mode: 'none',
+ why: 'the track has no measurable loudness (silence or near-silence), so it is left at its own level',
+ };
+ }
+ const [input_i, input_tp, input_lra, input_thresh, target_offset] = values;
+ return decideLoudnorm({ input_i, input_tp, input_lra, input_thresh, target_offset });
+}
diff --git a/cli/src/commands/prep.ts b/cli/src/commands/prep.ts
new file mode 100644
index 0000000..995915a
--- /dev/null
+++ b/cli/src/commands/prep.ts
@@ -0,0 +1,87 @@
+// Prep for one or more source videos. Probes the source to fix the canvas (aspect → W/H/fps), writes
+// runs//meta.json (the single source of canvas/duration/paths every downstream step reads),
+// synthesizes runs//word-timings.json from the transcript's real per-word times, and
+// extracts one base frame per beat. The transcript (any provider) must already exist — frames are
+// cut at each beat's mid time from it.
+//
+// openedit prep [ ...]
+// (any path works — absolute or relative to your CWD; outputs land in runs// under the runtime root)
+import { parseFlags } from '../args.ts';
+import { access, readFile, writeFile, mkdir } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { FFPROBE, runsDir } from '../config.ts';
+import { probeDisplaySize, probeFps } from '../probe.ts';
+import { extractBeatFrames } from '../prep/extract-beat-frames.ts';
+import { resolveVideoArg, runKeyOf } from '../resolve-video.ts';
+import { synthWordTimings, type TimedChunk } from '../prep/synth-word-timings.ts';
+
+interface Canvas { aspect: '9:16' | '16:9'; width: number; height: number; fps: number }
+
+function probeCanvas(src: string): { canvas: Canvas; durationSec: number } {
+ const { width: w, height: h } = probeDisplaySize(src);
+ const dur = Number(execFileSync(FFPROBE, ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', src]).toString().trim());
+ if (!Number.isFinite(dur)) throw new Error(`ffprobe: bad duration for ${src}`);
+ const canvas: Canvas = { aspect: h >= w ? '9:16' : '16:9', width: w, height: h, fps: Math.round(probeFps(src) * 1000) / 1000 };
+ return { canvas, durationSec: dur };
+}
+
+async function prepOne(file: string): Promise {
+ const key = runKeyOf(file);
+ const src = resolveVideoArg(file); // same rule as the transcription commands — the two must never disagree about the source file
+ const dir = join(runsDir(), key);
+ await mkdir(dir, { recursive: true });
+ const { canvas, durationSec } = probeCanvas(src);
+ const framesDir = join(dir, 'frames');
+ const meta = {
+ key, file, videoPath: src,
+ transcriptPath: join(dir, 'transcript.json'),
+ wordTimingsPath: join(dir, 'word-timings.json'),
+ framesDir,
+ aspect: canvas.aspect, width: canvas.width, height: canvas.height, fps: canvas.fps,
+ durationSec: Math.round(durationSec * 1000) / 1000,
+ };
+ await writeFile(join(dir, 'meta.json'), JSON.stringify(meta, null, 2));
+ console.log(`[meta] ${key}: ${canvas.aspect} ${canvas.width}x${canvas.height}@${canvas.fps} dur=${meta.durationSec}s`);
+
+ // The transcription step owns transcript.json (real per-word timings); frames are cut at each beat's mid time.
+ await access(meta.transcriptPath).catch(() => { throw new Error(`no ${meta.transcriptPath} — run the transcription step first`); });
+ await ensureWordTimings(dir, meta.transcriptPath, key);
+ extractBeatFrames(src, meta.transcriptPath, framesDir, canvas.width, canvas.height);
+ console.log(`[prep] ${key}: DONE`);
+}
+
+// Per-beat absolute-ms word reveal delays for the word-level caption animation. Transcripts carry REAL per-word
+// times in words:[{text,timestamp}] (the same shape as a TimedChunk) — flatten those as the word-level
+// source; even split only when a transcript has no word arrays at all. Every provider supplies real
+// times, so an even split means the transcript itself is deficient.
+async function ensureWordTimings(dir: string, transcriptPath: string, key: string): Promise {
+ const t = JSON.parse(await readFile(transcriptPath, 'utf8')) as { chunks?: (TimedChunk & { words?: TimedChunk[] })[] };
+ const chunks = Array.isArray(t.chunks) ? t.chunks : [];
+ const wordChunks = chunks.flatMap((c) => Array.isArray(c.words) ? c.words : []);
+ const wt = synthWordTimings(chunks, wordChunks.length ? wordChunks : undefined);
+ await writeFile(join(dir, 'word-timings.json'), JSON.stringify(wt, null, 2));
+ if (wordChunks.length) {
+ console.log(`[prep] ${key}: word-timings.json (real per-word times)`);
+ } else {
+ // An even split desynchronises the word reveals, so it must not read like a routine log line.
+ console.warn(
+ `[prep] ${key}: WARNING word-timings.json is an EVEN SPLIT — ${transcriptPath} carries no ` +
+ 'per-word times, so word reveals will drift out of sync with the audio.',
+ );
+ }
+}
+
+export async function prep(argv: string[]): Promise {
+ // Every argument is a video; prep takes no flags at all. Said strictly, so a flag meant for some other
+ // command is named here rather than resolved as a file path and reported as a missing video.
+ const { positionals: videos } = parseFlags({
+ args: argv,
+ options: {},
+ allowPositionals: true,
+ });
+ if (videos.length === 0) throw new Error('usage: openedit prep [...]');
+ for (const file of videos) await prepOne(file);
+ console.log('PREP DONE');
+ return 0;
+}
diff --git a/cli/src/commands/preview.ts b/cli/src/commands/preview.ts
new file mode 100644
index 0000000..bbbee05
--- /dev/null
+++ b/cli/src/commands/preview.ts
@@ -0,0 +1,172 @@
+// The preview server: serves the read-only page, streams the two media files with
+// Range support, and pushes run-dir state over SSE. Loopback-only, same trust model as
+// the openedit login command's OAuth catcher. Run:
+// node --import tsx preview/server.ts runs/
+// Env: VEED_PREVIEW_PORT (default 8978; falls back to an ephemeral port if busy),
+// VEED_PREVIEW_NO_OPEN=1 (print the URL, don't open the browser).
+import { createServer, type Server, type ServerResponse } from 'node:http';
+import { createReadStream, rmSync, writeFileSync } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { openUrl } from '../open-url.ts';
+import { basename, dirname, join } from 'node:path';
+import { pipeline } from 'node:stream';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { readRunState } from '../preview/state.ts';
+import { planRange } from '../preview/media.ts';
+import { makeHub, makeRunDirWatcher, type Hub } from '../preview/events.ts';
+
+// Beside the preview modules in src/ and dist/ alike; the build copies the page assets across.
+const PAGE_DIR = fileURLToPath(new URL('../preview/page', import.meta.url));
+const PAGE_ASSETS: Record = {
+ '/': { file: 'index.html', type: 'text/html; charset=utf-8' },
+ '/app.js': { file: 'app.js', type: 'text/javascript; charset=utf-8' },
+ '/helpers.mjs': { file: 'helpers.mjs', type: 'text/javascript; charset=utf-8' },
+ '/style.css': { file: 'style.css', type: 'text/css; charset=utf-8' },
+ '/tokens.css': { file: 'tokens.css', type: 'text/css; charset=utf-8' }, // style.css @imports the shared token SSOT
+};
+
+function boundPort(server: Server): number {
+ const addr = server.address();
+ if (addr === null || typeof addr === 'string') throw new Error('server has no bound tcp port');
+ return addr.port;
+}
+
+function json(res: ServerResponse, status: number, value: unknown): void {
+ const body = JSON.stringify(value);
+ res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body), 'cache-control': 'no-store' });
+ res.end(body);
+}
+
+async function streamMedia(res: ServerResponse, path: string, rangeHeader: string | undefined): Promise {
+ let size: number;
+ try {
+ size = (await stat(path)).size;
+ } catch {
+ json(res, 404, { error: 'not available yet' });
+ return;
+ }
+ const plan = planRange(rangeHeader, size);
+ const headers = { ...plan.headers, 'content-type': 'video/mp4', 'cache-control': 'no-store' };
+ if (plan.status === 416) {
+ res.writeHead(416, headers);
+ res.end();
+ return;
+ }
+ res.writeHead(plan.status, headers);
+ // pipeline, not pipe: a stream error after the headers (file removed/unreadable mid-request) must
+ // kill this response, never the process — and an aborted request (scrubbing cancels Range requests
+ // constantly) destroys the read stream too, releasing its file descriptor instead of leaking it.
+ pipeline(createReadStream(path, { start: plan.start, end: plan.end }), res, () => {});
+}
+
+export async function createPreviewServer(
+ runDir: string,
+ opts: { port?: number; openBrowser?: boolean } = {},
+): Promise<{ url: string; port: number; close: () => Promise }> {
+ const dirStat = await stat(runDir); // throws for a missing run dir
+ if (!dirStat.isDirectory()) throw new Error(`not a directory: ${runDir}`);
+
+ const hub: Hub = makeHub({
+ readState: () => readRunState(runDir),
+ watch: (onEvent) => makeRunDirWatcher(runDir, onEvent),
+ });
+ await hub.start();
+
+ const server: Server = createServer(async (req, res) => {
+ const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+ const path = url.pathname;
+ try {
+ // The loopback bind keeps remote clients out; this keeps DNS-rebinding pages out
+ // (a rebound document arrives carrying the attacker's own Host).
+ const host = (req.headers.host ?? '').replace(/:\d+$/, '');
+ if (host !== '127.0.0.1' && host !== 'localhost') {
+ json(res, 403, { error: 'forbidden host' });
+ return;
+ }
+ const asset = req.method === 'GET' ? PAGE_ASSETS[path] : undefined;
+ if (asset) {
+ const body = await readFile(join(PAGE_DIR, asset.file));
+ res.writeHead(200, { 'content-type': asset.type, 'content-length': body.length, 'cache-control': 'no-store' });
+ res.end(body);
+ return;
+ }
+ if (req.method === 'GET' && path === '/api/state') {
+ const current = hub.current();
+ if (current) json(res, 200, current);
+ else json(res, 503, { error: 'run state unreadable' });
+ return;
+ }
+ if (req.method === 'GET' && path === '/api/events') {
+ res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' });
+ const off = hub.addClient((frame) => res.write(frame));
+ req.on('close', off);
+ return;
+ }
+ if (req.method === 'GET' && path === '/video') {
+ const videoPath = hub.current()?.video?.videoPath;
+ if (!videoPath) json(res, 404, { error: 'no video yet (waiting for prep)' });
+ else await streamMedia(res, videoPath, req.headers.range);
+ return;
+ }
+ if (req.method === 'GET' && path === '/render') {
+ await streamMedia(res, join(runDir, 'final', 'out.mp4'), req.headers.range);
+ return;
+ }
+ json(res, 404, { error: 'not found' });
+ } catch (e) {
+ json(res, 500, { error: e instanceof Error ? e.message : 'internal error' });
+ }
+ });
+
+ const envPort = Number.parseInt(process.env.VEED_PREVIEW_PORT ?? '', 10);
+ const wanted = opts.port ?? (Number.isInteger(envPort) && envPort >= 0 && envPort <= 65535 ? envPort : 8978);
+ const port = await new Promise((resolve, reject) => {
+ server.once('error', (err: NodeJS.ErrnoException) => {
+ if (err.code !== 'EADDRINUSE') {
+ reject(err);
+ return;
+ }
+ // Default port busy (another preview, or an orphan) — take an ephemeral one.
+ // (this `once` handler has already been removed by firing; the next one is the real guard)
+ server.once('error', reject);
+ server.listen(0, '127.0.0.1', () => resolve(boundPort(server)));
+ });
+ server.listen(wanted, '127.0.0.1', () => resolve(boundPort(server)));
+ });
+
+ const url = `http://127.0.0.1:${port}`;
+ if (opts.openBrowser) openUrl(url);
+ return {
+ url,
+ port,
+ close: () => new Promise((resolve) => {
+ hub.stop();
+ server.closeAllConnections();
+ server.close(() => resolve());
+ }),
+ };
+}
+
+export async function preview(argv: string[]): Promise {
+ const runDir = argv[0];
+ if (!runDir) { console.error('usage: openedit preview runs/'); return 2; }
+ const srv = await createPreviewServer(runDir, {
+ openBrowser: process.env.VEED_PREVIEW_NO_OPEN !== '1',
+ });
+ const line = `preview: ${srv.url}/ (run: ${basename(runDir)})`;
+ console.log(line);
+ // Background launchers don't reliably surface a detached child's stdout (observed on Windows), so
+ // the URL is also mirrored to stderr off-TTY and written to a file the agent can read.
+ if (!process.stdout.isTTY) console.error(line);
+ const urlFile = join(runDir, 'preview.url');
+ try {
+ writeFileSync(urlFile, `${srv.url}/\n`);
+ } catch { /* the port is still discoverable from the log line */ }
+ const shutdown = (): void => {
+ rmSync(urlFile, { force: true });
+ void srv.close().then(() => process.exit(0));
+ };
+ process.on('SIGINT', shutdown);
+ process.on('SIGTERM', shutdown);
+ return 0;
+}
diff --git a/cli/src/commands/probe-qa.ts b/cli/src/commands/probe-qa.ts
new file mode 100644
index 0000000..972477a
--- /dev/null
+++ b/cli/src/commands/probe-qa.ts
@@ -0,0 +1,184 @@
+// Probe-frame QA — the mechanical eye that `--verify` doesn't have. Verify replays the draw list
+// (bounds/occlusion); it cannot see "no caption on screen mid-beat" (dead-air) or "white text on a
+// white mug" (low contrast). This tool samples frames at each beat's MID and TAIL (end − 120ms),
+// diffs the RENDER against the SOURCE at the same timestamp (the diff mask ≈ the painted overlay ink),
+// and checks: ink-present (mid-beat must show a caption) + WCAG-ish contrast of the ink against its
+// immediate surroundings. Verdict JSON + exit code; run by generate-recipe.ts as the last gate after
+// the record.
+//
+// Calibration notes: exit-fade tails read as low-opacity captions in
+// ±120ms probes BY DESIGN → tail probes only WARN; thresholds are conservative-lenient v1, tune on
+// known-good sheets. Double-print detection is NOT implemented (needs cluster analysis) — sheet rule.
+// node --import tsx pipeline/scripts/probe-qa.ts [--json]
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FFMPEG } from '../config.ts';
+
+// Probes are compared on a small fixed grayscale grid — enough to see captions, cheap to extract.
+export const GRID_W = 90;
+export const GRID_H = 160; // portrait; landscape uses 160x90 (set per meta)
+const DIFF_THRESHOLD = 24; // |render - source| above this = overlay ink
+const INK_MIN_PCT = 0.3; // a visible caption paints well above this fraction of the frame (%)
+const CONTRAST_FAIL = 2.0; // below = unreadable against its own surroundings
+const CONTRAST_WARN = 3.5; // WCAG large-text is 3.0; captions are large — warn band above fail
+
+export interface ProbeStats { inkPct: number; contrast: number | null }
+export interface ProbeResult {
+ beat: number; probe: 'mid' | 'tail'; tSec: number;
+ inkPct: number; contrast: number | null;
+ verdict: 'pass' | 'warn' | 'fail'; notes: string[];
+}
+
+// diff mask + ink fraction + text-vs-surroundings contrast over two same-size grayscale buffers.
+export function probeStats(render: Uint8Array, source: Uint8Array, w: number, h: number): ProbeStats {
+ const n = Math.min(render.length, source.length, w * h);
+ const mask = new Uint8Array(n);
+ let ink = 0;
+ for (let i = 0; i < n; i++) {
+ if (Math.abs(render[i] - source[i]) > DIFF_THRESHOLD) { mask[i] = 1; ink++; }
+ }
+ const inkPct = (ink / n) * 100;
+ if (ink === 0) return { inkPct, contrast: null };
+
+ // Two readability signals, take the BEST — text is readable if it separates from EITHER:
+ // (a) RING contrast: mask average vs the 2px ring around it (pure text sitting on footage);
+ // (b) INNER contrast: the mask's bright half vs dark half (card devices — the mask covers card +
+ // text, so the average washes out, but the internal split captures text-on-card separation).
+ let textSum = 0, ringSum = 0, ringN = 0;
+ for (let i = 0; i < n; i++) {
+ if (mask[i]) { textSum += render[i]; continue; }
+ const x = i % w, y = (i / w) | 0;
+ let nearInk = false;
+ for (let dy = -2; dy <= 2 && !nearInk; dy++) {
+ for (let dx = -2; dx <= 2 && !nearInk; dx++) {
+ const xx = x + dx, yy = y + dy;
+ if (xx >= 0 && xx < w && yy >= 0 && yy < h && mask[yy * w + xx]) nearInk = true;
+ }
+ }
+ if (nearInk) { ringSum += render[i]; ringN++; }
+ }
+ const lum = (v: number) => Math.pow(v / 255, 2.2); // gamma-approx relative luminance
+ const ratio = (a: number, b: number) => (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+ const meanText = textSum / ink;
+ const ringContrast = ratio(lum(meanText), lum(ringN ? ringSum / ringN : 0));
+ // Inner split by PERCENTILE, not mean: on an opaque-card design the mask is dominated by the card,
+ // so a mean split washes small text into the card class (hook-072 false-FAIL). Top decile ≈ the
+ // text ink, bottom half ≈ the fill it sits on.
+ const vals: number[] = [];
+ for (let i = 0; i < n; i++) if (mask[i]) vals.push(render[i]);
+ vals.sort((a, b) => a - b);
+ const meanOf = (arr: number[]) => arr.reduce((s, v) => s + v, 0) / arr.length;
+ const topDecile = vals.slice(Math.floor(vals.length * 0.9));
+ const bottomHalf = vals.slice(0, Math.max(1, Math.floor(vals.length * 0.5)));
+ const innerContrast = topDecile.length && bottomHalf.length
+ ? ratio(lum(meanOf(topDecile)), lum(meanOf(bottomHalf)))
+ : 1;
+ const contrast = Math.max(ringContrast, innerContrast);
+ return { inkPct, contrast: Math.round(contrast * 100) / 100 };
+}
+
+export function judge(probe: 'mid' | 'tail', s: ProbeStats): { verdict: 'pass' | 'warn' | 'fail'; notes: string[] } {
+ const notes: string[] = [];
+ let verdict: 'pass' | 'warn' | 'fail' = 'pass';
+ if (s.inkPct < INK_MIN_PCT) {
+ notes.push(`ink ${s.inkPct.toFixed(2)}% < ${INK_MIN_PCT}% — no visible caption`);
+ // dead-air mid-beat is a defect; a thin tail is a known non-defect (exit fades) → warn
+ verdict = probe === 'mid' ? 'fail' : 'warn';
+ return { verdict, notes };
+ }
+ if (s.contrast !== null) {
+ if (s.contrast < CONTRAST_FAIL) { verdict = 'fail'; notes.push(`contrast ${s.contrast} < ${CONTRAST_FAIL} — unreadable on this footage`); }
+ else if (s.contrast < CONTRAST_WARN) { verdict = 'warn'; notes.push(`contrast ${s.contrast} < ${CONTRAST_WARN} — borderline, eyeball it`); }
+ }
+ return { verdict, notes };
+}
+
+interface Beat { i: number; startSec: number; endSec: number; lastWordSec?: number }
+
+function beatsOf(runDir: string): Beat[] {
+ const wt = join(runDir, 'word-timings.json');
+ if (existsSync(wt)) {
+ const t = JSON.parse(readFileSync(wt, 'utf8')) as { beats: { i: number; startSec: number; endSec: number; words?: { delayMs: number }[] }[] };
+ return t.beats.map((b) => ({
+ i: b.i, startSec: b.startSec, endSec: b.endSec,
+ lastWordSec: b.words?.length ? Math.max(...b.words.map((w) => w.delayMs)) / 1000 : undefined,
+ }));
+ }
+ const tr = JSON.parse(readFileSync(join(runDir, 'transcript.json'), 'utf8')) as { chunks: { timestamp: [number, number] }[] };
+ return tr.chunks.map((c, idx) => ({ i: idx + 1, startSec: c.timestamp[0], endSec: c.timestamp[1] }));
+}
+
+// The geometric midpoint can precede the beat's speech (a late hero word, a page hand-off, an
+// arc-then-body build): a failing mid probe gets ONE second chance at the moment every word of the
+// beat has landed. True dead-air still fails — ink is absent then too. 39-sample validation showed
+// this artifact class produced every false FAIL on otherwise eyeball-clean renders.
+export function midRetryTime(b: Beat): number | null {
+ if (b.lastWordSec === undefined) return null;
+ const t = Math.min(b.lastWordSec + 0.3, b.endSec - 0.12);
+ return t > (b.startSec + b.endSec) / 2 + 0.05 ? t : null;
+}
+
+function grayFrame(video: string, tSec: number, w: number, h: number): Uint8Array {
+ return new Uint8Array(execFileSync(FFMPEG, [
+ '-v', 'error', '-ss', String(tSec), '-i', video, '-frames:v', '1',
+ '-vf', `scale=${w}:${h}`, '-f', 'rawvideo', '-pix_fmt', 'gray', '-',
+ ], { maxBuffer: 1 << 24 }));
+}
+
+export function probeRun(runDir: string, doc = 'final'): ProbeResult[] {
+ const meta = JSON.parse(readFileSync(join(runDir, 'meta.json'), 'utf8')) as { videoPath: string; width: number; height: number; durationSec: number };
+ const render = join(runDir, doc, 'out.silent.mp4');
+ if (!existsSync(render)) throw new Error(`no ${render} — record first`);
+ const portrait = meta.height >= meta.width;
+ const [w, h] = portrait ? [GRID_W, GRID_H] : [GRID_H, GRID_W];
+ const results: ProbeResult[] = [];
+ for (const b of beatsOf(runDir)) {
+ const probes: ['mid' | 'tail', number][] = [
+ ['mid', (b.startSec + b.endSec) / 2],
+ ['tail', Math.max(b.startSec, b.endSec - 0.12)],
+ ];
+ for (const [probe, tRaw] of probes) {
+ const t = Math.min(tRaw, meta.durationSec - 0.05);
+ let s = probeStats(grayFrame(render, t, w, h), grayFrame(meta.videoPath, t, w, h), w, h);
+ let { verdict, notes } = judge(probe, s);
+ let tUsed = t;
+ if (probe === 'mid' && verdict === 'fail') {
+ const t2 = midRetryTime(b);
+ if (t2 !== null) {
+ const t2c = Math.min(t2, meta.durationSec - 0.05);
+ const s2 = probeStats(grayFrame(render, t2c, w, h), grayFrame(meta.videoPath, t2c, w, h), w, h);
+ const r2 = judge(probe, s2);
+ if (r2.verdict !== 'fail') {
+ s = s2; verdict = r2.verdict; tUsed = t2c;
+ notes = [...r2.notes, `mid resampled @${t2c.toFixed(2)}s — words land late in this beat (midpoint probe was pre-speech)`];
+ }
+ }
+ }
+ results.push({ beat: b.i, probe, tSec: Math.round(tUsed * 100) / 100, inkPct: Math.round(s.inkPct * 100) / 100, contrast: s.contrast, verdict, notes });
+ }
+ }
+ return results;
+}
+
+export function probeQaCommand(argv: string[]): number {
+ // The value of a flag is not a positional. `--doc chapters/act-1 runs/f` took the chapter as the run.
+ const skip = new Set();
+ argv.forEach((a, i) => { if (a === '--doc') skip.add(i + 1); });
+ const runDir = argv.find((a, i) => !a.startsWith('--') && !skip.has(i));
+ if (!runDir) { console.error('usage: openedit probe-qa [--doc final] [--json]'); return 2; }
+ // A film gates one chapter at a time, so the document is not always `final`.
+ const at = argv.indexOf('--doc');
+ const doc = at >= 0 ? argv[at + 1] : 'final';
+ if (at >= 0 && !doc) { console.error('--doc needs a subdirectory'); return 2; }
+ const results = probeRun(runDir, doc);
+ if (argv.includes('--json')) console.log(JSON.stringify(results, null, 2));
+ else for (const r of results) {
+ console.log(`beat ${r.beat} ${r.probe}@${r.tSec}s ink=${r.inkPct}% contrast=${r.contrast ?? '-'} ${r.verdict.toUpperCase()}${r.notes.length ? ' — ' + r.notes.join('; ') : ''}`);
+ }
+ const fails = results.filter((r) => r.verdict === 'fail');
+ const warns = results.filter((r) => r.verdict === 'warn');
+ // summary → stderr so --json stdout stays parseable
+ console.error(fails.length ? `probe-qa: ${fails.length} FAIL, ${warns.length} warn` : `probe-qa: clean (${warns.length} warn)`);
+ return fails.length ? 1 : 0;
+}
diff --git a/cli/src/commands/readiness.ts b/cli/src/commands/readiness.ts
new file mode 100644
index 0000000..6d792fc
--- /dev/null
+++ b/cli/src/commands/readiness.ts
@@ -0,0 +1,70 @@
+// Readiness check for both the render flow and the VEED-native transcription path.
+// Reports what is present vs what is still missing for a run, and exits 1 when a blocking item is
+// missing. Read-only, no network.
+//
+// openedit readiness
+import { existsSync } from 'node:fs';
+import { FFMPEG, engineBinPath } from '../config.ts';
+import { FFMPEG_PROBE, probeVersion } from '../platform.ts';
+import { VEED_API_BASE } from '../veed/api.ts';
+import { DEFAULT_TOKEN_PATH } from '../veed/token-store.ts';
+
+type Check = { label: string; ok: boolean; detail: string; blocking: boolean };
+
+export function readiness(_argv: string[]): number {
+ const checks: Check[] = [];
+ const add = (label: string, ok: boolean, detail: string, blocking = true): void => {
+ checks.push({ label, ok, detail, blocking });
+ };
+
+ // --- toolchain (shared by both flows) ---
+ add('node', true, process.version);
+
+ // probeVersion, not a bare exec: a binary that exists but cannot start (the missing-DLL
+ // Server case) must be diagnosed as such, not as absent with the wrong remedy.
+ const ff = probeVersion(FFMPEG, FFMPEG_PROBE);
+ add('ffmpeg', ff.banner !== '', ff.banner || `not runnable at "${FFMPEG}" — ${ff.failure} (set VEED_ENGINE_FFMPEG)`);
+
+ const engineBin = engineBinPath();
+ const firstTry = probeVersion(engineBin);
+ const engine = firstTry.banner ? firstTry : probeVersion(engineBin, { args: ['version'] });
+ add(
+ 'veed-engine-cli',
+ engine.banner !== '',
+ engine.banner || `not runnable at "${engineBin}" — ${engine.failure} (run: npx @veedstudio/openedit-cli install-engine; only needed for render, not transcription)`,
+ false,
+ );
+
+ // --- VEED-native transcription path ---
+ add('VEED API base', true, VEED_API_BASE, false);
+
+ // Fabric generation rides the same login and the same REST edge as transcription — surface it so a user
+ // who wonders "can this thing make me a video?" gets an answer without reading the source. This command
+ // makes no network calls, so this reports the CONFIGURED url only; reachability is proven by the first real run.
+ add('Fabric generation endpoint', true, `${VEED_API_BASE} (configured; not contacted)`, false);
+
+ const tokenEnv = (process.env.VEED_ACCESS_TOKEN ?? '').trim() !== '';
+ const tokenCached = existsSync(DEFAULT_TOKEN_PATH);
+ // Optional, not blocking: only the VEED provider reads this token.
+ add(
+ 'VEED login token',
+ tokenEnv || tokenCached,
+ tokenEnv ? 'VEED_ACCESS_TOKEN set' : tokenCached ? `cached at ${DEFAULT_TOKEN_PATH}` : 'not logged in yet; needed ONLY for the VEED provider — run: npx @veedstudio/openedit-cli login',
+ false,
+ );
+
+ // --- report ---
+ console.log('\nVEED local editor readiness\n' + '='.repeat(40));
+ for (const c of checks) {
+ const mark = c.ok ? 'OK ' : c.blocking ? 'MISS' : 'opt ';
+ console.log(`[${mark}] ${c.label.padEnd(22)} ${c.detail}`);
+ }
+ const blockingMisses = checks.filter((c) => !c.ok && c.blocking);
+ console.log('='.repeat(40));
+ if (blockingMisses.length === 0) {
+ console.log('All blocking checks pass. Items marked "opt" are needed only by the step or provider named beside them.');
+ } else {
+ console.log(`${blockingMisses.length} blocking item(s) to resolve: ${blockingMisses.map((c) => c.label).join(', ')}`);
+ }
+ return blockingMisses.length === 0 ? 0 : 1;
+}
diff --git a/cli/src/commands/retime-transcript.ts b/cli/src/commands/retime-transcript.ts
new file mode 100644
index 0000000..80f5144
--- /dev/null
+++ b/cli/src/commands/retime-transcript.ts
@@ -0,0 +1,212 @@
+// Move per-word timings onto the timeline an EDL produced, instead of transcribing the cut again.
+//
+// openedit retime-transcript --edl --out 
+ 
+
+*Made in OpenEdit with GPT-6 Astra driving the pipeline: pure motion graphics, no source footage, prompted
+against the [OpenAI Brand Film](https://vimeo.com/1122006941) as a visual reference.*
+
+
+
+*The launch video, also made in OpenEdit. Click either one to watch with sound.*
+
+## What you can ask for
+
+Captions are the shortest path, not the limit. The agent can edit, cut and reframe footage, layer
+motion graphics and visual elements, turn slides into video, and pull in any
+[AI video/image generator](https://www.veed.io/tools/ai-video) or MCP server when it helps. Source
+video is optional: stills, slides or generated media are enough when the brief calls for it.
+
+As a first ask:
+
+```
+Add subtitles that look like this [IMG-REF] to my video [VIDEO]
+
+Cut the false start and the long pause around 0:42, then caption it
+
+Make a 20-second title sequence for my launch, no footage, in my brand colours
+```
+
+On a delivered render:
+
+```
+I don't like the yellow colour, make it darker
+
+Move the text up a bit
+
+When he says "go buy it now", make sure the 'now' really stands out
+```
+
+No footage at all? It can generate a talking-head clip from a script with
+[VEED Fabric](https://www.veed.io/ai/fabric-1-0) and edit that. Generation is billed: it quotes the price
+in your workspace's AI Playground credits and spends nothing without your yes.
+
+## Examples
+
+Real outputs, each with the prompt that produced it. Click any example to watch it with sound.
+
+```
+create viral subtitles with /open-edit and translate my video to 5 languages using VEED Lipsync 2.0 on Fal
+```
+
+One source clip, three languages, three caption styles, translated and re-lipsynced through
+[VEED's Lip Sync API](https://www.veed.io/tools/lip-sync-api):
+
+| Spanish | French | German |
+| --- | --- | --- |
+| [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/happy3-ES-078.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/remix-FR.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/happy2-DE-lowerthird.mp4) |
+
+```
+generate 3 viral hooks in Seedance 2.0 on Fal and create dynamic motion graphics using /open-edit
+```
+
+Three hooks generated with [Seedance](https://www.veed.io/tools/ai-video/seedance), three
+motion-graphic treatments:
+
+| | | |
+| --- | --- | --- |
+| [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/news-comic.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/chair-remix.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/makeup-happy-v2.mp4) |
+
+```
+use Figma MCP to study my BrandBook and create branded campaign graphics using /open-edit
+```
+
+One brand book, three campaign cards:
+
+| | | |
+| --- | --- | --- |
+| [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/race-card-1.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/race-card-2.mp4) | [](https://github.com/veedstudio/open-edit/releases/download/launch-examples/race-card-4.mp4) |
+
+## How it works
+
+The skill tells your agent the whole flow: transcribe with real per-word timings, draw a caption style
+from a pool of recipes, compose the document in HTML and CSS, render it with VEED's renderer, then check
+the result for timing and contrast before handing it back. Every step of a captioned run is a command
+from the `@veedstudio/openedit-cli` package; the [CLI reference](../README.md) lists them.
+
+The renderer is source-available and free to use, and it does not run a headless browser: nothing to
+install, launch or keep alive for the length of a render. It does need a desktop session, so renders
+run on your machine rather than on a headless box.
+
+Transcription is your choice, asked once and remembered. WhisperX runs locally and nothing leaves your
+machine. VEED's hosted transcription uploads the file in order to transcribe it and stores it for that
+purpose. Any Whisper-family JSON from your own service works too, and no credentials pass through
+OpenEdit. Every provider writes the same `runs/
- 
+Log in with VEED (OAuth 2.1 + PKCE via the browser; the token is stored locally
+and refreshed automatically):
-*This launch video was made in OpenEdit — click it to watch with sound.*
+```sh
+npx @veedstudio/openedit-cli login
+```
-
+Pass `--manual` (or set `VEED_LOGIN_MANUAL=1`) when no reachable browser exists:
+the URL is printed, and the redirect is pasted back instead of caught on a
+localhost loopback.
-*Also made in OpenEdit, with GPT-6 Astra driving the pipeline — pure motion graphics, no source
-footage. Its prompt was written against the [OpenAI Brand Film](https://vimeo.com/1122006941) as a
-visual reference.*
+### token
-## Requirements
+Print a valid VEED access token for other tools to consume, refreshing it
+first when stale (`VEED_ACCESS_TOKEN`, when set, is passed through as-is). The
+value is printed only when the output is captured; run it straight in a terminal
+and it reports that a token exists without putting one in your scrollback:
-| | |
-| --- | --- |
-| Platform | Apple Silicon Mac or Windows x64 PC. Preflight requires one of the two and stops elsewhere |
-| Intel Macs | Not supported — the renderer ships macOS-arm64 and windows-x64 only |
-| Older macOS | Built and tested on Tahoe 26.0. Nothing checks the version, so earlier releases may work — untested |
-| Windows | Windows 10 or newer (the installer extracts with the bundled `tar`). Git, Node, and ffmpeg via winget — preflight prints the exact commands and never runs them itself |
-| Linux | Planned; prioritisation depends on demand |
-| Transcription | needed only to caption speech — OpenEdit asks once and remembers: VEED ([sign up](https://www.veed.io/signup) / [login](https://www.veed.io/login)), WhisperX locally, or your own service. **VEED transcription consumes VEED credits**; WhisperX runs locally on your machine, and your own service is billed by whoever provides it |
-| Generation | optional — a veed.io account, only if you ask OpenEdit to generate footage you do not have |
-
-## Installation
-Download this repo, or install via the command line with:
```sh
-npx skills add veedstudio/open-edit
+npx @veedstudio/openedit-cli token
```
-## Agents
-OpenEdit uses an agent-agnostic skill and repository guide. It supports Claude Code, Codex, and Gemini;
-the installed skill prepares the runtime and loads its `AGENTS.md` instructions explicitly.
+Exits non-zero when no login is stored. `--path` prints the token store
+location instead of a token.
+
+### transcribe
+
+Transcribe videos, writing `runs/