@vibeframe/cli 0.113.29 → 0.114.0

package/CONTEXT.md

@@ -125,13 +125,17 @@ vibe guide <topic> --json              # Step-by-step guides (motion | scene | p
 }
 ```
 
-| Code            | Exit | Meaning             | Recovery                   |
-| --------------- | ---- | ------------------- | -------------------------- |
-| `USAGE_ERROR`   | 2    | bad arg             | check `vibe schema <cmd>`  |
-| `NOT_FOUND`     | 3    | file missing        | verify path                |
-| `AUTH_ERROR`    | 4    | key missing/invalid | `vibe doctor`              |
-| `API_ERROR`     | 5    | provider failed     | retry if `retryable: true` |
-| `NETWORK_ERROR` | 6    | connection          | retry with backoff         |
+| Code                 | Exit | Meaning                     | Recovery                          |
+| -------------------- | ---- | --------------------------- | --------------------------------- |
+| `COST_CAP_EXCEEDED`  | 1    | estimate over `--max-cost`  | follow `retryWith`; do not re-run as-is |
+| `USAGE_ERROR`        | 2    | bad arg                     | check `vibe schema <cmd>`         |
+| `NOT_FOUND`          | 3    | file missing                | verify path                       |
+| `AUTH_ERROR`         | 4    | key missing/invalid         | `vibe doctor`                     |
+| `API_ERROR`          | 5    | provider failed             | retry if `retryable: true`        |
+| `NETWORK_ERROR`      | 6    | connection                  | retry with backoff                |
+
+`COST_CAP_EXCEEDED` also carries `data.plan` - the priced plan the refusal was
+based on - so a refused call still tells you what the build would have cost.
 
 ## Authentication
 

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

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/scene-project.d.ts

@@ -98,7 +98,7 @@ export declare function buildHyperframesConfig(): HyperframesConfig;
 export declare function buildHyperframesMeta(name: string, now?: Date): HyperframesMeta;
 /**
  * Merge an existing Hyperframes config with our defaults, preserving any
- * user-authored keys and nested values. `vibe scene init` is idempotent:
+ * user-authored keys and nested values. `vibe init` is idempotent:
  * running it on a directory that already has `hyperframes.json` must never
  * lose user config.
  */

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/output.d.ts

@@ -22,6 +22,12 @@ export interface StructuredError {
     retryWith?: string[];
     recoverable?: boolean;
     retryable: boolean;
+    /**
+     * Structured context carried alongside the failure, so a refusal can hand
+     * back the evidence it refused on instead of forcing a second call. Used by
+     * the `--max-cost` gate to return the priced build plan with the refusal.
+     */
+    data?: Record<string, unknown>;
 }
 export declare function usageError(msg: string, suggestion?: string): StructuredError;
 export declare function authError(envVar: string, provider: string): StructuredError;
@@ -29,6 +35,21 @@ export declare function apiError(msg: string, retryable?: boolean): StructuredEr
 export declare function notFoundError(path: string): StructuredError;
 export declare function networkError(msg: string): StructuredError;
 export declare function generalError(msg: string, suggestion?: string): StructuredError;
+/**
+ * The `--max-cost` refusal. A command that declines to spend is a failure, so
+ * it takes the structured error path like every other refusal: `success:false`
+ * on stderr, exit 1. `data` carries the priced plan the refusal was based on,
+ * so an agent gets the estimate and the reason from one call.
+ *
+ * `recoverable: true` because the caller has two real ways forward (raise the
+ * ceiling, or narrow the scope), both spelled out in `retryWith`.
+ */
+export declare function costCapError(opts: {
+    estimatedCostUsd: number;
+    maxCostUsd: number;
+    retryWith: string[];
+    data?: Record<string, unknown>;
+}): StructuredError;
 /** Output structured error then exit */
 export declare function exitWithError(err: StructuredError): never;
 /** Check if --json flag is active */

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.