@mevdragon/vidfarm-devcli 0.17.0 → 0.18.0

package/dist/src/devcli/clips.js

@@ -14,9 +14,9 @@ import { createInterface } from "node:readline/promises";
 import { createIdV7 } from "../lib/ids.js";
 import { buildEffectiveGuidance, ClipModelClient, detectLocalAgent, detectScenes, estimateScanCostFromScenes, fitScenesToDurationBand, formatCostEstimate, hasFfmpeg, LocalAgentClipClient, normalizeAspect, normalizeCropFocus, normalizeWindows, parseClipHuntPrompt, parseTimeRanges, probeVideo, resolveDurationBand, 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 + local agent by default)
+export const CLIPS_HELP = `vidfarm raws — build & search a local raws library (local ffmpeg + local agent by default)
 
-  clips scan <video-path>          Mine a long-form video into tagged, searchable clips
+  raws scan <video-path>           Mine a long-form video into tagged, searchable raws
     --provider <p>                 agent | gemini | openai | openrouter
                                    Default: agent when a local claude/codex CLI is installed
                                    (your subscription, no API key), else gemini.
@@ -27,8 +27,8 @@ export const CLIPS_HELP = `vidfarm clips — build & search a local clip library
                                    Inline hints are honored too: "between 12:30 and 15:45",
                                    "30 sec clips", "vertical", "no captions".
     --range "MM:SS-MM:SS"          Only hunt inside this source range (repeatable / comma-separated)
-    --duration <sec>               Target clip length as a SOFT band (10→5-20s, 30→20-40s, …)
-    --aspect <a>                   Crop clips to 9:16 | 16:9 | 4:3 | 1:1 (or vertical/horizontal/square)
+    --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)
@@ -52,25 +52,25 @@ export const CLIPS_HELP = `vidfarm clips — build & search a local clip library
     --embed-provider gemini|openai --embed-key <key>       Embeddings for agent/openrouter scans
     --home <dir>                   Library dir (default: ~/.vidfarm or VIDFARM_HOME)
 
-  clips list                       List clips in the library
-    --source <id>                  Only clips from one source video
+  raws list                        List raws in the library
+    --source <id>                  Only raws from one source video
     --limit <n> | --json
 
-  clips search "<natural language>"  Hybrid structured + semantic search
+  raws 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)
+  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
 
-  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>'
+  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>'
 
-  clips sources                    List scanned source videos
-  clips export <clip-ids...> --to <dir>   Copy clip mp4s (+ metadata.json) out
+  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];
@@ -96,7 +96,7 @@ export async function runClipsCommand(argv) {
         case "-h":
             return runOverview();
         default:
-            console.error(`Unknown clips subcommand: ${sub}\n`);
+            console.error(`Unknown raws subcommand: ${sub}\n`);
             console.log(CLIPS_HELP);
             process.exitCode = 1;
     }
@@ -106,8 +106,8 @@ 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(`vidfarm raws — library at ${resolveHome()}`);
+    console.log(`  ${stats.clips} raws · ${stats.sources} source videos · ${stats.presets} presets\n`);
     console.log(CLIPS_HELP);
 }
 // ── clips scan ──────────────────────────────────────────────────────────────
@@ -186,12 +186,12 @@ async function runScan(argv) {
     }
     const videoArg = positionals[0];
     if (!videoArg)
-        throw new Error("Usage: vidfarm clips scan <video-path> [--range MM:SS-MM:SS] [--duration 30] [--aspect 9:16] [--dry-run]");
+        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 `clips scan` but was not found (bundled ffmpeg-static missing and none on PATH).");
+        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)
@@ -217,24 +217,24 @@ async function runScan(argv) {
     const embedding = provider === "agent"
         ? resolveAgentEmbeddingConfig(values)
         : apiKey ? resolveEmbeddingConfig(provider, apiKey, values) : null;
-    console.log(`[clips] probing ${path.basename(videoPath)} …`);
+    console.log(`[raws] 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(`[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.");
     }
     if (windows.length) {
-        console.log(`[clips] 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)}).`);
+        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(`[clips] target clip length ~${durationBand.target_sec}s (soft range ${durationBand.min_sec}–${durationBand.max_sec}s).`);
+        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(`[clips] cropping clips to ${aspect} (${cropFocus}).`);
+        console.log(`[raws] cropping clips to ${aspect} (${cropFocus}).`);
     if (avoidText)
-        console.log(`[clips] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
-    console.log(`[clips] detecting scenes …`);
+        console.log(`[raws] preferring scenes without on-screen text/captions (selection only — GhostCut is never run on the source).`);
+    console.log(`[raws] detecting scenes …`);
     const detected = await detectScenes(videoPath, { durationSec: probe.duration_sec, windows, ...sceneOptions });
     const scenes = fitScenesToDurationBand(detected, durationBand);
     if (scenes.length === 0)
