@mevdragon/vidfarm-devcli 0.7.1 → 0.9.0

package/dist/src/cli.js

@@ -9,6 +9,8 @@ import { spawnSync } from "node:child_process";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLayerWithMedia } from "./devcli/composition-edit.js";
+import { runClipsCommand } from "./devcli/clips.js";
+import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
@@ -79,6 +81,19 @@ Discover & inspiration (browse the viral-video catalog, add your own source):
   inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
   inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
 
+Make a video in one command (orchestrates ingest → decompose → fork):
+  replicate <url>           Recreate an existing video end-to-end: fetch   → ingest + decompose + fork
+                            the URL, AI-decompose/recreate its scenes,
+                            and open an editable fork. --prompt "...and
+                            make it about X" steers the recreation.
+                            --title, --no-fork optional.
+  create "<prompt>"         Spin up a NEW video from a text prompt: AI-     → generate + ingest + decompose + fork
+                            generate a base video, wrap it into an
+                            editable template, decompose + fork. --duration
+                            <s>, --aspect-ratio, --resolution, --provider,
+                            --model, --audio, --ref <url|@file>, --title,
+                            --no-decompose, --no-fork. Needs a provider key.
+
 Composition lifecycle (fork → decompose → snapshot → render):
   fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
   pull <forkId>             Sync composition.html/json + video-context   → GET  .../compositions/:forkId/{composition.html,...}
@@ -128,6 +143,17 @@ Generate AI media and drop it on the timeline (for local coding agents):
   remove-video-captions <forkId>   Read the two video sources:        → GET  .../compositions/:forkId/remove-video-captions
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
+
+Clip curation (the third library — mine long-form video into a reusable clip store):
+  clips scan <video-path>   Detect scenes → tag + transcribe (Gemini)    LOCAL: ffmpeg + BYOK Gemini
+                            → embed → persist to ~/.vidfarm/clips.db.     (cloud: POST /clips/scan)
+    --tier flash|flash-lite   Gemini tier (default flash-lite, cheapest)
+    --dry-run                 Show the estimated cost and stop (over $1 needs --yes/confirm)
+  clips list                List the local clip library                  → GET  /clips
+  clips search "<text>"     Hybrid structured + semantic search          → POST /clips/search
+  clips preset list|run <name>|save <name> --from-query '<...>'          → /clips/presets
+  clips export <ids...> --to <dir>   Copy clip mp4s + metadata out
+                            (run 'vidfarm clips' for the full clips help)
   versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
   snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
   render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/render
