@vibeframe/cli 0.113.30 → 0.115.0

package/dist/commands/_shared/build-plan.d.ts

@@ -1,5 +1,6 @@
 import { type BuildAssetKind } from "./build-cache.js";
 import { type AssetFreshness } from "./build-asset-metadata.js";
+import { type BeatCues } from "./storyboard-parse.js";
 import { type LoadedProjectConfig } from "./project-config.js";
 import { type StoryboardValidationIssue } from "./storyboard-edit.js";
 export type BuildStage = "assets" | "transcript" | "compose" | "sync" | "render" | "all";
@@ -11,7 +12,7 @@ export interface BuildPlanBeat {
     id: string;
     heading: string;
     durationSec: number | null;
-    cues: Record<string, unknown>;
+    cues: BeatCues;
     assets: {
         narration: AssetPlan | null;
         backdrop: AssetPlan | null;

package/dist/commands/_shared/compose-prompts.d.ts

@@ -1,7 +1,7 @@
 /**
  * @module _shared/compose-prompts
  *
- * Phase H2 — agentic compose primitive. Reads `STORYBOARD.md` + `DESIGN.md`
+ * Agentic compose primitive. Reads `STORYBOARD.md` + `DESIGN.md`
  * from a scene project and emits a structured plan for the host agent
  * (Claude Code, Cursor, Codex, Aider) to author per-beat HTML files
  * itself. **No LLM call from inside the CLI** — that's the point. The
@@ -31,6 +31,7 @@
  * This is the only model-authored compose path: the host agent writes each
  * file. `--composer template` is the deterministic alternative.
  */
+import { type BeatCues } from "./storyboard-parse.js";
 export interface ComposePromptsBeat {
     /** Stable beat id from `parseStoryboard().deriveBeatId()`. */
     id: string;
@@ -48,7 +49,7 @@ export interface ComposePromptsBeat {
      */
     finalDurationSec?: number;
     /** Per-beat YAML cues parsed from the leading code block of the body. */
-    cues?: Record<string, unknown>;
+    cues?: BeatCues;
     /** Beat body markdown (with the leading `\`\`\`yaml` cue block stripped). */
     body: string;
     /**

package/dist/commands/_shared/help-groups.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @module commands/_shared/help-groups
+ *
+ * Groups the root `vibe --help` command listing by use case instead of
+ * alphabetically.
+ *
+ * Before this, the root help printed the same commands twice: once as
+ * Commander's flat alphabetical `Commands:` block, then again under a
+ * "Common workflows" footer that re-listed most of them by use case. The
+ * footer's own preamble admitted it ("the alphabetical list above is the
+ * full command set; this section shows the typical entry points by use
+ * case"), which left the reader to map the two lists onto each other.
+ *
+ * Descriptions are read from the live command tree rather than restated
+ * here, so this file can only ever drift in *grouping*, never in wording.
+ * A command missing from {@link COMMAND_GROUPS} lands in a trailing
+ * "Other" group rather than disappearing; `help-groups.test.ts` asserts
+ * that group stays empty so adding a top-level command fails the test
+ * instead of silently degrading the help.
+ */
+import type { Command } from "commander";
+/**
+ * Use-case groups for the root help listing, in display order.
+ *
+ * Ordered by the sequence a first-time reader needs them: build a project
+ * video, reach for a one-off asset, then wire up hosts and automation.
+ */
+export declare const COMMAND_GROUPS: ReadonlyArray<{
+    readonly title: string;
+    readonly commands: readonly string[];
+}>;
+/**
+ * Top-level commands that appear in help, excluding hidden ones and
+ * Commander's auto-generated `help` command.
+ */
+export declare function visibleTopLevelCommands(prog: Command): Command[];
+/**
+ * Visible top-level command names that no group in {@link COMMAND_GROUPS}
+ * claims. Empty in a healthy tree; the test asserts that.
+ */
+export declare function ungroupedCommandNames(prog: Command): string[];
+/**
+ * Render the grouped command listing for the root `vibe --help`.
+ *
+ * Returns the block that replaces Commander's flat `Commands:` section,
+ * already prefixed and suffixed with a blank line so it slots between the
+ * options block and the remaining help footers.
+ */
+export declare function renderCommandGroups(prog: Command): string;

package/dist/commands/_shared/help-groups.test.d.ts

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

package/dist/commands/_shared/storyboard-edit.d.ts

@@ -1,6 +1,5 @@
 import { type Beat } from "./storyboard-parse.js";
-export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset", "characters", "eyebrow", "title", "caption", "kicker", "sub"];
-export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
+export { STORYBOARD_CUE_KEYS, type StoryboardCueKey } from "./storyboard-parse.js";
 export interface StoryboardValidationIssue {
     severity: "error" | "warning";
     code: string;
@@ -40,3 +39,14 @@ export declare function moveStoryboardBeat(markdown: string, opts: {
     beatId: string;
     afterBeatId: string;
 }): string;
+/**
+ * True for the untouched three-beat scaffold. Exported so the bundle writer
+ * makes the same "this is still the starter, replace it" call as the
+ * single-document writer, off the same assembled markdown.
+ */
+export declare function isStarterStoryboard(markdown: string): boolean;
+/**
+ * Coerce and validate one cue value. Shared with the bundle writer so both
+ * storage layouts reject the same bad input.
+ */
+export declare function normalizeCueValue(key: string, value: unknown): unknown;

package/dist/commands/_shared/storyboard-parse.d.ts

@@ -94,25 +94,36 @@ export interface ResolvedCharacter {
  * (generation skipped). Entries with neither are dropped.
  */
 export declare function resolveCharacters(frontmatter: ProjectFrontmatter | undefined): ResolvedCharacter[];
+/**
+ * The complete per-beat cue vocabulary, in the order it is presented to
+ * humans and agents.
+ *
+ * This is the single source of truth. {@link BeatCues} is derived from it,
+ * `validateStoryboardMarkdown` rejects anything outside it, `vibe storyboard
+ * set` refuses unlisted keys, and the compose and revise prompts render it
+ * rather than restating it - four surfaces had drifted to four different
+ * sub-lists before this became the one list.
+ */
+export declare const STORYBOARD_CUE_KEYS: readonly ["duration", "narration", "backdrop", "video", "keyframe", "motion", "voice", "music", "asset", "characters", "eyebrow", "title", "caption", "kicker", "sub"];
+export type StoryboardCueKey = (typeof STORYBOARD_CUE_KEYS)[number];
 /**
  * Per-beat cues extracted from the first ```yaml fenced block inside a beat
  * body. The driver passes these to TTS / image / compose calls so the
  * storyboard alone is enough source for `vibe scene build`.
+ *
+ * Every key in {@link STORYBOARD_CUE_KEYS} is declared here. There is
+ * deliberately no index signature: an unlisted key is a validation warning at
+ * runtime, so letting it typecheck only hides the drift.
  */
 export interface BeatCues {
+    /** Beat duration in seconds; overrides the `### Beat duration` subsection if both are present. */
+    duration?: number;
     /** Narration text for this beat (drives TTS + scene `<audio>` element). */
     narration?: string;
     /** Image prompt for the backdrop generation (drives T2I). */
     backdrop?: string;
-    /** Beat duration in seconds — overrides `### Beat duration` subsection if both present. */
-    duration?: number;
-    /** Voice override for this beat (overrides project frontmatter `voice`). */
-    voice?: string;
-    /**
-     * Character pool names whose reference sheets drive this beat's
-     * reference-to-video generation. A single name or a list.
-     */
-    characters?: string | string[];
+    /** Motion prompt for video generation. Pairs with `keyframe` for image-to-video. */
+    video?: string;
     /**
      * Keyframe still prompt. When set, the build generates a keyframe image for
      * this beat (using the character sheet as an edit reference when `characters`
@@ -120,13 +131,34 @@ export interface BeatCues {
      * if present, supplies the motion prompt; otherwise this text is used.
      */
     keyframe?: string;
+    /**
+     * Animation direction for the scene-authoring agent, e.g. "restrained camera
+     * push, headline settles first". Unlike the cues around it this drives no
+     * deterministic stage - it reaches the host agent through the compose plan
+     * and shapes the HTML that agent writes.
+     */
+    motion?: string;
+    /** Voice override for this beat (overrides project frontmatter `voice`). */
+    voice?: string;
+    /** Music prompt or a project-relative path to an existing track. */
+    music?: string;
+    /** Project-relative path to a file this beat should reuse instead of generating. */
+    asset?: string;
+    /**
+     * Character pool names whose reference sheets drive this beat's
+     * reference-to-video generation. A single name or a list.
+     */
+    characters?: string | string[];
     /** Lower-third overlay eyebrow/kicker (read by the deterministic composer). */
     eyebrow?: string;
     /** Lower-third headline; falls back to the beat heading when absent. */
     title?: string;
     /** Lower-third sub-line / caption. */
     caption?: string;
-    [key: string]: unknown;
+    /** Alias for `eyebrow`; `eyebrow` wins when both are present. */
+    kicker?: string;
+    /** Alias for `caption`; `caption` wins when both are present. */
+    sub?: string;
 }
 /** Normalize a beat's `characters` cue to a clean string[] (single or list). */
 export declare function beatCharacterNames(cues: BeatCues | undefined): string[];

package/dist/commands/_shared/storyboard-source.d.ts

@@ -0,0 +1,228 @@
+/**
+ * @module _shared/storyboard-source
+ *
+ * Resolves where a project's storyboard actually lives and hands back one
+ * markdown document either way.
+ *
+ * Two on-disk layouts are supported:
+ *
+ * **bundle** (preferred) - `STORYBOARD.md` holds project frontmatter and
+ * direction prose, and `scenes/NN-<id>.md` holds one scene per file with its
+ * cues in real document frontmatter:
+ *
+ * ```text
+ * launch/
+ *   STORYBOARD.md        --- type/title/duration/aspect/providers/characters ---
+ *   scenes/
+ *     01-hook.md         --- duration/narration/backdrop/... ---  + body
+ *     02-proof.md
+ * ```
+ *
+ * **single** (legacy) - one `STORYBOARD.md` with `## Beat <id> - <title>`
+ * headings, each carrying a leading ```yaml cue block.
+ *
+ * The bundle layout exists because `---` frontmatter is a *document* level
+ * construct. Used mid-document it is not frontmatter at all: the opening
+ * `---` is a horizontal rule and the closing one turns the lines above it
+ * into a setext heading. One scene per file is the only way per-scene cues
+ * can be written as frontmatter and still render correctly.
+ *
+ * A bundle is assembled back into the single-document shape in memory, so
+ * every existing consumer of `parseStoryboard()` keeps working unchanged.
+ * That is deliberate: the on-disk format users edit is decoupled from the
+ * in-memory representation the build already understands.
+ */
+import { type Beat, type BeatCues } from "./storyboard-parse.js";
+/** Directory, relative to the project root, that holds one file per scene. */
+export declare const SCENES_DIRNAME = "scenes";
+/** The project-level document, present in both layouts. */
+export declare const STORYBOARD_FILENAME = "STORYBOARD.md";
+export type StoryboardLayout = "bundle" | "single" | "missing";
+export interface SceneFile {
+    /** Beat id derived from the filename, with any ordering prefix stripped. */
+    id: string;
+    /** Absolute path to the scene file. */
+    path: string;
+    /** Filename, e.g. `01-hook.md`. */
+    filename: string;
+    /** Numeric ordering prefix when present (`01-hook.md` -> 1). */
+    order: number | null;
+}
+export interface LoadedStoryboard {
+    layout: StoryboardLayout;
+    /** One markdown document in the legacy single-file shape. */
+    markdown: string;
+    /** Scene files, in play order. Empty for the single layout. */
+    scenes: SceneFile[];
+    /** Absolute path of the project-level document. */
+    storyboardPath: string;
+    /**
+     * Beat ids found as `## Beat ...` headings inside STORYBOARD.md while the
+     * project is a bundle. Those headings are ignored - `scenes/` is the only
+     * source of scenes - and reported so validation can say so out loud.
+     * Always empty for the single layout.
+     */
+    strayBeatIds: string[];
+}
+/**
+ * Scene files in play order: numeric prefix first (ascending), then any
+ * unprefixed files in filename order. Mixing the two is legal but a lint
+ * elsewhere should discourage it.
+ */
+export declare function listSceneFiles(projectDir: string): Promise<SceneFile[]>;
+export declare function detectStoryboardLayout(projectDir: string, sceneCount: number): StoryboardLayout;
+/**
+ * Turn one scene file into the `## Beat <id> - <Title>` + cue-block section
+ * the single-document parser expects.
+ *
+ * `type:` is dropped: it is OKF bookkeeping identifying the file as a scene,
+ * not a cue, and passing it through would trip the unknown-cue warning.
+ * A `title:` in scene frontmatter is a lower-third cue, so the heading uses
+ * the humanised id and `title` stays in the cue block where it belongs.
+ */
+export declare function sceneToBeatSection(scene: SceneFile, contents: string): string;
+/**
+ * Load a project's storyboard as a single markdown document, whichever
+ * layout it uses on disk.
+ *
+ * For a bundle, STORYBOARD.md contributes only its frontmatter and direction
+ * prose. Anything from its first `## ` heading onward is dropped and its beat
+ * ids returned in `strayBeatIds`.
+ *
+ * Concatenating instead would merge two sets of scenes into one timeline: a
+ * project that has both would silently render the STORYBOARD.md beats *and*
+ * the scene files, in that order. `scenes/` is the layout the project opted
+ * into, so it is the only source of scenes, and the leftovers are surfaced as
+ * a validation error rather than quietly obeyed or quietly discarded.
+ */
+export declare function loadStoryboard(projectDir: string): Promise<LoadedStoryboard>;
+/** Convenience for the many call sites that only want the markdown. */
+export declare function loadStoryboardMarkdown(projectDir: string): Promise<string>;
+/** `01-hook.md` for order 1 and id `hook`. Two digits until a project needs three. */
+export declare function sceneFilename(order: number, id: string): string;
+export interface MigrationPlanFile {
+    /** Path relative to the project root, e.g. `scenes/01-hook.md`. */
+    path: string;
+    contents: string;
+}
+export interface MigrationPlan {
+    /** Files to create, in play order. */
+    scenes: MigrationPlanFile[];
+    /** What STORYBOARD.md becomes: frontmatter + direction prose, no beats. */
+    storyboard: MigrationPlanFile;
+    /** Beat ids in the order they will play. */
+    beatIds: string[];
+}
+/**
+ * Render one beat as a standalone scene document.
+ *
+ * Cues become real frontmatter, which is the whole point of the bundle
+ * layout. `type: Scene` is added so the file is a valid OKF document; the
+ * loader strips it again on the way back in.
+ */
+export declare function beatToSceneFile(beat: Beat, order: number): MigrationPlanFile;
+/**
+ * Plan the conversion of a single-document storyboard into a bundle.
+ *
+ * Pure: returns the files to write without touching disk, so the command can
+ * offer `--dry-run` and so the whole shape is testable.
+ */
+export declare function planMigration(markdown: string): MigrationPlan;
+/**
+ * Set or unset one cue in a scene file, rewriting only that file's
+ * frontmatter and leaving its body untouched.
+ *
+ * Key validation and value coercion come from the same helpers the
+ * single-document writer uses, so `duration: "abc"` is rejected identically
+ * in both layouts.
+ */
+export declare function setSceneCue(projectDir: string, opts: {
+    beatId: string;
+    key: string;
+    value?: unknown;
+    unset?: boolean;
+}): Promise<{
+    path: string;
+    cues: BeatCues;
+}>;
+/**
+ * Reorder scenes by renumbering their filename prefixes.
+ *
+ * Renames go through a temporary name first. Renaming `02 -> 01` while an
+ * `01` still exists would clobber it, and no ordering of direct renames is
+ * safe for an arbitrary permutation.
+ */
+export declare function moveScene(projectDir: string, opts: {
+    beatId: string;
+    afterBeatId: string;
+}): Promise<string[]>;
+/**
+ * Write a migration plan to disk.
+ *
+ * Scene files land before STORYBOARD.md is rewritten, so a failure part way
+ * through leaves the original single-file storyboard as the source of truth
+ * rather than a half-emptied document. Shared by `storyboard migrate` and by
+ * `vibe init`, which scaffolds straight into the bundle layout.
+ */
+export declare function writeMigration(projectDir: string, plan: MigrationPlan): Promise<void>;
+/**
+ * Scaffold a bundle from a single-document storyboard string.
+ *
+ * `vibe init` builds its starter (and its `--from` draft) as one markdown
+ * document, then hands it here rather than writing it out. That keeps one
+ * generator for the content and one converter for the layout, instead of a
+ * second scaffolder that could drift from the first.
+ */
+export declare function writeStoryboardAsBundle(projectDir: string, markdown: string): Promise<MigrationPlan>;
+/**
+ * Validation issues for beat headings left in STORYBOARD.md after a project
+ * became a bundle.
+ *
+ * An error, not a warning: the headings look like scenes and are not being
+ * rendered, so the project on disk does not describe the video that comes
+ * out. Anything less than an error lets that gap sit unnoticed.
+ */
+export declare function strayBeatIssues(strayBeatIds: string[]): Array<{
+    severity: "error";
+    code: "STRAY_BEATS_IN_STORYBOARD";
+    message: string;
+    beatId: string;
+}>;
+/**
+ * Create or update one scene file, mirroring `upsertStoryboardBeat`.
+ *
+ * The three actions match the single-document writer so `vibe scene add`
+ * reports the same thing either way:
+ *
+ * - `updated` - a scene with this id exists; its cues are merged and its
+ *   body is left alone unless a new one is supplied.
+ * - `replaced-starter` - the bundle is still the untouched three-beat
+ *   scaffold, so it is cleared rather than appended to.
+ * - `appended` - a new scene file after the current last one.
+ */
+export declare function upsertScene(projectDir: string, opts: {
+    beatId: string;
+    title?: string;
+    duration?: number;
+    narration?: string;
+    backdrop?: string;
+    body?: string;
+}): Promise<{
+    action: "updated" | "replaced-starter" | "appended";
+    path: string;
+}>;
+/**
+ * Replace a bundle's scenes with the ones described by a single markdown
+ * document.
+ *
+ * Used when something produces a whole storyboard at once - today
+ * `vibe storyboard revise`, whose model returns one document. Writing that
+ * document to STORYBOARD.md would lose the revision: `scenes/` still wins, so
+ * the old scenes would keep rendering while the new beats sat in
+ * STORYBOARD.md being reported as stray.
+ *
+ * Scene files the new document does not name are deleted, so a revision that
+ * removes a beat actually removes it rather than leaving an orphan that keeps
+ * playing.
+ */
+export declare function rewriteBundleFromMarkdown(projectDir: string, markdown: string): Promise<MigrationPlan>;

package/dist/commands/_shared/storyboard-source.test.d.ts

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

package/dist/commands/ai-motion.d.ts

@@ -21,7 +21,7 @@ export interface MotionCommandOptions {
     render?: boolean;
     /** Base video to composite the motion graphic onto */
     video?: string;
-    /** Image to analyze with Gemini — color/mood/composition fed into Claude prompt */
+    /** Image to analyze with Gemini - color/mood/composition fed into Claude prompt */
     image?: string;
     /** Analyze base video before generating motion: auto | off | required */
     understand?: "auto" | "off" | "required";

package/dist/commands/ai-review.d.ts

@@ -10,7 +10,6 @@
  *
  * @dependencies Gemini (Google), FFmpeg (auto-fix filters)
  */
-import { Command } from "commander";
 import type { VideoReviewFeedback } from "./ai-edit.js";
 /** Options for {@link executeReview}. */
 export interface ReviewOptions {
@@ -55,4 +54,3 @@ export interface ReviewResult {
  * @returns Result with structured feedback and optional fix details
  */
 export declare function executeReview(options: ReviewOptions): Promise<ReviewResult>;
-export declare function registerReviewCommand(aiCommand: Command): void;

package/dist/commands/generate/music-status.d.ts

@@ -4,7 +4,6 @@
  * generation status check. Split out of `generate.ts` in v0.69 (Plan G
  * Phase 2).
  */
-import type { Command } from "commander";
 export interface ExecuteMusicStatusOptions {
     taskId: string;
     apiKey?: string;
@@ -17,4 +16,3 @@ export interface ExecuteMusicStatusResult {
     error?: string;
 }
 export declare function executeMusicStatus(options: ExecuteMusicStatusOptions): Promise<ExecuteMusicStatusResult>;
-export declare function registerMusicStatusCommand(parent: Command): void;

package/dist/commands/generate/speech.d.ts

@@ -17,5 +17,4 @@ export interface ExecuteSpeechResult {
     error?: string;
 }
 export declare function executeSpeech(options: ExecuteSpeechOptions): Promise<ExecuteSpeechResult>;
-export declare function registerSpeechCommand(parent: Command): void;
 export declare function registerNarrationCommand(parent: Command): void;

package/dist/commands/generate/storyboard.d.ts

@@ -3,7 +3,6 @@
  * @description `vibe generate storyboard` — Claude-powered script-to-
  * storyboard analysis. Split out of `generate.ts` in v0.69 (Plan G Phase 2).
  */
-import type { Command } from "commander";
 export interface ExecuteStoryboardOptions {
     content: string;
     duration?: number;
@@ -24,4 +23,3 @@ export interface ExecuteStoryboardResult {
     error?: string;
 }
 export declare function executeStoryboard(options: ExecuteStoryboardOptions): Promise<ExecuteStoryboardResult>;
-export declare function registerStoryboardCommand(parent: Command): void;

package/dist/commands/generate.d.ts

@@ -6,15 +6,10 @@
  * Commands:
  *   generate image          - Generate image (Gemini, OpenAI, Grok, Runway)
  *   generate video          - Generate video (Seedance, Grok, Kling, Runway, Veo)
- *   generate speech         - Text-to-speech (ElevenLabs)
  *   generate sound-effect   - Sound effects (ElevenLabs)
  *   generate music          - Music generation (ElevenLabs default, Replicate MusicGen)
- *   generate music-status   - Check music generation status
- *   generate storyboard     - Script-to-storyboard (Claude)
  *   generate motion         - Standalone motion assets (Claude/Gemini + Remotion)
  *   generate thumbnail      - Thumbnail generation/extraction
- *   generate background     - AI background generation (OpenAI)
- *   generate video-status   - Check video generation status (Grok/Runway/Kling/Veo)
  *   generate video-cancel   - Cancel video generation (Grok/Runway)
  *   generate video-extend   - Extend video (Kling/Veo)
  *
@@ -25,8 +20,6 @@ export { executeSoundEffect } from "./generate/sound-effect.js";
 export type { ExecuteSoundEffectOptions, ExecuteSoundEffectResult, } from "./generate/sound-effect.js";
 export { executeMusicStatus } from "./generate/music-status.js";
 export type { ExecuteMusicStatusOptions, ExecuteMusicStatusResult, } from "./generate/music-status.js";
-export { executeBackground } from "./generate/background.js";
-export type { ExecuteBackgroundOptions, ExecuteBackgroundResult } from "./generate/background.js";
 export { executeStoryboard } from "./generate/storyboard.js";
 export type { ExecuteStoryboardOptions, ExecuteStoryboardResult } from "./generate/storyboard.js";
 export { executeSpeech } from "./generate/speech.js";

package/dist/commands/inspect.d.ts

@@ -10,8 +10,6 @@
  *   inspect project - Local project completeness and composition checks
  *   inspect render  - Local rendered video checks plus optional Gemini review
  *   inspect media   - Unified analysis for images, videos, and YouTube URLs (Gemini)
- *   inspect video   - Analyze video files or YouTube URLs with Gemini
- *   inspect review  - AI video quality review and auto-fix (Gemini)
  *   inspect suggest - Get AI edit suggestions using Gemini
  *
  * @dependencies Gemini (Google), FFmpeg (auto-fix filters)

package/dist/commands/run.d.ts

@@ -1,5 +1,5 @@
 /**
- * `vibe run` command — Execute declarative YAML video pipelines.
+ * `vibe run` command - Execute declarative YAML video pipelines.
  *
  * Video as Code: define reproducible, shareable video workflows in YAML.
  * Each step maps to an existing CLI command's execute function.