@vibeframe/cli 0.105.1 → 0.106.0

package/dist/utils/key-live-test.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Lightweight live-test for API keys. Each tester hits the provider's
+ * cheapest authenticated endpoint (typically a list-models route) and
+ * reports ok / not-ok. Tests run with a short timeout so a hung
+ * provider doesn't stall `vibe doctor`.
+ *
+ * Coverage is intentionally partial: providers without a free
+ * authenticated GET (fal, Kling, Runway, ImgBB) report `skipped: true`
+ * with a short reason. Adding a new provider tester is a one-row patch
+ * to the `TESTERS` table at the bottom.
+ */
+export interface KeyLiveTestResult {
+    /** Did the call succeed (2xx)? */
+    ok: boolean;
+    /** True when the provider has no cheap test endpoint. */
+    skipped?: boolean;
+    /** HTTP status when applicable. */
+    status?: number;
+    /** Short human-readable reason — set on skip or failure. */
+    message?: string;
+}
+/**
+ * Run a live test for one provider key. Returns `{ ok: false, skipped:
+ * true }` for providers without a cheap test, so the caller can render
+ * a different glyph.
+ */
+export declare function testKey(configKey: string, key: string, timeoutMs?: number): Promise<KeyLiveTestResult>;
+/** Lookup table introspection — used by tests + doctor's print loop. */
+export declare function isTestableProvider(configKey: string): boolean;

package/dist/utils/key-live-test.test.d.ts

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

package/dist/utils/open-url.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cross-platform URL opener. Spawns the OS browser handler in a detached
+ * process so the CLI's input flow continues uninterrupted.
+ *
+ * Silent on failure: launching a browser is convenience, never the user's
+ * critical path. If the OS hook is missing (CI containers, headless Linux
+ * without xdg-utils), the caller's prompt still works.
+ */
+/**
+ * Open `url` in the user's default browser.
+ *
+ * Resolves immediately; the spawned process is detached and unref'd, so the
+ * CLI doesn't wait for the browser. Errors are swallowed.
+ */
+export declare function openUrl(url: string): Promise<void>;
+interface Opener {
+    command: string | null;
+    args: string[];
+}
+/**
+ * Pick the OS-appropriate opener command. Exported for unit testing — the
+ * implementation has no side effects so we can verify the args without
+ * actually spawning anything.
+ */
+export declare function resolveOpener(url: string): Opener;
+export {};

package/dist/utils/open-url.test.d.ts

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

package/dist/utils/project-resolver.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @module utils/project-resolver
+ *
+ * Single resolver for "where is the timeline file?" The CLI accepts three
+ * input shapes:
+ *
+ *   1. Direct file path: passed through as-is.
+ *   2. Directory: looks for `timeline.json` first (canonical),
+ *      falls back to an existing `project.vibe.json` (legacy).
+ *   3. Non-existent path: passed through so the caller surfaces the error.
+ *
+ * `detectSceneProject(dir)` answers "is this a scene project directory?"
+ * (i.e. has `vibe.config.json` or legacy `vibe.project.yaml`). Used to give a useful error when the
+ * user runs `vibe timeline info` on a scene directory.
+ */
+export declare const TIMELINE_FILENAME = "timeline.json";
+export declare const LEGACY_TIMELINE_FILENAME = "project.vibe.json";
+export declare const SCENE_CONFIG_FILENAME = "vibe.config.json";
+export declare const LEGACY_SCENE_CONFIG_FILENAME = "vibe.project.yaml";
+/**
+ * Resolve `inputPath` to a concrete timeline file path.
+ *
+ * Directory inputs prefer `timeline.json`; if absent, fall back to an existing
+ * legacy `project.vibe.json`. Empty directories resolve to `timeline.json` so
+ * the caller surfaces a canonical missing-file error. File inputs and unknown
+ * paths pass through unchanged.
+ */
+export declare function resolveTimelineFile(inputPath: string, cwd?: string): Promise<string>;
+/** True when the directory contains `vibe.config.json` or legacy `vibe.project.yaml`. */
+export declare function detectSceneProject(dir: string): Promise<boolean>;

