@officexapp/vidfarm-devcli 0.21.43 → 0.21.46

package/dist/src/devcli/agent-imagegen.js

@@ -0,0 +1,181 @@
+// Agent-included image generation — the $0 rung between "free stock" and "pay
+// Vidfarm to generate it".
+//
+// The premise: Vidfarm does not need to broker an image model when the agent
+// driving the terminal ALREADY has one included in its own subscription. Google
+// Antigravity / Gemini CLI ship image generation (Nano Banana / Imagen) at no
+// extra charge. OpenAI Codex / ChatGPT ship gpt-image. Claude does not — there
+// is no Anthropic image model, so Claude Code has nothing to fall back on here.
+//
+// That distinction is the whole feature. In cost mode `minimize` the old answer
+// to "I need a graphic" was: free stock, IconScout, or hand the human a prompt.
+// If the agent's own runtime includes image generation, there is a better answer
+// that is still $0 — the agent generates the file itself and imports it. Same
+// house pattern as `vidfarm consult`: the devcli writes the brief, the agent in
+// the terminal executes it. See references/agent-included-imagegen.md.
+//
+// Availability is asserted by the AGENT, not sniffed by us. Env detection here
+// is a hint for the opening line only; the authoritative check is the agent
+// looking at its own tool list. Never claim a capability the agent has to prove.
+//
+// Backend-free (Node built-ins + pure sibling modules) so it ships in the public
+// cloud-only package.
+import { buildImageHandoff } from "./handoff.js";
+/**
+ * Hosts we can say something concrete about. Kept deliberately short: a wrong
+ * "yes" costs the user a wasted turn, a wrong "no" costs them money, so anything
+ * we are not sure of stays `unknown` and the agent checks its own tools.
+ */
+export const KNOWN_HOST_AGENTS = [
+    {
+        id: "claude-code",
+        name: "Claude Code",
+        availability: "none",
+        envMarkers: ["CLAUDECODE", "CLAUDE_CODE", "CLAUDE_CODE_ENTRYPOINT"],
+        note: "Anthropic ships no image model, so there is nothing included here. Use free stock / IconScout, hand the user a prompt (`vidfarm handoff image`), or spend on `vidfarm generate image`."
+    },
+    {
+        id: "antigravity",
+        name: "Google Antigravity",
+        availability: "included",
+        tool: "the built-in Gemini image generation (Nano Banana / Imagen)",
+        envMarkers: ["ANTIGRAVITY", "ANTIGRAVITY_SESSION", "ANTIGRAVITY_WORKSPACE"],
+        note: "Image generation is part of the Gemini subscription — generating a graphic costs $0 extra."
+    },
+    {
+        id: "gemini-cli",
+        name: "Gemini CLI",
+        availability: "included",
+        tool: "the built-in Gemini image generation (Nano Banana / Imagen)",
+        envMarkers: ["GEMINI_CLI", "GEMINI_CLI_SESSION", "GEMINI_SANDBOX"],
+        note: "Image generation is part of the Gemini subscription — generating a graphic costs $0 extra."
+    },
+    {
+        id: "codex",
+        name: "OpenAI Codex",
+        availability: "included",
+        tool: "the built-in OpenAI image generation (gpt-image)",
+        envMarkers: ["CODEX_SANDBOX", "CODEX_HOME", "CODEX_CLI"],
+        note: "Image generation is part of the ChatGPT/Codex subscription — generating a graphic costs $0 extra."
+    },
+    {
+        id: "opencode",
+        name: "OpenCode",
+        availability: "unknown",
+        envMarkers: ["OPENCODE", "OPENCODE_SESSION"],
+        note: "Depends entirely on which model is configured — check your own tool list."
+    },
+    {
+        id: "cursor",
+        name: "Cursor",
+        availability: "unknown",
+        envMarkers: ["CURSOR_TRACE_ID", "CURSOR_SESSION_ID"],
+        note: "Depends on the selected model — check your own tool list."
+    }
+];
+/**
+ * Guess which agent runtime is driving this terminal from its env markers.
+ * A miss is normal and harmless — `availability: "unknown"` just means the brief
+ * asks the agent to check its own tools instead of asserting anything.
+ */
+export function detectHostAgent(env = process.env) {
+    for (const host of KNOWN_HOST_AGENTS) {
+        const matched = host.envMarkers.filter((k) => {
+            const v = env[k];
+            return typeof v === "string" && v.trim() !== "" && v.trim() !== "0" && v.trim().toLowerCase() !== "false";
+        });
+        if (matched.length)
+            return { host, matched, availability: host.availability };
+    }
+    return { host: null, matched: [], availability: "unknown" };
+}
+/** One line naming this rung, for cost-mode block messages and help text. */
+export const AGENT_IMAGEGEN_ALTERNATIVE = "generate it YOURSELF for $0 if your own agent subscription includes image generation " +
+    "(Google Antigravity / Gemini CLI and OpenAI Codex / ChatGPT do; Claude Code does NOT — " +
+    'Anthropic ships no image model) — run `vidfarm agent-image "<subject>" --items "a,b,c"` for ' +
+    "the prompt, the plate rules and the import command, then `vidfarm put-file` the result";
+/** The shorter form used inside prose blurbs. */
+export const AGENT_IMAGEGEN_SHORT = 'if YOUR agent subscription includes image generation (Gemini/Antigravity, Codex/ChatGPT — not Claude), generate it yourself: `vidfarm agent-image "<subject>"`';
+/**
+ * Build the brief the AGENT executes itself. The prompt body is shared verbatim
+ * with `vidfarm handoff image` (`buildImageHandoff`) — a plate that keys cleanly
+ * and art that survives the cut are the same craft whoever runs the generator —
+ * only the STEPS change, because here the runner is the agent, not the human.
+ */
+export function buildAgentImageBrief(input) {
+    const base = buildImageHandoff(input);
+    const detection = input.detection ?? detectHostAgent();
+    const items = input.items.map((s) => s.trim()).filter(Boolean);
+    const pack = input.pack ?? items.length > 1;
+    const outDir = input.outDir ?? "./stickers";
+    const outFile = input.outFile ?? (pack ? "./sheet.png" : "./art.png");
+    const folderFlag = input.folder ? ` --folder ${input.folder}` : "";
+    const cutCmd = pack
+        ? `vidfarm sticker-pack ${outFile}${items.length ? ` --items "${items.join(",")}"` : ""} --out-dir ${outDir}`
+        : `vidfarm cutout ${outFile}`;
+    const steps = [
+        "Check YOUR OWN tool list for an image-generation tool included in this subscription — " +
+            "Antigravity / Gemini CLI have one (Nano Banana / Imagen), Codex / ChatGPT have one (gpt-image), " +
+            "Claude Code has none. If you have none, use the fallbacks below instead; do not pretend.",
+        `Generate the image with that tool using the prompt below, and save it to ${outFile}. ` +
+            "This spends nothing on Vidfarm and nothing extra on the provider — it is already in the subscription.",
+        "Look at the result before you use it: a flat even plate, crisp edges, nothing touching or " +
+            "cropped at the frame edge. Re-generate rather than shipping a sheet that will cut badly.",
+        `Cut it locally for $0: \`${cutCmd}\`.`,
+        `Bring the asset into the library so later videos reuse it: \`vidfarm put-file ${outDir}/<file>.png${folderFlag}\`.`
+    ];
+    const fallbacks = [
+        'Free stock first, always — `vidfarm media search "<meaning>" --type image|vector` (Openverse is keyless).',
+        'Any icon, sticker, illustration, 3D prop or Lottie — `vidfarm iconscout "<meaning>" --free` beats generation on price AND quality.',
+        'Hand the human the prompt — `vidfarm handoff image --theme "<what>" --items "a,b,c"`; they run it in a free web generator.',
+        "Only then spend: `vidfarm generate image --prompt \"…\"` (~$0.01–$0.05, billed to the user's own provider key)."
+    ];
+    return {
+        ...base,
+        outFile,
+        availability: detection.availability,
+        hostName: detection.host?.name ?? null,
+        steps,
+        followUp: cutCmd,
+        fallbacks,
+        tools: detection.host?.tool
+            ? [detection.host.tool]
+            : ["your own runtime's image-generation tool, if this subscription includes one"]
+    };
+}
+/** Render the brief as the block an agent reads (and may show the user). */
+export function formatAgentImageBrief(brief, detection) {
+    const lines = [];
+    const host = detection.host;
+    if (host && host.availability === "included") {
+        lines.push(`Detected host: ${host.name} — image generation IS included in this subscription.`);
+        lines.push(host.note);
+    }
+    else if (host && host.availability === "none") {
+        lines.push(`Detected host: ${host.name} — image generation is NOT included.`);
+        lines.push(host.note);
+    }
+    else if (host) {
+        lines.push(`Detected host: ${host.name} — unclear whether image generation is included.`);
+        lines.push(host.note);
+    }
+    else {
+        lines.push("Host agent not detected from the environment.");
+    }
+    lines.push("The env check is only a hint. YOU are the authority: look at your own tool list.");
+    lines.push("");
+    brief.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    lines.push("");
+    lines.push("─── the generation prompt ───");
+    lines.push(brief.prompt);
+    lines.push("─────────────────────────────");
+    if (brief.keyColorNote) {
+        lines.push("");
+        lines.push(`Plate: ${brief.keyColorNote}`);
+    }
+    lines.push("");
+    lines.push("If you have NO image tool of your own, in this order:");
+    brief.fallbacks.forEach((f) => lines.push(`  • ${f}`));
+    return lines.join("\n");
+}
+//# sourceMappingURL=agent-imagegen.js.map

