@vibeframe/cli 0.105.1 → 0.105.2

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

@@ -0,0 +1,107 @@
+import { type BuildAssetKind } from "./build-cache.js";
+import { type AssetFreshness } from "./build-asset-metadata.js";
+import { type LoadedProjectConfig } from "./project-config.js";
+import { type StoryboardValidationIssue } from "./storyboard-edit.js";
+export type BuildStage = "assets" | "compose" | "sync" | "render" | "all";
+export type BuildPlanStatus = "ready" | "invalid";
+export type AssetPlanReason = "canonical-exists" | "canonical-stale" | "canonical-unknown" | "content-cache-hit" | "force" | "missing" | "referenced-asset" | "invalid-reference" | "stage-skipped";
+export type ProviderResolutionKind = BuildAssetKind | "composer";
+export type ProviderResolutionSource = "cli" | "storyboard" | "project-config" | "default" | "auto";
+export interface BuildPlanBeat {
+    id: string;
+    heading: string;
+    durationSec: number | null;
+    cues: Record<string, unknown>;
+    assets: {
+        narration: AssetPlan | null;
+        backdrop: AssetPlan | null;
+        video: AssetPlan | null;
+        music: AssetPlan | null;
+    };
+    composition: {
+        path: string;
+        exists: boolean;
+    };
+}
+export interface AssetPlan {
+    kind: BuildAssetKind;
+    cue: string;
+    provider: string;
+    path: string;
+    cachePath?: string;
+    cacheKey?: string;
+    metadataPath?: string;
+    freshness?: AssetFreshness;
+    sourcePath?: string;
+    referenceError?: string;
+    exists: boolean;
+    canonicalExists: boolean;
+    cacheHit: boolean;
+    willCopyFromCache: boolean;
+    willGenerate: boolean;
+    estimatedCostUsd: number;
+    reason: AssetPlanReason;
+}
+export interface ProviderResolution {
+    kind: ProviderResolutionKind;
+    requested: string | null;
+    resolved: string;
+    source: ProviderResolutionSource;
+    requiresKey: boolean;
+    configured: boolean;
+    configKey?: string;
+    missingKey?: string;
+    retryWith: string[];
+}
+export interface BuildPlanResult {
+    schemaVersion: "1";
+    kind: "build-plan";
+    projectDir: string;
+    config: LoadedProjectConfig;
+    stage: BuildStage;
+    status: BuildPlanStatus;
+    currentStage: BuildStage;
+    mode: "agent" | "batch" | "auto";
+    beat: string | null;
+    beats: BuildPlanBeat[];
+    missing: string[];
+    providers: string[];
+    providerResolution: ProviderResolution[];
+    estimatedCostUsd: number;
+    summary: BuildPlanSummary;
+    nextCommands: string[];
+    warnings: string[];
+    retryWith: string[];
+    validation: {
+        ok: boolean;
+        issues: StoryboardValidationIssue[];
+    };
+}
+export interface BuildPlanSummary {
+    beats: number;
+    missing: string[];
+    providers: string[];
+    estimatedCostUsd: number;
+    validationErrors: number;
+    validationWarnings: number;
+}
+export interface CreateBuildPlanOptions {
+    projectDir: string;
+    stage?: BuildStage;
+    beat?: string;
+    mode?: "agent" | "batch" | "auto";
+    skipNarration?: boolean;
+    skipBackdrop?: boolean;
+    skipVideo?: boolean;
+    skipMusic?: boolean;
+    ttsProvider?: string;
+    voice?: string;
+    imageProvider?: string;
+    imageQuality?: "standard" | "hd";
+    imageSize?: string;
+    videoProvider?: string;
+    musicProvider?: string;
+    composer?: string;
+    force?: boolean;
+}
+export declare function createBuildPlan(opts: CreateBuildPlanOptions): Promise<BuildPlanResult>;

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

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

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

