@officexapp/vidfarm-devcli 0.21.26 → 0.21.27

package/dist/src/devcli/sequence.js

@@ -0,0 +1,619 @@
+// ── `vidfarm sequence` — storyboard-driven AI video pipeline ────────────────
+// A resumable, file-backed pipeline for the character-card → storyboard →
+// AI-video workflow. Every step reads and writes ONE file, `sequence.json`, so
+// the run survives a crash, a closed laptop, or a human editing the plan by
+// hand between steps. Rerunning a completed step is a no-op unless you pass
+// --force, which is what makes `sequence run` safe to invoke repeatedly.
+//
+// Steps, in order:
+//   init        write sequence.json + PLAN_TASK.md from a one-line brief
+//   plan        (optional) hand the plan to a desktop agent to direct properly
+//   characters  generate one identity sheet per character   [cheap  ~$0.05 ea]
+//   boards      generate one storyboard sheet per part      [cheap  ~$0.05 ea]
+//   prompts     compose the video prompts (free, local, deterministic)
+//   animate     generate video per part                     [EXPENSIVE ~$1+ ea]
+//   assemble    concat parts (+ optional music) into final.mp4  [free, ffmpeg]
+//
+// The ordering is the whole point, and it is the lesson from the public
+// workflows this is modelled on: the board is cheap and the video is not, so
+// you look at a board before you burn a video credit. The gates between steps
+// exist so that a human can say no at the two moments where saying no is worth
+// money — after the character card, and after the board.
+//
+// This module owns orchestration + disk state only. The prompt grammar lives in
+// services/sequence-prompts.ts (pure), and every billed call goes through the
+// `SequenceCloud` seam injected by cli.ts, so there is no second copy of the
+// REST/auth plumbing here.
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { resolveFfmpeg, resolveFfprobe } from "../services/clip-curation/ffmpeg.js";
+import { buildCharacterCardPrompt, buildPlanTaskMarkdown, buildShotPrompt, buildStarterPlan, buildStoryboardPrompt, slugify, validatePlan } from "../services/sequence-prompts.js";
+const DIM = "";
+const RESET = "";
+const BOLD = "";
+const GREEN = "";
+const YELLOW = "";
+export const SEQUENCE_PLAN_FILE = "sequence.json";
+const PLAN_TASK_FILE = "PLAN_TASK.md";
+// ── plan file I/O ───────────────────────────────────────────────────────────
+function planPath(dir) {
+    return path.join(dir, SEQUENCE_PLAN_FILE);
+}
+function readPlan(dir) {
+    const file = planPath(dir);
+    if (!existsSync(file)) {
+        throw new Error(`No ${SEQUENCE_PLAN_FILE} in ${dir}. Run \`vidfarm sequence init "<brief>" --dir ${dir}\` first.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new Error(`${file} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const check = validatePlan(parsed);
+    if (!check.ok) {
+        throw new Error(`${file} is not a usable plan:\n  - ${check.errors.join("\n  - ")}`);
+    }
+    return parsed;
+}
+/** Every mutation goes through here so the plan on disk is never half-written. */
+function writePlan(dir, plan) {
+    writeFileSync(planPath(dir), `${JSON.stringify(plan, null, 2)}\n`, "utf8");
+}
+function ensureDirs(dir) {
+    for (const sub of ["", "characters", "boards", "shots", "renders"]) {
+        mkdirSync(path.join(dir, sub), { recursive: true });
+    }
+}
+// ── human gates ─────────────────────────────────────────────────────────────
+/**
+ * Ask before spending the next tier of money. Auto-approves when --yes, in
+ * --json mode, or with no TTY — so the same command that walks a human through
+ * the workflow also runs unattended in CI or under an agent.
+ */
+async function gate(cloud, question) {
+    if (cloud.yes || cloud.json || !process.stdin.isTTY)
+        return true;
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question(`${YELLOW}${question}${RESET} [Y/n] `)).trim().toLowerCase();
+        return answer === "" || answer === "y" || answer === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+function say(cloud, message) {
+    if (!cloud.json)
+        console.log(message);
+}
+// ── step 1: init ────────────────────────────────────────────────────────────
+async function stepInit(argv, opts, cloud, extra) {
+    const brief = (extra.brief ?? argv[0] ?? "").trim();
+    if (!brief) {
+        throw new Error('sequence init needs a brief: vidfarm sequence init "a lone surfer rides the wind across grass hills"');
+    }
+    if (existsSync(planPath(opts.dir)) && !opts.force) {
+        throw new Error(`${planPath(opts.dir)} already exists. Edit it, or pass --force to start over.`);
+    }
+    ensureDirs(opts.dir);
+    const plan = buildStarterPlan({
+        brief,
+        title: extra.title,
+        parts: extra.parts,
+        panels: extra.panels,
+        aspectRatio: extra.aspectRatio,
+        durationSeconds: extra.duration,
+        style: extra.style,
+        boardStyle: extra.boardStyle,
+        laban: extra.laban,
+        characterName: extra.character,
+        characterDescription: extra.characterDescription
+    });
+    writePlan(opts.dir, plan);
+    writeFileSync(path.join(opts.dir, PLAN_TASK_FILE), buildPlanTaskMarkdown(plan, `./${SEQUENCE_PLAN_FILE}`), "utf8");
+    say(cloud, `${GREEN}Initialized${RESET} ${opts.dir}`);
+    say(cloud, `${DIM}  ${SEQUENCE_PLAN_FILE}   the plan — every prompt is generated from this file`);
+    say(cloud, `  ${PLAN_TASK_FILE}     hand this to a coding agent to direct the sequence properly${RESET}`);
+    say(cloud, "");
+    say(cloud, `${BOLD}The plan is a working skeleton, not direction.${RESET} Two ways forward:`);
+    say(cloud, `  ${DIM}•${RESET} Direct it yourself — open ${SEQUENCE_PLAN_FILE}, or point an agent at ${PLAN_TASK_FILE}`);
+    say(cloud, `  ${DIM}•${RESET} Run it as-is — ${BOLD}vidfarm sequence run --dir ${opts.dir}${RESET}`);
+    return plan;
+}
+// ── step 2: plan (agent hand-off / validation) ──────────────────────────────
+function stepPlan(opts, cloud, check) {
+    const plan = readPlan(opts.dir);
+    const panelTotal = plan.parts.reduce((sum, p) => sum + p.panels.length, 0);
+    if (check) {
+        say(cloud, `${GREEN}Plan is structurally valid.${RESET} ${plan.parts.length} part(s), ${panelTotal} panel(s), ${plan.characters.length} character(s).`);
+        if (cloud.json)
+            console.log(JSON.stringify({ ok: true, title: plan.title, parts: plan.parts.length, panels: panelTotal }, null, 2));
+        return plan;
+    }
+    const taskFile = path.join(opts.dir, PLAN_TASK_FILE);
+    writeFileSync(taskFile, buildPlanTaskMarkdown(plan, `./${SEQUENCE_PLAN_FILE}`), "utf8");
+    say(cloud, `${GREEN}Wrote${RESET} ${taskFile}`);
+    say(cloud, "");
+    say(cloud, "Hand it to a desktop coding agent in this folder:");
+    say(cloud, `  ${BOLD}claude${RESET} ${DIM}"read ${PLAN_TASK_FILE} and do it"${RESET}`);
+    say(cloud, "");
+    say(cloud, `Then: ${BOLD}vidfarm sequence plan --dir ${opts.dir} --check${RESET}`);
+    return plan;
+}
+// ── step 3: character cards ─────────────────────────────────────────────────
+async function stepCharacters(opts, cloud) {
+    let plan = readPlan(opts.dir);
+    const targets = plan.characters.filter((c) => (!opts.only || c.slug === opts.only || c.code.toLowerCase() === opts.only.toLowerCase())
+        && (opts.force || !c.card_url));
+    if (!targets.length) {
+        say(cloud, `${DIM}Character cards already generated — nothing to do (pass --force to regenerate).${RESET}`);
+        return plan;
+    }
+    cloud.guardBilled({
+        label: `${targets.length} character card image(s)`,
+        estimate: "cheap, ~$0.01–$0.05 each",
+        freeAlternative: "reuse an existing card — drop its URL into characters[].card_url in sequence.json, or point at a saved " +
+            "sprite card from /files/characters/<slug>/character_sprite_card.png"
+    });
+    for (const character of targets) {
+        say(cloud, `${DIM}Generating character card for ${character.name} (${character.code})…${RESET}`);
+        const prompt = buildCharacterCardPrompt(character, plan);
+        const result = await cloud.generateImage({
+            prompt,
+            // Cards read best tall: more room for a turnaround row plus an expression sheet.
+            aspectRatio: "2:3",
+            refs: [],
+            provider: opts.imageProvider,
+            model: opts.imageModel
+        });
+        const dest = path.join(opts.dir, "characters", `${character.slug}.png`);
+        await cloud.download(result.url, dest);
+        // Re-read: a long generate gives a human time to edit the plan underneath us.
+        plan = readPlan(opts.dir);
+        const target = plan.characters.find((c) => c.slug === character.slug);
+        if (target) {
+            target.card_url = result.url;
+            target.card_file = path.relative(opts.dir, dest);
+        }
+        writePlan(opts.dir, plan);
+        say(cloud, `${GREEN}  ${character.name}${RESET} → ${dest}`);
+    }
+    say(cloud, "");
+    say(cloud, `${BOLD}Look at the cards before continuing.${RESET} ${DIM}They are the identity authority for every shot — a wrong face here is a wrong face in every frame you pay for.${RESET}`);
+    return plan;
+}
+// ── step 4: storyboard sheets ───────────────────────────────────────────────
+function partsToRun(plan, opts, done) {
+    return plan.parts.filter((p) => (!opts.only || p.id === opts.only) && (opts.force || !done(p)));
+}
+async function stepBoards(opts, cloud) {
+    let plan = readPlan(opts.dir);
+    const targets = partsToRun(plan, opts, (p) => Boolean(p.board_url));
+    if (!targets.length) {
+        say(cloud, `${DIM}Storyboards already generated — nothing to do (pass --force to regenerate).${RESET}`);
+        return plan;
+    }
+    cloud.guardBilled({
+        label: `${targets.length} storyboard sheet image(s)`,
+        estimate: "cheap, ~$0.01–$0.05 each",
+        freeAlternative: "draw or source the board yourself and set parts[].board_url in sequence.json — the video step only needs a URL"
+    });
+    const cardRefs = plan.characters.map((c) => c.card_url).filter((u) => Boolean(u));
+    if (!cardRefs.length) {
+        say(cloud, `${YELLOW}No character cards yet${RESET} ${DIM}— boards will be generated without an identity reference, so faces will drift. Run \`vidfarm sequence characters\` first for consistency.${RESET}`);
+    }
+    for (const part of targets) {
+        say(cloud, `${DIM}Generating storyboard for ${part.id} (${part.panels.length} panels, ${part.grid.cols}x${part.grid.rows})…${RESET}`);
+        const prompt = buildStoryboardPrompt(part, plan);
+        writeFileSync(path.join(opts.dir, "boards", `${part.id}.board-prompt.txt`), `${prompt}\n`, "utf8");
+        const result = await cloud.generateImage({
+            prompt,
+            aspectRatio: plan.aspect_ratio,
+            refs: cardRefs.slice(0, 4),
+            provider: opts.imageProvider,
+            model: opts.imageModel
+        });
+        const dest = path.join(opts.dir, "boards", `${part.id}.png`);
+        await cloud.download(result.url, dest);
+        plan = readPlan(opts.dir);
+        const target = plan.parts.find((p) => p.id === part.id);
+        if (target) {
+            target.board_url = result.url;
+            target.board_file = path.relative(opts.dir, dest);
+        }
+        writePlan(opts.dir, plan);
+        say(cloud, `${GREEN}  ${part.id}${RESET} → ${dest}`);
+    }
+    say(cloud, "");
+    say(cloud, `${BOLD}This is the cheap checkpoint.${RESET} ${DIM}Read the board like an edit: is the order right, does one panel own the peak, does the geography hold? Fixing it here costs cents; fixing it after \`animate\` costs dollars.${RESET}`);
+    return plan;
+}
+// ── step 5: shot prompts (free, deterministic) ──────────────────────────────
+function shotRefsFor(part, plan) {
+    const previous = part.extend_from ? plan.parts.find((p) => p.id === part.extend_from) : undefined;
+    return {
+        characterCards: plan.characters.map((c) => ({ code: c.code, name: c.name, url: c.card_url })),
+        boardUrl: part.board_url,
+        extendFromUrl: previous?.video_url
+    };
+}
+function stepPrompts(opts, cloud, printSpec) {
+    const plan = readPlan(opts.dir);
+    // `--print <kind>:<id>` renders one prompt to stdout without touching disk —
+    // the tight loop for iterating on the plan before spending anything.
+    if (printSpec) {
+        const [kind, id] = printSpec.includes(":") ? printSpec.split(":", 2) : ["shot", printSpec];
+        if (kind === "card") {
+            const character = plan.characters.find((c) => c.slug === id || c.code.toLowerCase() === id.toLowerCase());
+            if (!character)
+                throw new Error(`No character "${id}". Have: ${plan.characters.map((c) => c.slug).join(", ")}`);
+            process.stdout.write(`${buildCharacterCardPrompt(character, plan)}\n`);
+            return plan;
+        }
+        const part = plan.parts.find((p) => p.id === id);
+        if (!part)
+            throw new Error(`No part "${id}". Have: ${plan.parts.map((p) => p.id).join(", ")}`);
+        process.stdout.write(`${kind === "board" ? buildStoryboardPrompt(part, plan) : buildShotPrompt(part, plan, shotRefsFor(part, plan))}\n`);
+        return plan;
+    }
+    for (const part of plan.parts) {
+        if (opts.only && part.id !== opts.only)
+            continue;
+        const prompt = buildShotPrompt(part, plan, shotRefsFor(part, plan));
+        const dest = path.join(opts.dir, "shots", `${part.id}.prompt.txt`);
+        writeFileSync(dest, `${prompt}\n`, "utf8");
+        part.shot_prompt_file = path.relative(opts.dir, dest);
+        say(cloud, `${GREEN}  ${part.id}${RESET} → ${dest} ${DIM}(${prompt.length} chars)${RESET}`);
+    }
+    writePlan(opts.dir, plan);
+    return plan;
+}
+// ── step 6: animate ─────────────────────────────────────────────────────────
+async function stepAnimate(opts, cloud) {
+    let plan = readPlan(opts.dir);
+    const targets = partsToRun(plan, opts, (p) => Boolean(p.video_url));
+    if (!targets.length) {
+        say(cloud, `${DIM}All parts already animated — nothing to do (pass --force to regenerate).${RESET}`);
+        return plan;
+    }
+    const missingBoards = targets.filter((p) => !p.board_url);
+    if (missingBoards.length) {
+        throw new Error(`No storyboard for ${missingBoards.map((p) => p.id).join(", ")}. Run \`vidfarm sequence boards --dir ${opts.dir}\` first — ` +
+            "animating without a board is how you burn video credits on coverage you haven't seen.");
+    }
+    cloud.guardBilled({
+        label: `${targets.length} AI video generation(s)`,
+        estimate: "expensive, ~$1+ each",
+        freeAlternative: "animate the storyboard panels as stills instead — `vidfarm place` each panel with --ken-burns, which costs $0 " +
+            "and is the right call whenever the motion is a camera move rather than a performance"
+    });
+    for (const part of targets) {
+        // Parts chain: a later part's `extend` needs the previous part's finished
+        // video URL, so re-read the plan each iteration rather than caching it.
+        plan = readPlan(opts.dir);
+        const fresh = plan.parts.find((p) => p.id === part.id);
+        const refs = shotRefsFor(fresh, plan);
+        const prompt = buildShotPrompt(fresh, plan, refs);
+        writeFileSync(path.join(opts.dir, "shots", `${fresh.id}.prompt.txt`), `${prompt}\n`, "utf8");
+        if (fresh.extend_from && !refs.extendFromUrl) {
+            say(cloud, `${YELLOW}  ${fresh.id} extends ${fresh.extend_from}, which has no video yet${RESET} ${DIM}— generating it as a standalone shot instead.${RESET}`);
+        }
+        const inputRefs = [
+            ...(refs.extendFromUrl ? [refs.extendFromUrl] : []),
+            ...(fresh.board_url ? [fresh.board_url] : []),
+            ...plan.characters.map((c) => c.card_url).filter((u) => Boolean(u))
+        ].slice(0, 8);
+        say(cloud, `${DIM}Animating ${fresh.id} (${fresh.duration_seconds}s, ${inputRefs.length} reference(s))…${RESET}`);
+        const result = await cloud.generateVideo({
+            prompt,
+            durationSeconds: fresh.duration_seconds,
+            aspectRatio: plan.aspect_ratio,
+            resolution: opts.resolution,
+            audio: opts.audio,
+            refs: inputRefs,
+            provider: opts.provider,
+            model: opts.model
+        });
+        const dest = path.join(opts.dir, "renders", `${fresh.id}.mp4`);
+        await cloud.download(result.url, dest);
+        plan = readPlan(opts.dir);
+        const target = plan.parts.find((p) => p.id === fresh.id);
+        if (target) {
+            target.video_url = result.url;
+            target.video_file = path.relative(opts.dir, dest);
+            target.shot_prompt_file = path.relative(opts.dir, path.join(opts.dir, "shots", `${fresh.id}.prompt.txt`));
+        }
+        writePlan(opts.dir, plan);
+        say(cloud, `${GREEN}  ${fresh.id}${RESET} → ${dest}`);
+    }
+    return plan;
+}
+// ── step 7: assemble ────────────────────────────────────────────────────────
+function runFfmpeg(bin, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["ignore", "ignore", "pipe"] });
+        let stderr = "";
+        child.stderr?.on("data", (chunk) => { stderr += String(chunk); });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`ffmpeg exited ${code}: ${stderr.trim().split("\n").slice(-6).join("\n")}`));
+        });
+    });
+}
+/** Read width/height/fps off a clip so the concat can normalize against it. */
+async function probeVideoGeometry(_dir, clip) {
+    const fallback = { width: 1920, height: 1080, fps: 30 };
+    try {
+        const ffprobe = await resolveFfprobe();
+        const json = await new Promise((resolve, reject) => {
+            const child = spawn(ffprobe, [
+                "-v", "error", "-select_streams", "v:0",
+                "-show_entries", "stream=width,height,r_frame_rate",
+                "-of", "json", clip
+            ], { stdio: ["ignore", "pipe", "ignore"] });
+            let out = "";
+            child.stdout?.on("data", (chunk) => { out += String(chunk); });
+            child.on("error", reject);
+            child.on("close", () => resolve(out));
+        });
+        const stream = JSON.parse(json)?.streams?.[0];
+        const width = Number(stream?.width);
+        const height = Number(stream?.height);
+        const [num, den] = String(stream?.r_frame_rate ?? "30/1").split("/").map(Number);
+        const fps = den ? Math.round(num / den) : 30;
+        if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0)
+            return fallback;
+        // libx264 needs even dimensions with yuv420p.
+        return { width: width - (width % 2), height: height - (height % 2), fps: fps > 0 ? fps : 30 };
+    }
+    catch {
+        return fallback;
+    }
+}
+async function stepAssemble(opts, cloud) {
+    const plan = readPlan(opts.dir);
+    const clips = plan.parts
+        .map((p) => (p.video_file ? path.resolve(opts.dir, p.video_file) : null))
+        .filter((f) => Boolean(f) && existsSync(f));
+    if (!clips.length) {
+        throw new Error(`No rendered parts in ${opts.dir}/renders. Run \`vidfarm sequence animate --dir ${opts.dir}\` first.`);
+    }
+    const ffmpeg = await resolveFfmpeg();
+    const out = path.resolve(opts.dir, opts.out ?? path.join("renders", "final.mp4"));
+    mkdirSync(path.dirname(out), { recursive: true });
+    // Music, when supplied, is resolved to a local file first; a URL is fetched
+    // to disk so ffmpeg never has to speak HTTP.
+    let musicPath;
+    if (opts.music) {
+        if (/^https?:\/\//i.test(opts.music)) {
+            musicPath = path.join(opts.dir, "renders", "music.mp3");
+            await cloud.download(opts.music, musicPath);
+        }
+        else {
+            musicPath = path.resolve(process.cwd(), opts.music);
+            if (!existsSync(musicPath))
+                throw new Error(`No such music file: ${musicPath}`);
+        }
+    }
+    // Normalize every part to the first clip's geometry before concatenating.
+    // The concat FILTER requires identical width/height/SAR across inputs, and a
+    // provider that quietly hands back one part at a different size would
+    // otherwise fail the whole assemble at the last step.
+    const target = await probeVideoGeometry(opts.dir, clips[0]);
+    // Re-encode rather than stream-copy: parts come back with whatever timebase
+    // and profile the provider felt like, and concat-copy silently produces a
+    // file that only plays for the first clip.
+    const args = ["-y"];
+    for (const clip of clips)
+        args.push("-i", clip);
+    if (musicPath)
+        args.push("-i", musicPath);
+    const normalized = clips
+        .map((_clip, i) => `[${i}:v:0]scale=${target.width}:${target.height}:force_original_aspect_ratio=decrease,` +
+        `pad=${target.width}:${target.height}:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=${target.fps},format=yuv420p[v${i}]`)
+        .join(";");
+    const chain = clips.map((_clip, i) => `[v${i}]`).join("");
+    args.push("-filter_complex", `${normalized};${chain}concat=n=${clips.length}:v=1:a=0[outv]`, "-map", "[outv]");
+    if (musicPath) {
+        args.push("-map", `${clips.length}:a:0`, "-c:a", "aac", "-b:a", "192k", "-shortest");
+    }
+    args.push("-c:v", "libx264", "-preset", "medium", "-crf", "20", "-pix_fmt", "yuv420p", out);
+    say(cloud, `${DIM}Assembling ${clips.length} part(s)${musicPath ? " + music" : ""} → ${out}${RESET}`);
+    await runFfmpeg(ffmpeg, args);
+    say(cloud, `${GREEN}Final cut:${RESET} ${out}`);
+    return out;
+}
+// ── status ──────────────────────────────────────────────────────────────────
+function stepStatus(opts, cloud) {
+    const plan = readPlan(opts.dir);
+    const cards = plan.characters.filter((c) => c.card_url).length;
+    const boards = plan.parts.filter((p) => p.board_url).length;
+    const videos = plan.parts.filter((p) => p.video_url).length;
+    const finalPath = path.resolve(opts.dir, opts.out ?? path.join("renders", "final.mp4"));
+    if (cloud.json) {
+        console.log(JSON.stringify({
+            title: plan.title,
+            dir: opts.dir,
+            characters: { total: plan.characters.length, done: cards },
+            boards: { total: plan.parts.length, done: boards },
+            videos: { total: plan.parts.length, done: videos },
+            final: existsSync(finalPath) ? finalPath : null,
+            next: nextStep(plan, finalPath)
+        }, null, 2));
+        return;
+    }
+    console.log(`${BOLD}${plan.title}${RESET} ${DIM}(${opts.dir})${RESET}`);
+    console.log(`  ${cards === plan.characters.length ? GREEN : DIM}characters${RESET}  ${cards}/${plan.characters.length}`);
+    console.log(`  ${boards === plan.parts.length ? GREEN : DIM}boards${RESET}      ${boards}/${plan.parts.length}`);
+    console.log(`  ${videos === plan.parts.length ? GREEN : DIM}animate${RESET}     ${videos}/${plan.parts.length}`);
+    console.log(`  ${existsSync(finalPath) ? GREEN : DIM}assemble${RESET}    ${existsSync(finalPath) ? finalPath : "—"}`);
+    for (const part of plan.parts) {
+        const marks = [part.board_url ? "board" : null, part.video_url ? "video" : null].filter(Boolean).join(" + ") || "not started";
+        console.log(`${DIM}    ${part.id}  ${part.panels.length} panels, ${part.duration_seconds}s — ${marks}${RESET}`);
+    }
+    const next = nextStep(plan, finalPath);
+    if (next)
+        console.log(`\n  Next: ${BOLD}vidfarm sequence ${next} --dir ${opts.dir}${RESET}`);
+}
+function nextStep(plan, finalPath) {
+    if (plan.characters.some((c) => !c.card_url))
+        return "characters";
+    if (plan.parts.some((p) => !p.board_url))
+        return "boards";
+    if (plan.parts.some((p) => !p.video_url))
+        return "animate";
+    if (!existsSync(finalPath))
+        return "assemble";
+    return null;
+}
+// ── run: the whole pipeline ─────────────────────────────────────────────────
+async function stepRun(opts, cloud) {
+    const plan = readPlan(opts.dir);
+    const estimate = plan.parts.length;
+    say(cloud, `${BOLD}${plan.title}${RESET} — ${plan.characters.length} character card(s), ${estimate} board(s), ${estimate} video(s).`);
+    say(cloud, `${DIM}Cards and boards are cents; video is roughly $1+ per part. Gates before each spend (skip with --yes).${RESET}`);
+    say(cloud, "");
+    say(cloud, `${BOLD}1/5 character cards${RESET}`);
+    await stepCharacters(opts, cloud);
+    if (!(await gate(cloud, "Cards look right — generate storyboards?"))) {
+        say(cloud, `${DIM}Stopped. Resume with: vidfarm sequence run --dir ${opts.dir}${RESET}`);
+        return;
+    }
+    say(cloud, `\n${BOLD}2/5 storyboards${RESET}`);
+    await stepBoards(opts, cloud);
+    if (!(await gate(cloud, "Board reads correctly — spend on video?"))) {
+        say(cloud, `${DIM}Stopped before the expensive step. Fix ${SEQUENCE_PLAN_FILE}, re-run \`sequence boards --force\`, then \`sequence run\` again.${RESET}`);
+        return;
+    }
+    say(cloud, `\n${BOLD}3/5 shot prompts${RESET}`);
+    stepPrompts(opts, cloud);
+    say(cloud, `\n${BOLD}4/5 animate${RESET}`);
+    await stepAnimate(opts, cloud);
+    say(cloud, `\n${BOLD}5/5 assemble${RESET}`);
+    const out = await stepAssemble(opts, cloud);
+    say(cloud, "");
+    say(cloud, `${GREEN}Done.${RESET} ${out}`);
+    say(cloud, `${DIM}Next: vidfarm upload "${out}" — or drop it into a composition with \`vidfarm place\`.${RESET}`);
+    if (cloud.json)
+        console.log(JSON.stringify({ ok: true, final: out }, null, 2));
+}
+// ── entrypoint ──────────────────────────────────────────────────────────────
+const SUBCOMMANDS = ["init", "plan", "characters", "boards", "prompts", "animate", "assemble", "status", "run"];
+export async function runSequenceCommand(argv, cloud) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: false,
+        options: {
+            dir: { type: "string" },
+            brief: { type: "string" },
+            title: { type: "string" },
+            parts: { type: "string" },
+            panels: { type: "string" },
+            "aspect-ratio": { type: "string" },
+            duration: { type: "string" },
+            style: { type: "string" },
+            "board-style": { type: "string" },
+            character: { type: "string" },
+            "character-description": { type: "string" },
+            "no-laban": { type: "boolean", default: false },
+            only: { type: "string" },
+            part: { type: "string" },
+            force: { type: "boolean", default: false },
+            check: { type: "boolean", default: false },
+            print: { type: "string" },
+            provider: { type: "string" },
+            model: { type: "string" },
+            "image-provider": { type: "string" },
+            "image-model": { type: "string" },
+            resolution: { type: "string" },
+            audio: { type: "boolean", default: false },
+            music: { type: "string" },
+            out: { type: "string" }
+        }
+    });
+    const values = parsed.values;
+    const subcommand = String(parsed.positionals[0] ?? "status");
+    if (!SUBCOMMANDS.includes(subcommand)) {
+        throw new Error(`Unknown sequence subcommand "${subcommand}". Expected one of: ${SUBCOMMANDS.join(", ")}.`);
+    }
+    const num = (key) => {
+        const raw = values[key];
+        if (raw === undefined || raw === "")
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new Error(`--${key} must be a number, got "${String(raw)}".`);
+        return n;
+    };
+    const opts = {
+        // Default to a folder named after the brief on init, and to CWD otherwise —
+        // so `cd my-seq && vidfarm sequence run` needs no flags at all.
+        dir: path.resolve(process.cwd(), String(values.dir
+            ?? (subcommand === "init" ? `vidfarm-sequence-${slugify(String(values.brief ?? parsed.positionals[1] ?? "sequence"))}` : "."))),
+        force: Boolean(values.force),
+        // --part is the natural word for boards/animate; --only for characters.
+        only: (values.only ?? values.part),
+        provider: values.provider,
+        model: values.model,
+        imageProvider: values["image-provider"],
+        imageModel: values["image-model"],
+        resolution: values.resolution,
+        audio: Boolean(values.audio),
+        music: values.music,
+        out: values.out
+    };
+    const boardStyle = values["board-style"];
+    if (boardStyle && boardStyle !== "rough" && boardStyle !== "final") {
+        throw new Error('--board-style must be "rough" (monochrome previz) or "final" (rendered in the final look, doubles as a style check).');
+    }
+    switch (subcommand) {
+        case "init":
+            await stepInit(parsed.positionals.slice(1), opts, cloud, {
+                brief: values.brief,
+                title: values.title,
+                parts: num("parts"),
+                panels: num("panels"),
+                aspectRatio: values["aspect-ratio"],
+                duration: num("duration"),
+                style: values.style,
+                boardStyle: boardStyle,
+                character: values.character,
+                characterDescription: values["character-description"],
+                laban: !values["no-laban"]
+            });
+            return;
+        case "plan":
+            stepPlan(opts, cloud, Boolean(values.check));
+            return;
+        case "characters":
+            await stepCharacters(opts, cloud);
+            return;
+        case "boards":
+            await stepBoards(opts, cloud);
+            return;
+        case "prompts":
+            stepPrompts(opts, cloud, values.print);
+            return;
+        case "animate":
+            await stepAnimate(opts, cloud);
+            return;
+        case "assemble":
+            await stepAssemble(opts, cloud);
+            return;
+        case "run":
+            await stepRun(opts, cloud);
+            return;
+        default:
+            stepStatus(opts, cloud);
+    }
+}
+//# sourceMappingURL=sequence.js.map