@officexapp/vidfarm-devcli 0.21.10

package/dist/src/devcli/cost-mode.js

@@ -0,0 +1,149 @@
+// Cost mode — the devcli's money-saving preference. Vidfarm is founder-friendly:
+// most work can be done on FREE local compute (local render, local TTS/STT,
+// local greenscreen/matting, the raw-clip + HTML-hyperframe "paintbrushes")
+// before any billed AI credit is spent on the account's provider keys / wallet.
+//
+// The mode is a single durable preference the human picks ONCE (ideally asked by
+// their AI agent up front), then every billed command respects it:
+//   - minimize : never burn AI credits by surprise. Prefer free local engines;
+//                refuse billed cloud/AI ops unless the user re-confirms (--yes).
+//   - hybrid   : free where it's free, spend on AI only where it clearly wins.
+//                (default recommendation.) Billed ops run but print a cost line.
+//   - pure-ai  : best-quality; AI image/video/voice/music used freely. Billed
+//                ops run; cost is still surfaced.
+//
+// This module lives in the CLI's static import closure and is BACKEND-FREE (only
+// Node built-ins) so it ships in the public cloud-only package.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveDevcliHome } from "./auth-store.js";
+export const COST_MODES = ["minimize", "hybrid", "pure-ai"];
+/** What we assume when nothing is set. Hybrid is the founder-friendly middle,
+ *  but callers can tell it apart from an explicit choice via `isSet`. */
+export const DEFAULT_COST_MODE = "hybrid";
+function costModeFilePath(home) {
+    return path.join(resolveDevcliHome(home), "cost-mode.json");
+}
+/** Normalize loose spellings ("min", "cheap", "pureai", "best") to a CostMode. */
+export function normalizeCostMode(raw) {
+    const v = (raw ?? "").trim().toLowerCase().replace(/[\s_]+/g, "-");
+    if (!v)
+        return null;
+    if (["minimize", "min", "cheap", "thrift", "budget", "save", "free"].includes(v))
+        return "minimize";
+    if (["hybrid", "mixed", "balanced", "smart", "default"].includes(v))
+        return "hybrid";
+    if (["pure-ai", "pureai", "ai", "best", "best-quality", "premium", "max"].includes(v))
+        return "pure-ai";
+    return null;
+}
+/** Read the persisted cost mode, or null if absent/unparseable. */
+export function readStoredCostMode(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(costModeFilePath(home), "utf8"));
+        const mode = normalizeCostMode(parsed?.mode);
+        if (mode)
+            return { mode, note: parsed.note ?? null, savedAt: String(parsed.savedAt ?? "") };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the cost mode. Returns the file path written. */
+export function writeStoredCostMode(mode, savedAt, note, home) {
+    const dir = resolveDevcliHome(home);
+    mkdirSync(dir, { recursive: true });
+    const file = costModeFilePath(home);
+    const payload = { mode, note: note ?? null, savedAt };
+    writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return file;
+}
+/** Delete the persisted cost mode. Returns true if a file was removed. */
+export function clearStoredCostMode(home) {
+    const file = costModeFilePath(home);
+    if (!existsSync(file))
+        return false;
+    rmSync(file, { force: true });
+    return true;
+}
+/**
+ * Resolve the effective cost mode for a command run. Precedence:
+ *   --cost-mode flag → VIDFARM_COST_MODE env → stored preference → default.
+ * `isSet` is false only for the last case, so callers can nudge the agent to
+ * ASK the user and record a choice the first time real money is on the line.
+ */
+export function resolveCostMode(values) {
+    const flag = normalizeCostMode(values["cost-mode"]);
+    if (flag)
+        return { mode: flag, isSet: true, source: "flag" };
+    const env = normalizeCostMode(process.env.VIDFARM_COST_MODE);
+    if (env)
+        return { mode: env, isSet: true, source: "env" };
+    const stored = readStoredCostMode(values.home);
+    if (stored)
+        return { mode: stored.mode, isSet: true, source: "stored" };
+    return { mode: DEFAULT_COST_MODE, isSet: false, source: "default" };
+}
+export const COST_MODE_BLURB = {
+    minimize: "Minimize costs — stay on FREE local compute wherever possible (local render, " +
+        "local TTS/STT, local greenscreen/matting, reused clips + HTML motion). Billed " +
+        "cloud/AI generation is refused unless you re-confirm it (--yes).",
+    hybrid: "Hybrid (recommended) — free where it's free, spend AI credits only where they " +
+        "clearly win (a hero shot, a voice you can't fake locally). Billed ops run but " +
+        "each prints its cost so nothing is a surprise.",
+    "pure-ai": "Pure AI — best quality; AI image/video/voice/music used freely. Billed ops run " +
+        "without gating; cost is still shown."
+};
+/** One short human line summarizing the active mode. */
+export function costModeSummaryLine(resolved) {
+    const setNote = resolved.isSet ? `set via ${resolved.source}` : "NOT set — assuming hybrid";
+    return `cost mode: ${resolved.mode} (${setNote})`;
+}
+/** The 3-line "explain it simply" block an agent should relay to the user. */
+export function costModeExplainer() {
+    return [
+        "How much do you want Vidfarm to spend on AI credits?",
+        "  • minimize — cheapest: free local compute, no surprise AI spend.",
+        "  • hybrid   — recommended: free where free, pay AI only where it clearly wins.",
+        "  • pure-ai  — best quality: use AI image/video/voice/music freely."
+    ].join("\n");
+}
+export class CostModeBlockedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CostModeBlockedError";
+    }
+}
+/**
+ * Gate a BILLED cloud/AI operation against the active cost mode. Call this at the
+ * top of any command that spends the account's wallet or provider-key AI credits
+ * (cloud render, generate, music, cloud TTS/STT, inpaint, overlays, cloud
+ * greenscreen, decompose, etc.).
+ *
+ * - minimize: throws unless `yes` is set — the agent must confirm with the user
+ *   (or use the free local alternative named in `freeAlternative`).
+ * - hybrid / pure-ai: allowed; prints a one-line cost notice (unless json).
+ * - unset: allowed like hybrid, but prints a "no preference set — ask the user"
+ *   nudge once so the default posture really is "ask before spending."
+ */
+export function assertBilledAllowed(input) {
+    const { resolved, yes, json, label, estimate, freeAlternative } = input;
+    const log = input.log ?? ((line) => console.error(line));
+    const cost = estimate ? ` (${estimate})` : "";
+    if (resolved.mode === "minimize" && !yes) {
+        const alt = freeAlternative ? `\nFree alternative: ${freeAlternative}` : "";
+        throw new CostModeBlockedError(`Blocked by cost mode "minimize": ${label}${cost} spends billed AI credits.\n` +
+            `Confirm the spend with the user, then re-run with --yes (or switch modes: ` +
+            `vidfarm cost-mode hybrid).${alt}`);
+    }
+    if (json)
+        return;
+    if (!resolved.isSet) {
+        log(`[cost] No spend preference set — ${label}${cost} will bill the account. ` +
+            `Ask the user minimize / hybrid / pure-ai and save it: vidfarm cost-mode <choice>.`);
+        return;
+    }
+    log(`[cost] ${label}${cost} — billed (mode: ${resolved.mode}${yes ? ", confirmed" : ""}).`);
+}
+//# sourceMappingURL=cost-mode.js.map