package/dist/src/devcli/browser-harness.js

@@ -0,0 +1,384 @@
+// `vidfarm browser` — wire the agent's OWN Chrome up as a FREE substitute for
+// the paid cloud search/download primitives.
+//
+// WHY THIS EXISTS. The sourcing ladder in SKILL.md already starts at "your own
+// browser control, if you have it" — but nothing in the devcli ever made that
+// rung real, so every agent fell straight through to `video-search` /
+// `image-search` / `news-search` / `download-video`, all of which are paid
+// plans only. A free-tier director therefore got a 402 for the single most
+// common ask in the product ("find me a clip of X").
+//
+// browser-harness (https://github.com/browser-use/browser-harness) closes that
+// gap: it attaches an LLM to the user's already-running Chrome over one CDP
+// websocket, so the agent can drive Google Images / Google Videos / Google News
+// itself. The session is the user's own logged-in browser, on the user's own
+// IP, at $0. That is a genuine substitute for the paid primitives when the mode
+// is `minimize`, and a cost saver in `hybrid`.
+//
+// This module does NOT reimplement browser-harness. It does three things:
+//   1. detect / install it (`setup`), so "can easily set it up" is one command;
+//   2. report it in `vidfarm doctor` as an optional free capability;
+//   3. mint the exact browse RECIPE for a given sourcing job (`browse`), in the
+//      same house pattern as `vidfarm consult` and `vidfarm handoff` — the
+//      devcli writes the brief, the agent already in this terminal executes it.
+//
+// Nothing here is billed and nothing here needs a Vidfarm account.
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { resolveSkillsRoot } from "./skills.js";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+export const BROWSER_HARNESS_REPO = "https://github.com/browser-use/browser-harness";
+/** Where `uv tool install` drops console scripts, per platform. browser-harness
+ *  lands on PATH for most users, but a fresh `uv` install in the same shell has
+ *  not re-hashed PATH yet — so check the well-known bin dirs too rather than
+ *  telling a user who just installed it that it isn't there. */
+function candidateBins() {
+    const home = homedir();
+    const exe = process.platform === "win32" ? "browser-harness.exe" : "browser-harness";
+    const dirs = process.platform === "win32"
+        ? [path.join(home, ".local", "bin"), path.join(home, "AppData", "Roaming", "uv", "tools", "browser-harness", "Scripts")]
+        : [path.join(home, ".local", "bin"), "/usr/local/bin", "/opt/homebrew/bin"];
+    return dirs.map((dir) => path.join(dir, exe));
+}
+function which(command) {
+    const probe = process.platform === "win32" ? "where" : "which";
+    const res = spawnSync(probe, [command], { encoding: "utf8" });
+    if (res.status !== 0)
+        return null;
+    const first = String(res.stdout ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+    return first || null;
+}
+export function detectBrowserHarness() {
+    const uv = which("uv");
+    let bin = which("browser-harness");
+    if (!bin)
+        bin = candidateBins().find((candidate) => existsSync(candidate)) ?? null;
+    let version = null;
+    if (bin) {
+        const res = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 20_000 });
+        const out = `${res.stdout ?? ""}${res.stderr ?? ""}`.trim();
+        version = out ? out.split(/\r?\n/)[0].trim() : null;
+    }
+    return { bin, version, uv };
+}
+/** One line for `vidfarm doctor`. Never a failure — this is an OPTIONAL free
+ *  capability, and a box without it is a perfectly healthy box. */
+export function browserHarnessDoctorCheck() {
+    const found = detectBrowserHarness();
+    if (found.bin) {
+        return {
+            level: "ok",
+            detail: `${found.bin}${found.version ? ` (${found.version})` : ""} — free browser sourcing available; \`vidfarm browse videos "<shot>"\` for the recipe`
+        };
+    }
+    return {
+        level: "warn",
+        detail: found.uv
+            ? "not installed — the FREE substitute for the paid video-search/image-search/news-search/download-video primitives. Install: `vidfarm browser setup`"
+            : "not installed, and `uv` is missing too — run `vidfarm browser setup` (it prints the one-line uv install first)"
+    };
+}
+const RECIPES = {
+    videos: {
+        replaces: "vidfarm video-search (paid, $0.0003/call)",
+        udm: "7",
+        tbm: "vid",
+        extract: "every off-Google result link with its title and host — YouTube, TikTok, Pexels, Pixabay, Mixkit, archive.org, news sites",
+        next: [
+            "vidfarm raws scan \"<result url>\" --clips 8      # mine short raws out of the best hit",
+            "vidfarm clipper \"<result url>\" --start <t> --end <t>   # one surgical cut instead"
+        ]
+    },
+    images: {
+        replaces: "vidfarm image-search (paid, $0.0003/call)",
+        udm: "2",
+        tbm: "isch",
+        extract: "the SOURCE PAGE url behind each thumbnail (Google lazy-loads full-res, so the thumbnail src is a data: URI and not what you want) — click a result, then read the full-size image url off the detail panel",
+        next: [
+            "vidfarm put-file ./downloaded.png --folder brand-assets --notes \"<what it is, so files --search finds it later>\""
+        ]
+    },
+    news: {
+        replaces: "vidfarm news-search (paid, $0.0003/call)",
+        udm: "12",
+        tbm: "nws",
+        extract: "headline, publisher, timestamp and article url for each story — this is the STORY stage, not the visuals stage",
+        next: [
+            "# then a SECOND pass for the visuals — never one query for both:",
+            "vidfarm browse videos \"<the thing the story is about>\""
+        ]
+    },
+    page: {
+        replaces: "vidfarm download-video / download-audio (paid, wallet-billed resolver)",
+        udm: null,
+        tbm: null,
+        extract: "the media element itself — `document.querySelectorAll('video source, video')` for the src, or CDP `Network.getResponseBody` on the media request; a logged-in session sees what an anonymous resolver cannot",
+        next: [
+            "vidfarm put-file ./saved.mp4 --folder raws-inbox      # bring the local file in for $0",
+            "vidfarm clipper ./saved.mp4 --start <t> --end <t>     # or clip it straight away"
+        ]
+    }
+};
+function googleUrl(mode, query, legacy) {
+    const recipe = RECIPES[mode];
+    const q = encodeURIComponent(query);
+    if (!recipe.udm && !recipe.tbm)
+        return query.startsWith("http") ? query : `https://www.google.com/search?q=${q}`;
+    const surface = legacy ? `tbm=${recipe.tbm}` : `udm=${recipe.udm}`;
+    return `https://www.google.com/search?q=${q}&${surface}`;
+}
+/** The heredoc an agent runs. Deliberately short: browser-harness's own SKILL.md
+ *  teaches the AX-tree-first workflow, and we do not want to fight it with a
+ *  brittle selector script that Google will break next month. */
+function browseScript(mode, query, legacy, limit) {
+    const url = googleUrl(mode, query, legacy);
+    if (mode === "page") {
+        return [
+            "browser-harness <<'PY'",
+            `new_tab(${JSON.stringify(query)})`,
+            "wait_for_load()",
+            "print(page_info())",
+            "print(js(\"JSON.stringify([...document.querySelectorAll('video, video source')].map(n => n.currentSrc || n.src).filter(Boolean))\"))",
+            "PY"
+        ].join("\n");
+    }
+    return [
+        "browser-harness <<'PY'",
+        `new_tab(${JSON.stringify(url)})`,
+        "wait_for_load()",
+        "# Result links, deduped, Google's own chrome stripped out.",
+        "print(js(\"\"\"JSON.stringify(",
+        "  [...document.querySelectorAll('a[href^=\\\"http\\\"]')]",
+        "    .map(a => ({ url: a.href, title: (a.innerText || '').trim().split('\\\\n')[0] }))",
+        "    .filter(r => !/(^|\\\\.)google\\\\.com$/.test(new URL(r.url).hostname) && r.title)",
+        "    .filter((r, i, all) => all.findIndex(o => o.url === r.url) === i)",
+        `    .slice(0, ${limit})`,
+        ")\"\"\"))",
+        "PY"
+    ].join("\n");
+}
+function renderBrowseRecipe(mode, query, legacy, limit, installed) {
+    const recipe = RECIPES[mode];
+    const lines = [];
+    lines.push(`${BOLD}Free browser sourcing — ${mode}${RESET}  ${DIM}(replaces ${recipe.replaces})${RESET}`);
+    lines.push("");
+    if (!installed) {
+        lines.push(`${YELLOW}browser-harness is not installed yet.${RESET} Run ${BOLD}vidfarm browser setup${RESET} first — one command, no account, no key.`);
+        lines.push("");
+    }
+    lines.push(`${BOLD}1. Open it${RESET}`);
+    lines.push("");
+    lines.push(browseScript(mode, query, legacy, limit));
+    lines.push("");
+    lines.push(`${BOLD}2. Pull off the page${RESET}`);
+    lines.push(`   ${recipe.extract}`);
+    lines.push("");
+    lines.push(`${BOLD}3. Feed it forward${RESET}`);
+    for (const step of recipe.next)
+        lines.push(`   ${step}`);
+    lines.push("");
+    lines.push(`${DIM}Prefer the accessibility tree over screenshots — cdp("Accessibility.getFullAXTree"). If a`);
+    lines.push(`selector above comes back empty, Google changed its markup: read the AX tree and adapt,`);
+    lines.push(`don't retry the same query. Legacy surface param: rerun with --legacy (tbm=… instead of udm=…).${RESET}`);
+    lines.push("");
+    lines.push(`${DIM}A public result is not a licensed asset. Keep the source URL and the licence page for`);
+    lines.push(`anything that reaches a client render.${RESET}`);
+    return lines.join("\n");
+}
+// ── setup ───────────────────────────────────────────────────────────────────
+function runSetup(opts) {
+    const before = detectBrowserHarness();
+    console.log(`${BOLD}vidfarm browser setup${RESET} — free browser sourcing via browser-harness`);
+    console.log(`${DIM}${BROWSER_HARNESS_REPO}${RESET}`);
+    console.log("");
+    if (!before.uv) {
+        console.log(`${YELLOW}Step 0 — install uv (the Python tool installer browser-harness ships through):${RESET}`);
+        console.log(process.platform === "win32"
+            ? '  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"'
+            : "  curl -LsSf https://astral.sh/uv/install.sh | sh");
+        console.log("");
+        console.log("Then re-run `vidfarm browser setup`.");
+        return 1;
+    }
+    const install = ["tool", "install", "--python", "3.12", "--upgrade", "--force", "browser-harness"];
+    console.log(`${BOLD}Step 1 — install/upgrade browser-harness${RESET}`);
+    console.log(`  uv ${install.join(" ")}`);
+    if (opts.dryRun) {
+        console.log(`${DIM}  (--dry-run: not executed)${RESET}`);
+    }
+    else {
+        const res = spawnSync(before.uv, install, { stdio: "inherit" });
+        if (res.status !== 0) {
+            console.error(`${YELLOW}uv tool install failed (exit ${res.status}). Run the command above by hand to see why.${RESET}`);
+            return 1;
+        }
+    }
+    console.log("");
+    const found = opts.dryRun ? before : detectBrowserHarness();
+    const bin = found.bin ?? "browser-harness";
+    // Step 2 — register browser-harness's OWN skill next to the vidfarm pack, so
+    // the agent reading .agents/skills finds the browser workflow without a
+    // network fetch. `browser-harness skill` prints the canonical body; we never
+    // author or paraphrase it here.
+    const skillRoot = opts.skillDir ? path.resolve(process.cwd(), opts.skillDir) : resolveSkillsRoot();
+    const skillDir = path.join(skillRoot, ".agents", "skills", "browser-harness");
+    const skillFile = path.join(skillDir, "SKILL.md");
+    console.log(`${BOLD}Step 2 — register the browser-harness skill${RESET}`);
+    console.log(`  ${skillFile}`);
+    if (opts.dryRun) {
+        console.log(`${DIM}  (--dry-run: not written)${RESET}`);
+    }
+    else {
+        const res = spawnSync(bin, ["skill"], { encoding: "utf8", timeout: 60_000 });
+        const body = String(res.stdout ?? "").trim();
+        if (res.status === 0 && body) {
+            mkdirSync(skillDir, { recursive: true });
+            writeFileSync(skillFile, `${body}\n`, "utf8");
+            console.log(`  ${GREEN}written${RESET}`);
+        }
+        else {
+            console.log(`  ${YELLOW}\`${bin} skill\` produced nothing — register it by hand: \`${bin} skill > ${skillFile}\`${RESET}`);
+        }
+    }
+    console.log("");
+    // Step 3 — the one manual step. Chrome will not expose CDP until the user
+    // ticks the box, and no amount of tooling can do it for them.
+    console.log(`${BOLD}Step 3 — let Chrome be driven (one-time, the user must do this)${RESET}`);
+    console.log("  1. Open Chrome → chrome://inspect/#remote-debugging");
+    console.log('  2. Tick "Allow remote debugging for this browser instance"');
+    console.log(`  3. macOS only, if a permission sheet appears: ${bin} mac-approve`);
+    console.log("");
+    console.log(`${BOLD}Step 4 — verify${RESET}`);
+    console.log(`  ${bin} <<'PY'`);
+    console.log("  print(page_info())");
+    console.log("  PY");
+    console.log(`  ${DIM}(if it fails: ${bin} --doctor)${RESET}`);
+    console.log("");
+    console.log(`${GREEN}Then this is free:${RESET}`);
+    console.log('  vidfarm browse videos "warehouse worker packing orders POV 4K"   # was: video-search, paid');
+    console.log('  vidfarm browse images "manila street market wide shot"           # was: image-search, paid');
+    console.log('  vidfarm browse news   "AI startup funding announced"             # was: news-search, paid');
+    console.log('  vidfarm browse page   "https://…"                                # was: download-video, paid');
+    console.log("");
+    console.log(`${DIM}Recordings are OFF by default and stay off unless the user asks — they capture page`);
+    console.log(`content to disk. \`${bin} recordings\` shows the current preference.${RESET}`);
+    return 0;
+}
+function printStatus() {
+    const found = detectBrowserHarness();
+    console.log(`${BOLD}browser-harness${RESET}  ${DIM}— free substitute for the paid search/download primitives${RESET}`);
+    console.log("");
+    console.log(`  uv               ${found.uv ? `${GREEN}${found.uv}${RESET}` : `${YELLOW}not found${RESET}`}`);
+    console.log(`  browser-harness  ${found.bin ? `${GREEN}${found.bin}${RESET}${found.version ? ` ${DIM}(${found.version})${RESET}` : ""}` : `${YELLOW}not installed${RESET}`}`);
+    console.log("");
+    if (!found.bin) {
+        console.log(`Install it with ${BOLD}vidfarm browser setup${RESET} — no account, no API key, ~1 minute.`);
+        console.log(`${DIM}It replaces video-search / image-search / news-search / download-video, all of which are`);
+        console.log(`paid plans only. In cost mode \`minimize\` this is the difference between sourcing footage`);
+        console.log(`and telling the user you can't.${RESET}`);
+        return 0;
+    }
+    console.log(`Connection check: ${BOLD}${found.bin} --doctor${RESET}`);
+    console.log(`Browse recipes:  ${BOLD}vidfarm browse <videos|images|news|page> "<query>"${RESET}`);
+    return 0;
+}
+export async function runBrowserHarnessCommand(argv) {
+    const sub = (argv[0] ?? "status").toLowerCase();
+    const rest = argv.slice(1);
+    if (sub === "setup" || sub === "install") {
+        const parsed = parseArgs({
+            args: rest,
+            allowPositionals: false,
+            options: { "dry-run": { type: "boolean", default: false }, dir: { type: "string" } }
+        });
+        const code = runSetup({ dryRun: Boolean(parsed.values["dry-run"]), skillDir: parsed.values.dir });
+        if (code !== 0)
+            process.exitCode = code;
+        return;
+    }
+    if (sub === "doctor") {
+        const found = detectBrowserHarness();
+        if (!found.bin) {
+            printStatus();
+            return;
+        }
+        const res = spawnSync(found.bin, ["--doctor"], { stdio: "inherit" });
+        if (res.status !== 0)
+            process.exitCode = res.status ?? 1;
+        return;
+    }
+    if (sub === "status" || sub === "" || sub === "--help" || sub === "-h") {
+        printStatus();
+        return;
+    }
+    // `vidfarm browser videos "…"` is the same thing as `vidfarm browse videos "…"`.
+    if (sub === "videos" || sub === "images" || sub === "news" || sub === "page") {
+        await runBrowseCommand(argv);
+        return;
+    }
+    throw new Error(`Unknown browser subcommand "${sub}". Use: status | setup | doctor, or \`vidfarm browse <videos|images|news|page> "<query>"\`.`);
+}
+export async function runBrowseCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            limit: { type: "string", default: "40" },
+            legacy: { type: "boolean", default: false },
+            // Pipe the script straight into browser-harness instead of printing it.
+            // Off by default: the recipe is meant to be ADAPTED (Google's markup
+            // moves), and an agent that reads it first gets better results than one
+            // that runs it blind.
+            run: { type: "boolean", default: false },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const positionals = parsed.positionals ?? [];
+    const mode = String(positionals[0] ?? "").toLowerCase();
+    const query = positionals.slice(1).join(" ").trim();
+    if (!["videos", "images", "news", "page"].includes(mode) || !query) {
+        throw new Error('Usage: vidfarm browse <videos|images|news|page> "<query or url>" [--limit 40] [--legacy] [--run]\n' +
+            '  videos → replaces the paid video-search · images → image-search · news → news-search · page → download-video');
+    }
+    const limit = Math.max(1, Math.min(200, Number(parsed.values.limit) || 40));
+    const legacy = Boolean(parsed.values.legacy);
+    const found = detectBrowserHarness();
+    if (parsed.values.json) {
+        console.log(JSON.stringify({
+            mode,
+            query,
+            installed: Boolean(found.bin),
+            bin: found.bin,
+            replaces: RECIPES[mode].replaces,
+            url: googleUrl(mode, query, legacy),
+            script: browseScript(mode, query, legacy, limit),
+            extract: RECIPES[mode].extract,
+            next: RECIPES[mode].next
+        }, null, 2));
+        return;
+    }
+    if (parsed.values.run) {
+        if (!found.bin) {
+            throw new Error("--run needs browser-harness. Install it with `vidfarm browser setup`, or drop --run to print the recipe.");
+        }
+        // Feed the PY body (not the wrapper) to the binary on stdin, exactly as the
+        // heredoc would.
+        const script = browseScript(mode, query, legacy, limit)
+            .split("\n")
+            .slice(1, -1)
+            .join("\n");
+        const res = spawnSync(found.bin, [], { input: `${script}\n`, stdio: ["pipe", "inherit", "inherit"] });
+        if (res.status !== 0)
+            process.exitCode = res.status ?? 1;
+        return;
+    }
+    console.log(renderBrowseRecipe(mode, query, legacy, limit, Boolean(found.bin)));
+}
+//# sourceMappingURL=browser-harness.js.map

