@mevdragon/vidfarm-devcli 0.8.0 → 0.9.0

package/dist/src/app.js

@@ -4096,6 +4096,28 @@ function createEditorFrontendActionTool(input) {
         }
     });
 }
+// Discover-chat only: lets the AI create a BRAND-NEW video for the user, either
+// from a text prompt (mode=generate) or by replicating a pasted video URL
+// (mode=replicate). The tool itself is a passthrough — it just structures the
+// user's intent; the chat frontend runs the ingest→decompose→fork pipeline and
+// drops an "Open in editor" link into the thread when it's ready.
+function createVideoCreationTool() {
+    return tool({
+        description: "Create a NEW editable video for the user from scratch. Call this the MOMENT the user asks to \"create/make a video of ...\" (set mode=generate and put the idea in `prompt`) OR to \"replicate/recreate/remix this video\" from a pasted TikTok/YouTube/Instagram/X URL (set mode=replicate, put the URL in `source_url`, and put any requested changes in `instructions`). This kicks off video creation in the browser and posts an 'Open in editor' link to the chat when the new video is ready — you do not need to poll or call any other tool. This is the ONLY way to make a brand-new video; the editor tools only edit an already-open composition.",
+        inputSchema: z.object({
+            mode: z.enum(["generate", "replicate"]).describe("generate = brand-new from a text prompt; replicate = recreate a pasted video URL."),
+            prompt: z.string().optional().describe("For mode=generate: what the video should be about."),
+            source_url: z.string().optional().describe("For mode=replicate: the TikTok/YouTube/Instagram/X video URL to recreate."),
+            instructions: z.string().optional().describe("Optional changes to apply while creating/recreating (e.g. 'make it about my coffee brand', 'change the hook to ...').")
+        }),
+        execute: async ({ mode, prompt, source_url, instructions }) => ({
+            mode,
+            prompt: prompt ?? null,
+            source_url: source_url ?? null,
+            instructions: instructions ?? null
+        })
+    });
+}
 function createEditorActionTool() {
     return tool({
         description: "Directly mutate the composition timeline in the editor OR start an export render OR generate-and-place AI media. Use this whenever the user asks for a timeline change (add/remove/duplicate/split layers, retime, reposition, resize, restyle text, swap media, group/ungroup), asks to generate an AI video/image and drop it on the timeline (action_type=generate_layer), or asks to export/render/publish/download the final MP4 (action_type=export_composition). The most recent <editor_context> in the user message is the source of truth for current layer_keys, layer indices (called 'track'), durations, timeline_gaps (blank spans), pending_generations (AI gens still rendering), and the most recent exported MP4 (last_export_url). Always provide explanation. For add_layer, also provide layer_key with a stable descriptive id (e.g., 'vf-caption-hook', 'vf-hero-image') so subsequent tool calls in the same turn can reference it — the editor will use that id as the new layer's data-hf-id. PREFER action_type=generate_layer to create NEW AI footage/images on the timeline: it submits the primitive generate job, drops a placeholder clip into the target slot immediately, and auto-swaps in the finished media when the job settles (no manual poll, no separate add_layer). Only use the http_request→add_layer flow for media that already has a URL. Avoid layer/track collisions: pick a track index higher than any existing layer on the requested time range, or set start/duration so the range is free. Never invent layer_keys for remove/set/duplicate/split actions; only use keys present in the most recent editor_context. For action_type=export_composition, no layer_key/geometry fields are needed; the editor kicks off the render and streams status in the UI, and the resulting MP4 URL will appear in the next <editor_context> as last_export_url.",
@@ -4303,7 +4325,12 @@ async function streamEditorChatAgent(input, send) {
                 frontend_action: createEditorFrontendActionTool({
                     tracerRegistry
                 }),
-                editor_action: createEditorActionTool()
+                editor_action: createEditorActionTool(),
+                // Discover/brainstorm surface only: "create me a video of…" / "replicate
+                // this URL…". The editor surfaces edit an already-open composition.
+                ...(input.template.templateId === "chat-brainstorm"
+                    ? { create_video: createVideoCreationTool() }
+                    : {})
             };
         })()
         : undefined;
@@ -6536,6 +6563,66 @@ app.post(`${INSPIRATIONS_PREFIX}/:inspirationId/decompose`, async (c) => {
         }
     });
 });