package/dist/utils/project-resolver.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file project-resolver.test.ts
+ *
+ * Coverage for the timeline file resolver. The CLI accepts file paths,
+ * directory paths, and unknown paths; the resolver normalizes all three
+ * to a concrete file path that the caller can `readFile()`.
+ */
+export {};

package/dist/utils/provider-resolver.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Smart provider auto-resolution
+ * 1. Check user/project config.yaml defaults (if set)
+ * 2. Fall back to first provider with a configured API key
+ *
+ * Provider candidate lists (image / video / speech) are derived from the
+ * `defineProvider` registry in `@vibeframe/ai-providers/api-keys.ts` +
+ * each provider's `index.ts`. Priority order, label, and envvar mapping
+ * all live there now — adding a new provider is a single declaration.
+ *
+ * Pre-v0.68 the IMAGE_PROVIDERS / VIDEO_PROVIDERS / SPEECH_PROVIDERS
+ * arrays were hardcoded here and cross-validated against four other
+ * files via `scripts/sync-counts.sh` category B. v0.68 collapsed all
+ * five into a single registry; the cross-validation became structural.
+ */
+import { type ProviderCandidate } from "@vibeframe/ai-providers";
+import type { VibeConfig } from "../config/schema.js";
+export type { ProviderCandidate };
+export declare function loadProviderDefaultsFromConfig(config: VibeConfig | null | undefined): void;
+/**
+ * Load provider defaults from config (async, cached).
+ * Call once at startup if you want config-aware resolution.
+ */
+export declare function loadProviderDefaults(): Promise<void>;
+/**
+ * Resolve the best available provider for a given category.
+ * Priority: 1) config defaults  2) first provider with API key
+ */
+export declare function resolveProvider(category: "image" | "video" | "speech"): {
+    name: string;
+    label: string;
+} | null;

package/dist/utils/provider-resolver.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Snapshot tests pinning the derived provider arrays + commandsKeyMap to
+ * the values that the previously-hardcoded source files expressed.
+ *
+ * These tests exist to catch silent regressions when `defineProvider` /
+ * `defineApiKey` declarations drift away from CLI surface expectations.
+ *
+ * If a test here fails after a deliberate change, update the snapshot in
+ * lockstep — but read the diff carefully: the resolver / doctor / setup
+ * outputs are user-facing and changing their order or names is a UX
+ * change, not just a refactor.
+ */
+export {};