package/dist/src/devcli/clip-store.js

@@ -6,8 +6,7 @@
 //   ~/.vidfarm/clips/<id>.mp4    clip files
 //   ~/.vidfarm/thumbs/<id>.jpg   thumbnails
 // Override the base dir with VIDFARM_HOME.
-import Database from "better-sqlite3";
-import * as sqliteVec from "sqlite-vec";
+import { createRequire } from "node:module";
 import { existsSync, mkdirSync, rmSync } from "node:fs";
 import path from "node:path";
 import { homedir } from "node:os";
@@ -27,6 +26,44 @@ export function resolveClipStorePaths(baseOverride) {
         workDir: path.join(base, "scan-tmp")
     };
 }
+const requireFrom = createRequire(import.meta.url);
+let cachedSqlite;
+/**
+ * A missing OPTIONAL native module is an expected environment condition, not a
+ * bug — cli.ts prints the message without a stack and skips the crash report,
+ * the same treatment LocalModeUnavailableError gets.
+ */
+export class NativeModuleUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NativeModuleUnavailableError";
+    }
+}
+/**
+ * Load the optional native SQLite stack, or throw a message that names the
+ * actual fix. Called from the ClipStore constructor, never at import time.
+ */
+function loadSqlite() {
+    if (cachedSqlite)
+        return cachedSqlite;
+    try {
+        const mod = requireFrom("better-sqlite3");
+        const ctor = (typeof mod === "function" ? mod : mod.default);
+        const sqliteVec = requireFrom("sqlite-vec");
+        return (cachedSqlite = { Database: ctor, sqliteVec });
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message.split("\n")[0] : String(error);
+        throw new NativeModuleUnavailableError("The local clip library needs the optional native module `better-sqlite3`, which is not built on this machine.\n" +
+            "  Everything else in vidfarm works without it — only `vidfarm clips` does not.\n" +
+            "  To enable it, install a C++ toolchain and reinstall:\n" +
+            "    Windows : npm i -g windows-build-tools   (or install \"Desktop development with C++\" from the Visual Studio Installer)\n" +
+            "    macOS   : xcode-select --install\n" +
+            "    Linux   : apt install build-essential python3\n" +
+            "  Then: npm i -g @officexapp/vidfarm-devcli\n" +
+            `  Underlying load error: ${detail}`);
+    }
+}
 export class ClipStore {
     paths;
     db;
@@ -36,7 +73,8 @@ export class ClipStore {
         mkdirSync(this.paths.base, { recursive: true });
         mkdirSync(this.paths.clipsDir, { recursive: true });
         mkdirSync(this.paths.thumbsDir, { recursive: true });
-        this.db = new Database(this.paths.db);
+        const { Database: DatabaseCtor, sqliteVec } = loadSqlite();
+        this.db = new DatabaseCtor(this.paths.db);
         this.db.pragma("journal_mode = WAL");
         sqliteVec.load(this.db);
         this.dim = this.initSchema();

package/dist/src/devcli/consult.js

@@ -63,6 +63,18 @@ const STEP_ORDER = ["coldstart", "awareness", "angles", "hooks"];
  * answered. It lives in the working folder next to the other artifacts.
  */
 export const CONSULT_CONTEXT_FILE = "CONTEXT.md";
+/**
+ * CONTENT IDEAS COME BEFORE THE INTERVIEW.
+ *
+ * An interview asks the director to work before they have seen anything, which
+ * is the worst trade a first session can offer. `vidfarm ideas --topic "<their
+ * offer in a line>"` inverts it: one sentence in, 20+ titled video ideas out,
+ * offline and free. The director gets a win first, and the ideas they react to
+ * ("this one, not that one") are better interview answers than the ones they
+ * would have typed cold. So every interview brief opens by offering the ideas
+ * pass, and the interview becomes the thing they opt INTO once they want depth.
+ */
+const IDEAS_FIRST = 'START WITH CONTENT IDEAS, NOT THIS INTERVIEW, unless the director already ran them or explicitly asked for a consultation. Get their offer in ONE line, run `vidfarm ideas --topic "<that line>"`, sharpen the frames into 20+ real titles and save `content-ideas.md`. It is offline, free, and gives them something to react to. Then say the interview is available when they want the strategy behind the ideas — and run it now only if they say yes.';
 /**
  * The SHORT interview. The full cold-start prompt asks a model to invent 12-30
  * questions; that is the right depth for a director who wants a real strategy
@@ -244,6 +256,7 @@ export function buildConsultBrief(input) {
             prompt: buildShortInterviewPrompt(),
             steps: [
                 contextRead,
+                IDEAS_FIRST,
                 `Ask the human these ${SHORT_INTERVIEW.length} questions in two batches of three. Ask them as written. Do not add questions, do not invent answers, and do not skip ahead to advice.`,
                 `Keep their phrasing for the pain and the desire answers word for word: the angles and hooks steps quote them back, and a paraphrase is what makes an ad sound generic.`,
                 "TELL THEM UP FRONT that every question is optional: they can skip any one, or say stop and end the interview on the spot. Then work with whatever they gave — do not push, do not re-ask, and do not make finishing the set a condition of getting a video.",
@@ -264,6 +277,7 @@ export function buildConsultBrief(input) {
             prompt: buildColdstartPrompt(input.userMessage?.trim() || "The director asked for a consultation and has given no offer context yet.", count),
             steps: [
                 ...common,
+                IDEAS_FIRST,
                 `This one is an INTERVIEW, not a report. Answer the prompt to get the question set, then ASK THE HUMAN those questions conversationally, a few at a time — never dump all ${count} at once, and never invent their answers.`,
                 `Assemble their real words into \`${artifact}\`: keep their phrasing for pain and desire, because the later angle and hook steps quote it back.`,
                 "Stop and wait for the human between batches. If they go quiet on a question, mark it UNKNOWN in the file rather than guessing — an invented customer psyche poisons every later step.",