@@ -220,8 +246,11 @@ Publish-mode options:
   --message <text>    Message attached to the published version snapshot
   --no-snapshot       Only update the working copy; skip the version snapshot
 `;
-void main().catch((error) => {
+void main().catch(async (error) => {
     console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    // Report only unexpected crashes (bugs), never the deliberate user-facing
+    // `throw new Error(...)` above; no-op unless a devcli DSN is configured.
+    await reportCliCrash(error);
     process.exit(1);
 });
 async function main() {
@@ -231,6 +260,9 @@ async function main() {
         return;
     }
     const command = argv[0];
+    // Opt-out crash telemetry (also covers the long-lived `serve` runtime, whose
+    // in-process job/render captures share this client). Guarded + no-op by default.
+    initTelemetry(command);
     const rest = argv.slice(1);
     switch (command) {
         // `serve` (and the bare `<template_id>` / legacy `edit` alias) boot the full
@@ -261,6 +293,12 @@ async function main() {
         case "inspiration-decompose":
             await runInspirationDecomposeCommand(rest);
             return;
+        case "replicate":
+            await runReplicateCommand(rest);
+            return;
+        case "create":
+            await runCreateCommand(rest);
+            return;
         case "fork":
             await runForkCommand(rest);
             return;
@@ -351,6 +389,9 @@ async function main() {
         case "save-file":
             await runPutFileCommand(rest);
             return;
+        case "clips":
+            await runClipsCommand(rest);
+            return;
         default:
             if (!command.startsWith("-")) {
                 // Positional template id → default to booting the local editor.
@@ -803,7 +844,10 @@ async function fetchCompositionFiles(input) {
     // can ground edits in what the video actually says and shows.
     // cast.json carries the identified recurring people/characters plus their
     // reference-still URLs so agents can reuse "the same person" in new gens.
-    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json"];
+    // scene-annotations.json carries the detected content format + per-scene
+    // literal + viral DNA an agent needs to REPLACE a scene from the clip library
+    // or RE-CREATE it from scratch (recreation_prompt + recreation_notes).
+    const files = ["composition.html", "composition.json", "manifest.json", "video-context.json", "cast.json", "scene-annotations.json"];
     for (const filename of files) {
         const target = path.join(input.dir, filename);
         if (existsSync(target) && !input.refetch) {
@@ -1176,54 +1220,14 @@ async function runInspirationAddCommand(argv) {
         if (!existsSync(localPath)) {
             throw new Error(`inspiration-add: "${source}" is not an http(s) URL and no such local file exists.`);
         }
-        const fileName = path.basename(localPath);
         const buffer = readFileSync(localPath);
-        const contentType = guessContentType(fileName);
-        const presign = await apiRequest({
-            method: "POST",
-            host: ctx.host,
-            path: "/discover/templates/upload/presign",
-            auth: ctx.auth,
-            body: { file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength }
-        });
-        assertApiOk(presign, "inspiration-add (presign)");
-        let storageKey = presign.json?.storage_key;
-        let uploadedName = presign.json?.file_name || fileName;
-        if (presign.json?.transport === "presigned" && presign.json?.upload?.url) {
-            const upload = presign.json.upload;
-            const put = await fetch(upload.url, {
-                method: upload.method || "PUT",
-                headers: upload.headers || {},
-                body: new Uint8Array(buffer)
-            });
-            if (!put.ok)
-                throw new Error(`inspiration-add upload failed with HTTP ${put.status}.`);
-        }
-        else {
-            const form = new FormData();
-            form.append("file", new Blob([new Uint8Array(buffer)], { type: contentType }), fileName);
-            const res = await fetch(new URL(presign.json?.upload?.url || "/discover/templates/upload", ctx.host), {
-                method: "POST",
-                headers: buildAuthHeaders(ctx.auth),
-                body: form
-            });
-            const json = await res.json().catch(() => null);
-            if (!res.ok || !json?.storage_key) {
-                throw new Error(`inspiration-add upload failed with HTTP ${res.status}${json?.error ? `: ${json.error}` : ""}.`);
-            }
-            storageKey = json.storage_key;
-            uploadedName = json.file_name || fileName;
-        }
-        if (!storageKey)
-            throw new Error("inspiration-add upload did not return a storage key.");
-        const result = await apiRequest({
-            method: "POST",
-            host: ctx.host,
-            path: "/discover/templates",
-            auth: ctx.auth,
-            body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: parsed.values.title, tagline: parsed.values.tagline, notes: parsed.values.notes }
+        const result = await ingestUploadedVideo(ctx, {
+            buffer,
+            fileName: path.basename(localPath),
+            title: parsed.values.title,
+            tagline: parsed.values.tagline,
+            notes: parsed.values.notes
         });
-        assertApiOk(result, "inspiration-add");
         emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
         return;
     }
@@ -1269,6 +1273,259 @@ async function runInspirationDecomposeCommand(argv) {
     }
     emitResult(result, ctx.json);
 }
+// Presign → PUT the bytes (or server multipart fallback) → POST /discover/templates
+// with the storage key. Shared by `inspiration-add` (local file) and `create`
+// (a generated MP4 wrapped into a new template). Returns the ingest ApiResult.
+async function ingestUploadedVideo(ctx, input) {
+    const { buffer, fileName } = input;
+    const contentType = input.contentType || guessContentType(fileName);
+    const presign = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/discover/templates/upload/presign",
+        auth: ctx.auth,
+        body: { file_name: fileName, content_type: contentType, size_bytes: buffer.byteLength }
+    });
+    assertApiOk(presign, "upload (presign)");
+    let storageKey = presign.json?.storage_key;
+    let uploadedName = presign.json?.file_name || fileName;
+    if (presign.json?.transport === "presigned" && presign.json?.upload?.url) {
+        const upload = presign.json.upload;
+        const put = await fetch(upload.url, {
+            method: upload.method || "PUT",
+            headers: upload.headers || {},
+            body: new Uint8Array(buffer)
+        });
+        if (!put.ok)
+            throw new Error(`upload failed with HTTP ${put.status}.`);
+    }
+    else {
+        const form = new FormData();
+        form.append("file", new Blob([new Uint8Array(buffer)], { type: contentType }), fileName);
+        const res = await fetch(new URL(presign.json?.upload?.url || "/discover/templates/upload", ctx.host), {
+            method: "POST",
+            headers: buildAuthHeaders(ctx.auth),
+            body: form
+        });
+        const json = await res.json().catch(() => null);
+        if (!res.ok || !json?.storage_key) {
+            throw new Error(`upload failed with HTTP ${res.status}${json?.error ? `: ${json.error}` : ""}.`);
+        }
+        storageKey = json.storage_key;
+        uploadedName = json.file_name || fileName;
+    }
+    if (!storageKey)
+        throw new Error("upload did not return a storage key.");
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/discover/templates",
+        auth: ctx.auth,
+        body: { upload: { storage_key: storageKey, file_name: uploadedName }, title: input.title, tagline: input.tagline, notes: input.notes }
+    });
+    assertApiOk(result, "ingest");
+    return result;
+}
+// Poll GET /api/v1/videos/:id (which finalizes the download job and mints the
+// template once the source video lands) until the inspiration is ready/failed.
+async function pollInspirationReady(ctx, inspirationId, timeoutMs = 5 * 60 * 1000) {
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    for (;;) {
+        const res = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/videos/${encodeURIComponent(inspirationId)}`, auth: ctx.auth });
+        if (res.ok && res.json) {
+            last = res.json;
+            const status = String(last.status ?? "");
+            if (status === "ready")
+                return last;
+            if (status === "failed")
+                throw new Error(`source video download failed${last.error ? `: ${last.error}` : ""}.`);
+        }
+        if (Date.now() > deadline) {
+            throw new Error("source video download did not finish in time — re-run, or check with `vidfarm videos --mine`.");
+        }
+        await sleep(5000);
+    }
+}
+async function decomposeInspiration(ctx, inspirationId, userPrompt) {
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/inspirations/${encodeURIComponent(inspirationId)}/decompose`,
+        auth: ctx.auth,
+        body: { user_prompt: userPrompt }
+    });
+    assertApiOk(result, "decompose");
+    return result;
+}
+async function forkTemplate(ctx, templateId, title) {
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/compositions",
+        auth: ctx.auth,
+        body: { template_id: templateId, title }
+    });
+    assertApiOk(result, "fork");
+    return result;
+}
+// Print the final "your video is ready" block with the openable editor URL.
+function emitVideoResult(ctx, payload, openTemplate, forkId) {
+    if (ctx.json) {
+        printJson({ ok: true, ...payload });
+        return;
+    }
+    printJson({ ok: true, ...payload });
+    console.log("");
+    console.log(`  ${BOLD}Open editor ${RESET}  ${FRONTEND}${editorFrontendUrl(ctx.host, openTemplate, forkId)}${RESET}`);
+    if (forkId) {
+        console.log(`${DIM}Edit with an agent on disk: vidfarm pull ${forkId} --dir .vidfarm/${forkId}${RESET}`);
+    }
+}
+// `replicate <url> [--prompt "...and make it about X"]` — one command from a
+// TikTok/YT/IG/X URL to an editable recreation. Chains: ingest → wait for the
+// download + template mint → AI decompose/recreate (steered by --prompt) →
+// fork a personal editable copy → print the editor URL.
+async function runReplicateCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), prompt: { type: "string" }, title: { type: "string" }, "no-fork": { type: "boolean", default: false } }
+    });
+    const url = parsed.positionals[0];
+    if (!url || !/^https?:\/\//i.test(url)) {
+        throw new Error('replicate requires a video URL (TikTok/YouTube/Instagram/X): `vidfarm replicate <url> --prompt "..."`.');
+    }
+    const ctx = commonContext(parsed.values);
+    const userPrompt = parsed.values.prompt?.trim() || null;
+    // 1. Ingest the URL → private inspiration (downloads the source video).
+    if (!ctx.json)
+        process.stdout.write(`${DIM}Fetching source video… ${RESET}`);
+    const add = await apiRequest({ method: "POST", host: ctx.host, path: "/discover/templates", auth: ctx.auth, body: { source_url: url } });
+    assertApiOk(add, "replicate (ingest)");
+    const inspirationId = add.json?.inspiration_id;
+    if (!inspirationId)
+        throw new Error("replicate: ingest did not return an inspiration id.");
+    // 2. Wait for the download + template mint.
+    const ready = add.json?.status === "ready" ? add.json : await pollInspirationReady(ctx, inspirationId);
+    if (!ctx.json)
+        console.log(`${GREEN}done${RESET}`);
+    const templateId = ready.template_id;
+    if (!templateId)
+        throw new Error("replicate: no template was minted from the source video.");
+    // 3. Decompose (AI scene analysis + recreation), steered by --prompt.
+    if (!ctx.json)
+        process.stdout.write(`${DIM}Analyzing + recreating scenes (can take a minute)… ${RESET}`);
+    const decomposed = await decomposeInspiration(ctx, inspirationId, userPrompt);
+    if (!ctx.json)
+        console.log(`${GREEN}done${RESET}`);
+    const defaultForkId = decomposed.json?.default_fork_id;
+    // 4. Fork a personal editable copy (unless --no-fork opens the shared base).
+    let forkId = defaultForkId;
+    let openTemplate = templateId;
+    if (!parsed.values["no-fork"]) {
+        const fork = await forkTemplate(ctx, templateId, parsed.values.title);
+        forkId = fork.json?.fork_id ?? defaultForkId;
+        openTemplate = fork.json?.template_id ?? templateId;
+    }
+    emitVideoResult(ctx, { inspiration_id: inspirationId, template_id: openTemplate, fork_id: forkId, default_fork_id: defaultForkId }, openTemplate, forkId);
+}
+// `create "<prompt>"` — spin up a brand-new editable video from a text prompt
+// (no source URL). Chains: generate a base video via the video primitive → wrap
+// the MP4 into a new template (upload-ingest) → AI decompose into an editable
+// timeline → fork → print the editor URL. Requires an AI provider key (the
+// generate + decompose steps use it), same as the web editor.
+async function runCreateCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            prompt: { type: "string" },
+            "aspect-ratio": { type: "string" },
+            duration: { type: "string" },
+            resolution: { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            audio: { type: "boolean", default: false },
+            ref: { type: "string", multiple: true },
+            title: { type: "string" },
+            "no-decompose": { type: "boolean", default: false },
+            "no-fork": { type: "boolean", default: false }
+        }
+    });
+    const prompt = (parsed.values.prompt ?? parsed.positionals.join(" ")).trim();
+    if (!prompt)
+        throw new Error('create requires a prompt: `vidfarm create "a 15s ad for my coffee brand"` (or --prompt "...").');
+    const ctx = commonContext(parsed.values);
+    const refs = await resolveReferenceUrls(ctx, parsed.values.ref);
+    // 1. Generate the base video from the prompt.
+    const payload = { prompt };
+    if (parsed.values["aspect-ratio"])
+        payload.aspect_ratio = parsed.values["aspect-ratio"];
+    if (parsed.values.provider)
+        payload.provider = parsed.values.provider;
+    if (parsed.values.model)
+        payload.model = parsed.values.model;
+    if (parsed.values.duration)
+        payload.duration = Math.round(Number(parsed.values.duration));
+    if (parsed.values.resolution)
+        payload.resolution = parsed.values.resolution;
+    if (parsed.values.audio)
+        payload.generate_audio = true;
+    if (refs.length)
+        payload.input_references = refs.slice(0, 8);
+    const tracer = `devcli-create-${Date.now().toString(36)}`;
+    const submit = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/primitives/videos/generate", auth: ctx.auth, body: { tracer, payload } });
+    assertApiOk(submit, "create (generate)");
+    const jobId = submit.json?.job_id;
+    if (!jobId)
+        throw new Error("create: generate did not return a job id.");
+    if (!ctx.json)
+        console.log(`${DIM}Generating base video (${jobId})… polling every 5s.${RESET}`);
+    const job = await pollPrimitiveJob(ctx, jobId);
+    const mediaUrl = resolveJobMediaUrl(job);
+    if (!mediaUrl)
+        throw new Error(`create: generation ${String(job?.status ?? "did not finish")} — no media URL. Check your provider keys and wallet.`);
+    // 2. Download the generated MP4 and wrap it into a new template (upload-ingest
+    // path — the same one `inspiration-add <file>` uses).
+    if (!ctx.json)
+        process.stdout.write(`${DIM}Building an editable template from the generated video… ${RESET}`);
+    const dl = await fetch(mediaUrl, { headers: buildAuthHeaders(ctx.auth) });
+    if (!dl.ok)
+        throw new Error(`create: could not fetch the generated video (${dl.status}).`);
+    const buffer = Buffer.from(await dl.arrayBuffer());
+    const title = parsed.values.title ?? prompt.slice(0, 80);
+    const add = await ingestUploadedVideo(ctx, { buffer, fileName: "generated.mp4", contentType: "video/mp4", title });
+    const inspirationId = add.json?.inspiration_id;
+    if (!inspirationId)
+        throw new Error("create: ingest did not return an inspiration id.");
+    const ready = add.json?.status === "ready" ? add.json : await pollInspirationReady(ctx, inspirationId);
+    if (!ctx.json)
+        console.log(`${GREEN}done${RESET}`);
+    const templateId = ready.template_id;
+    if (!templateId)
+        throw new Error("create: no template was minted from the generated video.");
+    // 3. Decompose into an editable per-scene timeline (unless --no-decompose).
+    let defaultForkId;
+    if (!parsed.values["no-decompose"]) {
+        if (!ctx.json)
+            process.stdout.write(`${DIM}Analyzing into an editable timeline… ${RESET}`);
+        const decomposed = await decomposeInspiration(ctx, inspirationId, prompt);
+        defaultForkId = decomposed.json?.default_fork_id;
+        if (!ctx.json)
+            console.log(`${GREEN}done${RESET}`);
+    }
+    // 4. Fork a personal editable copy (unless --no-fork).
+    let forkId = defaultForkId;
+    let openTemplate = templateId;
+    if (!parsed.values["no-fork"]) {
+        const fork = await forkTemplate(ctx, templateId, parsed.values.title);
+        forkId = fork.json?.fork_id ?? defaultForkId;
+        openTemplate = fork.json?.template_id ?? templateId;
+    }
+    emitVideoResult(ctx, { inspiration_id: inspirationId, template_id: openTemplate, fork_id: forkId, default_fork_id: defaultForkId, generated_video_url: mediaUrl }, openTemplate, forkId);
+}
 // ── Composition lifecycle ───────────────────────────────────────────────────
 async function runForkCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" } } });
@@ -1294,17 +1551,96 @@ async function runDecomposeCommand(argv) {
     if (!forkId)
         throw new Error("decompose requires a fork id.");
     const ctx = commonContext(parsed.values);
-    const result = await apiRequest({
+    const decomposePath = `/api/v1/compositions/${encodeURIComponent(forkId)}/auto-decompose`;
+    // Decompose can run longer than the 60s CloudFront origin timeout on long
+    // videos. `force: true` KICKS a resumable run; the server keeps working even
+    // if this request 504s. So we tolerate a non-`done` kick and poll GET
+    // .../auto-decompose until the job is terminal.
+    let result = await apiRequest({
         method: "POST",
         host: ctx.host,
-        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/auto-decompose`,
+        path: decomposePath,
         auth: ctx.auth,
-        body: { mode: parsed.values.mode, user_prompt: parsed.values.prompt ?? null }
+        body: { force: true, mode: parsed.values.mode, user_prompt: parsed.values.prompt ?? null }
     });
