@officexapp/vidfarm-devcli 0.21.59 → 0.21.61

package/dist/src/cli.js

@@ -26,10 +26,10 @@ import { dedupeMediaLocal, localDedupeAvailable, defaultDedupeOutPath, describeL
 import { segmentAlphaComponents, encodeTransparentGif, encodeTransparentAnimatedGif, pickPlateColor, detectPlateColor, keySafeArtInstruction, connectivitySafeArtInstruction, analyzeKeyedArt, measureOpaqueShare, HOLE_WARN_PCT } from "./devcli/sticker-pack.js";
 import { smartKeyPlate, planZonedSheet, zonedSheetInstruction } from "./devcli/plate-key.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
-import { findFreePort } from "./devcli/port-utils.js";
+import { findFreePort, isPortFree } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
-import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadAngleBank, loadAwarenessLadder, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
+import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadAdFormatBank, loadAngleBank, loadAwarenessLadder, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 import { NativeModuleUnavailableError } from "./devcli/clip-store.js";
@@ -1049,11 +1049,13 @@ Account:
                             (iconscout takes BOTH values as one secret: <client_id>:<client_secret>)
 
 Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
-  ideas [topic]             "What should I post?" — the THREE IDEA BANKS    (local — offline, free, no AI)
+  ideas [topic]             "What should I post?" — the FOUR IDEA BANKS     (local — offline, free, no AI)
                             50 frames (the rise of · then vs now · …), 5
                             AWARENESS STAGES (what the viewer already knows,
-                            and what the video may ask for), and 44 PROBLEM
-                            ANGLES (which side of the problem it comes from).
+                            and what the video may ask for), 44 PROBLEM
+                            ANGLES (which side of the problem it comes from),
+                            and 40 AD FORMATS (what the finished video IS —
+                            iphone notes, tier list, warning, greenscreen).
                             An idea is one point in that grid; vary TWO axes
                             and 30 videos never read as repeats. It hands over
                             the banks — you fill them with the director's
@@ -1068,7 +1070,9 @@ Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
     --stage <name|n>          One stage (unaware · problem-aware · … · most-aware)
     --angles                  The 44 problem angles, by family
     --angle <name>            One angle family or one named angle
-    --grid                    Stage × angle × frame — one row per video
+    --formats                 The 40 ad formats — what the video LOOKS like
+    --format <name>           One format family or one named format
+    --grid                    Stage × angle × frame × format — one row per video
     --count <n>               Sample N, spread across families (default 20 with --topic)
     --json                    Machine-readable banks (+ starter lines)
   skill topics              The craft this pack knows, by SPOKEN name —       (local — offline, no account)
@@ -1229,6 +1233,14 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
     e.g. vidfarm clipper-run mode quick-interactive
          vidfarm clipper-run next
     (see: vidfarm clipper-run help)
+  dashboard                 THE CLIPPER DASHBOARD for a mission folder, on localhost
+    One page: what waits on you (with the cut PLAYING, not a path to open by hand),
+    what each agent is mid-way through, what was submitted, and the money owed.
+    Every button calls the same clipper-run verb, so the page and the terminal
+    can never disagree. Loopback only, disk only — no key, no network.
+    OFFER IT to a marketplace clipper before the first task; most want it.
+    e.g. vidfarm dashboard        ·  vidfarm dashboard --dir ./CLIPPER --port 4400
+         (vidfarm panel is the same command)
   shared <sub> <link>       USE a link someone shared with you — NO account, NO API key
     info · ls --tree · search · grab · note · mkdir · put · get
     grab is the one to reach for: it finds footage by MEANING and downloads it in one step.
