@mevdragon/vidfarm-devcli 0.7.1 → 0.9.0

package/dist/src/devcli/clips.js

@@ -0,0 +1,803 @@
+// devcli `vidfarm clips …` — the local clip-curation surface. Uses local
+// ffmpeg (near-zero compute) + BYOK Gemini, persisting to a SQLite clip library
+// (~/.vidfarm). Every scan shows an estimated cost first; scans over $1 require
+// --yes or an interactive confirm. Mirrors the cloud REST surface 1:1.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import path from "node:path";
+import { homedir } from "node:os";
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { createIdV7 } from "../lib/ids.js";
+import { ClipModelClient, estimateScanCostFromScenes, formatCostEstimate, detectScenes, hasFfmpeg, probeVideo, scanVideo, searchClips } from "../services/clip-curation/index.js";
+import { ClipStore } from "./clip-store.js";
+export const CLIPS_HELP = `vidfarm clips — build & search a local clip library (local ffmpeg + BYOK Gemini)
+
+  clips scan <video-path>          Mine a long-form video into tagged, searchable clips
+    --provider <p>                 gemini | openai | openrouter (default: gemini)
+                                   gemini→gemini-2.5-flash-lite, openai→gpt-5.4-nano,
+                                   openrouter→google/gemini-2.5-flash
+    --tier flash|flash-lite        Gemini tier (default: flash-lite; ignored for openai/openrouter)
+    --prompt "<guidance>"          Reshape clipping toward your goal: an LLM pass
+                                   keeps/drops/merges scenes, and tags are biased to it
+    --no-refine                    Keep prompt tag-bias but skip the keep/drop/merge pass
+    --dry-run                      Print the estimated cost and exit
+    --yes                          Skip the >$1 confirmation prompt
+    --frames <n>                   Keyframes per scene for tagging (1-3, default 2)
+    --no-audio                     Skip per-scene audio (Gemini only; no transcripts; cheaper)
+    --concurrency <n>              Parallel scenes (default 3; respect rate limits)
+    --threshold <0..1>             Scene-cut sensitivity (default 0.3; lower = more cuts)
+    --min-scene <sec>              Merge scenes shorter than this (default 0.6)
+    --max-scene <sec>              Split scenes longer than this (default 8)
+    --gemini-key / --openai-key / --openrouter-key <key>   Provider key (or *_API_KEY env)
+    --embed-provider gemini|openai --embed-key <key>       Embeddings when using openrouter
+    --home <dir>                   Library dir (default: ~/.vidfarm or VIDFARM_HOME)
+
+  clips list                       List clips in the library
+    --source <id>                  Only clips from one source video
+    --limit <n> | --json
+
+  clips search "<natural language>"  Hybrid structured + semantic search
+    --limit <n> | --json | --gemini-key <key>
+
+  clips match "<text>"             Top library clips to REPLACE a scene (vector search)
+    --criteria '<json>'            Match a structured SplicingCriteria instead of text
+    --scenes <annotations.json>    Batch: match every scene of a decomposed video
+                                   (array of scene annotations, or {annotations|scenes:[…]})
+    --limit <n> | --json
+
+  clips preset list                List built-in + saved presets
+  clips preset run <name>          Run a preset query   [--limit <n>] [--json]
+  clips preset save <name> --from-query '<json | natural language>'
+
+  clips sources                    List scanned source videos
+  clips export <clip-ids...> --to <dir>   Copy clip mp4s (+ metadata.json) out
+`;
+export async function runClipsCommand(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    switch (sub) {
+        case "scan":
+            return runScan(rest);
+        case "list":
+            return runList(rest);
+        case "search":
+            return runSearch(rest);
+        case "match":
+            return runMatch(rest);
+        case "preset":
+            return runPreset(rest);
+        case "sources":
+            return runSources(rest);
+        case "export":
+            return runExport(rest);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            return runOverview();
+        default:
+            console.error(`Unknown clips subcommand: ${sub}\n`);
+            console.log(CLIPS_HELP);
+            process.exitCode = 1;
+    }
+}
+// ── clips (overview) ────────────────────────────────────────────────────────
+function runOverview() {
+    const store = new ClipStore();
+    const stats = store.stats();
+    store.close();
+    console.log(`vidfarm clips — library at ${resolveHome()}`);
+    console.log(`  ${stats.clips} clips · ${stats.sources} source videos · ${stats.presets} presets\n`);
+    console.log(CLIPS_HELP);
+}
+// ── clips scan ──────────────────────────────────────────────────────────────
+async function runScan(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            provider: { type: "string" },
+            tier: { type: "string" },
+            prompt: { type: "string" },
+            "no-refine": { type: "boolean" },
+            "dry-run": { type: "boolean" },
+            yes: { type: "boolean" },
+            frames: { type: "string" },
+            "no-audio": { type: "boolean" },
+            concurrency: { type: "string" },
+            threshold: { type: "string" },
+            "min-scene": { type: "string" },
+            "max-scene": { type: "string" },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            "embed-provider": { type: "string" },
+            "embed-key": { type: "string" },
+            home: { type: "string" }
+        }
+    });
+    const videoArg = positionals[0];
+    if (!videoArg)
+        throw new Error("Usage: vidfarm clips scan <video-path> [--tier flash|flash-lite] [--dry-run]");
+    const videoPath = path.resolve(process.cwd(), videoArg);
+    if (!existsSync(videoPath))
+        throw new Error(`No such video: ${videoPath}`);
+    if (!(await hasFfmpeg())) {
+        throw new Error("ffmpeg is required for `clips scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
+    }
+    const provider = normalizeProvider(values.provider);
+    const tier = normalizeTier(values.tier);
+    const framesPerScene = clampInt(values.frames, 2, 1, 3);
+    // Audio is Gemini-only (chat models on openai/openrouter don't take the clip).
+    const includeAudio = !values["no-audio"] && provider === "gemini";
+    const guidancePrompt = values.prompt?.trim() || undefined;
+    const concurrency = clampInt(values.concurrency, 3, 1, 12);
+    const sceneOptions = {
+        threshold: values.threshold ? Number(values.threshold) : undefined,
+        minSceneSec: values["min-scene"] ? Number(values["min-scene"]) : undefined,
+        maxSceneSec: values["max-scene"] ? Number(values["max-scene"]) : undefined
+    };
+    // Resolve the tagging key + optional embedding config. Optional here so
+    // --dry-run can show the cost without a key; the key is required below to scan.
+    const apiKey = resolveProviderKey(provider, values, { optional: true });
+    const embedding = apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
+    console.log(`[clips] probing ${path.basename(videoPath)} …`);
+    const probe = await probeVideo(videoPath);
+    console.log(`[clips] ${fmtDuration(probe.duration_sec)} · ${probe.width ?? "?"}x${probe.height ?? "?"} · ${probe.codec ?? "?"}`);
+    console.log(`[clips] detecting scenes …`);
+    const scenes = await detectScenes(videoPath, { durationSec: probe.duration_sec, ...sceneOptions });
+    if (scenes.length === 0)
+        throw new Error("No scenes detected (is the video readable / non-empty?).");
+    const store = new ClipStore(values.home);
+    const client = apiKey ? new ClipModelClient({ provider, apiKey, tier, embedding }) : null;
+    if (client && !client.canEmbed) {
+        console.warn(`[clips] no embedding provider for "${provider}" — clips will be structured-searchable only.`);
+        console.warn(`        Add --embed-provider gemini|openai --embed-key <key> for semantic search.`);
+    }
+    const estimate = estimateScanCostFromScenes(scenes, {
+        tier,
+        provider,
+        tagModelId: client?.tagModelId,
+        embedModelId: client ? client.embeddingModelId : defaultEmbedModelForEstimate(provider),
+        framesPerScene,
+        includeAudio
+    });
+    console.log(`\n  Cost estimate: ${formatCostEstimate(estimate)}`);
+    console.log(`  Target: $0.05–0.10 per source hour (${withinTarget(estimate.usd_per_source_hour) ? "on target" : "note"}).`);
+    if (guidancePrompt)
+        console.log(`  Guidance: "${guidancePrompt}"`);
+    console.log("");
+    if (values["dry-run"]) {
+        console.log("[clips] --dry-run: not scanning. Re-run without --dry-run to build the library.");
+        return;
+    }
+    // Actually scanning now — a key is required.
+    if (!client)
+        resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+    const activeClient = client;
+    // $1 confirmation gate (handoff Target 1).
+    if (estimate.usd > 1 && !values.yes) {
+        const ok = await confirm(`This scan is estimated at $${estimate.usd.toFixed(2)}. Proceed? [y/N] `);
+        if (!ok) {
+            console.log("[clips] aborted.");
+            return;
+        }
+    }
+    // Warn if this scan's embedding model differs from the library's (vectors won't compare).
+    if (activeClient.embeddingModelId) {
+        const existing = store.getLibraryEmbeddingModel();
+        if (existing && existing !== activeClient.embeddingModelId) {
+            console.warn(`[clips] WARNING: library was built with "${existing}" embeddings but this scan uses "${activeClient.embeddingModelId}". Semantic search across them will be unreliable.`);
+        }
+        else {
+            store.rememberEmbeddingModel(activeClient.embeddingModelId);
+        }
+    }
+    const ctx = {
+        client: activeClient,
+        workDir: path.join(store.paths.workDir, createIdV7("scan")),
+        clipsDir: store.paths.clipsDir,
+        thumbsDir: store.paths.thumbsDir,
+        framesPerScene,
+        includeAudio,
+        guidancePrompt,
+        refineSegmentation: !values["no-refine"],
+        reencodeClips: true
+    };
+    console.log(`[clips] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
+    let errors = 0;
+    const started = timestamp();
+    const result = await scanVideo({
+        ctx,
+        videoPath,
+        scenes,
+        probe,
+        sourceFilename: path.basename(videoPath),
+        concurrency,
+        onRefine: (r) => {
+            if (r.refined) {
+                console.log(`[clips] guided segmentation: ${scenes.length} → ${r.kept} clips (dropped ${r.dropped}, merged ${r.merged}).`);
+            }
+            else if (r.note) {
+                console.log(`[clips] guided segmentation skipped: ${r.note}.`);
+            }
+        },
+        onClip: (clip, i, total) => {
+            store.insertClip(clip);
+            const tagline = summarizeTags(clip);
+            console.log(`  [${i}/${total}] ${clip.clip_id.slice(0, 14)} ${fmtRange(clip)}  ${tagline}`);
+        },
+        onError: (scene, error) => {
+            errors++;
+            console.warn(`  ✗ scene @${scene.start_time_sec.toFixed(1)}s: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    store.recordSourceVideo({
+        source_video_id: result.source_video_id,
+        filename: path.basename(videoPath),
+        source_path: videoPath,
+        duration_sec: probe.duration_sec,
+        clip_count: result.clips.length,
+        tier
+    });
+    // Scratch frames/audio are disposable.
+    try {
+        rmSync(ctx.workDir, { recursive: true, force: true });
+    }
+    catch {
+        /* ignore */
+    }
+    store.close();
+    console.log(`\n[clips] done in ${elapsed(started)}: ${result.clips.length} clips${errors ? `, ${errors} scene(s) failed` : ""}.`);
+    console.log(`  clips → ${store.paths.clipsDir}`);
+    console.log(`  db    → ${store.paths.db}`);
+    console.log(`  try:  vidfarm clips search "…"  |  vidfarm clips preset run "funny reaction gifs"`);
+}
+// ── clips list ──────────────────────────────────────────────────────────────
+async function runList(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            source: { type: "string" },
+            limit: { type: "string" },
+            json: { type: "boolean" },
+            home: { type: "string" }
+        }
+    });
+    const store = new ClipStore(values.home);
+    const clips = store.listClips({ sourceVideoId: values.source, limit: clampInt(values.limit, 50, 1, 5000) });
+    store.close();
+    if (values.json) {
+        console.log(JSON.stringify(clips, null, 2));
+        return;
+    }
+    if (clips.length === 0) {
+        console.log("No clips yet. Run: vidfarm clips scan <video-path>");
+        return;
+    }
+    for (const clip of clips) {
+        console.log(`${clip.clip_id.slice(0, 14)}  ${fmtRange(clip)}  ${clip.source_filename}  ${summarizeTags(clip)}`);
+    }
+    console.log(`\n${clips.length} clips.`);
+}
+// ── clips search ────────────────────────────────────────────────────────────
+async function runSearch(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            provider: { type: "string" },
+            limit: { type: "string" },
+            json: { type: "boolean" },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            home: { type: "string" }
+        }
+    });
+    const query = positionals.join(" ").trim();
+    if (!query)
+        throw new Error('Usage: vidfarm clips search "<natural language>"');
+    const limit = clampInt(values.limit, 10, 1, 200);
+    const store = new ClipStore(values.home);
+    if (store.stats().clips === 0) {
+        store.close();
+        console.log("Library is empty — scan a video first: vidfarm clips scan <video-path>");
+        return;
+    }
+    const provider = normalizeProvider(values.provider);
+    const apiKey = resolveProviderKey(provider, values, { optional: true });
+    let criteria = { semantic_text: query };
+    let queryEmbedding;
+    if (apiKey) {
+        const client = new ClipModelClient({ provider, apiKey });
+        criteria = await client.naturalLanguageToCriteria(query);
+        if (client.canEmbed) {
+            const libModel = store.getLibraryEmbeddingModel();
+            if (libModel && client.embeddingModelId && libModel !== client.embeddingModelId) {
+                console.warn(`[clips] note: library uses "${libModel}" embeddings but you're searching with "${client.embeddingModelId}" — semantic re-rank may be off; pass --provider to match.`);
+            }
+            queryEmbedding = await client.embedQuery(criteria.semantic_text ?? query);
+        }
+    }
+    else {
+        console.warn(`[clips] no ${provider} key — structured/keyword search only (set the provider key for semantic search).`);
+    }
+    const t0 = timestamp();
+    const hits = store.search({ criteria, queryEmbedding, limit });
+    const ms = elapsedMs(t0);
+    store.close();
+    if (values.json) {
+        console.log(JSON.stringify(hits, null, 2));
+        return;
+    }
+    printHits(hits, { query, ms, criteria });
+}
+function normalizeMatchScene(s, i) {
+    const mc = (s.match_criteria ?? s.criteria);
+    const embText = (s.embedding_text ?? s.text);
+    const criteria = mc ?? (embText ? { semantic_text: embText } : {});
+    const text = embText || criteria.semantic_text || "";
+    return {
+        id: s.scene_slug || s.id || `scene_${i}`,
+        criteria,
+        text,
+        meta: {
+            replaceability: typeof s.replaceability === "string" ? s.replaceability : undefined,
+            duration: typeof s.duration === "number" ? s.duration : undefined,
+            start: typeof s.start === "number" ? s.start : undefined,
+            scene_role: typeof s.scene_role === "string" ? s.scene_role : undefined
+        }
+    };
+}
+async function runMatch(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            criteria: { type: "string" },
+            scenes: { type: "string" },
+            provider: { type: "string" },
+            limit: { type: "string" },
+            json: { type: "boolean" },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            home: { type: "string" }
+        }
+    });
+    const store = new ClipStore(values.home);
+    if (store.stats().clips === 0) {
+        store.close();
+        console.log("Library is empty — scan a video first: vidfarm clips scan <video-path>");
+        return;
+    }
+    // Embed the match query in the SAME space the library was built with.
+    const libModel = store.getLibraryEmbeddingModel();
+    const embedProvider = libModel && libModel.startsWith("text-embedding") ? "openai" : "gemini";
+    const embedKey = resolveProviderKey(embedProvider, values, { optional: true });
+    const client = embedKey ? new ClipModelClient({ provider: embedProvider, apiKey: embedKey }) : null;
+    if (!client)
+        console.warn(`[clips] no ${embedProvider} key — structured match only (set the key for vector re-rank).`);
+    if (values.scenes) {
+        const filePath = path.resolve(process.cwd(), values.scenes);
+        if (!existsSync(filePath))
+            throw new Error(`No such file: ${filePath}`);
+        const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+        const rawScenes = (Array.isArray(parsed)
+            ? parsed
+            : (parsed.annotations ??
+                parsed.scenes ??
+                []));
+        if (rawScenes.length === 0)
+            throw new Error("No scene annotations found in file (expected an array, or {annotations|scenes:[…]}).");
+        const scenes = rawScenes.map(normalizeMatchScene);
+        const perScene = clampInt(values.limit, 5, 1, 50);
+        const embeddings = client ? await client.embedQueries(scenes.map((s) => s.text || " ")) : [];
+        // Load the library once for the whole batch.
+        const all = store.listClips();
+        store.attachEmbeddings(all);
+        store.close();
+        const output = scenes.map((s, i) => ({
+            scene_slug: s.id,
+            ...s.meta,
+            matches: searchClips(all, {
+                criteria: s.criteria,
+                queryEmbedding: client ? embeddings[i] : undefined,
+                limit: perScene,
+                relaxWhenEmpty: true
+            })
+        }));
+        if (values.json) {
+            console.log(JSON.stringify(output, null, 2));
+            return;
+        }
+        console.log(`Matched ${scenes.length} scenes against ${all.length} clips:`);
+        for (const o of output) {
+            const rep = o.replaceability ? ` [replaceability: ${o.replaceability}]` : "";
+            const dur = typeof o.duration === "number" ? ` (${o.duration.toFixed(1)}s)` : "";
+            console.log(`\n▶ ${o.scene_slug}${rep}${dur}`);
+            if (o.matches.length === 0) {
+                console.log("   (no library match)");
+                continue;
+            }
+            o.matches.forEach((h, j) => {
+                const sim = h.similarity != null ? ` sim=${h.similarity.toFixed(2)}` : "";
+                console.log(`   ${j + 1}. ${h.clip.clip_id.slice(0, 14)} ${fmtRange(h.clip)} score=${h.score.toFixed(2)}${sim}  ${summarizeTags(h.clip)}`);
+            });
+        }
+        return;
+    }
+    // Single scene: --criteria '<json>' or a free-text query.
+    const limit = clampInt(values.limit, 8, 1, 50);
+    let criteria;
+    let text;
+    const asJson = values.criteria ? tryParseJson(values.criteria) : null;
+    if (asJson && typeof asJson === "object") {
+        criteria = asJson;
+        text = criteria.semantic_text ?? positionals.join(" ").trim();
+    }
+    else {
+        text = positionals.join(" ").trim();
+        if (!text) {
+            store.close();
+            throw new Error('Usage: vidfarm clips match "<text>" | --criteria \'<json>\' | --scenes <annotations.json>');
+        }
+        criteria = { semantic_text: text };
+    }
+    const queryEmbedding = client && text ? await client.embedQuery(text) : undefined;
+    const t0 = timestamp();
+    const hits = store.search({ criteria, queryEmbedding, limit });
+    const ms = elapsedMs(t0);
+    store.close();
+    if (values.json) {
+        console.log(JSON.stringify(hits, null, 2));
+        return;
+    }
+    printHits(hits, { query: text || "criteria", ms, criteria });
+}
+// ── clips preset ────────────────────────────────────────────────────────────
+async function runPreset(argv) {
+    const action = argv[0];
+    const rest = argv.slice(1);
+    if (action === "list")
+        return runPresetList(rest);
+    if (action === "run")
+        return runPresetRun(rest);
+    if (action === "save")
+        return runPresetSave(rest);
+    throw new Error("Usage: vidfarm clips preset <list|run <name>|save <name> --from-query '<...>'>");
+}
+async function runPresetList(argv) {
+    const { values } = parseArgs({ args: argv, options: { json: { type: "boolean" }, home: { type: "string" } } });
+    const store = new ClipStore(values.home);
+    const presets = store.listPresets();
+    store.close();
+    if (values.json) {
+        console.log(JSON.stringify(presets, null, 2));
+        return;
+    }
+    for (const p of presets) {
+        const tag = p.builtin ? "(built-in)" : "(saved)";
+        console.log(`${p.name}  ${tag}\n    ${p.description ?? ""}\n    ${describeCriteria(p.criteria)}`);
+    }
+}
+async function runPresetRun(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            provider: { type: "string" },
+            limit: { type: "string" },
+            json: { type: "boolean" },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            home: { type: "string" }
+        }
+    });
+    const name = positionals.join(" ").trim();
+    if (!name)
+        throw new Error("Usage: vidfarm clips preset run <name>");
+    const store = new ClipStore(values.home);
+    const preset = store.findPreset(name);
+    if (!preset) {
+        store.close();
+        throw new Error(`No preset "${name}". Try: vidfarm clips preset list`);
+    }
+    const limit = clampInt(values.limit, 10, 1, 200);
+    // Presets carry semantic_text; embed it if we have a key for the re-rank.
+    let queryEmbedding;
+    const provider = normalizeProvider(values.provider);
+    const apiKey = resolveProviderKey(provider, values, { optional: true });
+    if (apiKey && preset.criteria.semantic_text) {
+        const client = new ClipModelClient({ provider, apiKey });
+        if (client.canEmbed)
+            queryEmbedding = await client.embedQuery(preset.criteria.semantic_text);
+    }
+    const t0 = timestamp();
+    const hits = store.search({ criteria: preset.criteria, queryEmbedding, limit });
+    const ms = elapsedMs(t0);
+    store.close();
+    if (values.json) {
+        console.log(JSON.stringify(hits, null, 2));
+        return;
+    }
+    printHits(hits, { query: preset.name, ms, criteria: preset.criteria });
+}
+async function runPresetSave(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            "from-query": { type: "string" },
+            description: { type: "string" },
+            provider: { type: "string" },
+            "gemini-key": { type: "string" },
+            "openai-key": { type: "string" },
+            "openrouter-key": { type: "string" },
+            home: { type: "string" }
+        }
+    });
+    const name = positionals.join(" ").trim();
+    const fromQuery = values["from-query"];
+    if (!name || !fromQuery) {
+        throw new Error("Usage: vidfarm clips preset save <name> --from-query '<json | natural language>'");
+    }
+    let criteria;
+    const asJson = tryParseJson(fromQuery);
+    if (asJson && typeof asJson === "object") {
+        criteria = asJson;
+    }
+    else {
+        // Treat as natural language → structured (needs a provider key).
+        const provider = normalizeProvider(values.provider);
+        const apiKey = resolveProviderKey(provider, values);
+        criteria = await new ClipModelClient({ provider, apiKey }).naturalLanguageToCriteria(fromQuery);
+    }
+    const store = new ClipStore(values.home);
+    const preset = store.savePreset({ name, criteria, description: values.description });
+    store.close();
+    console.log(`Saved preset "${preset.name}" (${preset.preset_id}).`);
+    console.log(`  ${describeCriteria(preset.criteria)}`);
+}
+// ── clips sources ───────────────────────────────────────────────────────────
+async function runSources(argv) {
+    const { values } = parseArgs({ args: argv, options: { json: { type: "boolean" }, home: { type: "string" } } });
+    const store = new ClipStore(values.home);
+    const sources = store.listSourceVideos();
+    store.close();
+    if (values.json) {
+        console.log(JSON.stringify(sources, null, 2));
+        return;
+    }
+    if (sources.length === 0) {
+        console.log("No sources scanned yet.");
+        return;
+    }
+    for (const s of sources) {
+        console.log(`${s.source_video_id.slice(0, 14)}  ${s.filename}  ${s.clip_count} clips  ${s.duration_sec ? fmtDuration(s.duration_sec) : ""}  ${s.scanned_at}`);
+    }
+}
+// ── clips export ────────────────────────────────────────────────────────────
+async function runExport(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { to: { type: "string" }, home: { type: "string" } }
+    });
+    const ids = positionals;
+    const to = values.to;
+    if (ids.length === 0 || !to) {
+        throw new Error("Usage: vidfarm clips export <clip-ids...> --to <dir>");
+    }
+    const outDir = path.resolve(process.cwd(), to);
+    mkdirSync(outDir, { recursive: true });
+    const store = new ClipStore(values.home);
+    const exported = [];
+    for (const id of ids) {
+        const clip = store.getClip(id);
+        if (!clip) {
+            console.warn(`  ✗ no clip ${id}`);
+            continue;
+        }
+        const src = path.join(store.paths.clipsDir, `${clip.clip_id}.mp4`);
+        if (!existsSync(src)) {
+            console.warn(`  ✗ missing file for ${id} (${src})`);
+            continue;
+        }
+        const dest = path.join(outDir, `${clip.clip_id}.mp4`);
+        copyFileSync(src, dest);
+        const thumb = path.join(store.paths.thumbsDir, `${clip.clip_id}.jpg`);
+        if (existsSync(thumb))
+            copyFileSync(thumb, path.join(outDir, `${clip.clip_id}.jpg`));
+        exported.push(clip);
+        console.log(`  ✓ ${clip.clip_id} → ${dest}`);
+    }
+    store.close();
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(path.join(outDir, "clips.metadata.json"), JSON.stringify(exported, null, 2));
+    console.log(`\nExported ${exported.length} clips + clips.metadata.json → ${outDir}`);
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+function normalizeProvider(value) {
+    if (value === undefined || value === "gemini")
+        return "gemini";
+    if (value === "openai" || value === "openrouter")
+        return value;
+    throw new Error(`--provider must be gemini | openai | openrouter (got "${value}")`);
+}
+function normalizeTier(value) {
+    if (value === "flash")
+        return "flash";
+    if (value === "flash-lite" || value === undefined)
+        return "flash-lite";
+    throw new Error(`--tier must be "flash" or "flash-lite" (got "${value}")`);
+}
+// Best-guess embedding model for the --dry-run estimate when no key is present
+// (openrouter falls back to gemini embeddings by default).
+function defaultEmbedModelForEstimate(provider) {
+    return provider === "openai" ? "text-embedding-3-small" : "gemini-embedding-001";
+}
+const ENV_KEYS = {
+    gemini: ["GEMINI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
+    openai: ["OPENAI_API_KEY"],
+    openrouter: ["OPENROUTER_API_KEY"]
+};
+const CONFIG_KEYS = {
+    gemini: "gemini_api_key",
+    openai: "openai_api_key",
+    openrouter: "openrouter_api_key"
+};
+/** Resolve a provider key: --<provider>-key flag → *_API_KEY env → ~/.vidfarm/config.json. */
+function resolveProviderKey(provider, flags, opts = {}) {
+    const flagVal = flags[`${provider}-key`]?.trim();
+    if (flagVal)
+        return flagVal;
+    for (const env of ENV_KEYS[provider]) {
+        const v = (process.env[env] || "").trim();
+        if (v)
+            return v;
+    }
+    const cfgPath = path.join(resolveHome(), "config.json");
+    if (existsSync(cfgPath)) {
+        try {
+            const cfg = JSON.parse(readFileSync(cfgPath, "utf8"));
+            const v = cfg[CONFIG_KEYS[provider]]?.trim();
+            if (v)
+                return v;
+        }
+        catch {
+            /* ignore malformed config */
+        }
+    }
+    if (opts.optional)
+        return "";
+    const envHint = ENV_KEYS[provider][0];
+    throw new Error(`No ${provider} API key. Pass --${provider}-key <key> or set ${envHint}.`);
+}
+/**
+ * Embedding config for a scan. gemini/openai embed with their own key; openrouter
+ * can't embed, so pair it with a gemini/openai key via --embed-provider/--embed-key
+ * (or GEMINI_API_KEY/OPENAI_API_KEY env). Returns null → semantic search disabled.
+ */
+function resolveEmbeddingConfig(provider, apiKey, flags) {
+    if (provider === "gemini")
+        return { provider: "gemini", apiKey };
+    if (provider === "openai")
+        return { provider: "openai", apiKey };
+    // openrouter → look for an explicit embed provider, else any gemini/openai key.
+    const explicit = flags["embed-provider"]?.trim();
+    const tryProvider = (p) => {
+        const key = flags["embed-key"]?.trim() || resolveProviderKey(p, flags, { optional: true });
+        return key ? { provider: p, apiKey: key } : null;
+    };
+    if (explicit === "gemini")
+        return tryProvider("gemini");
+    if (explicit === "openai")
+        return tryProvider("openai");
+    return tryProvider("gemini") ?? tryProvider("openai");
+}
+function clampInt(value, fallback, min, max) {
+    if (value === undefined)
+        return fallback;
+    const n = Math.round(Number(value));
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(min, Math.min(max, n));
+}
+function resolveHome() {
+    return process.env.VIDFARM_HOME ? path.resolve(process.env.VIDFARM_HOME) : path.join(homedir(), ".vidfarm");
+}
+async function confirm(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(question)).trim().toLowerCase();
+        return answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function tryParseJson(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("["))
+        return null;
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeTags(clip) {
+    const t = clip.tags;
+    const bits = [...t.subject.slice(0, 1), ...t.action.slice(0, 1), ...t.emotion.slice(0, 1)].filter(Boolean);
+    const energy = `⚡${t.energy}`;
+    const desc = clip.description ? `— ${clip.description.slice(0, 48)}` : "";
+    return `${bits.join("/") || "untagged"} ${energy} ${desc}`.trim();
+}
+function printHits(hits, ctx) {
+    console.log(`\n"${ctx.query}"  →  ${hits.length} results in ${ctx.ms}ms`);
+    console.log(`  filter: ${describeCriteria(ctx.criteria)}\n`);
+    if (hits.length === 0) {
+        console.log("  (no matches — try a broader query or scan more footage)");
+        return;
+    }
+    hits.forEach((hit, i) => {
+        const c = hit.clip;
+        const sim = hit.similarity != null ? ` sim=${hit.similarity.toFixed(2)}` : "";
+        console.log(`  ${String(i + 1).padStart(2)}. ${c.clip_id.slice(0, 14)}  ${fmtRange(c)}  score=${hit.score.toFixed(2)}${sim}`);
+        console.log(`      ${summarizeTags(c)}`);
+        console.log(`      ${c.thumbnail_path}`);
+    });
+}
+function describeCriteria(criteria) {
+    const parts = [];
+    for (const key of ["subject", "action", "emotion", "setting", "composition", "motion", "audio_type", "energy"]) {
+        const v = criteria[key];
+        if (Array.isArray(v) && v.length)
+            parts.push(`${key} ∈ {${v.join(",")}}`);
+    }
+    if (criteria.min_duration_sec != null)
+        parts.push(`≥${criteria.min_duration_sec}s`);
+    if (criteria.max_duration_sec != null)
+        parts.push(`≤${criteria.max_duration_sec}s`);
+    if (criteria.has_dialogue != null)
+        parts.push(criteria.has_dialogue ? "has dialogue" : "no dialogue");
+    if (criteria.has_subject != null)
+        parts.push(criteria.has_subject ? "has subject" : "no subject");
+    if (criteria.semantic_text)
+        parts.push(`~"${criteria.semantic_text}"`);
+    return parts.length ? parts.join(" · ") : "(no constraints)";
+}
+function withinTarget(usdPerHour) {
+    return usdPerHour <= 0.12;
+}
+function fmtRange(clip) {
+    return `${fmtClock(clip.start_time_sec)}–${fmtClock(clip.end_time_sec)} (${clip.duration_sec.toFixed(1)}s)`;
+}
+function fmtClock(sec) {
+    const m = Math.floor(sec / 60);
+    const s = Math.floor(sec % 60);
+    return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
+}
+function fmtDuration(sec) {
+    if (sec >= 60)
+        return `${Math.floor(sec / 60)}m${Math.round(sec % 60)}s`;
+    return `${sec.toFixed(1)}s`;
+}
+function timestamp() {
+    return process.hrtime();
+}
+function elapsedMs(start) {
+    const [s, ns] = process.hrtime(start);
+    return Math.round(s * 1000 + ns / 1e6);
+}
+function elapsed(start) {
+    const ms = elapsedMs(start);
+    return ms >= 1000 ? `${(ms / 1000).toFixed(1)}s` : `${ms}ms`;
+}
+//# sourceMappingURL=clips.js.map