package/dist/utils/remotion.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Remotion rendering and compositing utilities.
+ *
+ * Uses `npx remotion` on-demand — Remotion is NOT a package dependency.
+ * Scaffolds a temporary project, renders H264 MP4, and muxes audio separately.
+ *
+ * Strategy:
+ * - Images/Videos are embedded NATIVELY inside the Remotion component using
+ *   <Img> / <Video> from Remotion (copied to public/).
+ * - No transparent WebM rendering. No FFmpeg overlay compositing.
+ * - Final output is always a standard H264 MP4.
+ */
+export interface RenderMotionOptions {
+    /** Generated TSX component code */
+    componentCode: string;
+    /** Export name of the component */
+    componentName: string;
+    width: number;
+    height: number;
+    fps: number;
+    durationInFrames: number;
+    /** Output path for rendered video (.webm or .mp4) */
+    outputPath: string;
+    /** Render with transparent background (default: true) */
+    transparent?: boolean;
+}
+export interface RenderResult {
+    success: boolean;
+    outputPath?: string;
+    error?: string;
+}
+/**
+ * Check that `npx remotion` is available. Returns an error message if not.
+ */
+export declare function ensureRemotionInstalled(): Promise<string | null>;
+/**
+ * Create a minimal Remotion project in a temp directory.
+ * Returns the directory path.
+ *
+ * @param useMediaPackage - Include @remotion/media for <Video> support (default: false)
+ */
+export declare function scaffoldRemotionProject(componentCode: string, componentName: string, opts: {
+    width: number;
+    height: number;
+    fps: number;
+    durationInFrames: number;
+    useMediaPackage?: boolean;
+}): Promise<string>;
+/**
+ * Render a standalone Remotion composition to video (no base media).
+ * When transparent: tries VP8 then VP9.
+ * When opaque: renders H264 MP4.
+ */
+export declare function renderMotion(options: RenderMotionOptions): Promise<RenderResult>;
+/**
+ * Validates and auto-fixes common LLM-generated Remotion code bugs before
+ * attempting to render. Returns fixed code and a list of applied fixes.
+ *
+ * Known patterns fixed:
+ *  1. interpolate(x, [a,b], scalar, num) → interpolate(x, [a,b], [scalar, num])
+ *     Cause: outputRange must be an array, not a bare scalar.
+ *  2. interpolate(x, [a,b], scalar) where scalar is a variable name
+ *     Cause: same — LLM passes a single number variable instead of [from, to].
+ */
+export declare function validateAndFixMotionCode(code: string): {
+    code: string;
+    fixes: string[];
+};
+/**
+ * Wrap an overlay component to embed a static image as background.
+ * Uses Remotion's <Img> component (required per Remotion docs — ensures
+ * image is fully loaded before each frame renders).
+ *
+ * Injects Img and staticFile into the component's existing remotion import
+ * to avoid duplicate identifier errors.
+ */
+export declare function wrapComponentWithImage(componentCode: string, componentName: string, imageFileName: string): {
+    code: string;
+    name: string;
+};
+/**
+ * Render a Remotion component that embeds a static image as background.
+ * Copies image to public/, renders H264 MP4 directly — no transparency needed.
+ */
+export declare function renderWithEmbeddedImage(options: {
+    componentCode: string;
+    componentName: string;
+    width: number;
+    height: number;
+    fps: number;
+    durationInFrames: number;
+    imagePath: string;
+    imageFileName: string;
+    outputPath: string;
+}): Promise<RenderResult>;
+/**
+ * Wrap an overlay component to embed a video as background.
+ * Uses <Video> from @remotion/media (required per Remotion docs).
+ * Video is muted — audio is muxed back via FFmpeg after rendering.
+ *
+ * Injects staticFile into the component's existing remotion import to avoid
+ * duplicate identifier errors. Video is imported from @remotion/media
+ * (different module — no conflict).
+ */
+export declare function wrapComponentWithVideo(componentCode: string, componentName: string, videoFileName: string): {
+    code: string;
+    name: string;
+};
+/**
+ * Render a Remotion component that embeds the video directly.
+ * Uses @remotion/media's <Video> component (official Remotion approach).
+ * After rendering, muxes audio from the original video back into the output.
+ */
+export declare function renderWithEmbeddedVideo(options: {
+    componentCode: string;
+    componentName: string;
+    width: number;
+    height: number;
+    fps: number;
+    durationInFrames: number;
+    videoPath: string;
+    videoFileName: string;
+    outputPath: string;
+}): Promise<RenderResult>;
+export interface CaptionSegment {
+    start: number;
+    end: number;
+    text: string;
+}
+export type CaptionStylePreset = "bold" | "minimal" | "outline" | "karaoke";
+export interface GenerateCaptionComponentOptions {
+    segments: CaptionSegment[];
+    style: CaptionStylePreset;
+    fontSize: number;
+    fontColor: string;
+    position: "top" | "center" | "bottom";
+    width: number;
+    height: number;
+    /** When set, embed the video inside the component (no transparency needed) */
+    videoFileName?: string;
+}
+export type TextOverlayStyle = "lower-third" | "center-bold" | "subtitle" | "minimal";
+export interface GenerateTextOverlayComponentOptions {
+    texts: string[];
+    style: TextOverlayStyle;
+    fontSize: number;
+    fontColor: string;
+    startTime: number;
+    endTime: number;
+    fadeDuration: number;
+    width: number;
+    height: number;
+    videoFileName: string;
+}
+/**
+ * Generate a Remotion TSX component for text overlays.
+ * Fallback for when FFmpeg drawtext filter (libfreetype) is unavailable.
+ */
+export declare function generateTextOverlayComponent(options: GenerateTextOverlayComponentOptions): {
+    code: string;
+    name: string;
+};
+/**
+ * Generate a Remotion TSX component that renders styled captions.
+ * No LLM call — purely programmatic from SRT segments + style config.
+ */
+export declare function generateCaptionComponent(options: GenerateCaptionComponentOptions): {
+    code: string;
+    name: string;
+};
+export interface AnimatedCaptionWord {
+    word: string;
+    start: number;
+    end: number;
+}
+export interface AnimatedCaptionGroup {
+    words: AnimatedCaptionWord[];
+    startTime: number;
+    endTime: number;
+    text: string;
+}
+export type AnimatedCaptionStylePreset = "highlight" | "bounce" | "pop-in" | "neon";
+export interface GenerateAnimatedCaptionComponentOptions {
+    groups: AnimatedCaptionGroup[];
+    style: AnimatedCaptionStylePreset;
+    highlightColor: string;
+    fontSize: number;
+    position: "top" | "center" | "bottom";
+    width: number;
+    height: number;
+    fps: number;
+    videoFileName?: string;
+}
+/**
+ * Generate a Remotion TSX component for word-level animated captions.
+ * Each style creates different visual effects per word.
+ */
+export declare function generateAnimatedCaptionComponent(options: GenerateAnimatedCaptionComponentOptions): {
+    code: string;
+    name: string;
+};