+    const kickStatus = typeof result.json?.status === "string" ? result.json.status : null;
+    if (!(result.ok && kickStatus === "done")) {
+        if (!ctx.json)
+            process.stdout.write(`${DIM}Decomposing (may take a minute on long videos)… ${RESET}`);
+        const deadline = Date.now() + 12 * 60 * 1000;
+        let settled = null;
+        while (Date.now() < deadline) {
+            await sleep(5000);
+            let statusResult;
+            try {
+                statusResult = await apiRequest({ method: "GET", host: ctx.host, path: decomposePath, auth: ctx.auth });
+            }
+            catch {
+                continue;
+            }
+            const s = typeof statusResult.json?.status === "string" ? statusResult.json.status : "none";
+            if (s === "done" || s === "failed") {
+                settled = statusResult;
+                break;
+            }
+            if (s === "none")
+                break; // the run never claimed — surface the kick error below
+        }
+        if (settled) {
+            result = settled;
+            if (!ctx.json)
+                console.log(settled.json?.status === "done" ? `${GREEN}done${RESET}` : `${RED}failed${RESET}`);
+        }
+        else {
+            // Timed out or never started — surface the kick's own error if it was one.
+            assertApiOk(result, "decompose");
+            throw new Error("decompose did not complete in time (it may still finish server-side; re-run `vidfarm decompose` to check).");
+        }
+    }
+    if (result.json?.status === "failed") {
+        throw new Error(`decompose failed: ${result.json?.error ?? "unknown error"}`);
+    }
     assertApiOk(result, "decompose");
     if (!ctx.json && result.json?.ghostcut_pending) {
         console.log(`${DIM}Subtitle removal (GhostCut) is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/remove-video-captions-poll\` or GET .../remove-video-captions until done.${RESET}`);
     }