+// A "processing" state older than this is treated as abandoned (crashed lambda)
+// so a forced re-run may start. Must exceed the longest real decompose but stay
+// under the API lambda's 15-min timeout.
+const DECOMPOSE_PROCESSING_STALE_MS = 10 * 60 * 1000;
+async function readDecomposeJobState(forkId) {
+    const text = await storage.readText(storage.compositionForkWorkingKey(forkId, "decompose.json"));
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeDecomposeJobState(forkId, state) {
+    try {
+        await storage.putJson(storage.compositionForkWorkingKey(forkId, "decompose.json"), state);
+    }
+    catch (error) {
+        console.error("decompose.json write failed", error instanceof Error ? error.message : error);
+    }
+}
+function decomposeDoneResponse(job, extra = {}) {
+    return {
+        ok: true,
+        status: "done",
+        mode: "smart",
+        provider: job.provider ?? null,
+        model: job.model ?? null,
+        scene_count: job.sceneCount ?? 0,
+        caption_count: job.captionCount ?? 0,
+        duration_seconds: job.durationSeconds ?? null,
+        became_default_fork: job.becameDefaultFork ?? false,
+        ghostcut_pending: job.ghostcutPending ?? false,
+        ...extra
+    };
+}
+// Read-only decompose job status — the client's poll target while a decompose
+// runs (or after a 504). Fast: just reads decompose.json.
+app.get(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
+    const caller = await getBrowserCustomer(c);
+    try {
+        const access = await assertForkAccess({ forkId: c.req.param("forkId"), customerId: caller?.id ?? null, shareToken: readShareToken(c) }, "view");
+        const job = await readDecomposeJobState(access.fork.id);
+        if (!job)
+            return c.json({ ok: true, status: "none" });
+        if (job.status === "done")
+            return c.json(decomposeDoneResponse(job, { resumed: true }));
+        if (job.status === "failed")
+            return c.json({ ok: true, status: "failed", error: job.failureReason ?? "Decompose failed." });
+        const stale = Date.now() - (job.updatedAtMs ?? job.startedAtMs ?? 0) >= DECOMPOSE_PROCESSING_STALE_MS;
+        return c.json({ ok: true, status: "processing", stale, started_at_ms: job.startedAtMs });
+    }
+    catch (error) {
+        if (error instanceof ForkNotFoundError || error instanceof ForkAccessDeniedError)
+            return forkAccessErrorResponse(c, error);
+        return c.json({ ok: false, error: error instanceof Error ? error.message : String(error) }, 500);
+    }
+});
 app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
     const caller = await getBrowserCustomer(c);
     if (!caller)
@@ -6552,6 +6639,36 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         const body = asRecord(await c.req.json().catch(() => ({}))) ?? {};
         const userPromptRaw = typeof body.user_prompt === "string" ? body.user_prompt.trim() : "";
         const userPrompt = userPromptRaw.length > 0 ? userPromptRaw.slice(0, 4000) : null;
+        // Idempotency / resumability guard. POST STARTS a decompose (idempotently);
+        // GET /auto-decompose is the poll. An in-flight run always wins so a client's
+        // post-504 retry (or a second caller) never starts a duplicate. A completed
+        // job is returned from cache unless `force` (the editor's decompose click)
+        // asks for a fresh re-run. Absent / failed / abandoned jobs (re)start — so a
+        // plain POST with no `force` still kicks the first decompose (back-compat for
+        // the editor-chat copilot's http_request call).
+        const forceRun = body.force === true;
+        const existingJob = await readDecomposeJobState(fork.id);
+        const jobFresh = existingJob
+            ? Date.now() - (existingJob.updatedAtMs ?? existingJob.startedAtMs ?? 0) < DECOMPOSE_PROCESSING_STALE_MS
+            : false;
+        if (existingJob?.status === "processing" && jobFresh) {
+            return c.json({ ok: true, status: "processing", started_at_ms: existingJob.startedAtMs });
+        }
+        if (existingJob?.status === "done" && !forceRun) {
+            return c.json(decomposeDoneResponse(existingJob, { resumed: true }));
+        }
+        // Claim the job so concurrent polls/kicks back off. A local helper stamps
+        // "failed" on every early-error return so a poller never hangs on processing.
+        await writeDecomposeJobState(fork.id, { status: "processing", startedAtMs, updatedAtMs: Date.now() });
+        const failDecompose = async (payload, statusCode) => {
+            await writeDecomposeJobState(fork.id, {
+                status: "failed",
+                startedAtMs,
+                updatedAtMs: Date.now(),
+                failureReason: typeof payload.error === "string" ? payload.error : "Auto-decompose failed."
+            });
+            return c.json(payload, statusCode);
+        };
         // Parse the current composition HTML with a real DOM (linkedom) so
         // attribute values come back UNESCAPED — `data-source-video="foo?a=1&amp;b=2"`
         // reads as `foo?a=1&b=2`, which is what ghostcut and the vision extractor