package/dist/src/devcli/doctor.js

@@ -0,0 +1,192 @@
+// `vidfarm doctor` — one-shot health check of everything the devcli's local
+// loops depend on: node, the bundled ffmpeg/ffprobe, the hyperframes local
+// engines, Chrome for in-process rendering, cloud auth, provider keys, agent
+// CLIs, poisoned-env traps, port 3000, and installed agent skills.
+//
+// Exit code: 0 unless a HARD requirement (ffmpeg) is missing — everything
+// else prints as ⚠/✗ but does not fail the command, so agents can run doctor
+// unconditionally at session start.
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import net from "node:net";
+import { homedir } from "node:os";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { detectLocalAgent } from "../services/clip-curation/index.js";
+import { hasFfmpeg, resolveFfmpeg, resolveFfprobe } from "../services/clip-curation/ffmpeg.js";
+import { resolveHyperframesCli } from "./hyperframes-cli.js";
+import { resolveSkillsRoot } from "./skills.js";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const YELLOW = "\x1b[33m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+// The cloud ARNs/URLs the `serve` command blanks before booting (see
+// runServeCommand in src/cli.ts). Any of these set in a plain dev shell will
+// silently route local work to cloud infra — the classic poisoned-.env trap.
+const SERVE_BLANKED_ENV_VARS = [
+    "VIDFARM_JOB_STATE_MACHINE_ARN",
+    "VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN",
+    "VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL",
+    "VIDFARM_PRIMITIVE_MEDIA_LAMBDA_SECRET",
+    "AWS_S3_BUCKET"
+];
+const PROVIDER_KEY_ENV_VARS = ["OPENAI_API_KEY", "GEMINI_API_KEY", "OPENROUTER_API_KEY", "ELEVENLABS_API_KEY"];
+function isPortInUse(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", (error) => {
+            resolve(error.code === "EADDRINUSE");
+        });
+        server.once("listening", () => {
+            server.close(() => resolve(false));
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+// Best-effort Chrome availability for the in-process HyperFrames render:
+// explicit env overrides, the puppeteer download cache, or a system Chrome.
+function detectChromeForRender() {
+    for (const envName of ["PUPPETEER_EXECUTABLE_PATH", "CHROME_PATH", "HYPERFRAMES_CHROME_PATH"]) {
+        const value = process.env[envName]?.trim();
+        if (value && existsSync(value))
+            return { found: true, detail: `${envName}=${value}` };
+    }
+    const cacheDir = process.env.PUPPETEER_CACHE_DIR?.trim() || path.join(homedir(), ".cache", "puppeteer");
+    try {
+        const entries = readdirSync(cacheDir).filter((name) => /chrome/i.test(name));
+        if (entries.length > 0)
+            return { found: true, detail: `puppeteer cache ${cacheDir} (${entries.join(", ")})` };
+    }
+    catch {
+        // no cache dir — fall through
+    }
+    const systemCandidates = process.platform === "darwin"
+        ? ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium"]
+        : ["/usr/bin/google-chrome", "/usr/bin/chromium", "/usr/bin/chromium-browser"];
+    for (const candidate of systemCandidates) {
+        if (existsSync(candidate))
+            return { found: true, detail: candidate };
+    }
+    return { found: false, detail: `no PUPPETEER_EXECUTABLE_PATH/CHROME_PATH, no ${cacheDir}, no system Chrome` };
+}
+// Count installed skills under the SAME root the `vidfarm skills` command
+// resolves (resolveSkillsRoot: walk up from cwd to the first dir with
+// .agents/skills or .git, else cwd) — one resolution, no drift.
+function countInstalledSkills() {
+    const root = resolveSkillsRoot();
+    const skillsDir = path.join(root, ".agents", "skills");
+    if (!existsSync(skillsDir))
+        return { root: null, count: 0, names: [] };
+    try {
+        const names = readdirSync(skillsDir).filter((name) => existsSync(path.join(skillsDir, name, "SKILL.md")));
+        return { root, count: names.length, names };
+    }
+    catch {
+        return { root, count: 0, names: [] };
+    }
+}
+async function fetchWhoami(host, apiKey) {
+    try {
+        const res = await fetch(new URL("/api/v1/user/me", host), {
+            headers: { "vidfarm-api-key": apiKey, accept: "application/json" }
+        });
+        if (!res.ok)
+            return { ok: false, detail: `GET /api/v1/user/me → ${res.status} (check the key/host)` };
+        const json = await res.json().catch(() => null);
+        const email = json?.email ?? json?.user?.email ?? json?.customer?.email;
+        return { ok: true, detail: email ? `authenticated as ${email} (${host})` : `authenticated (${host})` };
+    }
+    catch (error) {
+        return { ok: false, detail: `could not reach ${host}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+export async function runDoctorCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            host: { type: "string", default: "https://vidfarm.cc" },
+            "api-key": { type: "string" },
+            json: { type: "boolean", default: false }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const checks = [];
+    const add = (name, level, detail) => checks.push({ name, level, detail });
+    // 1. Node version.
+    const nodeMajor = Number(process.versions.node.split(".")[0]);
+    add("node", nodeMajor >= 22 ? "ok" : "fail", `v${process.versions.node}${nodeMajor >= 22 ? "" : " — vidfarm-devcli needs Node >= 22"}`);
+    // 2. ffmpeg / ffprobe (HARD requirement).
+    const ffmpegPath = await resolveFfmpeg();
+    const ffprobePath = await resolveFfprobe();
+    const ffmpegOk = await hasFfmpeg();
+    add("ffmpeg", ffmpegOk ? "ok" : "fail", ffmpegOk ? ffmpegPath : "not found (bundled ffmpeg-static missing and none on PATH) — media commands cannot run");
+    add("ffprobe", existsSync(ffprobePath) || spawnSync(ffprobePath, ["-version"], { stdio: "ignore" }).status === 0 ? "ok" : "warn", ffprobePath);
+    // 3. hyperframes CLI (local engines: Kokoro tts, whisper stt, matting, capture, beats).
+    const hyperframesCli = resolveHyperframesCli();
+    add("hyperframes", hyperframesCli ? "ok" : "warn", hyperframesCli ?? "not installed — local engines (tts/transcribe/remove-background/capture/beats) will fall back to `npx -y hyperframes`");
+    // 4. Chrome for the in-process render (stills / serve local render).
+    const chrome = detectChromeForRender();
+    add("chrome", chrome.found ? "ok" : "warn", chrome.found ? chrome.detail : `${chrome.detail} — local render/stills will try to download one on first run`);
+    // 5. Vidfarm cloud auth.
+    const apiKey = parsed.values["api-key"] ?? process.env.VIDFARM_API_KEY;
+    if (apiKey) {
+        const who = await fetchWhoami(String(parsed.values.host).replace(/\/+$/, ""), apiKey);
+        add("vidfarm auth", who.ok ? "ok" : "warn", who.ok ? who.detail : `${who.detail} — serve will fall back to local browse mode`);
+    }
+    else {
+        add("vidfarm auth", "warn", "VIDFARM_API_KEY not set — serve will fall back to local browse mode; cloud catalog/bulk routes need it");
+    }
+    // 6. Provider keys in env (BYOK local-first engines).
+    const presentKeys = PROVIDER_KEY_ENV_VARS.filter((name) => process.env[name]?.trim());
+    add("provider keys", presentKeys.length > 0 ? "ok" : "warn", presentKeys.length > 0
+        ? presentKeys.join(", ")
+        : "none of OPENAI/GEMINI/OPENROUTER/ELEVENLABS_API_KEY set — BYOK speech/clip tagging unavailable (keyless local engines still work)");
+    // 7. Local agent CLI (claude / codex) for clips scan etc.
+    const agent = detectLocalAgent();
+    add("agent CLI", agent ? "ok" : "warn", agent ? `${agent.kind} (${agent.bin})` : "no claude/codex CLI on PATH — `clips scan` falls back to provider keys");
+    // 8. Poisoned-env traps.
+    if (process.env.AWS_PROFILE?.trim()) {
+        add("env AWS_PROFILE", "warn", `AWS_PROFILE=${process.env.AWS_PROFILE} is set — it can hijack AWS SDK auth; run \`env -u AWS_PROFILE\` or unset it`);
+    }
+    else {
+        add("env AWS_PROFILE", "ok", "not set");
+    }
+    const poisoned = SERVE_BLANKED_ENV_VARS.filter((name) => process.env[name]?.trim());
+    add("env cloud ARNs/URLs", poisoned.length > 0 ? "warn" : "ok", poisoned.length > 0
+        ? `${poisoned.join(", ")} set — outside \`vidfarm serve\` these route local work to cloud infra (serve blanks them itself)`
+        : "no stray cloud ARNs/URLs in env");
+    // 9. Port 3000 (default serve port).
+    const portBusy = await isPortInUse(3000);
+    add("port 3000", portBusy ? "warn" : "ok", portBusy ? "in use — a serve box may already be running (or pass --port to serve)" : "free");
+    // 10. HeyGen credential file — vidfarm never uses it.
+    const heygenCredentials = path.join(homedir(), ".heygen", "credentials");
+    if (existsSync(heygenCredentials) || existsSync(path.join(homedir(), ".heygen", "credentials.json"))) {
+        add("heygen credentials", "warn", "found a HeyGen credential file — vidfarm never uses it; local engines and vidfarm BYOK keys are the only auth");
+    }
+    else {
+        add("heygen credentials", "ok", "none (vidfarm never uses HeyGen accounts)");
+    }
+    // 11. Installed agent skills.
+    const skills = countInstalledSkills();
+    add("agent skills", skills.count > 0 ? "ok" : "warn", skills.count > 0
+        ? `${skills.count} installed under ${skills.root}/.agents/skills`
+        : "no .agents/skills found walking up from cwd — run `vidfarm skills add <names…>`");
+    const ffmpegMissing = checks.some((check) => check.name === "ffmpeg" && check.level === "fail");
+    if (json) {
+        process.stdout.write(`${JSON.stringify({ ok: !ffmpegMissing, checks }, null, 2)}\n`);
+    }
+    else {
+        for (const check of checks) {
+            const mark = check.level === "ok" ? `${GREEN}✓${RESET}` : check.level === "warn" ? `${YELLOW}⚠${RESET}` : `${RED}✗${RESET}`;
+            console.log(`${mark} ${check.name.padEnd(20)} ${DIM}${check.detail}${RESET}`);
+        }
+        if (ffmpegMissing) {
+            console.log(`\n${RED}ffmpeg is a hard requirement — install it (or \`npm i ffmpeg-static\`) and re-run.${RESET}`);
+        }
+    }
+    if (ffmpegMissing)
+        process.exitCode = 1;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/src/devcli/hyperframes-cli.js

@@ -0,0 +1,118 @@
+// Guarded bridge to the bundled `hyperframes` npm CLI — the devcli's local
+// media engine. Only the LOCAL, account-free commands are reachable through
+// this module (tts / transcribe / remove-background / capture / beats / …);
+// the HeyGen account + telemetry surface (`auth`, `cloud`, `publish`, `play`,
+// `feedback`, `telemetry`) is rejected outright so no vidfarm command can ever
+// touch a HeyGen account, even by accident.
+//
+// Every spawn additionally hardens the child env:
+//   - HYPERFRAMES_NO_TELEMETRY=1  → no anonymous usage pings
+//   - HYPERFRAMES_SKIP_SKILLS=1   → no skill-install prompts in pipelines
+//   - HEYGEN_CONFIG_DIR=<fresh empty temp dir> → a stray ~/.heygen credential
+//     can NEVER be picked up (some hyperframes commands silently flip their
+//     audio-provider preference when a HeyGen credential is present).
+import { spawn } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const BLOCKED_SUBCOMMANDS = new Set(["auth", "cloud", "publish", "play", "feedback", "telemetry"]);
+/**
+ * Locate the bundled hyperframes CLI entrypoint by walking node_modules from
+ * this module's directory first (the published devcli package carries the
+ * dependency), then from process.cwd() (running inside a repo that installed
+ * it). Returns null when the package is not installed anywhere reachable.
+ */
+export function resolveHyperframesCli() {
+    const anchors = [path.dirname(fileURLToPath(import.meta.url)), process.cwd()];
+    for (const anchor of anchors) {
+        try {
+            const localRequire = createRequire(path.join(anchor, "__resolve__.js"));
+            return localRequire.resolve("hyperframes/dist/cli.js");
+        }
+        catch {
+            // keep walking — try the next anchor
+        }
+    }
+    return null;
+}
+/**
+ * Run `hyperframes <subcommand> ...args` with the hardened env described in
+ * the module header. Falls back to `npx -y hyperframes` when the package
+ * cannot be resolved locally. Throws on blocked subcommands; resolves with
+ * the exit code + captured output (empty strings in inherit mode).
+ */
+export async function runHyperframesCommand(subcommand, args, opts = {}) {
+    if (BLOCKED_SUBCOMMANDS.has(subcommand)) {
+        throw new Error(`hyperframes ${subcommand} is blocked: vidfarm never uses HeyGen accounts or telemetry. ` +
+            "Local engines and vidfarm BYOK keys are the only auth.");
+    }
+    const cli = resolveHyperframesCli();
+    // Fresh empty config dir per invocation — guarantees no ~/.heygen credential
+    // (or any other persisted account state) leaks into the child process.
+    const emptyConfigDir = mkdtempSync(path.join(os.tmpdir(), "vidfarm-hf-noauth-"));
+    const env = {
+        ...process.env,
+        HYPERFRAMES_NO_TELEMETRY: "1",
+        HYPERFRAMES_SKIP_SKILLS: "1",
+        HEYGEN_CONFIG_DIR: emptyConfigDir,
+        ...opts.env
+    };
+    const [bin, baseArgs] = cli
+        ? [process.execPath, [cli]]
+        : ["npx", ["-y", "hyperframes"]];
+    const capture = opts.stdio === "capture";
+    return new Promise((resolvePromise, rejectPromise) => {
+        const child = spawn(bin, [...baseArgs, subcommand, ...args], {
+            cwd: opts.cwd,
+            env,
+            stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit"
+        });
+        let stdout = "";
+        let stderr = "";
+        if (capture) {
+            child.stdout?.on("data", (chunk) => (stdout += chunk.toString()));
+            child.stderr?.on("data", (chunk) => (stderr += chunk.toString()));
+        }
+        child.on("error", (error) => {
+            rejectPromise(error.code === "ENOENT"
+                ? new Error("Could not launch the hyperframes CLI (not installed and npx unavailable). Run `npm i hyperframes` in your project.")
+                : error);
+        });
+        child.on("close", (code) => {
+            resolvePromise({ code: code ?? 1, stdout, stderr });
+        });
+    });
+}
+/** Parse the last JSON object printed by a captured hyperframes --json run
+ * (tolerates both compact single-line and pretty multi-line output, with log
+ * lines interleaved before it). */
+export function parseHyperframesJson(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    // Whole output is the JSON document (the common --json case).
+    try {
+        const whole = JSON.parse(trimmed);
+        if (whole && typeof whole === "object")
+            return whole;
+    }
+    catch { /* fall through */ }
+    // Log lines first, JSON at the end: parse from each line that opens an
+    // object through the end of the output, scanning bottom-up.
+    const lines = trimmed.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        if (!lines[i].trimStart().startsWith("{"))
+            continue;
+        const candidate = lines.slice(i).join("\n").trim();
+        try {
+            const parsed = JSON.parse(candidate);
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch { /* keep scanning upward */ }
+    }
+    return null;
+}
+//# sourceMappingURL=hyperframes-cli.js.map

package/dist/src/devcli/local-backend.js

@@ -0,0 +1,167 @@
+// In-process LOCAL backend for the devcli — the "local" half of local-first,
+// dual local/cloud operation.
+//
+// The whole Vidfarm backend already runs over disk-backed drivers when
+// RECORDS_DRIVER=local + STORAGE_DRIVER=local (the same drivers `vidfarm serve`
+// uses). Rather than re-implement the directory / files / raws logic a second
+// time, we boot the real Hono `app` in-process and drive it with `app.request()`
+// — Hono's fetch interface runs the full middleware + handler stack WITHOUT
+// binding a socket. So `vidfarm directory ls --local` and `vidfarm serve` share
+// one on-disk backend, and a `clips scan --local` is instantly browsable in a
+// running serve UI.
+//
+// IMPORTANT (env-before-import): `config.ts` binds the driver + data dir from
+// env at module load. We MUST set the local env BEFORE the first `import` of
+// `../app.js` / any service. `cli.ts`'s static import graph deliberately does
+// not reach `config.js`, so setting env here (then dynamic-importing) flips the
+// drivers correctly — exactly the discipline `runServeCommand` follows.
+import path from "node:path";
+import { homedir } from "node:os";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * Thrown when a local / `serve` command is invoked in the PUBLISHED CLI, which
+ * ships as a cloud client only — the in-process backend (`app.js` et al.) is
+ * deliberately excluded from the npm tarball so the server is never open-sourced.
+ * A full source checkout (where `app.js` sits next to the CLI on disk) still runs
+ * local mode; the published package degrades to this friendly error instead.
+ */
+export class LocalModeUnavailableError extends Error {
+    constructor() {
+        super("Local / serve mode isn't available in the published Vidfarm CLI — it would require the full backend. " +
+            "Use cloud mode (the default): drop --local/--both, or pass --cloud. " +
+            "(Local mode is available when running the CLI from a full source checkout.)");
+        this.name = "LocalModeUnavailableError";
+    }
+}
+/** True only when the in-process backend (`app.js`) is present next to the CLI
+ *  on disk — i.e. a full source/dist checkout, never the published npm package. */
+export function localBackendAvailable() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url)); // dist/src/devcli
+        return existsSync(path.join(here, "..", "app.js"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Wrap a dynamic import of a backend module so an absent file (published CLI)
+ *  surfaces as a clean LocalModeUnavailableError, not a raw ERR_MODULE_NOT_FOUND. */
+export async function importBackendModule(loader) {
+    try {
+        return await loader();
+    }
+    catch (error) {
+        if (error && typeof error === "object" && error.code === "ERR_MODULE_NOT_FOUND") {
+            throw new LocalModeUnavailableError();
+        }
+        throw error;
+    }
+}
+/** The durable per-user local home. Everything the local backend persists lives
+ *  under here: records + storage at `<home>/data`, legacy clips at
+ *  `<home>/clips.db`, provider config at `<home>/config.json`. */
+export function resolveLocalHome(overrideDir) {
+    if (overrideDir)
+        return path.resolve(overrideDir);
+    if (process.env.VIDFARM_HOME)
+        return path.resolve(process.env.VIDFARM_HOME);
+    return path.join(homedir(), ".vidfarm");
+}
+/** The data dir (records + storage) for the local backend. */
+export function resolveLocalDataDir(overrideDir) {
+    return path.join(resolveLocalHome(overrideDir), "data");
+}
+let cached = null;
+/**
+ * Boot (once) the in-process local backend and return a handle. Idempotent:
+ * repeated calls return the same booted app. Safe to call from any local
+ * command; cloud-only commands never call this, so the cloud path is untouched.
+ */
+export async function withLocalBackend(opts = {}) {
+    if (cached)
+        return cached;
+    const home = resolveLocalHome(opts.home);
+    const dataDir = resolveLocalDataDir(opts.home);
+    // Force the fully-local drivers, and blank every knob that would otherwise
+    // route this in-process box at the cloud (mirrors runServeCommand). These
+    // MUST be set before app.js / config.js is imported below.
+    process.env.RECORDS_DRIVER = "local";
+    process.env.STORAGE_DRIVER = "local";
+    process.env.AWS_S3_BUCKET = "";
+    process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
+    process.env.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN = "";
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_URL = "";
+    process.env.VIDFARM_PRIMITIVE_MEDIA_LAMBDA_SECRET = "";
+    // The one records-touching service that bypasses the local shim and talks to a
+    // real DynamoDB table via middleware — blank it or every /api/* 500s when a
+    // dev-shell .env carries a table name. In-process service calls don't hit
+    // middleware, but app.request() does, so this must be blank.
+    process.env.VIDFARM_RATE_LIMITS_TABLE_NAME = "";
+    process.env.VIDFARM_DATA_DIR = dataDir;
+    if (!process.env.NODE_ENV)
+        process.env.NODE_ENV = "development";
+    process.env.HYPERFRAMES_NO_TELEMETRY ||= "1";
+    process.env.HYPERFRAMES_SKIP_SKILLS ||= "1";
+    // No cloud passthrough by default for pure-local commands; sync/`--cloud` reach
+    // the cloud host directly via the devcli's own apiRequest, not this app.
+    process.env.VIDFARM_UPSTREAM_HOST ||= "";
+    process.env.VIDFARM_UPSTREAM_API_KEY ||= "";
+    // A stable local bootstrap key. The same value auto-provisions the local
+    // customer (tryBootstrapFromEnv) and authenticates app.request() calls. An
+    // empty/whitespace override falls through to the env key or the fixed default
+    // (so `--api-key ""` never breaks the local backend).
+    const apiKey = (opts.apiKey && opts.apiKey.trim()) ||
+        (process.env.VIDFARM_API_KEY && process.env.VIDFARM_API_KEY.trim()) ||
+        "vidfarm-local-dev-key";
+    process.env.VIDFARM_API_KEY = apiKey;
+    // Dynamic imports AFTER env is set, so config.ts binds the local drivers.
+    // Wrapped so the published (cloud-only) CLI — which ships without these backend
+    // modules — fails with a friendly LocalModeUnavailableError instead of a raw
+    // module-not-found stack trace.
+    const { ServerlessAuthService } = await importBackendModule(() => import("../services/serverless-auth.js"));
+    const customer = await new ServerlessAuthService().authenticate(apiKey);
+    const appMod = await importBackendModule(() => import("../app.js"));
+    const app = appMod.default;
+    cached = { app, apiKey, ownerId: customer.id, home };
+    return cached;
+}
+/**
+ * Dispatch a REST call to the in-process local app. Mirrors the cloud
+ * `apiRequest` shape so commands can branch on target without reshaping results.
+ */
+export async function localApiRequest(input) {
+    const backend = await withLocalBackend({ home: input.home, apiKey: input.auth?.apiKey });
+    // A synthetic origin — only the path + query matter to Hono routing.
+    const url = new URL(input.path, "http://vidfarm.local");
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value !== undefined && value !== null && value !== "")
+            url.searchParams.set(key, value);
+    }
+    const headers = {
+        accept: "application/json",
+        "vidfarm-api-key": input.auth?.apiKey || backend.apiKey
+    };
+    if (input.auth?.shareToken)
+        headers["vidfarm-share-token"] = input.auth.shareToken;
+    let body;
+    if (input.body !== undefined) {
+        headers["content-type"] = "application/json";
+        body = JSON.stringify(input.body);
+    }
+    const res = await backend.app.request(url.pathname + url.search, {
+        method: input.method.toUpperCase(),
+        headers,
+        body
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    return { status: res.status, ok: res.ok, json, text };
+}
+//# sourceMappingURL=local-backend.js.map