package/dist/utils/subtitle.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Subtitle format utilities for SRT/VTT generation
+ */
+export type SubtitleFormat = "json" | "srt" | "vtt";
+export interface SubtitleSegment {
+    startTime: number;
+    endTime: number;
+    text: string;
+}
+export interface TranscriptResult {
+    id: string;
+    status: string;
+    fullText?: string;
+    segments?: SubtitleSegment[];
+    detectedLanguage?: string;
+    error?: string;
+}
+/**
+ * Detect subtitle format from file extension or explicit format option
+ */
+export declare function detectFormat(outputPath: string, explicitFormat?: string): SubtitleFormat;
+/**
+ * Format transcript result to the specified format
+ */
+export declare function formatTranscript(result: TranscriptResult, format: SubtitleFormat): string;
+/**
+ * Format segments as SRT (SubRip Subtitle)
+ *
+ * SRT Format:
+ * 1
+ * 00:00:00,000 --> 00:00:02,500
+ * Hello world
+ */
+export declare function formatSRT(segments: SubtitleSegment[]): string;
+/**
+ * Format segments as WebVTT (Web Video Text Tracks)
+ *
+ * VTT Format:
+ * WEBVTT
+ *
+ * 1
+ * 00:00:00.000 --> 00:00:02.500
+ * Hello world
+ */
+export declare function formatVTT(segments: SubtitleSegment[]): string;
+/**
+ * Format time for SRT (uses comma for milliseconds)
+ * Format: HH:MM:SS,mmm
+ */
+export declare function formatSRTTime(seconds: number): string;
+/**
+ * Format time for VTT (uses period for milliseconds)
+ * Format: HH:MM:SS.mmm
+ */
+export declare function formatVTTTime(seconds: number): string;
+/**
+ * Parse SRT content into SubtitleSegment array
+ *
+ * Handles standard SRT format:
+ * 1
+ * 00:00:00,000 --> 00:00:02,500
+ * Hello world
+ */
+export declare function parseSRT(content: string): SubtitleSegment[];

package/dist/utils/subtitle.test.d.ts

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

package/dist/utils/tty.d.ts