@@ -1706,10 +1718,24 @@ async function main() {
         case "clipper-run":
         case "clipper-mode":
         case "run-mode": {
+            // `clipper-run panel` is the same command as `vidfarm panel` — a
+            // gigworker who lives in `clipper-run` should not have to learn a
+            // second top-level verb to find the screen.
+            if ((rest[0] ?? "").toLowerCase() === "panel" || (rest[0] ?? "").toLowerCase() === "dashboard") {
+                await runClipperPanelCommand(rest.slice(1));
+                return;
+            }
             const { runClipperRunCommand } = await import("./devcli/clipper-run.js");
             await runClipperRunCommand(rest);
             return;
         }
+        // THE CLIPPER DASHBOARD — the visual half of the clipper loop: watch the
+        // cut, answer the gate, see what is owed.
+        case "dashboard":
+        case "panel":
+        case "clipper-panel":
+            await runClipperPanelCommand(rest);
+            return;
         case "get-file":
             await runGetFileCommand(rest);
             return;
@@ -2485,6 +2511,83 @@ function printServeBanner(input) {
     console.log(line);
     console.log("");
 }
+// `vidfarm dashboard` (aka `vidfarm panel`) — the CLIPPER DASHBOARD over a
+// mission folder.
+// Backend-free and disk-only: no key, no network. It exists because the CUT
+// gate means "watch this video", and a terminal cannot play one.
+async function runClipperPanelCommand(argv) {
+    const { ClipperUserError: PanelArgError } = await import("./devcli/clipper-run.js");
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                dir: { type: "string" },
+                port: { type: "string", default: "4400" },
+                open: { type: "boolean", default: true },
+                "no-open": { type: "boolean", default: false }
+            }
+        });
+    }
+    catch (error) {
+        // Node's own parser rejects things like `--port -5` ("ambiguous") before any
+        // of our validation runs, and its message names neither the flag nor the fix.
+        throw new PanelArgError(`${error instanceof Error ? error.message.replace(/^\w+ \[[^\]]+\]: /, "") : String(error)}\n` +
+            `Usage: vidfarm panel [--dir <mission folder>] [--port <1-65535>] [--no-open]`);
+    }
+    const { resolveMissionRoot, listTaskStates, readMissionMode } = await import("./devcli/clipper-run.js");
+    const { startClipperPanel, mintPanelToken } = await import("./devcli/clipper-panel.js");
+    const { ClipperUserError } = await import("./devcli/clipper-run.js");
+    const root = resolveMissionRoot(parsed.values.dir ?? parsed.positionals[0]);
+    if (!existsSync(root)) {
+        throw new ClipperUserError(`No mission folder at ${root}.\nCreate one first: vidfarm clipper-run init${parsed.values.dir ? ` --dir ${parsed.values.dir}` : ""}`);
+    }
+    // `--dir MISSION.md` used to boot a panel that looked fine and showed nothing.
+    if (!statSync(root).isDirectory()) {
+        throw new ClipperUserError(`${root} is a file, not a mission folder. Point --dir at the folder that contains it.`);
+    }
+    const rawPort = String(parsed.values.port);
+    const requestedPort = Number(rawPort);
+    if (!Number.isInteger(requestedPort) || requestedPort < 1 || requestedPort > 65535) {
+        throw new ClipperUserError(`Invalid --port "${rawPort}" — give a whole number between 1 and 65535.`);
+    }
+    // An EXPLICIT port that is busy must fail. Silently binding the next one free
+    // meant a bookmarked tab on the old port showed a DIFFERENT mission, and
+    // approvals there went to the wrong gig. With no --port given, moving on is
+    // fine: nobody has been told a number yet.
+    // `--port=4492` is the same intent as `--port 4492`; an exact-string match
+    // meant the `=` form silently fell back to auto-advancing.
+    const portWasChosen = argv.concat(process.argv)
+        .some((a) => a === "--port" || a.startsWith("--port="));
+    const port = portWasChosen ? requestedPort : await findFreePort(requestedPort);
+    if (portWasChosen && !(await isPortFree(port))) {
+        throw new ClipperUserError(`Port ${port} is already in use — another panel or local job is on it.\n` +
+            `Pass a different --port, or run \`vidfarm doctor --kill-orphans\` to reclaim it.`);
+    }
+    const token = mintPanelToken();
+    const { url } = await startClipperPanel({ root, port, token });
+    const tasks = listTaskStates(root);
+    const waiting = tasks.filter((task) => task.gate).length;
+    const open = tasks.filter((task) => !task.gate && task.stage !== "done" && task.stage !== "discarded").length;
+    const mode = readMissionMode(root);
+    const line = `${DIM}${"─".repeat(74)}${RESET}`;
+    console.log("");
+    console.log(line);
+    console.log(`${BOLD}${GREEN}  Clipper dashboard${RESET}  ${DIM}(local files only — no key, no network)${RESET}`);
+    console.log(line);
+    console.log(`  mission     ${root}`);
+    console.log(`  run mode    ${mode.mode}${mode.isSet ? "" : `${DIM} (not set — assuming this)${RESET}`}`);
+    console.log(`  tasks       ${waiting ? `${YELLOW}${waiting} waiting on you${RESET}` : `${DIM}none waiting on you${RESET}`}${DIM} · ${open} in progress · ${tasks.length} total${RESET}`);
+    console.log("");
+    console.log(`  ${BOLD}Open:${RESET} ${url}`);
+    console.log(`  ${DIM}The token in that URL is minted per run. Loopback only; do not share the link.${RESET}`);
+    console.log(line);
+    console.log("");
+    if (parsed.values.open && !parsed.values["no-open"])
+        openInBrowser(url);
+    // The HTTP server keeps the process alive.
+}
 function openInBrowser(url) {
     const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
     const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
@@ -13003,6 +13106,8 @@ async function runIdeasCommand(argv) {
             angle: { type: "string" },
             stages: { type: "boolean", default: false },
             stage: { type: "string" },
+            formats: { type: "boolean", default: false },
+            format: { type: "string" },
             grid: { type: "boolean", default: false }
         }
     });