@@ -0,0 +1,97 @@
+/**
+ * @module _shared/compose-prompts
+ *
+ * Phase H2 — 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
+ * CLI is the deterministic toolbelt; the host agent is the sole reasoner.
+ *
+ * Output shape:
+ *
+ *   {
+ *     "projectDir": "<abs>",
+ *     "designReference":     "DESIGN.md",
+ *     "storyboardReference": "STORYBOARD.md",
+ *     "skillReference":      "SKILL.md",        // present after `scene install-skill`
+ *     "compositionsDir":     "compositions",
+ *     "beats": [
+ *       { "id": "hook", "outputPath": "compositions/scene-hook.html",
+ *         "userPrompt": "...", "body": "...", "cues": {...}, "exists": false }
+ *     ],
+ *     "instructions": [...]
+ *   }
+ *
+ * Pairs with H1 (`vibe scene install-skill`) — the host agent reads
+ * `SKILL.md` for framework rules, `DESIGN.md` for visual identity, then
+ * writes each `compositions/scene-<id>.html`. After authoring, runs
+ * `vibe scene lint --fix` to verify and `vibe render` to produce MP4.
+ *
+ * The internal-LLM path (`vibe scene build`, PR #176) still works — it's
+ * the batch / non-agent fallback. H3 will add mode dispatch so a single
+ * entry point picks between agentic and batch depending on context.
+ */
+export interface ComposePromptsBeat {
+    /** Stable beat id from `parseStoryboard().deriveBeatId()`. */
+    id: string;
+    /** Original `## …` heading line (without the `## ` prefix). */
+    heading: string;
+    /** Path the agent should write the composition to (relative to projectDir). */
+    outputPath: string;
+    /** Beat duration in seconds (from cues or `### Beat duration` subsection), if known. */
+    duration?: number;
+    /** Per-beat YAML cues parsed from the leading code block of the body. */
+    cues?: Record<string, unknown>;
+    /** Beat body markdown (with the leading `\`\`\`yaml` cue block stripped). */
+    body: string;
+    /**
+     * Pre-built user prompt — the same shape `composeBeatHtml` would send to
+     * Claude / OpenAI / Gemini. The host agent consumes this directly so the
+     * agentic and batch paths produce equivalent HTML.
+     */
+    userPrompt: string;
+    /** True when `compositions/scene-<id>.html` already exists on disk. */
+    exists: boolean;
+}
+export interface ComposePromptsResult {
+    success: boolean;
+    /** Absolute project directory. */
+    projectDir: string;
+    /** Project-root-relative path to DESIGN.md (always "DESIGN.md"). */
+    designReference: string;
+    /** Project-root-relative path to STORYBOARD.md (always "STORYBOARD.md"). */
+    storyboardReference: string;
+    /**
+     * Project-root-relative path to the universal Hyperframes SKILL.md.
+     * `null` when the skill hasn't been installed — the
+     * `warnings` field then carries an actionable hint.
+     */
+    skillReference: string | null;
+    /** Project-root-relative compositions directory (always "compositions"). */
+    compositionsDir: string;
+    /** Per-beat plan, ordered by source document position. */
+    beats: ComposePromptsBeat[];
+    /** Step-by-step instructions for the host agent. */
+    instructions: string[];
+    /** Hyperframes bundle version — informational; ties cache keys back to the internal-LLM path. */
+    bundleVersion: string;
+    /** Non-fatal hints surfaced to the agent (e.g. missing SKILL.md). */
+    warnings: string[];
+    /** Set when {@link success} is false. */
+    error?: string;
+}
+export interface ComposePromptsOptions {
+    /** Project directory containing STORYBOARD.md / DESIGN.md. */
+    projectDir: string;
+    /**
+     * Restrict output to a single beat id. When unset, every beat in the
+     * storyboard is emitted.
+     */
+    beatId?: string;
+}
+/**
+ * Build the agent compose plan from a scene project on disk. Pure I/O —
+ * no network, no LLM, no mutation. Caller (CLI handler / manifest tool /
+ * MCP surface) decides how to surface the result.
+ */
+export declare function getComposePrompts(opts: ComposePromptsOptions): Promise<ComposePromptsResult>;

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

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

