@vibeframe/cli 0.104.3 → 0.105.2

package/dist/commands/_shared/hf-skill-bundle/bundle.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module _shared/hf-skill-bundle
+ *
+ * Loads the vendored Hyperframes skill content as a single concatenated
+ * system-prompt string. Used by `compose-scenes-with-skills` (v0.59+).
+ *
+ * Hyperframes (https://github.com/heygen-com/hyperframes, Apache 2.0)
+ * publishes this skill content as the agent-loadable definition of its
+ * composition craft. VibeFrame is not affiliated with HeyGen — see
+ * `/CREDITS.md` and `./NOTICE` for the relationship + license obligations
+ * VibeFrame honours.
+ *
+ * Sourcing order (highest precedence first):
+ *   1. User-installed skill — `~/.claude/skills/hyperframes/` (read at runtime
+ *      via readFileSync — kept fresh by the user's `npx skills update` flow)
+ *   2. Vendored snapshot in this directory (always available, even after
+ *      `npm install -g @vibeframe/cli` because the .md files are inlined
+ *      into the esbuild bundle via the text loader — see `build.js`)
+ *
+ * The vendored copy is byte-identical to upstream: no semantic edits. We
+ * mirror Hyperframes' own treatment of prior art (see their CREDITS.md
+ * "Prior art" section about Remotion). Refresh the snapshot with
+ * `scripts/refresh-hf-bundle.sh`, which re-copies from a sibling clone of
+ * the upstream repo and bumps BUNDLE_VERSION.
+ *
+ * The cache for `compose-scenes-with-skills` keys on `BUNDLE_VERSION` (folded
+ * into the hash) so snapshot upgrades automatically invalidate previously-cached
+ * HTML.
+ */
+/**
+ * Snapshot identifier. Bump on every refresh of the vendored MD files.
+ * Format: `<upstream-git-sha>-<YYYY-MM-DD>` so cache keys auto-invalidate
+ * even when the upstream sha alone is unchanged but our local copy wasn't
+ * actually re-fetched.
+ *
+ * **Update rule:** any time you change a file under this directory, also
+ * bump this constant. `scripts/refresh-hf-bundle.sh` does this automatically.
+ */
+export declare const BUNDLE_VERSION = "970367f-2026-04-25";
+/**
+ * Load the Hyperframes skill bundle as a single string. Prefers the
+ * user-installed skill (kept fresh by `npx skills add heygen-com/hyperframes`
+ * + `npx skills update`) and falls back to the vendored snapshot inlined
+ * into this bundle.
+ *
+ * Side-effect free except for the optional `~/.claude/skills/hyperframes/`
+ * filesystem read.
+ */
+export declare function loadHyperframesSkillBundle(): {
+    content: string;
+    /** "installed" (user has ~/.claude/skills/hyperframes/) or "vendored" (esbuild-inlined snapshot). */
+    source: "installed" | "vendored";
+    /** Human-readable hint for first-load logging. */
+    hint: string;
+    /** Stable hash of (BUNDLE_VERSION + content). Used as cache-key input. */
+    hash: string;
+};

package/dist/commands/_shared/hf-skill-bundle/bundle.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/init-templates.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @module _shared/init-templates
+ *
+ * Templates the `vibe init` (v0.61 C2) project scaffolder writes. Pure
+ * string constants + tiny functions; no I/O. The orchestrator decides
+ * which files to render based on detected agent hosts.
+ *
+ * Template philosophy: keep generated content *short* and point at
+ * dynamic sources (`vibe schema --list`, `vibe doctor`) instead of
+ * baking exhaustive catalogs that go stale across releases. The user is
+ * expected to extend these with project-specific guidance.
+ */
+/**
+ * agents.md spec-compliant cross-tool agent declaration. Recognised by
+ * OpenAI Codex, Cursor, Aider, Sourcegraph Cody, OpenCode, and (via
+ * the @AGENTS.md import) Claude Code. Gemini CLI users may want to
+ * also keep a sibling \`GEMINI.md\` since that's its primary context
+ * file. Keep this as the canonical source of truth for agent guidance —
+ * \`CLAUDE.md\` and \`GEMINI.md\` just import it.
+ */
+export declare const AGENTS_MD = "# AGENTS.md\n\nThis project uses [VibeFrame](https://github.com/vericontext/vibeframe) \u2014\na CLI for AI-powered video editing. The `vibe` command provides 80+\nsubcommands for video generation, editing, analysis, and pipeline\norchestration. Cost tiers below \u2014 **always confirm with the user before\nrunning High / Very High tier commands**.\n\n## Agent host coverage\n\nVibeFrame's CLI works with any bash-capable AI coding agent. Six host\nfamilies have first-class auto-detection and scaffolds today:\n\n- **Claude Code** \u2014 `CLAUDE.md` (this file's import wrapper) +\n  `AGENTS.md` + `/vibe-*` slash commands.\n- **OpenAI Codex** \u2014 reads `AGENTS.md` natively (agents.md spec).\n- **Cursor** \u2014 reads `AGENTS.md` plus `.cursor/rules/` for project\n  rules; supports MCP via `.cursor/mcp.json`.\n- **Aider** \u2014 reads `AGENTS.md` (binary-only detection by VibeFrame).\n- **Gemini CLI** \u2014 primary context file is `GEMINI.md`; also reads\n  `AGENTS.md` if present.\n- **OpenCode** \u2014 reads `AGENTS.md` (officially supported per\n  `opencode.ai/docs/rules`); supports MCP via `.opencode/mcp.json`.\n\nRun `vibe doctor` to see which host(s) the CLI detects in your\nenvironment. Anyone running another bash-capable agent (Continue,\nSourcegraph Cody, etc.) still gets this `AGENTS.md` as the universal\nfallback.\n\n## Self-discovery\n\nDon't memorise the command surface \u2014 read it from the CLI:\n\n```bash\nvibe --help                    # command groups overview\nvibe schema --list             # full machine-readable catalog (80+)\nvibe schema --list --surface public  # small first-run/product command surface\nvibe schema generate.video     # JSON Schema for any single command\nvibe doctor                    # available providers + system health\nvibe guide motion              # choose text-overlay vs motion-overlay vs generate motion\nvibe guide scene               # step-by-step authoring guide (scene)\nvibe guide pipeline            # step-by-step authoring guide (pipeline)\n```\n\n## Route by the user's actual request\n\nRouting the user's request correctly is the most important judgement call\nyou'll make. Do not force everything into a scene project.\n\n**ASSET \u2014 default for any single-asset request OR ambiguous prompt.**\nIf the user asks for a single image, single video clip, sound effect, music\nbed, or narration file \u2014 **OR pastes a visual/audio brief without explicit\nstoryboard / scene / multi-scene language** \u2014 treat it as ASSET. Use\n`vibe generate ...` directly. Do **not** edit `DESIGN.md`,\n`STORYBOARD.md`, run `vibe scene ...`, or auto-load the hyperframes\nskill until BUILD intent is explicit. The visual-identity hard-gate\napplies to BUILD only.\n\nExamples:\n- \"make this image\" \u2192 `vibe generate image \"...\" -o assets/name.png`\n- \"use this image to make a video\" \u2192 `vibe generate video \"...\" -i image.png -o renders/name.mp4`\n- \"add a lower-third/title/animated overlay/grain/vignette to this clip\" \u2192 prefer `vibe edit motion-overlay clip.mp4 \"...\" --understand auto -o out.mp4` when the request asks for designed or animated motion graphics.\n- \"please add visuals using OpenAI image gen\" \u2192 `vibe generate image \"...\" -p openai ...`\n- *(verb-less paste)* \"aerial view of a misty mountain peak at sunrise...\" \u2192 `vibe generate image \"<paste>\" -o assets/mountain-peak.png`. **Don't** read it as a brief for DESIGN.md.\n\nIf genuinely uncertain, ask one short question: *\"single asset or\nmulti-scene project?\"* before authoring DESIGN.md or loading the\nhyperframes skill.\n\n**BUILD \u2014 create new video from text intent.**\nUse `vibe build` with a STORYBOARD.md + DESIGN.md. The\nskills-driven pipeline (v0.60+) dispatches narration TTS + backdrop\nimage-gen per beat, composes scene HTML via the bundled composition rules\nbundle, then renders to MP4. Idempotent re-runs reuse cached assets.\n\n**REMIX \u2014 transform existing video / audio.**\nUse `vibe remix`, `vibe edit`, or `vibe audio`. One-shot,\nbatch-oriented operations on a file the user already has on disk.\n`vibe edit text-overlay` is the free deterministic path for simple static\ntext burn-in. If the user asks for motion design, animated lower-thirds,\ndesigned titles, grain/vignette as part of a graphic treatment, or says\n\"motion graphics\", use `vibe edit motion-overlay ... --understand auto` instead.\n\nDecision rule: if the user asks for one asset, it's ASSET. If the user asks\nfor a multi-scene/storyboard/composed video, it's BUILD. If the user is\nstarting from a media file and wants it transformed, it's REMIX.\n\n## Common workflows\n\n### BUILD (new video from text)\n\n| Task | Command |\n|---|---|\n| One-shot storyboard \u2192 video | `vibe build [project-dir]` |\n| Render an existing scene project | `vibe render [project-dir] -o out.mp4` |\n| Lint scene HTML | `vibe scene lint --json` |\n| Generate a single image | `vibe generate image \"prompt\" -o img.png --quality hd` |\n| Generate a single video | `vibe generate video \"prompt\" -i image.png -o clip.mp4` |\n| Generate narration | `vibe generate narration \"text\" -o voice.mp3` |\n\n### REMIX (transform existing media)\n\n| Task | Command |\n|---|---|\n| Extract highlights from a long video | `vibe remix highlights file.mp4 -d 60` |\n| Long video \u2192 vertical shorts | `vibe remix auto-shorts file.mp4 -n 3 --add-captions` |\n| Add animated word-by-word captions | `vibe remix animated-caption file.mp4 -s karaoke-sweep` |\n| Add designed motion graphics overlay | `vibe edit motion-overlay file.mp4 \"lower-third...\" --understand auto -o out.mp4` |\n| Remove silence | `vibe edit silence-cut in.mp4 -o out.mp4` |\n| Add static captions | `vibe edit caption in.mp4 -o out.mp4` |\n| Translate audio (transcribe \u2192 TTS) | `vibe audio dub file.mp4 -t ko` |\n| Transcribe (Whisper, word-level) | `vibe audio transcribe file.mp4 --granularity word` |\n| Inspect media with Gemini | `vibe inspect media file.mp4 \"summarise\" --json` |\n\n### Compose pipelines (Video as Code)\n\n| Task | Command |\n|---|---|\n| Run a YAML pipeline | `vibe run pipeline.yaml --dry-run` |\n| Resume from last checkpoint | `vibe run pipeline.yaml --resume` |\n\n## Cost tiers\n\n| Tier | Examples | Approx. per call |\n|---|---|---|\n| **Free** | `schema/context/doctor`, `detect *`, `status *`, `plan`, `storyboard validate`, `inspect project/render --cheap`, deterministic edits | $0 |\n| **Low** | `generate narration/sound-effect/music`, `audio transcribe`, `inspect media`, optional AI review | $0.01\u2013$0.10 |\n| **High** | `generate image/motion`, `edit image/reframe/grade/speed-ramp` | $1\u2013$5 |\n| **Very High** | `generate video`, `edit fill-gaps`, `remix highlights/auto-shorts`, `build` with generated assets | $5\u2013$50+ |\n\n## Agent invariants\n\nWhen you run vibe commands programmatically:\n\n1. **Always `--json`** for structured output you can parse without regex\n2. **Always `--dry-run` first** for any High/Very-High tier command \u2014 it returns\n   the cost estimate without spending API budget\n3. **Use `vibe schema <command>`** to discover parameters; do not guess flags\n4. **Pass complex options via `--stdin`**:\n   ```bash\n   echo '{\"video\":\"long.mp4\",\"count\":3,\"aspect\":\"9:16\"}' | vibe remix auto-shorts --stdin --json\n   ```\n\n## Provider keys and project scope\n\nPrefer `vibe setup --scope project` for project-local keys. It writes\n`.vibeframe/config.yaml` in the setup directory; when you work from a\nnested scene directory, the `vibe` CLI automatically searches parent\ndirectories and uses the nearest project config. Do not assume the config\nfile must exist in the current subdirectory.\n\nRun `vibe doctor --json` from the directory where you will run commands\nand check `data.scope.project.configPath` / `data.scope.activeScope` before\ndeciding keys are missing. Never print or copy config file contents.\n\nFor generated project assets, use VibeFrame commands such as\n`vibe generate image|video|speech ...` so these project-scope keys are\nused. Do not switch to a host agent's built-in image/audio generation tool\nunless the user explicitly asks for a non-VibeFrame asset.\n\n`.env` is still supported as a gitignored fallback. Copy `.env.example`\nto start if you prefer environment variables.\n\n### Composition rules (scene HTML)\n\n`vibe init` installs local composition rules into your project. The\nuniversal copy lives at `SKILL.md` (with `references/*.md`), and\nhost-specific copies are placed where each agent expects them\n(`.claude/skills/hyperframes/` for Claude Code, `.cursor/rules/hyperframes.mdc`\nfor Cursor). **Read `SKILL.md` before authoring any scene composition HTML\nunder `compositions/`** \u2014 it defines the framework rules, motion\nprinciples, type system, and visual-identity hard-gate. The same skill\ngoverns `vibe scene lint` so your authored HTML and the linter stay in\nagreement.\n\nFor render-stable text, do not apply continuous `scale`, `x`, `y`,\n`filter`, or other transform tweens to `.scene-content` or any ancestor\ncontaining live text/cards. Put ambient zoom/parallax on background or media\nlayers only; text should enter briefly and then hold still at its final CSS\nposition.\n\nTo retro-install on a project scaffolded before this command existed, run\n`vibe scene install-skill [--host all]`.\n\n### Scene composer (batch / non-agent fallback)\n\nWhen you don't want to author HTML yourself, `vibe build --mode batch` runs an\nLLM internally with the same skill bundle. It auto-picks a provider based\non available keys (`claude > gemini > openai`) \u2014 pass `--composer <name>`\nto force one:\n\n| Provider | Env var | Spike notes (v0.70) |\n|---|---|---|\n| Claude (default) | `ANTHROPIC_API_KEY` | ~9 s/beat. Fastest, validated baseline. |\n| Gemini | `GOOGLE_API_KEY` | ~20 s/beat. ~2.6\u00D7 cheaper than Claude. |\n| OpenAI | `OPENAI_API_KEY` | ~70 s/beat. gpt-5 reasoning latency \u2014 opt-in only. |\n\nAll three pass first-shot lint at every effort tier on the `vibeframe-promo`\nfixture. Quality on more complex storyboards may differ \u2014 fall back to\n`--composer claude` if a non-default provider repeatedly fails lint.\n\n## Project conventions\n\n<!-- Edit this section with YOUR project's specifics. Examples below. -->\n\n- Default aspect ratio: `16:9`\n- Default scene duration: `3 seconds` (per beat)\n- Brand voice: <describe>\n- Output naming: `renders/<name>-<timestamp>.mp4`\n";
+/**
+ * Claude Code project file. Imports AGENTS.md so guidance stays
+ * single-sourced; adds Claude-specific overrides (slash commands, etc.).
+ */
+export declare const CLAUDE_MD = "@AGENTS.md\n\n# Claude Code overrides\n\nThis file imports `AGENTS.md` (above) \u2014 that's the canonical source.\nAdd anything Claude-Code-specific *below*; everything generic should\nstay in AGENTS.md so other agent hosts (Codex, Cursor, Aider, Gemini CLI, OpenCode) see it\ntoo.\n\n## Skills\n\nIf you ran `vibe init` with Claude Code detected, the VibeFrame skill\npack is available as slash commands (consolidated to 2 in v0.62 \u2014 the\noverview content moved into AGENTS.md above):\n\n- `/vibe-pipeline` \u2014 YAML pipeline authoring helper (Video as Code)\n- `/vibe-scene` \u2014 per-scene HTML authoring + `vibe build`\n\nClaude-specific routing note: follow the ASSET / BUILD / REMIX decision\nrules in `AGENTS.md`. In particular, a request for one generated image or\none generated video clip is an ASSET request: use `vibe generate image` or\n`vibe generate video` directly. A request for designed/animated overlays\non an existing clip is usually `vibe edit motion-overlay ... --understand auto`,\nnot `vibe edit text-overlay`, unless the user explicitly asks for a simple\nstatic text burn-in. Do not invoke `/vibe-scene`, edit\n`DESIGN.md`, or edit `STORYBOARD.md` unless the user explicitly asks for a\nscene, storyboard, or composed video.\n\nTo install / update them later:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/vericontext/vibeframe/main/scripts/install-skills.sh | bash\n```\n\n## Project-specific guidance\n\n<!-- Add Claude-specific notes here: which sub-agents to prefer, custom\n     slash commands you've added, conversational style preferences, etc. -->\n";
+/**
+ * Gemini CLI project file. Gemini CLI's primary context file is
+ * `GEMINI.md` (per https://geminicli.com/docs/cli/gemini-md/), so this
+ * scaffold gives Gemini CLI users a top-level entry point that points
+ * at the canonical `AGENTS.md`. The leading `@AGENTS.md` follows the
+ * same import convention Claude Code's `CLAUDE.md` uses; Gemini CLI
+ * also honours sibling-file references in context, and the
+ * human-readable note below ensures the agent picks up `AGENTS.md`
+ * either way.
+ */
+export declare const GEMINI_MD = "@AGENTS.md\n\n# Gemini CLI overrides\n\nThis project's canonical agent guidance lives in `AGENTS.md` \u2014 read\nit first. The `@AGENTS.md` line above is the import marker; if\nGemini CLI doesn't inline imported files in your version, open\n`AGENTS.md` directly. Both files are kept in sync by `vibe init`.\n\n## Project-specific guidance\n\n<!-- Add Gemini-CLI-specific notes here: any conventions specific to\n     how you drive vibe from Gemini CLI (preferred models, tone, etc.). -->\n";
+/** Shape the init renderer can fill in for the .env.example body. */
+export interface EnvExampleOptions {
+    /** When true, surfaces a "tier: free local fallbacks" section at the top. */
+    withLocalFallbackHeader?: boolean;
+}
+/**
+ * .env.example covering all 13 providers VibeFrame integrates, grouped
+ * by tier so a new user can skip "premium / paid" without losing sight
+ * of the free path.
+ */
+export declare function renderEnvExample(opts?: EnvExampleOptions): string;
+/** Lines vibe init merges into the project's .gitignore (idempotent). */
+export declare const GITIGNORE_ADDITIONS = "\n# VibeFrame\n.env\n.env.local\nrenders/\n.pipeline-state.yaml\n*.vibe.json\n.vibeframe/\n";
+/**
+ * vibe.project.yaml minimal scaffold. Only written when no project
+ * config exists — `vibe init` never overwrites an existing file unless
+ * --force.
+ */
+export declare function renderProjectYaml(opts: {
+    name: string;
+}): string;

package/dist/commands/_shared/init-templates.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/install-skill.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @module _shared/install-skill
+ *
+ * Phase H1 — install the vendored Hyperframes skill bundle into a user's
+ * scene project so that the host agent (Claude Code, Cursor, Codex, Aider,
+ * etc.) can read the framework rules + house style directly. This is the
+ * agentic-CLI-native pattern: the host agent is the sole LLM that reasons
+ * about scene composition, and it does so with the skill files in its
+ * context — VibeFrame's CLI is the deterministic toolbelt.
+ *
+ * Layout written:
+ *
+ *   <project>/
+ *     SKILL.md                              # universal — all agents see this
+ *     references/
+ *       house-style.md
+ *       motion-principles.md
+ *       typography.md
+ *       transitions.md
+ *     .claude/skills/hyperframes/           # if hosts includes "claude-code"
+ *       SKILL.md (copy)
+ *       references/{house-style,...}.md
+ *     .cursor/rules/hyperframes.mdc         # if hosts includes "cursor"
+ *
+ * Codex + Aider are AGENTS.md-driven hosts; they read the project root
+ * SKILL.md via an `@SKILL.md` reference in AGENTS.md (handled by the
+ * init-templates AGENTS_MD section, not here).
+ *
+ * The content is byte-identical to what `loadHyperframesSkillBundle()`
+ * uses — same vendored files, same `BUNDLE_VERSION`. After install, the
+ * agentic compose path (Phase H2) reads these files instead of the
+ * vendored TS string constants, so users can edit them per project.
+ */
+import type { AgentHostId } from "../../utils/agent-host-detect.js";
+/** Hosts the install-skill command knows file layouts for. */
+export type InstallSkillHost = "claude-code" | "cursor" | "all";
+export interface InstallSkillOptions {
+    /** Project directory (must exist or be creatable). */
+    projectDir: string;
+    /**
+     * Hosts to install host-specific copies for. The universal `SKILL.md` +
+     * `references/` directory at the project root are always written.
+     * Pass `["all"]` to install every host-specific layout.
+     */
+    hosts: InstallSkillHost[];
+    /** Overwrite existing files. Default false (skip-on-exist). */
+    force?: boolean;
+    /** Don't write — just describe what would happen. */
+    dryRun?: boolean;
+}
+export type InstallSkillFileStatus = "wrote" | "skipped-exists" | "would-write" | "would-skip-exists";
+export interface InstallSkillFileAction {
+    path: string;
+    status: InstallSkillFileStatus;
+    bytes: number;
+}
+export interface InstallSkillResult {
+    success: boolean;
+    bundleVersion: string;
+    files: InstallSkillFileAction[];
+}
+/**
+ * Install Hyperframes skill files at the project + host-specific paths.
+ *
+ * Idempotent by default — existing files are skipped (logged as
+ * `skipped-exists`). Pass `force: true` to overwrite. `dryRun: true`
+ * reports the same actions but with `would-*` status and writes nothing.
+ */
+export declare function installHyperframesSkill(opts: InstallSkillOptions): Promise<InstallSkillResult>;
+/**
+ * Map an `AgentHostId[]` (from `detectedAgentHosts()`) to the
+ * install-skill command's host vocabulary. Codex / Aider don't get
+ * host-specific layouts — they read the universal `SKILL.md` via
+ * AGENTS.md, so they're filtered out here.
+ */
+export declare function deriveInstallHosts(detected: AgentHostId[]): InstallSkillHost[];

package/dist/commands/_shared/install-skill.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/openai-image.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module _shared/openai-image
+ *
+ * Shared OpenAI `generateImage` helper for `vibe ai image` and
+ * `vibe generate image`. Both commands had their own near-identical
+ * provider initialisation + model-alias parsing + result construction.
+ * v0.52.0 added gpt-image-2 wiring to `ai-image.ts` only and
+ * `vibe generate image -m 2` silently fell back to gpt-image-1.5 — the
+ * duplication guarantees a recurrence next time the OpenAI image flow
+ * is touched.
+ *
+ * Each top-level command keeps its own CLI wiring and output formatting;
+ * this helper owns just the API call + label derivation.
+ *
+ * See issue #58.
+ */
+import type { ImageResult } from "@vibeframe/ai-providers";
+/** Subset of CLI options consumed by the helper. */
+export interface OpenAIImageHelperOptions {
+    model?: string;
+    size?: string;
+    quality?: string;
+    style?: string;
+    /** Stringified count from commander; parsed inside the helper. */
+    count?: string;
+}
+export interface OpenAIImageHelperResult {
+    result: ImageResult;
+    /** Resolved model id passed to the API. */
+    openaiModel: "gpt-image-2" | "gpt-image-1.5";
+    /** Human-friendly label for spinner / success output. */
+    modelLabel: "GPT Image 2" | "GPT Image 1.5";
+}
+/**
+ * Resolve the user-supplied model alias to the API id + display label.
+ * Exported so unit tests can assert label↔model parity (regression cover
+ * for v0.52.0 bug).
+ */
+export declare function resolveOpenAIImageModel(modelAlias?: string): {
+    openaiModel: "gpt-image-2" | "gpt-image-1.5";
+    modelLabel: "GPT Image 2" | "GPT Image 1.5";
+};
+/**
+ * Run an OpenAI image generation. Caller owns: api-key acquisition,
+ * spinner lifecycle, output formatting (JSON vs human), and file save.
+ */
+export declare function executeOpenAIImageGenerate(prompt: string, options: OpenAIImageHelperOptions, ctx: {
+    apiKey: string;
+}): Promise<OpenAIImageHelperResult>;

package/dist/commands/_shared/openai-image.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/product-surface.d.ts

@@ -0,0 +1,11 @@
+export declare const PRODUCT_SURFACES: readonly ["public", "agent", "advanced", "legacy", "internal"];
+export type ProductSurface = (typeof PRODUCT_SURFACES)[number];
+export interface ProductSurfaceMetadata {
+    surface: ProductSurface;
+    replacement?: string;
+    note?: string;
+}
+export declare function isProductSurface(value: string | undefined): value is ProductSurface;
+export declare function productSurfaceForCommandPath(path: string): ProductSurfaceMetadata;
+export declare function commandPathFromToolName(name: string): string;
+export declare function productSurfaceForToolName(name: string): ProductSurfaceMetadata;

package/dist/commands/_shared/product-surface.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/project-config.d.ts

@@ -0,0 +1,60 @@
+import type { SceneAspect } from "./scene-project.js";
+export declare const VIBE_CONFIG_FILENAME = "vibe.config.json";
+export declare const LEGACY_VIBE_PROJECT_FILENAME = "vibe.project.yaml";
+export type CompositionEngine = "hyperframes";
+export type ProjectImageProvider = "openai" | "gemini" | "grok" | null;
+export type ProjectVideoProvider = "seedance" | "grok" | "kling" | "runway" | "veo" | null;
+export type ProjectNarrationProvider = "elevenlabs" | "kokoro" | null;
+export type ProjectComposerProvider = "claude" | "openai" | "gemini" | null;
+export type ProjectQuality = "draft" | "standard" | "high";
+export interface VibeProjectConfigV1 {
+    schemaVersion: "1";
+    name: string;
+    aspect: SceneAspect;
+    defaults: {
+        sceneDurationSec: number;
+        narrationPaddingSec: number;
+        fps: 24 | 30 | 60;
+        quality: ProjectQuality;
+    };
+    providers: {
+        image: ProjectImageProvider;
+        video: ProjectVideoProvider;
+        narration: ProjectNarrationProvider;
+        music: string | null;
+        composer: ProjectComposerProvider;
+    };
+    build: {
+        mode: "agent" | "batch" | "auto";
+        stage: "all" | "assets" | "compose" | "sync" | "render";
+        maxCostUsd: number | null;
+        imageQuality: "standard" | "hd";
+        imageSize: "1024x1024" | "1536x1024" | "1024x1536";
+    };
+    composition: {
+        engine: CompositionEngine;
+        entry: string;
+        compositionsDir: string;
+        assetsDir: string;
+        rendersDir: string;
+    };
+}
+export interface LoadedProjectConfig {
+    config: VibeProjectConfigV1;
+    /** `vibe.config.json`, `vibe.project.yaml`, or `default`. */
+    source: string;
+    path: string | null;
+    legacy: boolean;
+}
+export declare function defaultProjectConfig(opts: {
+    name: string;
+    aspect?: SceneAspect;
+    sceneDurationSec?: number;
+}): VibeProjectConfigV1;
+export declare function mergeProjectConfig(parsed: Partial<VibeProjectConfigV1> | null | undefined, fallback: VibeProjectConfigV1): VibeProjectConfigV1;
+export declare function projectConfigJson(opts: {
+    name: string;
+    aspect?: SceneAspect;
+    sceneDurationSec?: number;
+}): string;
+export declare function readProjectConfig(projectDir: string): Promise<LoadedProjectConfig>;

package/dist/commands/_shared/render-inspect.d.ts

@@ -0,0 +1,104 @@
+import type { VideoReviewFeedback } from "../ai-edit.js";
+import { type ReviewIssue, type ReviewSeverity, type ReviewSummary, type ReviewStatus } from "./review-report.js";
+export interface TimeRange {
+    start: number;
+    end: number;
+    duration: number;
+}
+export interface BeatTiming {
+    id: string;
+    start: number;
+    end: number;
+    sceneDurationSec: number;
+    narrationDurationSec?: number;
+}
+export type RenderInspectModel = "flash" | "flash-2.5" | "pro";
+export interface RenderInspectOptions {
+    projectDir: string;
+    beatId?: string;
+    videoPath?: string;
+    outputPath?: string;
+    writeReport?: boolean;
+    ai?: boolean;
+    model?: RenderInspectModel;
+}
+export interface RenderInspectDryRunResult {
+    schemaVersion: "1";
+    kind: "render";
+    project: string;
+    beat?: string;
+    videoPath: string | null;
+    reportPath?: string;
+    params: {
+        projectDir: string;
+        beatId?: string;
+        videoPath?: string;
+        outputPath?: string;
+        writeReport: boolean;
+        cheap: true;
+        ai: boolean;
+        model: RenderInspectModel;
+    };
+    checks: {
+        renderFound: boolean;
+        storyboardPath: string | null;
+    };
+}
+export interface RenderAiCheck {
+    enabled: true;
+    model: RenderInspectModel;
+    success: boolean;
+    overallScore?: number;
+    categories?: VideoReviewFeedback["categories"];
+    recommendations?: string[];
+    error?: string;
+}
+export interface RenderInspectResult {
+    schemaVersion: "1";
+    kind: "render";
+    mode: "render";
+    project: string;
+    beat?: string;
+    videoPath: string | null;
+    status: ReviewStatus;
+    score: number;
+    issues: ReviewIssue[];
+    summary: ReviewSummary;
+    sourceReports: string[];
+    checks: {
+        renderFound: boolean;
+        fileSizeBytes?: number;
+        durationSec?: number;
+        expectedDurationSec?: number;
+        durationDriftSec?: number;
+        width?: number;
+        height?: number;
+        expectedAspect?: string;
+        hasAudio?: boolean;
+        blackFrames: TimeRange[];
+        staticFrames: TimeRange[];
+        silences: TimeRange[];
+        ai?: RenderAiCheck;
+    };
+    retryWith: string[];
+    reportPath?: string;
+}
+export declare function parseBlackdetectOutput(output: string): TimeRange[];
+export declare function parseSilencedetectOutput(output: string): TimeRange[];
+export declare function parseFreezedetectOutput(output: string): TimeRange[];
+export declare function staticFrameIssueForRange(range: TimeRange, beats: BeatTiming[], videoPath?: string): ReviewIssue;
+export declare function blackFrameIssueForRange(range: TimeRange, beats: BeatTiming[], videoPath?: string): ReviewIssue;
+export declare function durationDriftIssue(params: {
+    durationSec: number;
+    expectedDurationSec: number;
+    driftSec: number;
+    beats: BeatTiming[];
+    beatId?: string;
+    videoPath?: string;
+}): ReviewIssue;
+export declare function previewInspectRender(opts: RenderInspectOptions): Promise<RenderInspectDryRunResult>;
+export declare function aiReviewSeverity(score: number): ReviewSeverity;
+export declare function mapAiReviewFeedbackToIssues(feedback: VideoReviewFeedback, videoPath?: string): ReviewIssue[];
+export declare function scoreRenderReview(issues: ReviewIssue[], aiOverallScore?: number): number;
+export declare function inspectRender(opts: RenderInspectOptions): Promise<RenderInspectResult>;
+export declare function resolveRenderVideoPath(projectDir: string, explicit?: string, beatId?: string): Promise<string | null>;

package/dist/commands/_shared/render-inspect.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commands/_shared/review-report.d.ts

@@ -0,0 +1,65 @@
+export type ReviewSeverity = "error" | "warning" | "info";
+export type ReviewStatus = "pass" | "warn" | "fail";
+export type ReviewMode = "project" | "render";
+export type ReviewFixOwner = "vibe" | "host-agent";
+export interface ReviewIssue {
+    severity: ReviewSeverity;
+    code: string;
+    message: string;
+    file?: string;
+    scene?: string;
+    beatId?: string;
+    timeRange?: {
+        start: number;
+        end: number;
+        duration?: number;
+    };
+    sceneDurationSec?: number;
+    narrationDurationSec?: number;
+    audioCoverageRatio?: number;
+    fixOwner?: ReviewFixOwner;
+    suggestedFix?: string;
+}
+export interface ReviewSummary {
+    issueCount: number;
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+    fixOwners: {
+        vibe: number;
+        hostAgent: number;
+    };
+}
+export interface ReviewReport {
+    schemaVersion: "1";
+    kind: "review";
+    project: string;
+    mode: ReviewMode;
+    beat?: string;
+    status: ReviewStatus;
+    score: number;
+    issues: ReviewIssue[];
+    summary: ReviewSummary;
+    retryWith: string[];
+    sourceReports: string[];
+    reportPath?: string;
+}
+export declare function statusFromIssues(issues: ReviewIssue[]): ReviewStatus;
+export declare function scoreIssues(issues: ReviewIssue[]): number;
+export declare function uniqueRetryWith(items: Array<string | undefined | null>): string[];
+export declare function fixOwnerForIssue(issue: Pick<ReviewIssue, "code" | "fixOwner">): ReviewFixOwner;
+export declare function normalizeReviewIssues(issues: ReviewIssue[], fallbackOwner?: ReviewFixOwner): ReviewIssue[];
+export declare function summarizeReviewIssues(issues: ReviewIssue[]): ReviewSummary;
+export declare function buildReviewReport(opts: {
+    project: string;
+    mode: ReviewMode;
+    beat?: string;
+    status: ReviewStatus;
+    score: number;
+    issues: ReviewIssue[];
+    retryWith: string[];
+    sourceReports?: string[];
+    reportPath?: string;
+}): ReviewReport;
+export declare function defaultReviewReportPath(projectDir: string): string;
+export declare function writeReviewReport(path: string, report: Record<string, unknown>): Promise<void>;

package/dist/commands/_shared/root-sync.d.ts

@@ -0,0 +1,39 @@
+import type { ReviewIssue } from "./review-report.js";
+export declare const ROOT_SYNC_FIX_CODES: {
+    readonly clipRefs: "root_clip_refs_synced";
+    readonly duration: "root_duration_synced";
+    readonly narrationAudio: "root_narration_audio_synced";
+    readonly musicAudio: "root_music_audio_synced";
+};
+export interface RootSyncBeatInput {
+    id: string;
+    duration?: number;
+    narrationPath?: string;
+    musicPath?: string;
+    sceneDurationSec?: number;
+}
+export interface RootSyncPlan {
+    rootPath: string;
+    rootRel: string;
+    exists: boolean;
+    changed: boolean;
+    fixCodes: string[];
+    issues: ReviewIssue[];
+    nextHtml?: string;
+    totalDurationSec?: number;
+}
+export declare function createRootSyncPlan(opts: {
+    projectDir: string;
+    beats: RootSyncBeatInput[];
+    rootRel?: string;
+}): Promise<RootSyncPlan>;
+export declare function createProjectRootSyncPlan(opts: {
+    projectDir: string;
+    rootRel?: string;
+}): Promise<RootSyncPlan>;
+export declare function syncRootComposition(opts: {
+    projectDir: string;
+    beats: RootSyncBeatInput[];
+    rootRel?: string;
+}): Promise<RootSyncPlan>;
+export declare function loadProjectRootSyncBeats(projectDir: string): Promise<RootSyncBeatInput[]>;

package/dist/commands/_shared/scene-audio-mux.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @module _shared/scene-audio-mux
+ *
+ * Lay every `<audio>` element discovered by `scene-audio-scan.ts` onto a
+ * single audio track and mux it into the producer's silent video output.
+ *
+ * Why this exists: `@hyperframes/producer` renders frames + assembles the
+ * MP4 but does not embed audio from sub-composition `<audio>` elements
+ * (verified against the upstream Hyperframes reference example). We do the
+ * mux ourselves with one ffmpeg pass, copying the producer's video stream
+ * untouched so we don't pay a re-encode tax.
+ *
+ * The filter graph for N audio inputs is:
+ *
+ *   [1:a]adelay=Sms:all=1,volume=V[a1];
+ *   [2:a]adelay=Sms:all=1,volume=V[a2];
+ *   ...
+ *   [a1][a2]...amix=inputs=N:dropout_transition=0:normalize=0[mixed]
+ *
+ * Single-input case skips the amix (cheaper and avoids amix's auto-gain).
+ *
+ * Pure construction lives in `buildAudioMuxFilter`. The async `muxAudioIntoVideo`
+ * shells out to ffmpeg via the project's existing `execSafe` wrapper.
+ */
+import type { SceneAudioElement } from "./scene-audio-scan.js";
+export interface AudioMuxFilter {
+    /** ffmpeg `-filter_complex` string. */
+    filterComplex: string;
+    /** Output stream label inside the graph (e.g. `[mixed]` or `[a0]`). */
+    outLabel: string;
+    /** Number of audio inputs the caller must `-i` before this filter. */
+    inputCount: number;
+}
+/**
+ * Build a filter_complex for the given audio elements. Pure — no I/O.
+ *
+ * Each element becomes one ffmpeg input (input index 1, 2, ... — input 0 is
+ * the silent video). `adelay` shifts the audio to its absolute timeline
+ * start, `volume` applies per-element gain, and `amix` blends them. When
+ * there's only one element we skip `amix` entirely.
+ */
+export declare function buildAudioMuxFilter(audios: SceneAudioElement[]): AudioMuxFilter | null;
+export interface AudioMuxOptions {
+    /** Producer's silent video output (will be replaced with the mux'd file). */
+    videoPath: string;
+    /** Audio elements with absolute timing, from `scanSceneAudio`. */
+    audios: SceneAudioElement[];
+    /** Final output container — drives the audio codec choice. */
+    format: "mp4" | "webm" | "mov";
+    /** Cap output to this many seconds via ffmpeg `-t`. Falls back to `videoDuration`. */
+    totalDuration?: number;
+    /** Producer's video duration (probed by ffprobe). Used as default cap. */
+    videoDuration?: number;
+    /** Callback for ffmpeg stderr lines (progress / errors). */
+    onProgress?: (line: string) => void;
+}
+export interface AudioMuxResult {
+    /** True when ffmpeg succeeded. */
+    success: boolean;
+    /** Absolute path of the produced file (overwrites the input on success). */
+    outputPath: string;
+    /** ffmpeg stderr tail when success === false. */
+    error?: string;
+    /** Number of audio inputs muxed. */
+    audioCount: number;
+}
+/**
+ * Run ffmpeg to overlay every `<audio>` element onto the producer's silent
+ * video. Replaces the input file on success. Idempotent — re-running on the
+ * same project repeats the work but produces an equivalent result.
+ *
+ * No-op (`success: true, audioCount: 0`) when `audios` is empty.
+ */
+export declare function muxAudioIntoVideo(opts: AudioMuxOptions): Promise<AudioMuxResult>;

package/dist/commands/_shared/scene-audio-mux.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Unit tests for scene-audio-mux. Pure construction only — `muxAudioIntoVideo`
+ * is exercised by the C3 smoke test, not here, so CI doesn't depend on
+ * ffmpeg installation.
+ */
+export {};