+    // The scene-annotation pass (per-scene clip-match + recreation DNA + content
+    // format) is seeded "pending" by decompose and runs as its own bounded vision
+    // call — kept out of the decompose request so that stays under the origin
+    // timeout. Drive it to completion here so CLI/agent users get annotations
+    // without needing the editor. Each poll is one call; usually one round
+    // finishes it. Best-effort: transient failures leave it pending for another
+    // client (or a later `vidfarm pull`) to finish.
+    if (!ctx.json)
+        process.stdout.write(`${DIM}Annotating scenes (clip-match + recreation DNA)… ${RESET}`);
+    let annotationStatus = "pending";
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        let poll;
+        try {
+            poll = await apiRequest({
+                method: "POST",
+                host: ctx.host,
+                path: `/api/v1/compositions/${encodeURIComponent(forkId)}/scene-annotations-poll`,
+                auth: ctx.auth,
+                body: {}
+            });
+        }
+        catch {
+            break;
+        }
+        annotationStatus = typeof poll.json?.status === "string" ? poll.json.status : "none";
+        if (annotationStatus === "none" || annotationStatus === "done" || annotationStatus === "failed")
+            break;
+        await sleep(3000);
+    }
+    if (!ctx.json) {
+        if (annotationStatus === "done")
+            console.log(`${GREEN}done${RESET}`);
+        else if (annotationStatus === "failed")
+            console.log(`${RED}failed${RESET} ${DIM}(run \`vidfarm api POST /api/v1/compositions/${forkId}/scene-annotations-poll\` to retry)${RESET}`);
+        else
+            console.log(`${DIM}still running — poll .../scene-annotations-poll until done${RESET}`);
+    }
     emitResult(result, ctx.json);
 }
 async function runRemoveVideoCaptionsCommand(argv) {
@@ -1827,8 +2163,9 @@ async function runPullCommand(argv) {
     const info = inspectComposition(readFileSync(htmlPath, "utf8"));
     const hasContext = existsSync(path.join(dir, "video-context.json"));
     const hasCast = existsSync(path.join(dir, "cast.json"));
+    const hasAnnotations = existsSync(path.join(dir, "scene-annotations.json"));
     if (ctx.json) {
-        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, ...info });
+        printJson({ ok: true, fork_id: forkId, dir, has_video_context: hasContext, has_cast: hasCast, has_scene_annotations: hasAnnotations, ...info });
         return;
     }
     console.log(`${GREEN}Pulled ${forkId} → ${dir}${RESET}`);