package/dist/commands/_shared/compose-scenes-skills.d.ts

@@ -0,0 +1,282 @@
+/**
+ * @module _shared/compose-scenes-skills
+ *
+ * Single-beat Claude composer for the `compose-scenes-with-skills` v0.59
+ * pipeline action. Per beat:
+ *
+ *   1. Compute a sha256 cache key over (skill-bundle hash, DESIGN.md,
+ *      storyboard global direction, beat body, model id, retry-feedback).
+ *   2. Read the user cache's `compose-scenes/<key>.html` if present.
+ *   3. Otherwise call Claude Sonnet 4.6 with the skill bundle as system
+ *      prompt and the beat as user prompt; parse HTML out of a fenced
+ *      code block; persist to cache.
+ *
+ * Pre-flight (PR #111) validated this exact prompt shape at 5/5 lint pass,
+ * $0.058/scene, 8.4 s. The diff between runs is high (~33 % line-Jaccard)
+ * which is precisely *why* we cache on input rather than output: same
+ * input prompts always return the same cached HTML.
+ *
+ * C3 ships:
+ *   - `composeBeatHtml(ctx)` — single shot, no retry
+ *   - Cache I/O (read + write) by sha256 input key
+ *   - Anthropic SDK call with model selection + cost reporting
+ *   - Pure prompt construction helpers (testable without API key)
+ *
+ * Lint feedback retry loop comes in C4 (extends this module).
+ */
+import { type LintFinding } from "./scene-lint.js";
+import { type Beat } from "./storyboard-parse.js";
+import { type ComposerProvider } from "./composer-resolve.js";
+/** Effort level → token caps. Model is per-provider (see MODEL_SETTINGS_BY_PROVIDER). */
+export type ComposeEffort = "low" | "medium" | "high";
+export interface ComposeBeatContext {
+    /** The beat to compose, from `parseStoryboard()`. */
+    beat: Beat;
+    /** Project's `DESIGN.md` content (visual identity hard-gate). */
+    designMd: string;
+    /** Storyboard's global direction (everything before the first `## Beat`). */
+    storyboardGlobal: string;
+    /** Hyperframes skill bundle content + hash, from `loadHyperframesSkillBundle()`. */
+    skillBundle: {
+        content: string;
+        hash: string;
+    };
+    /** Effort level — picks model + token caps. Defaults to "medium". */
+    effort?: ComposeEffort;
+    /**
+     * Optional lint feedback to append to the user prompt, used by C4's retry
+     * loop. When non-empty, the cache key includes it so retries don't return
+     * the cached first-shot HTML.
+     */
+    retryFeedback?: string;
+    /**
+     * LLM provider that powers the composer. Picked by `resolveComposer()` at
+     * the entry point (CLI flag → env auto-resolve). The `apiKey` field below
+     * is the matching key for this provider.
+     */
+    provider: ComposerProvider;
+    /** API key for {@link ComposeBeatContext.provider}. */
+    apiKey: string;
+    /**
+     * Cache directory override. Defaults to `~/.vibeframe/cache/compose-scenes/`.
+     * Tests pass a temp dir.
+     */
+    cacheDir?: string;
+}
+export interface ComposeBeatResult {
+    /** Generated HTML (from cache or fresh API call). */
+    html: string;
+    /** True when the HTML came from cache (no API call made). */
+    cached: boolean;
+    /** Cache key used (sha256 hex). */
+    cacheKey: string;
+    /** Provider input tokens (only set on fresh API call). */
+    inputTokens?: number;
+    /** Provider output tokens (only set on fresh API call). */
+    outputTokens?: number;
+    /** USD cost of this beat (only set on fresh API call). */
+    costUsd?: number;
+    /** Wall-clock latency in ms (only set on fresh API call). */
+    latencyMs?: number;
+    /** Resolved model id (e.g. "claude-sonnet-4-6"). */
+    model: string;
+    /** Composer provider that produced this beat. */
+    provider: ComposerProvider;
+}
+/** Build the system prompt — skill bundle + DESIGN.md hard-gate. */
+export declare function buildSystemPrompt(ctx: Pick<ComposeBeatContext, "skillBundle" | "designMd">): string;
+/** Build the user prompt — instructions + storyboard global + beat body. */
+export declare function buildUserPrompt(ctx: Pick<ComposeBeatContext, "beat" | "storyboardGlobal" | "retryFeedback">): string;
+/**
+ * Compute the sha256 cache key for a (provider, model, system, user) tuple.
+ * Provider id is folded in so switching `--composer` doesn't serve cached
+ * HTML produced by a different model.
+ */
+export declare function computeCacheKey(parts: {
+    provider: ComposerProvider;
+    systemPrompt: string;
+    userPrompt: string;
+    model: string;
+}): string;
+/** Default cache root: `~/.vibeframe/cache/compose-scenes/`. */
+export declare function defaultCacheDir(): string;
+/**
+ * Pull the HTML out of Claude's response. Prefers a fenced ```html block;
+ * accepts a bare HTML response as fallback (some completions skip the fence
+ * when the entire reply is the document).
+ */
+export declare function extractHtml(responseText: string): string;
+export declare class ComposeBeatError extends Error {
+    readonly code: string;
+    readonly cause?: unknown | undefined;
+    constructor(code: string, message: string, cause?: unknown | undefined);
+}
+/** Raw text-completion result from any of the three providers. */
+export interface LLMCallResult {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+}
+/** Injectable LLM call function — used by tests to mock the SDK calls. */
+export type LLMCallFn = (req: {
+    provider: ComposerProvider;
+    apiKey: string;
+    model: string;
+    maxTokens: number;
+    systemPrompt: string;
+    userPrompt: string;
+}) => Promise<LLMCallResult>;
+/**
+ * Compose one beat into HTML. Cache-first; on miss, call the configured
+ * composer provider (Claude / OpenAI / Gemini — picked at the entry point
+ * via `resolveComposer()` and threaded through `ctx.provider`).
+ *
+ * @param overrides allows tests to inject a mocked LLM call. In prod we use
+ *   `defaultCallLLM` which dispatches to the matching SDK.
+ */
+export declare function composeBeatHtml(ctx: ComposeBeatContext, overrides?: {
+    callLLM?: LLMCallFn;
+    now?: () => number;
+}): Promise<ComposeBeatResult>;
+export interface BeatLintResult {
+    errorCount: number;
+    warningCount: number;
+    findings: LintFinding[];
+}
+/**
+ * Lint a single beat's HTML in-memory using `@hyperframes/producer`'s
+ * `runHyperframeLint` directly — no temp project shell, no subprocess.
+ *
+ * Sub-composition false-positives are filtered (matches what the
+ * `vibe scene lint` command does). The result is the same set of
+ * findings the user would see if they ran `vibe scene lint` after
+ * the beat HTML landed in a project.
+ */
+export declare function lintBeatHtml(html: string, beatId: string): BeatLintResult;
+/**
+ * Format lint findings into a feedback block for the retry prompt.
+ * Errors only — warnings don't block, so we don't burn the LLM's
+ * attention budget on them.
+ */
+export declare function formatLintFeedback(findings: LintFinding[]): string;
+export interface ComposeBeatWithRetryResult extends ComposeBeatResult {
+    /** 1 if first-shot HTML linted clean; 2 if retry succeeded. */
+    lintAttempts: 1 | 2;
+    /** Lint result from the *final* (winning) attempt. */
+    lint: BeatLintResult;
+}
+/**
+ * `composeBeatHtml` + lint feedback retry loop, capped at 1 retry.
+ *
+ * Pre-flight (PR #111) showed 5/5 first-pass success at $0.058/scene; deeper
+ * retry loops just burn budget. If the second attempt also fails lint,
+ * throws `ComposeBeatError("lint-failed-after-retry", ...)` with the final
+ * findings — caller (C5 pipeline action) decides whether to fall back to
+ * the 5-preset emit path or surface the failure to the user.
+ *
+ * Cache contract preserved: retries use a different `retryFeedback`, which
+ * is folded into the cache key, so retries don't accidentally serve the
+ * cached first-shot HTML.
+ */
+export declare function composeBeatWithRetry(ctx: ComposeBeatContext, overrides?: {
+    callLLM?: LLMCallFn;
+    now?: () => number;
+}): Promise<ComposeBeatWithRetryResult>;
+/**
+ * YAML pipeline action: read DESIGN.md + STORYBOARD.md, compose each beat
+ * via Claude, write `compositions/scene-<id>.html` per beat. Sequential
+ * fanout; C6 swaps in `Promise.all` parallelism.
+ *
+ * Wired into `pipeline/executor.ts` as the `compose-scenes-with-skills`
+ * action. YAML shape:
+ *
+ *     - id: compose
+ *       action: compose-scenes-with-skills
+ *       design: DESIGN.md          # required (relative to project)
+ *       storyboard: STORYBOARD.md  # required
+ *       project: .                 # optional, default outputDir
+ *       effort: medium             # optional, low|medium|high
+ *
+ * Returns the project root as `output` and per-beat metadata in `data`.
+ */
+/** Per-beat lifecycle event emitted to the optional `onProgress` callback. */
+export type ComposeProgressEvent = {
+    type: "beat-start";
+    beatId: string;
+    beatIndex: number;
+    totalBeats: number;
+} | {
+    type: "beat-cached";
+    beatId: string;
+    beatIndex: number;
+    totalBeats: number;
+    lintAttempts: 1 | 2;
+} | {
+    type: "beat-fresh";
+    beatId: string;
+    beatIndex: number;
+    totalBeats: number;
+    lintAttempts: 1 | 2;
+    costUsd?: number;
+    latencyMs?: number;
+} | {
+    type: "beat-failed";
+    beatId: string;
+    beatIndex: number;
+    totalBeats: number;
+    error: string;
+};
+export interface ComposeScenesParams {
+    /** Path to DESIGN.md, relative to project root. */
+    design?: string;
+    /** Path to STORYBOARD.md, relative to project root. */
+    storyboard?: string;
+    /** Scene project root, relative to outputDir. Defaults to outputDir. */
+    project?: string;
+    /** Effort tier — low/medium/high. Defaults to medium. */
+    effort?: ComposeEffort;
+    /**
+     * Composer provider override. When undefined, `resolveComposer()` picks
+     * one based on env keys (`claude > gemini > openai` order).
+     */
+    composer?: ComposerProvider;
+    /** Override the cache directory (tests). */
+    cacheDir?: string;
+    /** Optional per-beat progress callback (CLI spinner / pipeline reporter). */
+    onProgress?: (event: ComposeProgressEvent) => void;
+}
+export interface ComposeScenesActionResult {
+    success: boolean;
+    /** Project root (where compositions/ lives). */
+    outputPath?: string;
+    /** Aggregated metadata for the dry-run / final report. */
+    data?: {
+        beats: number;
+        written: Array<{
+            beatId: string;
+            path: string;
+            cached: boolean;
+            cacheKey: string;
+            lintAttempts: 1 | 2;
+            costUsd?: number;
+        }>;
+        totalCostUsd: number;
+        totalTokensIn: number;
+        totalTokensOut: number;
+        cacheHits: number;
+    };
+    error?: string;
+}
+/**
+ * Execute the action. Per-beat fanout via `Promise.allSettled` — all beats
+ * compose in parallel, all errors surface together (rather than fail-fast,
+ * which would still pay for in-flight API calls without surfacing their
+ * findings). Tests inject `overrides` to mock the SDK + clock.
+ *
+ * Wall-clock for an N-beat compose ≈ slowest single beat (~8s @ Sonnet 4.6
+ * per pre-flight PR #111), regardless of N. Cost still scales with N.
+ */
+export declare function executeComposeScenesWithSkills(params: ComposeScenesParams, outputDir: string, overrides?: {
+    callLLM?: LLMCallFn;
+    now?: () => number;
+}): Promise<ComposeScenesActionResult>;

