@mevdragon/vidfarm-devcli 0.3.4 → 0.3.6

package/SKILL.director.md

@@ -306,11 +306,23 @@ For iterating on a composition on disk (e.g. Claude Code editing HTML directly),
 
 ```bash
 npx -y @mevdragon/vidfarm-devcli <template_id>
-# → downloads composition.html/json + manifest.json into .vidfarm/<template_id>/
+# → downloads composition.html/json + manifest.json + video-context.json into .vidfarm/<template_id>/
+# → downloads the videos + per-scene frames for local analysis (see below)
 # → starts dev-serve on http://localhost:4321
 # → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
 ```
 
+### Local media for analysis (`sources.json`, videos, frames)
+
+So a coding agent can *see* what it is editing — not just read URLs — `vidfarm edit` also drops the actual media next to the composition:
+
+- **`original.mp4`** — the raw source video, before any processing.
+- **`source.mp4`** — the video the composition timeline actually renders from. This differs from `original.mp4` only when the fork was ghostcut/subtitle-removed; otherwise `sources.json` marks them `same_as_decomposed: true` and only `source.mp4` is written.
+- **`frames/<scene>.png`** — one still per timeline scene, sampled at the scene midpoint from `source.mp4`. Open these as images to analyze what each scene shows. Requires `ffmpeg` (bundled via `ffmpeg-static`); if unavailable the videos still download and frames are skipped.
+- **`sources.json`** — the manifest tying it together: each video's role/url/local path/byte size, the total duration, and per-scene `{ slug, start, duration, label, description, transcript_excerpt, frame }`.
+
+This is best-effort and never blocks the editor session. Re-run with `--refetch` to refresh the media after a new decompose or ghostcut. For deeper text grounding (full transcript, per-scene visual descriptions) read `video-context.json` — the media files complement it with the pixels.
+
 Open the printed URL in your browser. An orange **LOCAL DEV MODE** banner pins to the top with an Exit button. All fork API fetches now route to your local dir instead of the deployed API; disk edits push an SSE reload event and the editor re-fetches automatically.
 
 Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or set `VIDFARM_API_KEY`), `--share`, `--refetch`. For a fork that already has composition files on disk (or that you've populated manually), use `vidfarm-devcli dev-serve --dir ./my-fork --port 4321` to skip the fetch step.
@@ -443,3 +455,39 @@ curl -X POST "$VIDFARM_BASE/api/v1/primitives/media/dedupe" \
     }
   }'
 ```
+
+## Brainstorm primitives
+
+The `brainstorm/*` primitives are the strategy toolkit. They are reusable, billable AI reasoning steps — the same family the AI Copilot exposes as chip suggestions. Treat **product placement** as a first-class member of this family, right alongside angles and hooks:
+
+- `POST /api/v1/primitives/brainstorm/coldstart` — `{ payload: { user_message } }` → foundational questionnaire for a customer starting from zero.
+- `POST /api/v1/primitives/brainstorm/awareness_stages` — `{ payload: { offer_description } }` → which Eugene-Schwartz awareness stages to target first.
+- `POST /api/v1/primitives/brainstorm/angles` — `{ payload: { offer_description, problem_awareness, solution_awareness } }` → persuasive angles.
+- `POST /api/v1/primitives/brainstorm/hooks` — `{ payload: { offer_description } }` → many TikTok-native hooks.
+- `POST /api/v1/primitives/brainstorm/product_placement` — `{ payload: { source_video_url, offer_description } }` → **watches the video** and returns concrete, timestamped opportunities to natively place the product.
+
+### Primitive: brainstorm_product_placement
+
+Analyze a source video and identify where a product can be organically placed so it feels native rather than bolted on. This is a **multimodal** primitive: it feeds the actual video to a vision-capable model, so prefer a saved **Gemini** key (native video understanding). OpenRouter multimodal models also work; plain OpenAI chat keys cannot watch video.
+
+- `POST /api/v1/primitives/brainstorm/product_placement`
+- Body: `{ "tracer": "...", "payload": { "source_video_url": "...", "offer_description": "...", "count"?: 8, "provider"?: "gemini" }, "webhook_url"?: "..." }`
+  - `source_video_url` (required, URL) — the exact durable/public video to analyze. Aliases accepted: `video_url`, `source_url`, `url`. For a fork's composition, call `GET /api/v1/compositions/:forkId/ghostcut` first and pass the correct raw-upload vs caption-free-mirror URL.
+  - `offer_description` (required) — the product/offer to place. Aliases: `offer`, `description`, `details`.
+  - `count` (optional, 3–30, default 8) — number of opportunities; only send when the user asks for a specific number.
+- Response: standard primitive job. Poll `GET /api/v1/primitives/jobs/:jobId` to completion, then read `result.json` (also surfaced on the job output as `opportunities[]`), where each entry has `timestamp`, `scene`, `placement_type`, `placement_idea`, and `why_it_works`.
+
+You can also satisfy a quick, conversational product-placement question by reasoning over an attached video directly instead of calling this primitive — use the primitive when you want a durable, structured, billable artifact the customer can save and reuse.
+
+```bash
+curl -X POST "$VIDFARM_BASE/api/v1/primitives/brainstorm/product_placement" \
+  -H "vidfarm-api-key: $VIDFARM_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{
+    "tracer": "product-placement-01",
+    "payload": {
+      "source_video_url": "https://cdn.example.com/source.mp4",
+      "offer_description": "A $29/mo AI meal-planning app for busy parents."
+    }
+  }'
+```

package/dist/src/cli.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 // vidfarm-devcli — thin CLI that pairs a local composition directory with the
 // hosted Trackpad Editor at https://vidfarm.cc/editor/. Point it at a template
 // id, and it: resolves the user's fork, downloads the current composition,
@@ -12,6 +15,7 @@ const HELP = `vidfarm-devcli — local editor bridge for the Vidfarm Trackpad Ed
 
 Usage:
   vidfarm-devcli <template_id> [options]        Start local editor session
+  vidfarm-devcli publish <template_id> [opts]   Push local composition to your fork
   vidfarm-devcli dev-serve [options]            Serve an existing local dir only
   vidfarm-devcli --help                         Show this help
 
@@ -24,6 +28,14 @@ Options (edit mode):
   --share <token>     Share token for a shared fork (public read)
   --refetch           Overwrite local composition files with the latest remote copy
 
+Options (publish mode):
+  --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
+  --host <url>        Vidfarm host to publish to (default: ${DEFAULT_HOST})
+  --fork <id>         Fork id to publish into (default: auto-resolve for the current user)
+  --api-key <key>     Vidfarm API key (or set VIDFARM_API_KEY) — required to write
+  --message <text>    Optional message attached to the published version snapshot
+  --no-snapshot       Only update the working copy; skip the version snapshot
+
 Options (dev-serve mode):
   --dir <path>        Directory to serve (default: current dir)
   --port <n>          Port to listen on (default: ${DEFAULT_PORT})
@@ -48,6 +60,10 @@ async function main() {
         await runEditCommand(argv.slice(1));
         return;
     }
+    if (command === "publish") {
+        await runPublishCommand(argv.slice(1));
+        return;
+    }
     if (!command.startsWith("-")) {
         // Positional template id → default `edit` command.
         await runEditCommand(argv);
@@ -94,12 +110,164 @@ async function runEditCommand(argv) {
         shareToken,
         refetch: parsed.values.refetch
     });
+    // Give local coding agents (Claude Code / Codex / opencode) the actual media
+    // to look at: the original source video, the composition's decomposed source
+    // (which may differ after ghostcut subtitle-removal), one still frame per
+    // scene, and a sources.json manifest tying it all together. Best-effort —
+    // never blocks the editor session if a download or frame extraction fails.
+    try {
+        await fetchVideoAssets({ dir: rootDir, apiKey, shareToken, refetch: parsed.values.refetch });
+    }
+    catch (error) {
+        console.warn(`[vidfarm] video assets skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const devSource = `http://localhost:${port}`;
     const editorUrl = `${host}/editor/${encodeURIComponent(templateId)}?fork=${encodeURIComponent(forkId)}&dev=${encodeURIComponent(devSource)}`;
     printEditorBanner({ templateId, forkId, dir: rootDir, port, editorUrl });
     const { runDevServeCommand } = await import("./dev-serve.js");
     await runDevServeCommand(["--dir", rootDir, "--port", String(port)]);
 }
+async function runPublishCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            dir: { type: "string" },
+            host: { type: "string", default: DEFAULT_HOST },
+            fork: { type: "string" },
+            "api-key": { type: "string" },
+            share: { type: "string" },
+            message: { type: "string" },
+            "no-snapshot": { type: "boolean", default: false }
+        }
+    });
+    const templateId = parsed.positionals[0];
+    if (!templateId && !parsed.values.dir) {
+        throw new Error(`publish requires a template id (or --dir).\n\n${HELP}`);
+    }
+    const host = trimTrailingSlash(parsed.values.host);
+    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
+    const shareToken = parsed.values.share;
+    if (!apiKey && !shareToken) {
+        throw new Error("publish needs credentials to write. Pass --api-key <key> or set VIDFARM_API_KEY.");
+    }
+    const rootDir = path.resolve(process.cwd(), parsed.values.dir ?? path.join(".vidfarm", templateId ?? ""));
+    const forkId = parsed.values.fork ?? (templateId
+        ? await resolveForkId({ host, templateId, apiKey, shareToken })
+        : null);
+    if (!forkId) {
+        throw new Error(`Could not resolve a fork id. Pass --fork <id>${templateId ? "" : " (no template id was given to auto-resolve)"}.`);
+    }
+    const htmlPath = path.join(rootDir, "composition.html");
+    if (!existsSync(htmlPath)) {
+        throw new Error(`No composition.html at ${htmlPath}. Run \`vidfarm-devcli ${templateId ?? "<template>"} --fork ${forkId}\` first, or pass --dir.`);
+    }
+    const html = readFileSync(htmlPath, "utf8");
+    if (!html.includes("data-composition-id=")) {
+        throw new Error("composition.html is missing data-composition-id — refusing to publish a malformed composition.");
+    }
+    const jsonPath = path.join(rootDir, "composition.json");
+    const json = existsSync(jsonPath) ? readFileSync(jsonPath, "utf8") : null;
+    if (json !== null) {
+        try {
+            JSON.parse(json || "{}");
+        }
+        catch (error) {
+            throw new Error(`composition.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const auth = { apiKey, shareToken };
+    console.log(`[vidfarm] publishing ${forkId} → ${host}`);
+    // 1) Working copy: composition.html (required) then composition.json (if any).
+    await putComposition(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/composition.html`, "PUT", html, "text/html; charset=utf-8", auth);
+    console.log(`[vidfarm] pushed composition.html (${Buffer.byteLength(html)} bytes)`);
+    if (json !== null) {
+        await putComposition(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/composition.json`, "PATCH", json, "application/json", auth);
+        console.log(`[vidfarm] pushed composition.json (${Buffer.byteLength(json)} bytes)`);
+    }
+    // 2) Optional immutable version snapshot.
+    let publishedVersion = null;
+    if (!parsed.values["no-snapshot"]) {
+        const snapshot = await postJson(`${host}/api/v1/compositions/${encodeURIComponent(forkId)}/versions`, { message: parsed.values.message ?? null }, auth);
+        publishedVersion = typeof snapshot?.version === "number" ? snapshot.version : null;
+        console.log(`[vidfarm] snapshotted version ${publishedVersion ?? "(unknown)"}`);
+    }
+    printPublishBanner({ forkId, dir: rootDir, host, version: publishedVersion, snapshotted: !parsed.values["no-snapshot"] });
+}
+// Writes one composition file to the remote fork. Unlike the edit-mode
+// fetchCompositionFiles (which tolerates misses), publish MUST fail loudly — a
+// silent skip would make the user think their work is safely stored when it is
+// not.
+async function putComposition(url, method, body, contentType, auth) {
+    const res = await fetch(url, {
+        method,
+        headers: { ...buildAuthHeaders(auth), "content-type": contentType },
+        body
+    });
+    if (!res.ok) {
+        throw new Error(await describeHttpFailure(res, url));
+    }
+}
+async function postJson(url, body, auth) {
+    const res = await fetch(url, {
+        method: "POST",
+        headers: { ...buildAuthHeaders(auth), "content-type": "application/json" },
+        body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+        throw new Error(await describeHttpFailure(res, url));
+    }
+    return await res.json().catch(() => ({}));
+}
+async function describeHttpFailure(res, url) {
+    let detail = "";
+    try {
+        const text = await res.text();
+        if (text) {
+            try {
+                const parsed = JSON.parse(text);
+                detail = parsed.error ? ` — ${parsed.error}${parsed.type ? ` (${parsed.type})` : ""}` : ` — ${text.slice(0, 300)}`;
+            }
+            catch {
+                detail = ` — ${text.slice(0, 300)}`;
+            }
+        }
+    }
+    catch {
+        // ignore body read failure
+    }
+    const hint = res.status === 401 || res.status === 403
+        ? " Check your --api-key and that you own (or have edit rights on) this fork."
+        : res.status === 413
+            ? " The composition exceeds the server size limit."
+            : res.status === 429
+                ? " You are being rate-limited; wait and retry."
+                : "";
+    return `Publish failed: ${res.status} ${res.statusText}${detail} (${url}).${hint}`;
+}
+function printPublishBanner(input) {
+    const bold = "\x1b[1m";
+    const green = "\x1b[32m";
+    const cyan = "\x1b[36m";
+    const dim = "\x1b[2m";
+    const reset = "\x1b[0m";
+    const line = `${dim}${"─".repeat(74)}${reset}`;
+    console.log("");
+    console.log(line);
+    console.log(`${bold}${green}  Published to Vidfarm${reset}`);
+    console.log(line);
+    console.log(`  fork        ${input.forkId}`);
+    console.log(`  local dir   ${input.dir}`);
+    if (input.snapshotted) {
+        console.log(`  version     ${input.version ?? "(unknown)"}`);
+    }
+    else {
+        console.log(`  version     ${dim}skipped (--no-snapshot)${reset}`);
+    }
+    console.log(`  live html   ${cyan}${input.host}/api/v1/compositions/${input.forkId}/composition.html${reset}`);
+    console.log(line);
+    console.log("");
+}
 async function resolveForkId(input) {
     // /editor/<template_id> issues a 302 → /editor/<template_id>?fork=<id>
     // whenever the caller (or the template's default fork) has one. Follow the
@@ -148,6 +316,232 @@ async function fetchCompositionFiles(input) {
         console.log(`[vidfarm] fetched ${filename} (${body.length} bytes)`);
     }
 }
+async function fetchVideoAssets(input) {
+    const refs = readSourceRefs(input.dir);
+    if (!refs.compositionSourceUrl && !refs.originalSourceUrl) {
+        console.log("[vidfarm] no source video URL found in composition — skipping video assets");
+        return;
+    }
+    // "decomposed video in composition" = the source the composition currently
+    // renders from (post-ghostcut if applicable). "original" = the raw source the
+    // decompose ran against, before any processing. They coincide when the fork
+    // was never ghostcut/subtitle-removed.
+    const compositionUrl = refs.compositionSourceUrl ?? refs.originalSourceUrl;
+    const originalUrl = refs.originalSourceUrl ?? refs.compositionSourceUrl;
+    const sameSource = compositionUrl === originalUrl;
+    const headers = buildAuthHeaders(input);
+    const decomposedName = "source.mp4";
+    const originalName = "original.mp4";
+    const decomposed = await downloadVideo({
+        url: compositionUrl,
+        target: path.join(input.dir, decomposedName),
+        headers,
+        refetch: input.refetch,
+        label: "decomposed source"
+    });
+    let original = decomposed && sameSource ? { ...decomposed, path: decomposedName } : null;
+    if (!sameSource) {
+        original = await downloadVideo({
+            url: originalUrl,
+            target: path.join(input.dir, originalName),
+            headers,
+            refetch: input.refetch,
+            label: "original source"
+        });
+    }
+    // One representative still per scene, taken from the decomposed source (what
+    // the composition actually renders). Falls back to the original if that's the
+    // only video that came down.
+    const frameBase = decomposed ? decomposedName : original ? originalName : null;
+    const frames = frameBase
+        ? await extractSceneFrames({
+            dir: input.dir,
+            videoName: frameBase,
+            scenes: refs.scenes,
+            durationSeconds: refs.durationSeconds,
+            refetch: input.refetch
+        })
+        : new Map();
+    const manifest = {
+        generated_by: "vidfarm-devcli",
+        note: "Local media references for coding agents. `original.mp4` is the raw source video; " +
+            "`source.mp4` is the video the composition timeline renders from (may differ from the " +
+            "original after ghostcut subtitle-removal). Scene entries map timeline segments to a still " +
+            "frame you can open as an image. Run `--refetch` to refresh.",
+        videos: {
+            decomposed: {
+                role: "video the composition timeline renders from (decomposed source)",
+                url: compositionUrl,
+                path: decomposed ? decomposedName : null,
+                bytes: decomposed?.bytes ?? null
+            },
+            original: {
+                role: "raw original source video (before any processing)",
+                url: originalUrl,
+                path: original ? original.path : null,
+                bytes: original?.bytes ?? null,
+                same_as_decomposed: sameSource
+            }
+        },
+        duration_seconds: refs.durationSeconds,
+        scenes: refs.scenes.map((scene, index) => ({
+            slug: scene.slug,
+            start: scene.start,
+            duration: scene.duration,
+            label: scene.label,
+            description: scene.description,
+            transcript_excerpt: scene.transcript_excerpt,
+            frame: frames.get(index) ?? null,
+            frame_source: frameBase
+        }))
+    };
+    writeFileSync(path.join(input.dir, "sources.json"), JSON.stringify(manifest, null, 2));
+    console.log(`[vidfarm] wrote sources.json (${refs.scenes.length} scenes, ${frames.size} frames)`);
+}
+// Derive the source URLs and scene list from the files already on disk
+// (composition.html + video-context.json) — no extra network round-trips.
+function readSourceRefs(dir) {
+    let compositionSourceUrl = null;
+    const htmlPath = path.join(dir, "composition.html");
+    if (existsSync(htmlPath)) {
+        const html = readFileSync(htmlPath, "utf8");
+        compositionSourceUrl =
+            matchAttr(html, "data-source-video") ??
+                matchPlaybackSourceSrc(html) ??
+                null;
+    }
+    let originalSourceUrl = null;
+    let scenes = [];
+    let durationSeconds = null;
+    const ctxPath = path.join(dir, "video-context.json");
+    if (existsSync(ctxPath)) {
+        try {
+            const ctx = JSON.parse(readFileSync(ctxPath, "utf8"));
+            if (typeof ctx.source_url === "string" && ctx.source_url)
+                originalSourceUrl = ctx.source_url;
+            if (typeof ctx.duration_seconds === "number")
+                durationSeconds = ctx.duration_seconds;
+            if (Array.isArray(ctx.scenes)) {
+                scenes = ctx.scenes
+                    .map((raw) => {
+                    if (!raw || typeof raw !== "object")
+                        return null;
+                    const s = raw;
+                    return {
+                        slug: typeof s.slug === "string" ? s.slug : null,
+                        start: Number(s.start ?? 0),
+                        duration: Number(s.duration ?? 0),
+                        label: typeof s.label === "string" ? s.label : null,
+                        description: typeof s.description === "string" ? s.description : "",
+                        transcript_excerpt: typeof s.transcript_excerpt === "string" ? s.transcript_excerpt : ""
+                    };
+                })
+                    .filter((s) => s !== null);
+            }
+        }
+        catch {
+            // video-context.json absent/status:none/malformed → fall back to composition source only
+        }
+    }
+    return { compositionSourceUrl, originalSourceUrl, scenes, durationSeconds };
+}
+function matchAttr(html, attr) {
+    const match = html.match(new RegExp(`${attr}="([^"]+)"`));
+    return match ? decodeHtmlEntities(match[1]) : null;
+}
+function matchPlaybackSourceSrc(html) {
+    const match = html.match(/data-vf-playback-source="true"[^>]*\ssrc="([^"]+)"/) ??
+        html.match(/<video[^>]*\ssrc="([^"]+)"/);
+    return match ? decodeHtmlEntities(match[1]) : null;
+}
+function decodeHtmlEntities(value) {
+    return value
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">");
+}
+async function downloadVideo(input) {
+    const name = path.basename(input.target);
+    if (existsSync(input.target) && !input.refetch) {
+        console.log(`[vidfarm] keep local ${name} (use --refetch to overwrite)`);
+        return { path: name, bytes: safeSize(input.target) };
+    }
+    try {
+        const res = await fetch(input.url, { headers: input.headers });
+        if (!res.ok || !res.body) {
+            console.warn(`[vidfarm] skip ${name} (${input.label}): ${res.status} ${res.statusText}`);
+            return null;
+        }
+        await pipeline(Readable.fromWeb(res.body), createWriteStream(input.target));
+        const bytes = safeSize(input.target);
+        console.log(`[vidfarm] fetched ${name} (${input.label}, ${formatBytes(bytes)})`);
+        return { path: name, bytes };
+    }
+    catch (error) {
+        console.warn(`[vidfarm] skip ${name} (${input.label}): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+async function extractSceneFrames(input) {
+    const out = new Map();
+    if (input.scenes.length === 0)
+        return out;
+    const ffmpeg = await resolveFfmpegPath();
+    if (!ffmpeg) {
+        console.log("[vidfarm] ffmpeg unavailable — skipping scene frames (videos still downloaded)");
+        return out;
+    }
+    const framesDir = path.join(input.dir, "frames");
+    mkdirSync(framesDir, { recursive: true });
+    const videoPath = path.join(input.dir, input.videoName);
+    input.scenes.forEach((scene, index) => {
+        const slug = scene.slug || `scene-${index + 1}`;
+        const rel = path.join("frames", `${slug}.png`);
+        const target = path.join(input.dir, rel);
+        if (existsSync(target) && !input.refetch) {
+            out.set(index, rel);
+            return;
+        }
+        // Sample the scene midpoint, clamped inside the clip.
+        const mid = scene.start + Math.max(0, scene.duration) / 2;
+        const seek = Number.isFinite(mid) && mid > 0 ? mid : Math.max(0, scene.start);
+        const result = spawnSync(ffmpeg, ["-y", "-ss", seek.toFixed(3), "-i", videoPath, "-frames:v", "1", "-q:v", "3", target], { stdio: "ignore" });
+        if (result.status === 0 && existsSync(target)) {
+            out.set(index, rel);
+        }
+    });
+    console.log(`[vidfarm] extracted ${out.size}/${input.scenes.length} scene frames from ${input.videoName}`);
+    return out;
+}
+async function resolveFfmpegPath() {
+    // ffmpeg-static is already a dependency; import lazily so the common path
+    // (no frame extraction) never pays for it, and degrade gracefully if absent.
+    try {
+        const mod = (await import("ffmpeg-static"));
+        const resolved = typeof mod === "string" ? mod : mod.default;
+        return typeof resolved === "string" && resolved.length > 0 && existsSync(resolved) ? resolved : null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeSize(target) {
+    try {
+        return statSync(target).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function formatBytes(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${bytes} bytes`;
+}
 function buildAuthHeaders(input) {
     const headers = { accept: "text/html,application/json" };
     // The server reads exactly these header names (see requireAuth and
@@ -174,6 +568,8 @@ function printEditorBanner(input) {
     console.log(`  local dir   ${input.dir}`);
     console.log(`  dev-serve   http://localhost:${input.port}`);
     console.log("");
+    console.log(`  ${dim}Agent media: original.mp4, source.mp4, frames/*.png, sources.json${reset}`);
+    console.log("");
     console.log(`  ${bold}Open in browser:${reset}`);
     console.log(`  ${cyan}${input.editorUrl}${reset}`);
     console.log(line);

package/dist/src/dev-serve.js

@@ -11,7 +11,11 @@ import { parseArgs } from "node:util";
 const CORS_HEADERS = {
     "access-control-allow-origin": "*",
     "access-control-allow-methods": "GET,PUT,PATCH,POST,OPTIONS",
-    "access-control-allow-headers": "content-type,authorization",
+    // The editor page (vidfarm.cc) fetches us cross-origin and its Sentry
+    // instrumentation attaches distributed-tracing headers (sentry-trace,
+    // baggage). List them so the preflight passes; the OPTIONS handler also
+    // echoes whatever the browser actually asks for, which is the real guard.
+    "access-control-allow-headers": "content-type,authorization,vidfarm-api-key,vidfarm-share-token,sentry-trace,baggage",
     "access-control-max-age": "600"
 };
 // Cap request bodies at 8MB so a runaway or malicious client can't OOM the
@@ -155,7 +159,14 @@ function handleRequest(req, res, ctx) {
     const url = new URL(req.url ?? "/", `http://localhost`);
     const pathname = url.pathname;
     if (method === "OPTIONS") {
-        res.writeHead(204, CORS_HEADERS);
+        // Echo the exact headers the browser requested so a preflight never fails
+        // over an unexpected header (Sentry tracing, etc.). This is a local dev
+        // tool, so permissive CORS is fine.
+        const requested = req.headers["access-control-request-headers"];
+        res.writeHead(204, {
+            ...CORS_HEADERS,
+            "access-control-allow-headers": typeof requested === "string" && requested ? requested : CORS_HEADERS["access-control-allow-headers"]
+        });
         res.end();
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Local bridge for the Vidfarm Trackpad Editor. Point it at a template id, edit composition.html on disk (Claude Code, Codex, etc.), preview live in the browser at https://vidfarm.cc/editor/.",
   "type": "module",
   "bin": {