@officexapp/vidfarm-devcli 0.21.27 → 0.21.29

package/dist/src/devcli/handoff.js

@@ -0,0 +1,162 @@
+// Interactive-mode HAND-OFF briefs — the copy-paste packets an agent gives the
+// human when the pair (cost mode × interaction mode) says "a human step here
+// beats spending, and beats going without".
+//
+// Two hand-offs cover almost every real case:
+//
+//   1. IMAGES (`buildImageHandoff`) — the agent writes the prompt, the user runs
+//      it in a FREE frontier web generator (meta.ai / ChatGPT / Gemini / a
+//      Hugging Face Space) and drops the file back. Defaults to a STICKER PACK:
+//      one prompt → one greenscreen sheet holding every graphic → `vidfarm
+//      sticker-pack` splits it into many transparent stickers locally. One round
+//      trip for a whole cast is both the cheapest thing for the user's time and
+//      the most token-efficient thing for the agent.
+//
+//   2. RAW CLIPS (`buildRawsHandoff`) — the agent hands over search keywords and
+//      where to search, the user downloads a few clips with a free online
+//      downloader and points the agent at the folder. This is the LAST rung of
+//      the sourcing ladder: an agent should first try its own browser control,
+//      then vidfarm's cloud scan, and only ask the human when neither is
+//      available (fully-local, keyless devcli) or when human taste matters.
+//
+// Both builders return plain text meant to be shown verbatim to the user, plus a
+// structured form for `--json` so an agent can render it its own way. No network,
+// no backend imports — this module is pure string assembly.
+import { pickPlateColor } from "./sticker-pack.js";
+const DEFAULT_STYLE = "simple flat vector illustration, minimal detail, 2-3 flat colors, no shadows, no text";
+/** Pick a sensible grid for N items (roughly square, wider than tall). */
+function gridFor(count) {
+    if (count <= 1)
+        return "1x1";
+    const cols = Math.ceil(Math.sqrt(count));
+    const rows = Math.ceil(count / cols);
+    return `${cols}x${rows}`;
+}
+/**
+ * Build the free-image-generation hand-off. Sticker-pack shaped by default: ONE
+ * image containing every item on a flat chroma plate, generously spaced, which
+ * `vidfarm sticker-pack` then splits into individually-trimmed transparent
+ * stickers. The spacing/no-touching instruction is load-bearing — items that
+ * touch on the sheet segment as a single sticker.
+ */
+export function buildImageHandoff(input) {
+    // Plate choice matters MORE here than anywhere else: the user is about to
+    // spend their own effort generating this sheet, and a green plate under green
+    // art means the stickers come back with holes. Pick the plate off the subject
+    // unless the caller pinned one.
+    const picked = pickPlateColor([input.theme, input.items.join(" "), input.style ?? ""].join(" "));
+    const keyColor = (input.keyColor ?? picked.keyColor).toUpperCase();
+    const keyColorNote = input.keyColor
+        ? null
+        : picked.moved
+            ? `Plate moved off green to ${picked.preset} (${picked.keyColor}) — ${picked.reason}. A green plate would key holes through green artwork.`
+            : picked.reason;
+    const style = input.style?.trim() || DEFAULT_STYLE;
+    const items = input.items.map((s) => s.trim()).filter(Boolean);
+    const pack = input.pack ?? items.length > 1;
+    const outDir = input.outDir ?? "./stickers";
+    const grid = input.grid ?? gridFor(items.length || 6);
+    const prompt = pack
+        ? [
+            `A sticker sheet of ${items.length || "several"} separate objects — ${style} — on a solid pure ${keyColor} background`,
+            `(flat, evenly lit, no gradient, no shadow, no text, no labels, no frames or dividing lines).`,
+            `Theme: ${input.theme}.`,
+            items.length
+                ? `Arranged in a ${grid} grid with generous even spacing: ${items.map((it, i) => `(${i + 1}) ${it}`).join(", ")}.`
+                : `Arranged in a ${grid} grid with generous even spacing.`,
+            `CRITICAL: every object must be fully separated from the others by a clear margin of plain ${keyColor} background —`,
+            `nothing touching, overlapping or connected, and nothing touching the image edge.`,
+            `One consistent art style, line weight and palette across all objects. Front-facing, centered in its own cell.`,
+            `Square image, high resolution.`
+        ].join(" ")
+        : [
+            `${input.theme} — ${style} — isolated on a solid pure ${keyColor} background`,
+            `(flat, evenly lit, no gradient, no shadow cast on the background, no text).`,
+            `Center the subject with generous empty margin on all sides, crisp clean edges, single subject.`,
+            `Square image, high resolution.`
+        ].join(" ");
+    const steps = pack
+        ? [
+            "Open a FREE image generator you're already signed into (list below).",
+            "Paste the prompt below and generate. If any two objects come out touching, re-generate asking for wider spacing — touching objects get cut out as one sticker.",
+            "Download the image (PNG preferred) and tell me the file path — or drop it in this project folder.",
+            `I'll split it into individual transparent stickers locally for $0: \`vidfarm sticker-pack <sheet> --out-dir ${outDir}\`.`
+        ]
+        : [
+            "Open a FREE image generator you're already signed into (list below).",
+            "Paste the prompt below and generate.",
+            "Download the image (PNG preferred) and tell me the file path.",
+            "I'll key the background out and trim it to a snug transparent sticker locally for $0: `vidfarm cutout <file>`."
+        ];
+    const keyFlag = keyColor === "#00FF00" ? "" : ` --key-color "${keyColor}"`;
+    const followUp = pack
+        ? `vidfarm sticker-pack <downloaded-sheet.png>${items.length ? ` --items "${items.join(",")}"` : ""}${keyFlag} --out-dir ${outDir}`
+        : `vidfarm cutout <downloaded.png>${keyFlag}`;
+    return {
+        prompt,
+        steps,
+        followUp,
+        keyColor,
+        keyColorNote,
+        tools: [
+            "https://meta.ai (free, generous)",
+            "ChatGPT free tier (image generation included)",
+            "Google Gemini free tier",
+            "a free image Space on https://huggingface.co/spaces (search \"flux\" or \"sdxl\")"
+        ]
+    };
+}
+/**
+ * Build the manual raw-clip sourcing hand-off. Deliberately does NOT name one
+ * downloader site: those rot, get blocked, and vary by region — so the brief
+ * hands over a SEARCH for a downloader instead, which stays correct forever.
+ */
+export function buildRawsHandoff(input) {
+    const keywords = input.keywords.map((k) => k.trim()).filter(Boolean);
+    if (!keywords.length)
+        throw new Error("A raws hand-off needs at least one search keyword.");
+    const platforms = (input.platforms?.length ? input.platforms : ["tiktok", "youtube"]).map((p) => p.trim().toLowerCase());
+    const count = input.count ?? Math.max(3, keywords.length * 2);
+    const outDir = input.outDir ?? "./downloads";
+    const searchLines = keywords.map((k) => `  • "${k}"`).join("\n");
+    const prompt = [
+        `Search these keywords on ${platforms.join(" / ")} and download ${count} clips you like:`,
+        searchLines,
+        "",
+        `To download: search Google for a downloader — https://google.com/search?q=${encodeURIComponent(`${platforms[0]} video downloader`)} — and use whichever one works today.`
+    ].join("\n");
+    return {
+        prompt,
+        steps: [
+            `Search ${platforms.join(" and ")} for the keywords below.`,
+            input.purpose
+                ? `Pick ${count} clips that fit: ${input.purpose}. Favor clean, well-lit footage with no burned-in captions or watermarks over the subject.`
+                : `Pick ${count} clips with clean, well-lit footage and no burned-in captions or watermarks over the subject.`,
+            `Download them with any free online downloader (google "${platforms[0]} video downloader" — the working one changes often) into ${outDir}.`,
+            `Tell me the folder and I'll import each one into your raws library: \`vidfarm clipper ${outDir}/<file>.mp4\` (whole clip), or \`vidfarm raws scan ${outDir}/<file>.mp4\` to mine short clips out of a long one.`
+        ],
+        followUp: `vidfarm clipper ${outDir}/<file>.mp4   # per download; or: vidfarm raws scan ${outDir}/<file>.mp4`,
+        tools: [
+            `https://google.com/search?q=${encodeURIComponent(`${platforms[0]} video downloader`)}`,
+            ...platforms.map((p) => `https://google.com/search?q=${encodeURIComponent(`${p} ${keywords[0]}`)}`)
+        ]
+    };
+}
+/** Render a brief as the block of text an agent shows the user verbatim. */
+export function formatHandoff(title, brief, opts = {}) {
+    const lines = [];
+    lines.push(title);
+    lines.push("");
+    brief.steps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
+    lines.push("");
+    lines.push(`${opts.promptLabel ?? "─── copy from here ───"}`);
+    lines.push(brief.prompt);
+    lines.push("──────────────────────");
+    lines.push("");
+    lines.push("Free tools:");
+    brief.tools.forEach((t) => lines.push(`  • ${t}`));
+    lines.push("");
+    lines.push(`When the file(s) come back: ${brief.followUp}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=handoff.js.map

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

@@ -0,0 +1,154 @@
+// Interaction mode — is the human IN THE LOOP, or is the agent running solo?
+//
+// This is a SECOND, INDEPENDENT axis from cost mode (cost-mode.ts). Cost mode
+// answers "how much money may I spend?"; interaction mode answers "how much of
+// the user's own time and hands may I use?". Every cost mode can run either
+// way — interactive minimize, autonomous rich-ai, interactive pure-videogen —
+// and the pair is what actually determines the plan.
+//
+//   - interactive : the user is willing to do some manual work in exchange for
+//                   better output. The agent hands them copy-paste briefs at
+//                   fixed checkpoints — an image prompt to run in a free web
+//                   generator, a keyword list to source raw clips with — and
+//                   waits for the files to come back. Quality goes UP, because
+//                   the frontier web models (free tiers) beat what an API-key
+//                   budget usually buys, and a human eye picks better clips than
+//                   any keyword scan. In `minimize` this is the difference
+//                   between "no custom art at all" and "a full sticker pack for
+//                   $0", so ALWAYS offer it there.
+//   - autonomous  : the agent finishes end-to-end with zero user steps. It
+//                   spends (within cost mode) or does without. Faster and
+//                   hands-off; typically a quality floor below interactive.
+//
+// Like cost mode, this is a durable preference the human picks ONCE (`vidfarm
+// mode <interactive|autonomous>`) and every relevant command respects. Unset
+// means "nobody has asked yet" — the agent should ask before it either spends
+// money or silently downgrades quality.
+//
+// Backend-free (Node built-ins only) so it ships in the public cloud-only CLI.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { resolveDevcliHome } from "./auth-store.js";
+export const INTERACTION_MODES = ["interactive", "autonomous"];
+/** What we assume when nothing is set. Autonomous is the safe assumption for a
+ *  running pipeline (never block on a human who isn't there), but `isSet:false`
+ *  is the signal for an agent to ASK — interactive usually wins on quality. */
+export const DEFAULT_INTERACTION_MODE = "autonomous";
+function interactionModeFilePath(home) {
+    return path.join(resolveDevcliHome(home), "interaction-mode.json");
+}
+/** Normalize loose spellings ("manual", "hands-on", "auto", "solo"). */
+export function normalizeInteractionMode(raw) {
+    const v = (raw ?? "").trim().toLowerCase().replace(/[\s_]+/g, "-");
+    if (!v)
+        return null;
+    if (["interactive", "manual", "hands-on", "handson", "collab", "collaborative", "human", "human-in-the-loop", "hitl", "assisted", "guided", "with-me"].includes(v)) {
+        return "interactive";
+    }
+    if (["autonomous", "auto", "automatic", "solo", "hands-off", "handsoff", "unattended", "headless", "agentic", "full-auto"].includes(v)) {
+        return "autonomous";
+    }
+    return null;
+}
+export function readStoredInteractionMode(home) {
+    try {
+        const parsed = JSON.parse(readFileSync(interactionModeFilePath(home), "utf8"));
+        const mode = normalizeInteractionMode(parsed?.mode);
+        if (mode)
+            return { mode, note: parsed.note ?? null, savedAt: String(parsed.savedAt ?? "") };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Persist the interaction mode. Returns the file path written. */
+export function writeStoredInteractionMode(mode, savedAt, note, home) {
+    const dir = resolveDevcliHome(home);
+    mkdirSync(dir, { recursive: true });
+    const file = interactionModeFilePath(home);
+    const payload = { mode, note: note ?? null, savedAt };
+    writeFileSync(file, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    return file;
+}
+export function clearStoredInteractionMode(home) {
+    const file = interactionModeFilePath(home);
+    if (!existsSync(file))
+        return false;
+    rmSync(file, { force: true });
+    return true;
+}
+/**
+ * Resolve the effective interaction mode. Precedence:
+ *   --interaction-mode/--interactive/--autonomous → VIDFARM_INTERACTION_MODE →
+ *   stored preference → default (autonomous, isSet:false).
+ */
+export function resolveInteractionMode(values) {
+    if (values.interactive && !values.autonomous)
+        return { mode: "interactive", isSet: true, source: "flag" };
+    if (values.autonomous && !values.interactive)
+        return { mode: "autonomous", isSet: true, source: "flag" };
+    const flag = normalizeInteractionMode(values["interaction-mode"]);
+    if (flag)
+        return { mode: flag, isSet: true, source: "flag" };
+    const env = normalizeInteractionMode(process.env.VIDFARM_INTERACTION_MODE);
+    if (env)
+        return { mode: env, isSet: true, source: "env" };
+    const stored = readStoredInteractionMode(values.home);
+    if (stored)
+        return { mode: stored.mode, isSet: true, source: "stored" };
+    return { mode: DEFAULT_INTERACTION_MODE, isSet: false, source: "default" };
+}
+export const INTERACTION_MODE_BLURB = {
+    interactive: "Interactive — you're in the loop, and the video gets better for it. At fixed checkpoints the agent " +
+        "hands you a copy-paste brief instead of spending: an IMAGE PROMPT to run in a free web generator " +
+        "(meta.ai / ChatGPT / Gemini / a Hugging Face Space) and drop the PNG back, or a KEYWORD LIST to " +
+        "search TikTok/YouTube and download raw clips with a free online downloader. Frontier web models on " +
+        "their free tiers usually beat what an API budget buys, and a human eye picks better clips than any " +
+        "keyword scan — so quality goes UP, especially in cost mode `minimize` where the alternative is no " +
+        "custom art at all. Manual image work defaults to STICKER PACKS: one prompt → one greenscreen sheet " +
+        "→ `vidfarm sticker-pack` splits it into many transparent stickers.",
+    autonomous: "Autonomous — the agent finishes end-to-end with zero steps from you. No prompts to paste, no files " +
+        "to fetch: it sources clips itself (browser control, the free public raws catalog, cloud scan) and " +
+        "generates art within the cost mode's budget, or does without. Fastest and fully hands-off; the " +
+        "quality ceiling is usually a notch below interactive, and in `minimize` it means custom art simply " +
+        "doesn't happen."
+};
+/** One short human line summarizing the active interaction mode. */
+export function interactionModeSummaryLine(resolved) {
+    const setNote = resolved.isSet ? `set via ${resolved.source}` : "NOT set — assuming autonomous";
+    return `interaction mode: ${resolved.mode} (${setNote})`;
+}
+/** The "explain it simply" block an agent should relay to the user. */
+export function interactionModeExplainer() {
+    return [
+        "Do you want to be in the loop, or should the agent finish on its own?",
+        "  • interactive — you do a little manual work, the video comes out better. At checkpoints you get",
+        "                  a copy-paste IMAGE PROMPT for a free web generator (and drop the PNG back), or a",
+        "                  KEYWORD LIST to hand-source raw clips. Manual images default to sticker packs.",
+        "  • autonomous  — zero steps from you: the agent sources and generates everything itself, within",
+        "                  the cost mode's budget (or goes without).",
+        "This is INDEPENDENT of cost mode — any cost mode can run either way:",
+        "  minimize + interactive   → $0 videos WITH custom art and hand-picked footage (the sweet spot).",
+        "  minimize + autonomous    → $0 videos from stock + existing raws only; no custom art.",
+        "  hybrid/rich-ai + interactive → paid generation for the hard shots, your hands on the hero art.",
+        "  rich-ai/pure-videogen + autonomous → fully hands-off, budget does the work.",
+        "Quality usually goes UP in interactive mode — most of all in `minimize`, where the free frontier",
+        "web models replace an AI budget you're not spending.",
+        "Set it: vidfarm mode <interactive|autonomous>   (cost is separate: vidfarm cost-mode <…>)"
+    ].join("\n");
+}
+/**
+ * The line an agent should print (and act on) when it is about to do something
+ * that interactive mode would do better — generate art, or source raw clips.
+ * Returns null when the mode is set and the agent should just proceed.
+ */
+export function interactiveOfferLine(input) {
+    if (input.interaction.isSet)
+        return null;
+    return (`[mode] No interaction preference set — about to ${input.about} autonomously. ` +
+        "Ask the user whether they'd rather work INTERACTIVELY (they paste a prompt into a free image " +
+        "generator / hand-source clips — usually better output, and the only way to get custom art in " +
+        "`minimize`) and save it: vidfarm mode <interactive|autonomous>.");
+}
+//# sourceMappingURL=interaction-mode.js.map