package/dist/commands/_shared/compose-scenes-skills.test.d.ts

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

package/dist/commands/_shared/composer-resolve.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module _shared/composer-resolve
+ *
+ * Picks the LLM provider that powers `compose-scenes-with-skills`. Until
+ * v0.69 the composer was hardcoded to Anthropic Claude Sonnet 4.6; v0.70
+ * exposes Claude / OpenAI / Gemini as interchangeable backends behind the
+ * same Hyperframes skill-bundle prompt (Phase 0 spike validated that all
+ * three pass first-shot lint on the same prompts — see
+ * `scripts-spike-composer-providers.mts` for the data).
+ *
+ * Auto-resolve preserves the v0.69 default (Claude) when the user has an
+ * `ANTHROPIC_API_KEY` set. Without one we fall back to Gemini (cheapest of
+ * the three per the spike) and then OpenAI. Explicit `--composer <name>`
+ * always wins.
+ */
+export type ComposerProvider = "claude" | "openai" | "gemini";
+export interface ComposerResolution {
+    provider: ComposerProvider;
+    apiKey: string;
+}
+/** Env var name for a provider's composer key. */
+export declare function composerEnvVar(provider: ComposerProvider): string;
+/** Human label for error messages. */
+export declare function composerLabel(provider: ComposerProvider): string;
+/** Validate a composer string supplied via CLI flag / pipeline YAML. */
+export declare function isComposerProvider(value: unknown): value is ComposerProvider;
+/**
+ * Resolve a composer provider + key.
+ *
+ * `explicit` takes precedence — if it's set, we require its key and return
+ * exactly that provider. With no `explicit`, we walk the auto-resolve order
+ * (`claude > gemini > openai`) and return the first provider whose key is
+ * present.
+ *
+ * Throws `ComposerResolveError` if (a) `explicit` was set but its key is
+ * missing, or (b) no provider's key is present.
+ */
+export declare function resolveComposer(explicit?: ComposerProvider): ComposerResolution;
+export declare class ComposerResolveError extends Error {
+    readonly code: "missing-explicit-key" | "no-key-available";
+    readonly meta: {
+        requestedProvider?: ComposerProvider;
+    };
+    constructor(code: "missing-explicit-key" | "no-key-available", message: string, meta?: {
+        requestedProvider?: ComposerProvider;
+    });
+}