@@ -6588,7 +6705,7 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
             }
             catch (error) {
                 if (error instanceof MediaDurationExceededError) {
-                    return c.json({
+                    return failDecompose({
                         ok: false,
                         error: `Source video is ${error.durationSeconds.toFixed(1)}s — Vidfarm caps auto-decompose at ${error.maxDurationSeconds}s. Trim the source before forking.`,
                         code: "source_too_long",
@@ -6706,13 +6823,13 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         const customerKeys = await loadCustomerVisionKeys(caller.id);
         const hasAnyKey = Boolean(customerKeys.gemini || customerKeys.openai || customerKeys.openrouter);
         if (!hasAnyKey) {
-            return c.json({
+            return failDecompose({
                 ok: false,
                 error: "Decompose requires an AI provider key. Add a Gemini, OpenAI, or OpenRouter key in Settings and try again."
             }, 400);
         }
         if (!sourceUrl) {
-            return c.json({ ok: false, error: "Composition has no source video URL." }, 400);
+            return failDecompose({ ok: false, error: "Composition has no source video URL." }, 400);
         }
         const inspirationForTagline = forkInspirationId
             ? await serverlessRecords.getInspiration(forkInspirationId)
@@ -6742,13 +6859,13 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
         }
         catch (error) {
             console.error("smart decompose failed", error instanceof Error ? error.message : error);
-            return c.json({
+            return failDecompose({
                 ok: false,
                 error: error instanceof Error ? error.message : "Smart decompose failed."
             }, 502);
         }
         if (smart.scenes.length === 0 && smart.captions.length === 0) {
-            return c.json({
+            return failDecompose({
                 ok: false,
                 error: "Smart decompose returned no scenes. Try again with different guidance."
             }, 502);
@@ -6894,8 +7011,23 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
             }
         }
         await chargeDecomposeUsage({ mode: "smart" });
+        // Stamp the job "done" so a client whose request 504'd mid-run (or any later
+        // poll) resolves to completion and reloads the composition.
+        await writeDecomposeJobState(fork.id, {
+            status: "done",
+            startedAtMs,
+            updatedAtMs: Date.now(),
+            provider: smart.provider,
+            model: smart.model,
+            sceneCount: smart.scenes.length,
+            captionCount: smart.captions.length,
+            durationSeconds: smart.durationSeconds,
+            becameDefaultFork: becameDefault,
+            ghostcutPending: ghostcutTaskId !== null
+        });
         return c.json({
             ok: true,
+            status: "done",
             mode: "smart",
             provider: smart.provider,
             model: smart.model,
@@ -6911,6 +7043,15 @@ app.post(`${COMPOSITIONS_PREFIX}/:forkId/auto-decompose`, async (c) => {
     catch (error) {
         if (error instanceof ForkNotFoundError || error instanceof ForkAccessDeniedError)
             return forkAccessErrorResponse(c, error);
+        // Persist a failed job (best-effort) so the client's poll reads a terminal
+        // failure instead of hanging on "processing". Safe: only reached after the
+        // caller passed access control.
+        await writeDecomposeJobState(c.req.param("forkId"), {
+            status: "failed",
+            startedAtMs,
+            updatedAtMs: Date.now(),
+            failureReason: error instanceof Error ? error.message : "Auto-decompose failed."
+        });
         return c.json({ ok: false, error: error instanceof Error ? error.message : "Auto-decompose failed." }, 500);
     }
 });

package/dist/src/cli.js

@@ -10,6 +10,7 @@ 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
@@ -80,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,...}
@@ -232,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() {
@@ -243,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
@@ -273,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;
@@ -1194,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;
     }
@@ -1287,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" } } });
@@ -1312,13 +1551,55 @@ 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}`);