@mevdragon/vidfarm-devcli 0.3.4 → 0.3.5

package/SKILL.director.md

@@ -443,3 +443,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,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 // vidfarm-devcli — thin CLI that pairs a local composition directory with the
@@ -12,6 +12,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 +25,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 +57,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);
@@ -100,6 +113,147 @@ async function runEditCommand(argv) {
     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

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.5",
   "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": {