@@ -13011,13 +13116,14 @@ async function runIdeasCommand(argv) {
     const { frames, families } = loadIdeaBank();
     if (!frames.length)
         throw new Error("No bundled content-ideas reference found next to this devcli install. Fetch it with `vidfarm skills add vidfarm`.");
-    // The three axes of an idea live in one reference, so they live behind one
+    // Every axis of an idea lives in one reference, so they live behind one
     // command. A director who only ever sees the frames posts 30 videos at one
     // awareness stage from one angle, which is the exact failure this expansion
-    // exists to prevent — so the stage and angle banks are flags here, not a
-    // separate command nobody discovers.
+    // exists to prevent — so the stage, angle and format banks are flags here,
+    // not a separate command nobody discovers.
     const ladder = loadAwarenessLadder();
     const angleBank = loadAngleBank();
+    const formatBank = loadAdFormatBank();
     if (parsed.values.stages || parsed.values.stage) {
         const wanted = String(parsed.values.stage ?? "").trim().toLowerCase();
         const picked = wanted
@@ -13076,6 +13182,51 @@ async function runIdeasCommand(argv) {
         console.log(`${DIM}Pair angles with frames and stages: vidfarm ideas --grid --topic "<offer>"${RESET}`);
         return;
     }
+    // The format is the LAST field of an idea and the cheapest one to change:
+    // the subject, the angle and the script all survive a format swap, so one
+    // idea that worked becomes four posts that do not read as reposts. Printed
+    // here rather than left in the doc because "shoot another talking head" is
+    // what a director defaults to when nobody hands them the alternatives.
+    if (parsed.values.formats || parsed.values.format) {
+        if (!formatBank.formats.length) {
+            throw new Error("The bundled content-ideas reference has no ad-format bank. Update it with `vidfarm skills add vidfarm`.");
+        }
+        const wanted = String(parsed.values.format ?? "").trim().toLowerCase();
+        const picked = wanted
+            ? formatBank.formats.filter((entry) => entry.family.toLowerCase().includes(wanted) || entry.frame.toLowerCase().includes(wanted))
+            : formatBank.formats;
+        if (wanted && !picked.length) {
+            throw new Error(`No format matches "${wanted}". Format families: ${formatBank.families.join(", ")} (see \`vidfarm ideas --formats\`).`);
+        }
+        if (json) {
+            return printJson({
+                ok: true,
+                offline: true,
+                topic: topic || null,
+                total_formats: formatBank.formats.length,
+                families: formatBank.families,
+                formats: picked,
+                method: "references/content-ideas.md"
+            });
+        }
+        console.log(`${BOLD}Ad formats${RESET} ${DIM}(${picked.length} of ${formatBank.formats.length} · what the finished video IS)${RESET}`);
+        if (topic)
+            console.log(`${DIM}Topic: ${RESET}${topic}`);
+        console.log("");
+        let formatGroup = "";
+        for (const entry of picked) {
+            if (entry.family !== formatGroup) {
+                formatGroup = entry.family;
+                console.log(`  ${BOLD}${formatGroup}${RESET}`);
+            }
+            console.log(`    ${GREEN}${entry.frame}${RESET}${entry.note ? ` ${DIM}— ${entry.note}${RESET}` : ""}`);
+        }
+        console.log("");
+        console.log(`${DIM}The format is the LAST field, not the first. "Let's do a tier list" is a shoot with no idea in it.${RESET}`);
+        console.log(`${YELLOW}Formats that imitate a record${RESET}${DIM} — reviews, an inbox, a search, a stock count — must not fabricate it.${RESET}`);
+        console.log(`${DIM}Use the real screenshot, or keep every claim inside a staged one true: vidfarm skill show ad-formats${RESET}`);
+        return;
+    }
     if (parsed.values.grid) {
         // The grid is the honest answer to "give me 30 videos": vary TWO axes.
         // Walking frames, angles and stages at different strides keeps every row a
@@ -13119,24 +13270,47 @@ async function runIdeasCommand(argv) {
                     frame = usableFrames[(i + round + bump + 1) % usableFrames.length];
             }
             gridSeen.add(`${stage.index}|${frame.frame}|${angle.frame}`);
+            // The format walks the bank on its own stride, so a balanced month is
+            // also a varied SHOOT list instead of 30 rows that all get filmed the
+            // same way. It is advisory: unlike the frame and the angle, the stage
+            // does not name its formats, so a director may swap it freely.
+            //
+            // The one pairing that is actually WRONG: a two-column format (us vs
+            // them, myth vs fact) under a frame that is not itself a contrast gives
+            // the video two comparisons, which is the reference's "do not stack two
+            // frames" defect. Walk past those rather than print a row the doc bans.
+            const twoColumn = (entry) => /two-column/i.test(entry?.family ?? "");
+            const frameIsContrast = /contrast/i.test(frame.family);
+            let format = null;
+            for (let step = 0; step < (formatBank.formats.length || 1); step += 1) {
+                const candidate = formatBank.formats[(i * 7 + round + step) % (formatBank.formats.length || 1)];
+                if (!candidate)
+                    break;
+                if (twoColumn(candidate) && !frameIsContrast)
+                    continue;
+                format = candidate;
+                break;
+            }
             return {
                 stage: `${stage.index} · ${stage.stage}`,
                 angle: angle.frame,
                 angle_family: angle.family,
                 frame: frame.frame,
                 frame_family: frame.family,
+                format: format?.frame ?? null,
+                format_family: format?.family ?? null,
                 starter: topic ? joinIdeaFrame(frame.frame, topic) : null
             };
         });
         if (json)
             return printJson({ ok: true, offline: true, topic: topic || null, rows: grid, method: "references/content-ideas.md" });
-        console.log(`${BOLD}Idea grid${RESET} ${DIM}(${total} combinations · stage × angle × frame · offline, free, no AI call)${RESET}`);
+        console.log(`${BOLD}Idea grid${RESET} ${DIM}(${total} combinations · stage × angle × frame × format · offline, free, no AI call)${RESET}`);
         if (topic)
             console.log(`${DIM}Topic: ${RESET}${topic}`);
         console.log("");
         for (const row of grid) {
             console.log(`  ${DIM}${row.stage.padEnd(18)}${RESET}${GREEN}${row.angle}${RESET}`);
-            console.log(`    ${row.starter ?? row.frame}`);
+            console.log(`    ${row.starter ?? row.frame}${row.format ? ` ${DIM}· as: ${row.format}${RESET}` : ""}`);
         }
         console.log("");
         console.log(`${DIM}Each row is a DIFFERENT video, not a rewrite — the stage and the angle both moved.${RESET}`);
@@ -13217,11 +13391,12 @@ async function runIdeasCommand(argv) {
     else {
         console.log(`${DIM}Pour ONE topic into a frame to get a video: 'the rise of' + your niche. Add --topic "<offer>" to see it.${RESET}`);
     }
-    console.log(`${DIM}A frame is only ONE axis. The other two are here too, and a set that freezes them repeats:${RESET}`);
+    console.log(`${DIM}A frame is only ONE axis. The others are here too, and a set that freezes them repeats:${RESET}`);
     console.log(`${DIM}  vidfarm ideas --stages    ${RESET}${ladder.length} awareness stages ${DIM}— what the viewer knows, and what you may ask for${RESET}`);
     console.log(`${DIM}  vidfarm ideas --angles    ${RESET}${angleBank.angles.length} problem angles ${DIM}— which side of the problem the video comes from${RESET}`);
-    console.log(`${DIM}  vidfarm ideas --grid --topic "<offer>"${RESET} ${DIM}— stage × angle × frame, one row per video${RESET}`);
-    console.log(`${DIM}Method + frame→format notes: vidfarm skill show content-ideas   ·   families: vidfarm ideas --families${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --formats   ${RESET}${formatBank.formats.length} ad formats ${DIM}— what the finished video IS (iphone notes, tier list, warning)${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --grid --topic "<offer>"${RESET} ${DIM}— stage × angle × frame × format, one row per video${RESET}`);
+    console.log(`${DIM}Method + build notes: vidfarm skill show content-ideas   ·   families: vidfarm ideas --families${RESET}`);
     console.log(`${DIM}Never ship a frame as a hook — the four charges still apply: vidfarm skill show hooks${RESET}`);
     console.log(`${DIM}Producing the whole set is a batch: vidfarm skill show bulk (one frame per video).${RESET}`);
     // The natural upsell, in the right order: ideas are the easy win, and the
@@ -13410,7 +13585,11 @@ void main().catch(async (error) => {
         || error instanceof NativeModuleUnavailableError
         // marketplace-gigs is imported lazily, so match its "no key yet" error by
         // name rather than pulling the module into the startup path just for this.
-        || (error instanceof Error && error.name === "GigsAuthMissingError")) {
+        || (error instanceof Error && error.name === "GigsAuthMissingError")
+        // clipper-run / panel conditions: a wrong task id, an id already taken, a
+        // gate that has to be answered first. All of these are the CLI talking to a
+        // human, and a stack trace reads as "vidfarm is broken".
+        || (error instanceof Error && error.name === "ClipperUserError")) {
         console.error(error.message);
         process.exit(1);
     }