@@ -247,13 +247,13 @@ async function runScan(argv) {
             embedding,
             tier
         });
-        console.log(`[clips] evaluating scenes with your local ${client.tagModelId} subscription (no API cost).`);
+        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(`[clips] no embedding provider for "${provider}" — clips will be structured-searchable only.`);
+        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
@@ -279,7 +279,7 @@ async function runScan(argv) {
         console.log(`  Guidance: "${guidance.replace(/\n/g, " · ")}"`);
     console.log("");
     if (values["dry-run"]) {
-        console.log("[clips] --dry-run: not scanning. Re-run without --dry-run to build the library.");
+        console.log("[raws] --dry-run: not scanning. Re-run without --dry-run to build the library.");
         return;
     }
     // Actually scanning now — an evaluator is required.
@@ -293,7 +293,7 @@ async function runScan(argv) {
     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("[clips] aborted.");
+            console.log("[raws] aborted.");
             return;
         }
     }
@@ -301,7 +301,7 @@ async function runScan(argv) {
     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.`);
+            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);
@@ -319,7 +319,7 @@ async function runScan(argv) {
         reencodeClips: true,
         crop: aspect && aspect !== "original" ? { aspect, focus: cropFocus } : undefined
     };
-    console.log(`[clips] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
+    console.log(`[raws] scanning ${scenes.length} scenes (${provider}/${activeClient.tagModelId}, ${concurrency}x) …`);
     let errors = 0;
     const started = timestamp();
     const result = await scanVideo({
@@ -333,10 +333,10 @@ async function runScan(argv) {
         concurrency,
         onRefine: (r) => {
             if (r.refined) {
-                console.log(`[clips] guided segmentation: ${scenes.length} → ${r.kept} clips (dropped ${r.dropped}, merged ${r.merged}).`);
+                console.log(`[raws] guided segmentation: ${scenes.length} → ${r.kept} raws (dropped ${r.dropped}, merged ${r.merged}).`);
             }
             else if (r.note) {
-                console.log(`[clips] guided segmentation skipped: ${r.note}.`);
+                console.log(`[raws] guided segmentation skipped: ${r.note}.`);
             }
         },
         onClip: (clip, i, total) => {
@@ -365,10 +365,10 @@ async function runScan(argv) {
         /* 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"`);
+    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)
@@ -384,13 +384,13 @@ async function runScanCloud(input) {
     let fileName;
     if (!input.sourceUrl) {
         if (!input.videoArg)
-            throw new Error("Usage: vidfarm clips scan --cloud <video-path> | --cloud --url <video-url>");
+            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(`[clips] uploading ${fileName} (${(sizeBytes / (1024 * 1024)).toFixed(1)} MB) to your temp folder (auto-deletes in 30 days) …`);
+        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,
@@ -428,8 +428,8 @@ async function runScanCloud(input) {
         }
         tempFileId = presign.file_id;
     }
-    console.log(`[clips] starting cloud hunt …`);
-    const scanRes = await fetch(`${baseUrl}/clips/scan`, {
+    console.log(`[raws] starting cloud hunt …`);
+    const scanRes = await fetch(`${baseUrl}/raws/scan`, {
         method: "POST",
         headers,
         body: JSON.stringify({
@@ -450,28 +450,28 @@ async function runScanCloud(input) {
     if (!scanRes.ok || !scan.scan_id) {
         throw new Error(`Cloud scan failed to start (${scanRes.status}): ${scan.error ?? "unexpected response"}`);
     }
-    console.log(`[clips] scan ${scan.scan_id} ${scan.status ?? "queued"}${scan.tracer ? ` (tracer ${scan.tracer})` : ""}.`);
+    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(`[clips] estimated AWS compute charge ~$${scan.compute_estimate.estimated_charge_usd.toFixed(4)} (AI runs on your saved provider keys).`);
+        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}/clips/scan/${encodeURIComponent(scan.scan_id)}`, { headers });
+        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[clips] cloud hunt done in ${elapsed(started)}: ${poll.source?.clip_count ?? 0} clips.`);
-            console.log(`  browse → ${baseUrl}/clips`);
+            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[clips] ${status} … ${elapsed(started)} `);
+        process.stdout.write(`\r[raws] ${status} … ${elapsed(started)} `);
     }
 }
 /**
@@ -523,13 +523,13 @@ async function runList(argv) {
         return;
     }
     if (clips.length === 0) {
-        console.log("No clips yet. Run: vidfarm clips scan <video-path>");
+        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} clips.`);
+    console.log(`\n${clips.length} raws.`);
 }
 // ── clips search ────────────────────────────────────────────────────────────
 async function runSearch(argv) {
@@ -548,12 +548,12 @@ async function runSearch(argv) {
     });
     const query = positionals.join(" ").trim();
     if (!query)
-        throw new Error('Usage: vidfarm clips search "<natural language>"');
+        throw new Error('Usage: vidfarm raws 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>");
+        console.log("Library is empty — scan a video first: vidfarm raws scan <video-path>");
         return;
     }
     const provider = normalizeProvider(values.provider);
@@ -566,7 +566,7 @@ async function runSearch(argv) {
         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.`);
+                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);
         }
@@ -575,11 +575,11 @@ async function runSearch(argv) {
         // 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(`[clips] structuring query with your local ${agent.tagModelId} …`);
+        console.log(`[raws] structuring query with your local ${agent.tagModelId} …`);
         criteria = await agent.naturalLanguageToCriteria(query);
     }
     else {
-        console.warn(`[clips] no ${provider} key or local agent CLI — structured/keyword search only.`);
+        console.warn(`[raws] no ${provider} key or local agent CLI — structured/keyword search only.`);
     }
     const t0 = timestamp();
     const hits = store.search({ criteria, queryEmbedding, limit });
@@ -627,7 +627,7 @@ async function runMatch(argv) {
     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>");
+        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.
@@ -636,7 +636,7 @@ async function runMatch(argv) {
     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).`);
+        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))
@@ -670,7 +670,7 @@ async function runMatch(argv) {
             console.log(JSON.stringify(output, null, 2));
             return;
         }
-        console.log(`Matched ${scenes.length} scenes against ${all.length} clips:`);
+        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)` : "";
@@ -699,7 +699,7 @@ async function runMatch(argv) {
         text = positionals.join(" ").trim();
         if (!text) {
             store.close();
-            throw new Error('Usage: vidfarm clips match "<text>" | --criteria \'<json>\' | --scenes <annotations.json>');
+            throw new Error('Usage: vidfarm raws match "<text>" | --criteria \'<json>\' | --scenes <annotations.json>');
         }
         criteria = { semantic_text: text };
     }
@@ -724,7 +724,7 @@ async function runPreset(argv) {
         return runPresetRun(rest);
     if (action === "save")
         return runPresetSave(rest);
-    throw new Error("Usage: vidfarm clips preset <list|run <name>|save <name> --from-query '<...>'>");
+    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" } } });
@@ -756,12 +756,12 @@ async function runPresetRun(argv) {
     });
     const name = positionals.join(" ").trim();
     if (!name)
-        throw new Error("Usage: vidfarm clips preset run <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 clips preset list`);
+        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.
@@ -800,7 +800,7 @@ async function runPresetSave(argv) {
     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>'");
+        throw new Error("Usage: vidfarm raws preset save <name> --from-query '<json | natural language>'");
     }
     let criteria;
     const asJson = tryParseJson(fromQuery);
@@ -857,7 +857,7 @@ async function runExport(argv) {
     const ids = positionals;
     const to = values.to;
     if (ids.length === 0 || !to) {
-        throw new Error("Usage: vidfarm clips export <clip-ids...> --to <dir>");
+        throw new Error("Usage: vidfarm raws export <raw-ids...> --to <dir>");
     }
     const outDir = path.resolve(process.cwd(), to);
     mkdirSync(outDir, { recursive: true });
@@ -885,7 +885,7 @@ async function runExport(argv) {
     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}`);
+    console.log(`\nExported ${exported.length} raws + clips.metadata.json → ${outDir}`);
 }
 // ── helpers ─────────────────────────────────────────────────────────────────
 function normalizeProvider(value) {