package/dist/commands/_shared/composer-resolve.test.d.ts

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

package/dist/commands/_shared/cost-tier.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Cost-tier metadata for CLI subcommands.
+ *
+ * Top-level `vibe --help` shows the four-tier table at the bottom; this
+ * module attaches the tier *per subcommand* so users see the cost
+ * directly on each `vibe <group> <sub> --help` page. The schema
+ * generator also reads it back via the symbol stamped on each Command,
+ * exposing the tier as `--describe` JSON for agents.
+ *
+ * The command modules apply the actual tier values near their command
+ * registration so schema/help output stays close to the implementation.
+ */
+import type { Command } from "commander";
+export type CostTier = "free" | "low" | "high" | "very-high";
+export declare const TIER_DESCRIPTION: Record<CostTier, string>;
+/**
+ * Tier → chalk colorizer. Cool colors for safe tiers, warm for paid ones.
+ * Used in `--help` footers (here) and in `vibe schema --list` human output.
+ */
+export declare const TIER_COLOR: Record<CostTier, (s: string) => string>;
+/**
+ * Conservative USD midpoint estimate per tier — used for budget caps
+ * where we'd rather over-count than under-count and blow past the
+ * ceiling. Pick the upper third of each tier's published range so a
+ * `--budget-usd 1` agent session denies a `very-high` tool before it
+ * fires (`$25 > $1`), but a string of `low` calls fits comfortably.
+ *
+ * Note: the agent's tool registry has a 5-tier vocabulary
+ * (`free|low|medium|high|very-high`); the CLI catalog uses 4 (no
+ * `medium`). When estimating from a tool's tier, fall back to `medium
+ * ≈ $0.50` for the in-between case.
+ */
+export declare const TIER_USD_ESTIMATE: Record<CostTier, number>;
+/**
+ * Attach a cost tier to a Command — adds a footer to its `--help`
+ * output and stamps a private symbol so the schema generator can emit
+ * `cost: "<tier>"`.
+ *
+ * Returns the command for chaining.
+ */
+export declare function applyTier<T extends Command>(cmd: T, tier: CostTier): T;
+/**
+ * Read back the cost tier from a Command, if `applyTier` was called.
+ * Returns `undefined` for commands that haven't opted in (e.g. utility
+ * commands like `setup`, `doctor`, `init`).
+ */
+export declare function getCostTier(cmd: Command): CostTier | undefined;
+/**
+ * Bulk-apply tiers to a parent's already-registered subcommands by name.
+ * Convenient for groups whose subcommands are registered via helper
+ * functions (e.g. `registerHighlightsCommands(parent)` adds two
+ * subcommands at once) — the caller doesn't have to track which slot
+ * was filled most recently.
+ *
+ * Subcommands not present in `tiers` are left untiered. Names in
+ * `tiers` that don't match any subcommand are silently ignored.
+ */
+export declare function applyTiers(parent: Command, tiers: Record<string, CostTier>): void;