@@ -1839,7 +2176,7 @@ async function runPullCommand(argv) {
         const flags = [layer.is_timeline_proxy ? "proxy" : null, layer.is_full_canvas ? "full-canvas" : null].filter(Boolean).join(",");
         console.log(`  ${layer.key}  ${DIM}${layer.kind ?? "?"} ${layer.start}-${(layer.start + layer.duration).toFixed(2)}s track${layer.track}${flags ? ` [${flags}]` : ""}${layer.slug ? ` slug=${layer.slug}` : ""}${RESET}`);
     }
-    console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}.${RESET}`);
+    console.log(`${DIM}Grounding: ${hasContext ? "video-context.json ✓" : "video-context.json ✗ (run `vidfarm decompose`)"}, ${hasCast ? "cast.json ✓" : "cast.json ✗"}, ${hasAnnotations ? "scene-annotations.json ✓" : "scene-annotations.json ✗"}.${RESET}`);
     console.log(`${DIM}Next: vidfarm generate video --prompt "..." --aspect-ratio ${info.aspect_ratio ?? "9:16"} --place ${dir} --at <gap start>|--replace <layer_key>${RESET}`);
 }
 async function runVisibilityCommand(argv) {

package/dist/src/config.js

@@ -108,6 +108,12 @@ const schema = z.object({
     VIDFARM_RATE_LIMITS_TABLE_NAME: z.string().optional(),
     VIDFARM_SERVERLESS_MAIN_TABLE_NAME: z.string().optional(),
     VIDFARM_JOB_STATE_MACHINE_ARN: z.string().optional(),
+    // Clip-curation scan pipeline (Step Functions). Optional: when unset, the
+    // /clips/scan route records the scan request but doesn't dispatch the machine.
+    VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN: z.string().optional(),
+    VIDFARM_CLIP_VECTOR_BACKEND: z.enum(["dynamo", "s3vectors"]).default("dynamo"),
+    VIDFARM_CLIP_VECTORS_BUCKET: z.string().optional(),
+    VIDFARM_CLIP_VECTORS_INDEX: z.string().optional(),
     SENTRY_DSN: z.string().optional(),
     SENTRY_ENVIRONMENT: z.string().optional(),
     SENTRY_RELEASE: z.string().optional(),