@officexapp/vidfarm-devcli 0.21.10

package/dist/src/devcli/clips.js

@@ -0,0 +1,1138 @@
+// devcli `vidfarm clips …` — the local clip-curation surface. LOCAL-FIRST:
+// local ffmpeg for compute and, by default, the user's local agent CLI
+// subscription (claude/codex) for scene evaluation — no API key needed. BYOK
+// provider keys are the first fallback, and `--cloud` is the explicit backup
+// that runs the hunt on the deployed pipeline instead (never the default).
+// Persists to a SQLite clip library (~/.vidfarm). Every keyed 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, statSync } 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 { buildEffectiveGuidance, buildPrivateUserNotesGuidance, ClipModelClient, DEFAULT_CLIP_ASPECT, DEFAULT_CLIP_DURATION_BAND, detectLocalAgent, detectScenes, effectiveHuntDurationSec, estimateScanCostFromScenes, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, resolveTargetClipCount, scanVideo, searchClips } from "../services/clip-curation/index.js";
+import { ClipStore } from "./clip-store.js";
+export const CLIPS_HELP = `vidfarm raws — build & search a local raws library (local ffmpeg + local agent by default)
+
+  raws scan <video-path>           Mine a long-form video into tagged, searchable raws
+    --provider <p>                 agent | gemini | openai | openrouter | nvidia
+                                   Default: agent when a local claude/codex CLI is installed
+                                   (your subscription, no API key), else gemini.
+                                   nvidia = lite, clipping-first key (minimax-m3); no audio/embeddings.
+    --agent claude|codex           Which local agent CLI to use for --provider agent (default: auto)
+    --tier flash|flash-lite        Gemini tier (default: flash-lite; ignored for openai/openrouter/agent)
+    --prompt "<guidance>"          Reshape clipping toward your goal: an LLM pass
+                                   keeps/drops/merges scenes, and tags are biased to it.
+                                   Inline hints are honored too: "between 12:30 and 15:45",
+                                   "30 sec clips", "vertical", "no captions".
+    --notes "<private notes>"      Store private owner notes as user_notes on derived raws
+                                   and feed them into decomposition/categorization. Explicit
+                                   private shot-kind hints like "content_type: demo" or
+                                   "category: talking_head" are honored and stay owner-only.
+    --range "MM:SS-MM:SS"          Only hunt inside this source range (repeatable / comma-separated)
+    --duration <sec>               Target raw length as a SOFT band (10→5-20s, 30→20-40s, …)
+    --aspect <a>                   Crop raws to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
+    --crop-focus <f>               center | top | bottom | left | right (default: center)
+    --no-text                      Prefer scenes WITHOUT burned-in captions/on-screen text
+                                   (scene selection — NEVER GhostCut on the long-form source)
+    --no-refine                    Keep prompt tag-bias but skip the keep/drop/merge pass
+    --cloud                        BACKUP: run the hunt on the deployed pipeline instead of this
+                                   machine (uploads to your temp folder — auto-deletes in 30 days —
+                                   or pass --url; needs VIDFARM_API_KEY; bills AWS compute only)
+    --url <video-url>              With --cloud: hunt a YouTube/TikTok/IG/X URL without uploading
+    --tracer <id>                  With --cloud: tag the hunt's billing/observability rollup
+    --api-url <base>               With --cloud: deployment base URL (or VIDFARM_API_URL)
+    --api-key <key>                With --cloud: API key (or VIDFARM_API_KEY)
+    --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)
+    --audio-only                   Save each mined clip as an audio-only .m4a (no video); waveform thumb
+    --concurrency <n>              Parallel scenes (default 3; agent default 2)
+    --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; --duration overrides)
+    --gemini-key / --openai-key / --openrouter-key / --nvidia-key <key>   Provider key (or *_API_KEY env)
+    --embed-provider gemini|openai --embed-key <key>       Embeddings for agent/openrouter/nvidia scans
+    --home <dir>                   Library dir (default: ~/.vidfarm or VIDFARM_HOME)
+
+  raws list                        List raws in the library
+    --source <id>                  Only raws from one source video
+    --content-type <a,b>           Only raws whose shot-KIND tag matches (comma-separated,
+                                   exact): talking_head, b_roll, product_shot, screen_recording,
+                                   demo, reaction, interview, establishing, lifestyle, text_graphic
+    --offset <n>                   Skip the first N (paginate with --limit)
+    --limit <n> | --json
+
+  raws search "<natural language>"   Hybrid structured + semantic search
+    --content-type <a,b>           Post-filter hits by shot-KIND tag (see \`raws list\`)
+    --limit <n> | --json | --gemini-key <key>
+
+  raws match "<text>"              Top library raws 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
+
+  raws preset list                 List built-in + saved presets
+  raws preset run <name>           Run a preset query   [--limit <n>] [--json]
+  raws preset save <name> --from-query '<json | natural language>'
+
+  raws sources                     List scanned source videos
+  raws export <raw-ids...> --to <dir>   Copy raw 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 raws 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 raws — library at ${resolveHome()}`);
+    console.log(`  ${stats.clips} raws · ${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" },
+            agent: { type: "string" },
+            tier: { type: "string" },
+            prompt: { type: "string" },
+            range: { type: "string", multiple: true },
+            duration: { type: "string" },
+            aspect: { type: "string" },
+            "crop-focus": { type: "string" },
+            "no-text": { type: "boolean" },
+            "allow-text": { type: "boolean" },
+            "max-clips": { type: "string" },
+            "no-refine": { type: "boolean" },
+            "audio-only": { type: "boolean" },
+            cloud: { type: "boolean" },
+            url: { type: "string" },
+            tracer: { type: "string" },
+            folder: { type: "string" },
+            "api-url": { type: "string" },
+            "api-key": { type: "string" },
+            "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" },
+            "nvidia-key": { type: "string" },
+            "embed-provider": { type: "string" },
+            "embed-key": { type: "string" },
+            notes: { type: "string" },
+            home: { type: "string" }
+        }
+    });
+    // ── Hunt spec: explicit flags win; inline prompt hints fill the gaps ──────
+    const userNotes = values.notes?.trim() || undefined;
+    const guidancePromptRaw = values.prompt?.trim() || undefined;
+    const parsedPrompt = parseClipHuntPrompt(guidancePromptRaw);
+    const rawWindows = values.range?.length
+        ? parseTimeRanges(values.range)
+        : parsedPrompt.windows;
+    // Explicit flags / prompt hints win; otherwise fall back to the same
+    // unspecified-prompt product defaults (5–15s clips, vertical 9:16, avoid text,
+    // ~10 clips / 10 min). Opt out with `--aspect original` / `--allow-text`.
+    const explicitBand = values.duration
+        ? resolveDurationBand(Number(values.duration))
+        : parsedPrompt.target_duration_sec != null
+            ? resolveDurationBand(parsedPrompt.target_duration_sec)
+            : null;
+    const durationBand = explicitBand ?? { ...DEFAULT_CLIP_DURATION_BAND };
+    const explicitAspect = values.aspect
+        ? (normalizeAspect(values.aspect) ?? (() => { throw new Error(`--aspect must be 9:16 | 16:9 | 4:3 | 1:1 | original (or vertical/horizontal/square), got "${values.aspect}"`); })())
+        : parsedPrompt.aspect;
+    const aspect = explicitAspect ?? DEFAULT_CLIP_ASPECT;
+    const cropFocus = normalizeCropFocus(values["crop-focus"]);
+    const avoidText = values["allow-text"] ? false : (Boolean(values["no-text"]) || parsedPrompt.avoid_text || true);
+    const maxClips = values["max-clips"] ? Math.max(1, Math.round(Number(values["max-clips"]))) : parsedPrompt.max_clips ?? undefined;
+    const guidance = buildEffectiveGuidance({
+        contentPrompt: [guidancePromptRaw, buildPrivateUserNotesGuidance(userNotes)].filter(Boolean).join("\n"),
+        avoidText
+    }) || undefined;
+    // ── BACKUP path: run the hunt on the deployed pipeline (--cloud) ──────────
+    if (values.cloud) {
+        const apiProvider = values.provider && !["agent", "local", "local-agent"].includes(values.provider)
+            ? normalizeProvider(values.provider)
+            : undefined; // unset → the cloud auto-picks from the account's saved keys
+        return runScanCloud({
+            videoArg: positionals[0],
+            sourceUrl: values.url?.trim() || undefined,
+            apiUrl: values["api-url"],
+            apiKey: values["api-key"],
+            tracer: values.tracer,
+            folder: values.folder,
+            prompt: guidancePromptRaw,
+            userNotes,
+            provider: apiProvider,
+            windows: rawWindows,
+            durationBand,
+            aspect,
+            cropFocus,
+            avoidText,
+            maxClips,
+            audioOnly: Boolean(values["audio-only"])
+        });
+    }
+    const videoArg = positionals[0];
+    if (!videoArg)
+        throw new Error("Usage: vidfarm raws scan <video-path> [--range MM:SS-MM:SS] [--duration 30] [--aspect 9:16] [--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 `raws scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
+    }
+    // ── Model resolution: LOCAL-FIRST ─────────────────────────────────────────
+    // 1. --provider agent (or no --provider + a local claude/codex CLI installed)
+    //    → the user's local agent subscription evaluates scenes; no API key.
+    // 2. --provider gemini|openai|openrouter (or a key in env/config) → BYOK API.
+    // 3. --cloud (handled above) → the deployed pipeline, as an explicit backup.
+    const provider = resolveScanProvider(values);
+    const tier = normalizeTier(values.tier);
+    const framesPerScene = clampInt(values.frames, 2, 1, 3);
+    // Audio is Gemini-only (chat models on openai/openrouter — and CLI agents — don't take the clip).
+    const includeAudio = !values["no-audio"] && provider === "gemini";
+    // Local agents run one process per call — keep parallelism modest by default.
+    const concurrency = clampInt(values.concurrency, provider === "agent" ? 2 : 3, 1, 12);
+    const sceneOptions = {
+        threshold: values.threshold ? Number(values.threshold) : undefined,
+        minSceneSec: values["min-scene"] ? Number(values["min-scene"]) : undefined,
+        // A duration band lifts the split ceiling; an explicit --max-scene still wins.
+        maxSceneSec: values["max-scene"] ? Number(values["max-scene"]) : durationBand?.max_sec
+    };
+    // Resolve the tagging key + optional embedding config. Optional here so
+    // --dry-run can show the cost without a key; required below to scan (API providers).
+    const apiKey = provider === "agent" ? "" : resolveProviderKey(provider, values, { optional: true });
+    const embedding = provider === "agent"
+        ? resolveAgentEmbeddingConfig(values)
+        : apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
+    console.log(`[raws] probing ${path.basename(videoPath)} …`);
+    const probe = await probeVideo(videoPath);
+    console.log(`[raws] ${fmtDuration(probe.duration_sec)} · ${probe.width ?? "?"}x${probe.height ?? "?"} · ${probe.codec ?? "?"}`);
+    const windows = normalizeWindows(rawWindows, probe.duration_sec);
+    if (rawWindows.length && !windows.length) {
+        throw new Error("--range produced no usable window inside the video's duration.");
+    }
+    // Density/uniqueness target: ~10 clips / 10 min unless --max-clips / "N clips".
+    const targetClipCount = resolveTargetClipCount(effectiveHuntDurationSec(probe.duration_sec, windows), { max_clips: maxClips });
+    if (windows.length) {
+        console.log(`[raws] hunting only ${windows.map((w) => `${fmtClock(w.start_sec)}–${fmtClock(w.end_sec)}`).join(", ")} (${fmtDuration(windows.reduce((a, w) => a + w.end_sec - w.start_sec, 0))} of ${fmtDuration(probe.duration_sec)}).`);
+    }
+    if (durationBand) {
+        console.log(`[raws] target clip length ~${durationBand.target_sec}s (soft range ${durationBand.min_sec}–${durationBand.max_sec}s).`);
+    }
+    if (aspect && aspect !== "original")
+        console.log(`[raws] cropping clips to ${aspect} (${cropFocus}).`);
+    if (avoidText)
+        console.log(`[raws] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
+    console.log(`[raws] aiming for ~${targetClipCount} distinct raw${targetClipCount === 1 ? "" : "s"}${maxClips ? " (--max-clips)" : " (~10 / 10 min)"}.`);
+    console.log(`[raws] detecting scenes …`);
+    const scenes = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
+    if (scenes.length === 0)
+        throw new Error("No scenes detected (is the video readable / non-empty?).");
+    const store = new ClipStore(values.home);
+    let client = null;
+    if (provider === "agent") {
+        client = new LocalAgentClipClient({
+            agent: values.agent === "claude" || values.agent === "codex" ? values.agent : "auto",
+            embedding,
+            tier
+        });
+        console.log(`[raws] evaluating scenes with your local ${client.tagModelId} subscription (no API cost).`);
+    }
+    else if (apiKey) {
+        client = new ClipModelClient({ provider, apiKey, tier, embedding });
+    }
+    if (client && !client.canEmbed) {
+        console.warn(`[raws] no embedding provider for "${provider}" — raws will be structured-searchable only.`);
+        console.warn(`        Add --embed-provider gemini|openai --embed-key <key> for semantic search.`);
+    }
+    // Cost estimate: local-agent scans ride the user's subscription, so only the
+    // optional embedding spend applies; API scans estimate the full BYOK cost.
+    const estimate = provider === "agent"
+        ? null
+        : estimateScanCostFromScenes(scenes, {
+            tier,
+            provider,
+            tagModelId: client?.tagModelId,
+            embedModelId: client ? client.embeddingModelId : defaultEmbedModelForEstimate(provider),
+            framesPerScene,
+            includeAudio
+        });
+    if (estimate) {
+        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"}).`);
+    }
+    else {
+        console.log(`\n  Cost: local agent subscription (${scenes.length} scenes; embeddings ${embedding ? `via ${embedding.provider}` : "off"}).`);
+    }
+    if (guidance)
+        console.log(`  Guidance: "${guidance.replace(/\n/g, " · ")}"`);
+    console.log("");
+    if (values["dry-run"]) {
+        console.log("[raws] --dry-run: not scanning. Re-run without --dry-run to build the library.");
+        return;
+    }
+    // Actually scanning now — an evaluator is required.
+    if (!client) {
+        if (provider !== "agent")
+            resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+        throw new Error("No scene evaluator available. Install Claude Code (`claude`) or Codex (`codex`), pass a provider key, or run with --cloud.");
+    }
+    const activeClient = client;
+    // $1 confirmation gate (handoff Target 1) — keyed scans only.
+    if (estimate && 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("[raws] 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(`[raws] 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: guidance,
+        userNotes,
+        refineSegmentation: !values["no-refine"],
+        reencodeClips: true,
+        audioOnly: Boolean(values["audio-only"]),
+        crop: aspect && aspect !== "original" ? { aspect, focus: cropFocus } : undefined
+    };
+    console.log(`[raws] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
+    let errors = 0;
+    const started = timestamp();
+    const result = await scanVideo({
+        ctx,
+        videoPath,
+        scenes,
+        probe,
+        windows,
+        durationBand,
+        targetClipCount,
+        sourceFilename: path.basename(videoPath),
+        concurrency,
+        onRefine: (r) => {
+            if (r.refined) {
+                console.log(`[raws] guided segmentation: ${scenes.length} → ${r.kept} raws (dropped ${r.dropped}, merged ${r.merged}).`);
+            }
+            else if (r.note) {
+                console.log(`[raws] 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[raws] done in ${elapsed(started)}: ${result.clips.length} raws${errors ? `, ${errors} scene(s) failed` : ""}.`);
+    console.log(`  raws → ${store.paths.clipsDir}`);
+    console.log(`  db   → ${store.paths.db}`);
+    console.log(`  try:  vidfarm raws search "…"  |  vidfarm raws preset run "funny reaction gifs"`);
+}
+// ── clips scan --cloud (explicit backup: the deployed pipeline) ─────────────
+// Uploads the local file into the user's temp folder (30-day TTL, auto-removed)
+// — or passes --url straight through — then starts POST /clips/scan and polls.
+// The hunt bills AWS compute only; AI runs on the account's saved BYOK keys.
+async function runScanCloud(input) {
+    const baseUrl = (input.apiUrl || process.env.VIDFARM_API_URL || process.env.VIDFARM_UPSTREAM_HOST || "https://vidfarm.cc").replace(/\/$/, "");
+    const apiKey = input.apiKey || process.env.VIDFARM_API_KEY || "";
+    if (!apiKey)
+        throw new Error("--cloud needs an API key: pass --api-key or set VIDFARM_API_KEY.");
+    const headers = { "vidfarm-api-key": apiKey, "content-type": "application/json", accept: "application/json" };
+    let tempFileId;
+    let fileName;
+    if (!input.sourceUrl) {
+        if (!input.videoArg)
+            throw new Error("Usage: vidfarm raws scan --cloud <video-path> | --cloud --url <video-url>");
+        const videoPath = path.resolve(process.cwd(), input.videoArg);
+        if (!existsSync(videoPath))
+            throw new Error(`No such video: ${videoPath}`);
+        fileName = path.basename(videoPath);
+        const sizeBytes = statSync(videoPath).size;
+        console.log(`[raws] uploading ${fileName} (${(sizeBytes / (1024 * 1024)).toFixed(1)} MB) to your temp folder (auto-deletes in 30 days) …`);
+        const presignRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files/presign`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ file_name: fileName, content_type: "video/mp4", size_bytes: sizeBytes, folder_path: "clip-sources" })
+        });
+        const presign = await presignRes.json();
+        if (!presignRes.ok || !presign.upload || !presign.file_id) {
+            throw new Error(`Temp upload presign failed (${presignRes.status}): ${presign.error ?? "unexpected response"}`);
+        }
+        if (presign.transport !== "presigned") {
+            throw new Error("The deployment does not support presigned uploads — upload via the web UI, then re-run with --url or temp_file_id.");
+        }
+        const putRes = await fetch(presign.upload.url, {
+            method: presign.upload.method,
+            headers: presign.upload.headers,
+            body: readFileSync(path.resolve(process.cwd(), input.videoArg))
+        });
+        if (!putRes.ok)
+            throw new Error(`Upload failed (${putRes.status}).`);
+        const finalizeRes = await fetch(`${baseUrl}/api/v1/user/me/temporary-files`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                file_id: presign.file_id,
+                file_name: fileName,
+                content_type: "video/mp4",
+                size_bytes: sizeBytes,
+                storage_key: presign.storage_key,
+                folder_path: "clip-sources"
+            })
+        });
+        if (!finalizeRes.ok) {
+            const body = await finalizeRes.text().catch(() => "");
+            throw new Error(`Temp upload finalize failed (${finalizeRes.status}): ${body.slice(0, 300)}`);
+        }
+        tempFileId = presign.file_id;
+    }
+    console.log(`[raws] starting cloud hunt …`);
+    const scanRes = await fetch(`${baseUrl}/raws/scan`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+            ...(input.sourceUrl ? { source_url: input.sourceUrl } : { temp_file_id: tempFileId, filename: fileName }),
+            prompt: input.prompt ?? "",
+            ...(input.userNotes ? { user_notes: input.userNotes } : {}),
+            ...(input.provider ? { provider: input.provider } : {}),
+            ...(input.tracer ? { tracer: input.tracer } : {}),
+            ...(input.folder ? { folder_path: input.folder } : {}),
+            hunt_spec: {
+                ...(input.windows.length ? { windows: input.windows } : {}),
+                ...(input.durationBand ? { duration_band: input.durationBand } : {}),
+                ...(input.aspect ? { aspect: input.aspect } : {}),
+                crop_focus: input.cropFocus,
+                // Send explicitly (incl. false) so --allow-text can override the
+                // server-side avoid-text default.
+                avoid_text: input.avoidText,
+                ...(input.maxClips ? { max_clips: input.maxClips } : {}),
+                ...(input.audioOnly ? { audio_only: true } : {})
+            }
+        })
+    });
+    const scan = await scanRes.json();
+    if (!scanRes.ok || !scan.scan_id) {
+        throw new Error(`Cloud scan failed to start (${scanRes.status}): ${scan.error ?? "unexpected response"}`);
+    }
+    console.log(`[raws] scan ${scan.scan_id} ${scan.status ?? "queued"}${scan.tracer ? ` (tracer ${scan.tracer})` : ""}.`);
+    if (scan.compute_estimate?.estimated_charge_usd != null) {
+        console.log(`[raws] estimated AWS compute charge ~$${scan.compute_estimate.estimated_charge_usd.toFixed(4)} (AI runs on your saved provider keys).`);
+    }
+    // Async by design — poll until the pipeline finishes.
+    const started = timestamp();
+    for (;;) {
+        await new Promise((r) => setTimeout(r, 5000));
+        const pollRes = await fetch(`${baseUrl}/raws/scan/${encodeURIComponent(scan.scan_id)}`, { headers });
+        if (!pollRes.ok)
+            continue;
+        const poll = await pollRes.json();
+        const status = poll.source?.status ?? poll.scan?.status ?? "running";
+        if (status === "complete") {
+            console.log(`\n[raws] cloud hunt done in ${elapsed(started)}: ${poll.source?.clip_count ?? 0} raws.`);
+            console.log(`  browse → ${baseUrl}/library/raws`);
+            return;
+        }
+        if (status === "failed") {
+            throw new Error(`Cloud hunt failed: ${poll.scan?.error ?? "unknown error"}`);
+        }
+        process.stdout.write(`\r[raws] ${status} … ${elapsed(started)} `);
+    }
+}
+/**
+ * LOCAL-FIRST provider pick: an explicit --provider always wins; otherwise use
+ * the local agent CLI when one is installed (subscription-powered, keyless),
+ * else fall back to gemini BYOK. The cloud pipeline is never a silent default
+ * — it's the explicit `--cloud` backup.
+ */
+function resolveScanProvider(values) {
+    if (values.provider === "agent" || values.provider === "local" || values.provider === "local-agent")
+        return "agent";
+    if (values.provider)
+        return normalizeProvider(values.provider);
+    if (values.agent)
+        return "agent";
+    if (detectLocalAgent())
+        return "agent";
+    return "gemini";
+}
+/** Embeddings for a local-agent scan: any gemini/openai key found makes the library semantically searchable. */
+function resolveAgentEmbeddingConfig(flags) {
+    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");
+}
+// ── clips list ──────────────────────────────────────────────────────────────
+async function runList(argv) {
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            source: { type: "string" },
+            "content-type": { type: "string" },
+            offset: { type: "string" },
+            limit: { type: "string" },
+            json: { type: "boolean" },
+            home: { type: "string" }
+        }
+    });
+    const store = new ClipStore(values.home);
+    const clips = store.listClips({
+        sourceVideoId: values.source,
+        contentTypes: parseContentTypes(values["content-type"]),
+        offset: values.offset ? clampInt(values.offset, 0, 0, 1_000_000) : undefined,
+        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 raws yet. Run: vidfarm raws 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} raws.`);
+}
+// ── clips search ────────────────────────────────────────────────────────────
+async function runSearch(argv) {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            provider: { type: "string" },
+            "content-type": { 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 raws search "<natural language>"');
+    const contentTypes = parseContentTypes(values["content-type"]);
+    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 raws 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(`[raws] 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 if (detectLocalAgent()) {
+        // Local-first: no key, but a local agent CLI can still turn the natural-
+        // language query into a structured filter (vector re-rank needs a key).
+        const agent = new LocalAgentClipClient({});
+        console.log(`[raws] structuring query with your local ${agent.tagModelId} …`);
+        criteria = await agent.naturalLanguageToCriteria(query);
+    }
+    else {
+        console.warn(`[raws] no ${provider} key or local agent CLI — structured/keyword search only.`);
+    }
+    const t0 = timestamp();
+    // Over-fetch when a content-type filter is on so the post-filter still fills
+    // the requested limit (the tag lives in tags_json, not the search index).
+    const searchLimit = contentTypes.length ? Math.min(1000, limit * 5) : limit;
+    let hits = store.search({ criteria, queryEmbedding, limit: searchLimit });
+    if (contentTypes.length) {
+        hits = hits.filter((h) => (h.clip.tags.content_type ?? []).some((t) => contentTypes.includes(String(t).toLowerCase()))).slice(0, 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 raws 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(`[raws] 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} raws:`);
+        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 raws 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 raws 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 raws 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 raws 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 raws preset save <name> --from-query '<json | natural language>'");
+    }
+    let criteria;
+    const asJson = tryParseJson(fromQuery);
+    if (asJson && typeof asJson === "object") {
+        criteria = asJson;
+    }
+    else {
+        // Natural language → structured: provider key when present, else the
+        // local agent CLI (local-first), else the usual missing-key error.
+        const provider = normalizeProvider(values.provider);
+        const apiKey = resolveProviderKey(provider, values, { optional: true });
+        if (apiKey) {
+            criteria = await new ClipModelClient({ provider, apiKey }).naturalLanguageToCriteria(fromQuery);
+        }
+        else if (detectLocalAgent()) {
+            criteria = await new LocalAgentClipClient({}).naturalLanguageToCriteria(fromQuery);
+        }
+        else {
+            resolveProviderKey(provider, values); // throws the "No <provider> API key" error
+            throw new Error("unreachable");
+        }
+    }
+    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 raws export <raw-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} raws + clips.metadata.json → ${outDir}`);
+}
+// ── helpers ─────────────────────────────────────────────────────────────────
+function normalizeProvider(value) {
+    if (value === undefined || value === "gemini")
+        return "gemini";
+    if (value === "openai" || value === "openrouter" || value === "nvidia")
+        return value;
+    throw new Error(`--provider must be gemini | openai | openrouter | nvidia (got "${value}")`);
+}
+// Parse a comma-separated --content-type flag into lowercase shot-KIND tags for
+// the tags.content_type filter (talking_head, b_roll, product_shot, …).
+function parseContentTypes(value) {
+    if (!value)
+        return [];
+    return value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+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"],
+    nvidia: ["NVIDIA_API_KEY"]
+};
+const CONFIG_KEYS = {
+    gemini: "gemini_api_key",
+    openai: "openai_api_key",
+    openrouter: "openrouter_api_key",
+    nvidia: "nvidia_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
+ * and nvidia can't embed, so pair them with a gemini/openai key via
+ * --embed-provider/--embed-key (or GEMINI_API_KEY/OPENAI_API_KEY env). Returns
+ * null → semantic search disabled (structured-only library).
+ */
+function resolveEmbeddingConfig(provider, apiKey, flags) {
+    if (provider === "gemini")
+        return { provider: "gemini", apiKey };
+    if (provider === "openai")
+        return { provider: "openai", apiKey };
+    // openrouter / nvidia → 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