package/dist/commands/_shared/edit/_helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module _shared/edit/_helpers
+ * @description Private helpers shared across the edit subcommand splits.
+ * Not part of the public ai-edit barrel re-export.
+ */
+/** Probe video resolution via ffprobe. Falls back to 1920x1080 on parse failure. */
+export declare function getVideoResolution(videoPath: string): Promise<{
+    width: number;
+    height: number;
+}>;
+/** Escape text for FFmpeg drawtext filter. */
+export declare function escapeDrawtext(text: string): string;

package/dist/commands/_shared/edit/caption.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @module _shared/edit/caption
+ * @description `executeCaption` — Whisper transcribe + ASS subtitles
+ * burn-in (or Remotion fallback if libass missing). Split out of
+ * `ai-edit.ts` in v0.69 (Plan G Phase 3).
+ */
+/** Visual style preset for burned-in captions. */
+export type CaptionStyle = "minimal" | "bold" | "outline" | "karaoke";
+/** Options for {@link executeCaption}. */
+export interface CaptionOptions {
+    /** Path to the input video file */
+    videoPath: string;
+    /** Path for the output video with burned-in captions */
+    outputPath: string;
+    /** Caption visual style preset (default: "bold") */
+    style?: CaptionStyle;
+    /** Font size override (auto-calculated from video height if omitted) */
+    fontSize?: number;
+    /** Font color name (default: "white") */
+    fontColor?: string;
+    /** Language code for Whisper transcription */
+    language?: string;
+    /** Vertical position of captions (default: "bottom") */
+    position?: "top" | "center" | "bottom";
+    /** Override OpenAI API key */
+    apiKey?: string;
+}
+/** Result from {@link executeCaption}. */
+export interface CaptionResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Path to the output video with captions */
+    outputPath?: string;
+    /** Path to the generated SRT file */
+    srtPath?: string;
+    /** Number of transcript segments */
+    segmentCount?: number;
+    /** Error message on failure */
+    error?: string;
+}
+/**
+ * Transcribe video audio and burn styled captions using Whisper + FFmpeg.
+ *
+ * Pipeline: extract audio -> Whisper transcription -> generate SRT ->
+ * burn captions via FFmpeg subtitles filter (or Remotion fallback).
+ */
+export declare function executeCaption(options: CaptionOptions): Promise<CaptionResult>;