@@ -0,0 +1,86 @@
+/**
+ * TTY Input Utilities
+ * Handles stdin fallback to /dev/tty for piped environments
+ */
+import { Interface } from "node:readline";
+import { ReadStream } from "node:tty";
+export declare function fitOptionToLine(value: string, prefixColumns: number): string;
+/**
+ * Get a TTY-capable input stream
+ * Falls back to /dev/tty when stdin is piped (e.g., from curl)
+ */
+export declare function getTTYInputStream(): typeof process.stdin | ReadStream;
+/**
+ * Check if we have TTY input available
+ */
+export declare function hasTTY(): boolean;
+/**
+ * Close the TTY stream if we opened one
+ */
+export declare function closeTTYStream(): void;
+/**
+ * Create a readline interface with TTY support
+ */
+export declare function createTTYInterface(options?: {
+    prompt?: string;
+    historySize?: number;
+}): Interface;
+/**
+ * Prompt for input (single line)
+ * Throws in non-TTY environments to prevent hanging.
+ */
+export declare function prompt(question: string): Promise<string>;
+/**
+ * Prompt for hidden input (password/API key).
+ * Characters are not echoed to the terminal.
+ *
+ * `opts.openHotkeyUrl`: when set, the user can press lowercase `o` as the
+ * very first key (no input typed yet) to launch the URL in their default
+ * browser. Subsequent keys behave normally. Safe for our setup wizard
+ * because every registered API-key prefix (`sk-`, `AIza`, `xai-`, `key_`,
+ * `r8_`, `sk_`, etc.) starts with something other than `o`. Pressing `o`
+ * after typing any character is treated as part of the value, not a hotkey.
+ */
+export interface PromptHiddenOptions {
+    /** URL to launch in the default browser when the user presses `o` first. */
+    openHotkeyUrl?: string;
+}
+export declare function promptHidden(question: string, opts?: PromptHiddenOptions): Promise<string>;
+/**
+ * Prompt for selection from a list (1-based index)
+ */
+export declare function promptSelect(_question: string, options: string[], defaultIndex?: number, opts?: {
+    backIndex?: number;
+}): Promise<number>;
+/**
+ * Prompt for yes/no confirmation.
+ *
+ * Renders an arrow-key Yes/No selector when a TTY is available (matching the
+ * paradigm of `promptSelect` / `promptMultiSelect`), falling back to the
+ * legacy `(Y/n)` text prompt for piped/CI input so scripts continue to work
+ * unchanged.
+ */
+export declare function promptConfirm(question: string, defaultYes?: boolean): Promise<boolean>;
+/**
+ * Prompt for multi-select (checkbox) from a list.
+ *
+ * Returns the indexes selected (sorted ascending). ↑↓ navigates, space toggles,
+ * enter confirms. `pickFocusedOnEnter` (formerly `enterSelectsFocusedWhenEmpty`)
+ * makes Enter behave like a single-choice select **as long as the user has
+ * not pressed space yet** — once any explicit toggle happens, Enter confirms
+ * the current selection as-is. This lets a pre-checked default be overridden
+ * by a single arrow + Enter while still allowing additive multi-pick via
+ * space + Enter.
+ * `preserveDefaultSelectionOnEnter` changes the no-toggle Enter shortcut from
+ * replace to add when there are already checked rows. This is useful for setup
+ * screens where previously configured choices should remain visible and sticky.
+ * In non-TTY environments accepts comma-separated 1-based indices, the literal
+ * "all", or empty/"none" for no selection.
+ */
+export declare function promptMultiSelect(_question: string, options: string[], defaultSelected?: boolean[], opts?: {
+    pickFocusedOnEnter?: boolean;
+    preserveDefaultSelectionOnEnter?: boolean;
+    backIndex?: number;
+    /** @deprecated Use pickFocusedOnEnter — same flag, broader semantics. */
+    enterSelectsFocusedWhenEmpty?: boolean;
+}): Promise<number[]>;

package/dist/utils/tty.test.d.ts

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

package/dist/utils/upload-host.d.ts

@@ -0,0 +1,15 @@
+export type UploadHostProvider = "imgbb" | "s3";
+export interface UploadImageOptions {
+    filename?: string;
+    mimeType?: string;
+}
+export interface UploadImageResult {
+    url: string;
+    provider: UploadHostProvider;
+    expiresAt?: string;
+}
+export interface UploadHost {
+    provider: UploadHostProvider;
+    uploadImage(imageBuffer: Buffer, opts?: UploadImageOptions): Promise<UploadImageResult>;
+}
+export declare function resolveUploadHost(): Promise<UploadHost>;

package/dist/utils/upload-host.test.d.ts

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