ossclip 0.1.5 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Local-first CLI video producer: cuts silence and fillers, word-timed captions, face-aware framing, and LLM-planned code-rendered graphics — transcription and rendering never leave your machine",
   "type": "module",
   "license": "MIT",
@@ -32,12 +32,13 @@
     "editor-dist"
   ],
   "dependencies": {
+    "@clack/prompts": "^1.7.0",
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/core": "0.1.5",
-    "@ossclip/scenes": "0.1.5",
-    "@ossclip/renderer": "0.1.5"
+    "@ossclip/core": "0.1.6",
+    "@ossclip/renderer": "0.1.6",
+    "@ossclip/scenes": "0.1.6"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/doctor.ts

@@ -18,7 +18,7 @@ import type { OssclipConfig } from "@ossclip/core";
  * Checks are pure over injected probes so the table is unit-testable; the
  * CLI wires the real spawn/existsSync in. The provider check MUST run after
  * `loadEnvFiles` (R16 §77) or a key living in `.env` reports a false
- * negative — `index.ts` loads env at module top, before any command runs.
+ * negative — `program.ts` loads env at module top, before any command runs.
  */
 
 export interface DoctorCheck {

package/src/edit.ts

@@ -3,7 +3,7 @@ import { createReadStream, existsSync, statSync } from "node:fs";
 import { mkdir, readFile, readdir, rename, writeFile } from "node:fs/promises";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { homedir } from "node:os";
-import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { z } from "zod/v4";
 import { OverrideDocSchema, emptyOverrideDoc } from "@ossclip/core";
@@ -194,7 +194,17 @@ export async function startEditServer(
   const openWorkdir = async (dirArg: string): Promise<void> => {
     const dir = resolve(dirArg);
     if (!isWorkdir(dir)) {
-      throw new Error(`no render-props.json in ${dir} — run \`ossclip produce\` there first`);
+      // Not "run produce there first" — the reported failure said that to a
+      // user who HAD, because produce writes one level down into
+      // .ossclip/<name>/ and this wanted that nested directory.
+      // The layout is spelled with the host separator, as resolve-workdir.ts
+      // does: hardcoded forward slashes here meant a Windows user met both
+      // conventions from one product depending on which entry point they hit.
+      throw new Error(
+        `no render-props.json in ${dir} — produce writes into ` +
+          `<video's folder>${sep}.ossclip${sep}<name>${sep}, and that nested folder ` +
+          `is what edit opens`,
+      );
     }
     workdir = dir;
     await recordRecentProject(dir, opts.recentDir);

package/src/index.ts

@@ -1,294 +1,11 @@
 #!/usr/bin/env tsx
-import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { Command, InvalidArgumentError } from "commander";
-import { z } from "zod/v4";
-import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
-import { STUDIO_ENTRY } from "@ossclip/renderer";
-import { loadEnvFiles } from "./env";
-import { produce } from "./produce";
+import { buildProgram } from "./program";
 
-// Before anything reads a provider key (R16 §77) — including the auto-detect
-// order in `defaultProviderName`, which decides which model runs.
-const envFiles = loadEnvFiles();
-
-const program = new Command();
-
-program
-  .name("ossclip")
-  .description(
-    "local-first video producer: cuts silence and fillers, word-timed captions, " +
-      "face-aware framing, LLM-planned code-rendered graphics",
-  )
-  // Read from the manifest, never hardcoded (R22 §113): a literal here said
-  // "0.1.0" for every release after it, so `--version` reported the number a
-  // developer typed rather than the one npm installed — the exact field a
-  // bug report is judged by. npm always packs package.json regardless of
-  // `files`, so this resolves in a published install too.
-  .version(
-    (
-      JSON.parse(
-        readFileSync(new URL("../package.json", import.meta.url), "utf8"),
-      ) as { version: string }
-    ).version,
-  );
-
-program
-  .command("produce")
-  .description("transcribe → analyze → cut → captions → render")
-  .argument("<input>", "input video file")
-  .option("-o, --out <path>", "output video path (default: <input>.ossclip.mp4)")
-  .option("--cleanup <level>", "exact | light | standard | aggressive", "standard")
-  .option("--transcript <path>", "inject a transcript JSON instead of running whisper")
-  .option("--no-render", "stop after writing production.json / render props")
-  .option(
-    "--no-mezzanine",
-    "render straight from the source instead of a dense-keyframe mezzanine " +
-      "(also makes the source's folder the render server's public dir)",
-  )
-  .option("--noise-db <db>", "override the measured silence threshold, e.g. -30", parseFloat)
-  .option("--workdir <dir>", "cache/work directory (default: <input dir>/.ossclip)")
-  .option(
-    "--aspect <ratio>",
-    "output shape: 9:16 (vertical, default) or 16:9 (landscape, 1920x1080)",
-    "9:16",
-  )
-  .option("--produce", "run the LLM producer brain to plan title cards & graphics", false)
-  .option(
-    "--clip <seconds>",
-    "produce only the strongest ~N-second window of a long take (requires --produce; " +
-      "a source already at or under the target is produced whole)",
-    (v: string) => {
-      // §93a: reject rather than coerce — `--clip 0`, negatives and typos must
-      // not silently become "no clip" or NaN-length windows.
-      const n = Number.parseFloat(v);
-      if (!Number.isFinite(n) || n <= 0) {
-        throw new InvalidArgumentError(`--clip wants a positive number of seconds, got "${v}"`);
-      }
-      return n;
-    },
-  )
-  .option(
-    "--clip-window <start:end>",
-    "internal: the resolved highlight's word range, recorded into command.json by --clip " +
-      "runs so the editor's Render replays the same window without an LLM call",
-  )
-  .option("--intent <text>", "what the video should be ('educational video about agents…')")
-  .option(
-    "--llm <provider>",
-    "claude | claude-cli | gemini | mock. Default: claude if ANTHROPIC_API_KEY is set, " +
-      "else claude-cli (your logged-in Claude Code — Pro/Max subscription, no API charges)",
-  )
-  .option("--llm-model <id>", "override the provider's default model")
-  .option(
-    "--llm-fast-model <id>",
-    "model for mechanical calls (repair, scene props); 'same' disables tiering",
-  )
-  .option(
-    "--speaker <who>",
-    'who is on camera, e.g. "Ahsan, host of Code with Ahsan" — helps repair recognise mangled names',
-  )
-  .option("--scenes <path>", "hand-authored scenes JSON (Scene[]) — no LLM in the loop")
-  .option(
-    "--no-repair",
-    "skip the ASR mishearing repair pass (captions then show the raw transcription)",
-  )
-  .option("--whisper-model <name>", "transcription model for this run, e.g. base.en | small.en | medium.en")
-  .option(
-    "--force-component <id>",
-    "debug: render every graphic with this component (e.g. FlowDiagram) to exercise it on real copy",
-  )
-  .option(
-    "--source-fit <mode>",
-    "cover | contain. cover (default) crops the source to fill the vertical " +
-      "frame; contain shows the WHOLE frame inset against the backdrop — the " +
-      "answer for a landscape take whose content matters beyond the speaker",
-    "cover",
-  )
-  .option(
-    "--source-is-edited",
-    "the source is already an edited reel with burned-in text — keep ossclip's graphics off it without waiting on detection",
-  )
-  .option(
-    "--blooper-marker <word>",
-    "cut the flubbed take whenever you say this word out loud (e.g. blooper): " +
-      "removal runs back to the start of the sentence it spoiled. Off unless given",
-  )
-  .option("--no-cover", "skip the cover image written beside the video")
-  .option("--cover <path>", "cover image output path (default: <out>.cover.jpg)")
-  .action(async (input: string, opts) => {
-    // Say which keys came from a file — never the keys themselves. A run that
-    // picks a provider from a `.env` should say where that came from.
-    if (envFiles.length > 0) console.log(`▸ env: ${envFiles.join(", ")}`);
-    const cleanup = CleanupLevelSchema.parse(opts.cleanup);
-    const provider = opts.llm
-      ? z.enum(["claude", "claude-cli", "gemini", "mock"]).parse(opts.llm)
-      : undefined;
-    const forceComponent = opts.forceComponent
-      ? SceneComponentIdSchema.parse(opts.forceComponent)
-      : undefined;
-    // Parsed, not coerced: a typo'd `--source-fit containn` silently falling
-    // back to cover is exactly the crop the flag exists to prevent.
-    const sourceFit = z.enum(["cover", "contain"]).parse(opts.sourceFit);
-    await produce(input, {
-      out: opts.out,
-      cleanup,
-      transcript: opts.transcript,
-      render: opts.render,
-      mezzanine: opts.mezzanine,
-      workdir: opts.workdir,
-      aspect: opts.aspect === "16:9" ? "16:9" : "9:16",
-      noiseDb: opts.noiseDb,
-      produce: opts.produce,
-      intent: opts.intent,
-      provider,
-      llmModel: opts.llmModel,
-      llmFastModel: opts.llmFastModel,
-      speaker: opts.speaker,
-      scenes: opts.scenes,
-      repair: opts.repair,
-      whisperModel: opts.whisperModel,
-      forceComponent,
-      // commander gives `--no-cover` as cover:false and `--cover <path>` as a
-      // string on the same key.
-      sourceIsEdited: opts.sourceIsEdited === true,
-      blooperMarker: opts.blooperMarker,
-      sourceFit,
-      cover: opts.cover !== false,
-      coverPath: typeof opts.cover === "string" ? opts.cover : undefined,
-      clip: opts.clip,
-      clipWindow: opts.clipWindow,
-    });
-  });
-
-program
-  .command("transcribe")
-  .description("run the pipeline up to the transcript and cut report, no render")
-  .argument("<input>", "input video file")
-  .option("--cleanup <level>", "exact | light | standard | aggressive", "standard")
-  .option("--transcript <path>", "inject a transcript JSON instead of running whisper")
-  .option("--noise-db <db>", "override the measured silence threshold, e.g. -30", parseFloat)
-  .option("--workdir <dir>", "cache/work directory")
-  .option("--whisper-model <name>", "transcription model for this run, e.g. base.en | small.en | medium.en")
-  .action(async (input: string, opts) => {
-    const cleanup = CleanupLevelSchema.parse(opts.cleanup);
-    await produce(input, {
-      cleanup,
-      transcript: opts.transcript,
-      render: false,
-      mezzanine: false,
-      workdir: opts.workdir,
-      noiseDb: opts.noiseDb,
-      whisperModel: opts.whisperModel,
-    });
-  });
-
-program
-  .command("studio")
-  .description("open Remotion Studio on a produced composition (visual debugging)")
-  .argument("<renderProps>", "path to a work dir's render-props.json")
-  .option("--video-dir <dir>", "directory containing the source video (public dir)")
-  .action(async (renderProps: string, opts) => {
-    const propsPath = resolve(renderProps);
-    const publicDir = opts.videoDir ? resolve(opts.videoDir) : dirname(propsPath);
-    // Resolve Remotion's CLI through module resolution instead of spawning
-    // `pnpm` — a global `npm i -g ossclip` has no pnpm and no workspace, and
-    // Windows would need the .cmd shim. `@remotion/cli` is a dependency of
-    // @ossclip/renderer, so resolving from THERE works in both a clone and a
-    // published install, on every OS, run via the node that's running us.
-    const { createRequire } = await import("node:module");
-    let remotionCliJs: string;
-    try {
-      const require = createRequire(import.meta.url);
-      const rendererDir = dirname(require.resolve("@ossclip/renderer/package.json"));
-      const fromRenderer = createRequire(join(rendererDir, "package.json"));
-      const cliPkgPath = fromRenderer.resolve("@remotion/cli/package.json");
-      const cliPkg = JSON.parse(readFileSync(cliPkgPath, "utf8")) as {
-        bin: string | Record<string, string>;
-      };
-      const binRel = typeof cliPkg.bin === "string" ? cliPkg.bin : cliPkg.bin.remotion;
-      if (!binRel) throw new Error("no remotion bin entry");
-      remotionCliJs = join(dirname(cliPkgPath), binRel);
-    } catch {
-      throw new Error(
-        "couldn't resolve @remotion/cli — in a clone, run `pnpm install` first",
-      );
-    }
-    const child = spawn(
-      process.execPath,
-      [remotionCliJs, "studio", STUDIO_ENTRY, `--props=${propsPath}`, `--public-dir=${publicDir}`],
-      { stdio: "inherit" },
-    );
-    child.on("error", (e) => {
-      console.error(`✗ failed to start Remotion Studio: ${e.message}`);
-      process.exit(1);
-    });
-    child.on("exit", (code) => process.exit(code ?? 0));
-  });
-
-program
-  .command("edit")
-  .description("open the editing page on a produced workdir")
-  // OPTIONAL since R17 §83: with no argument the editor opens on a project
-  // picker — recent produce runs plus a folder browser — and the top bar's
-  // Open button switches projects without restarting the server.
-  .argument("[workdir]", "a work directory containing render-props.json")
-  .option("--port <n>", "port to listen on", (v) => Number.parseInt(v, 10), 5174)
-  .option("--no-open", "do not open a browser")
-  .action(async (workdir: string | undefined, opts) => {
-    const { startEditServer, resolveEditorPageDir } = await import("./edit");
-    // An npm install ships the page prebuilt (editor-dist/); a clone builds
-    // it once with `pnpm build`. A server that starts fine but 404s every
-    // page request is the worst version of missing — fail loudly with the
-    // fix instead.
-    const pageDir = resolveEditorPageDir();
-    if (pageDir === null) {
-      throw new Error(
-        "editor UI isn't built yet — run `pnpm build` " +
-          "(or `pnpm --filter @ossclip/editor build`) once, then re-run `ossclip edit`.",
-      );
-    }
-    const server = await startEditServer(workdir, { port: opts.port, pageDir });
-    console.log(`▸ editor at ${server.url}`);
-    if (opts.open) {
-      const { openInBrowser } = await import("./open");
-      openInBrowser(server.url);
-    }
-  });
-
-program
-  .command("setup")
-  .description(
-    "install everything ossclip needs (ffmpeg, whisper.cpp, the transcription model) " +
-      "into ~/.ossclip — the one-command onboarding on macOS, Linux, and Windows",
-  )
-  .option("--model <name>", "transcription model to download (default: config, i.e. small.en)")
-  .option("--skip-llm", "don't ask about an LLM provider (only --produce needs one)", false)
-  .option("--force", "re-download the pieces setup manages, even if present", false)
-  .option("-y, --yes", "no questions — accept the plan and skip the provider prompt", false)
-  .action(async (opts) => {
-    if (envFiles.length > 0) console.log(`▸ env: ${envFiles.join(", ")}`);
-    const { setup } = await import("./setup/setup");
-    await setup({ model: opts.model, skipLlm: opts.skipLlm, force: opts.force, yes: opts.yes });
-  });
-
-program
-  .command("doctor")
-  .description("check every prerequisite and print the exact fix for anything missing")
-  .action(async () => {
-    // Env files are loaded at module top (R16 §77) — BEFORE this runs — so a
-    // provider key living in a `.env` is visible here, not a false negative.
-    if (envFiles.length > 0) console.log(`▸ env: ${envFiles.join(", ")}`);
-    const { runDoctor, formatDoctor, realProbes } = await import("./doctor");
-    const { resolveEditorPageDir } = await import("./edit");
-    const { loadConfig } = await import("@ossclip/core");
-    const checks = await runDoctor(loadConfig(), realProbes(resolveEditorPageDir()));
-    console.log(formatDoctor(checks));
-    if (checks.some((c) => !c.ok)) process.exit(1);
-  });
-
-program.parseAsync().catch((err) => {
+// The side effect (loadEnvFiles, R16 §77) stays at import time inside
+// program.ts: bin/ossclip.mjs imports this module and expects it to run, and
+// this file's first statement importing program.ts is what preserves that
+// ordering — before anything reads a provider key.
+buildProgram().parseAsync().catch((err) => {
   console.error(`\n✗ ${err instanceof Error ? err.message : err}`);
   process.exit(1);
 });

package/src/interactive/edit-hint.ts

@@ -0,0 +1,20 @@
+import { renderCommand } from "./render";
+
+/**
+ * The closing signpost of a produce run.
+ *
+ * `▸ workdir <path>` is printed at the START of a run, which after six
+ * minutes of transcription and rendering is thousands of lines up the
+ * scrollback. The reported user had the written guide open and still could
+ * not find the directory, because the last thing on screen named neither it
+ * nor the command that opens it.
+ */
+export function editHint(workdir: string, platform: NodeJS.Platform = process.platform): string {
+  // The platform is a parameter, defaulted to the host, for the same reason
+  // resolveWorkdir takes `sep`: the Windows rendering has to be assertable
+  // from a macOS dev machine and an ubuntu CI leg. It was previously PINNED
+  // to "linux", which handed a Windows user under `D:\My Videos\` POSIX
+  // single quotes that cmd.exe passes through literally — the branch's
+  // headline artifact, broken on the platform the bug report came from.
+  return `▸ edit it:  ${renderCommand(["edit", workdir], platform)}`;
+}

package/src/interactive/menu.ts

@@ -0,0 +1,32 @@
+import { assertInteractive, intro, select, unwrap } from "./prompts";
+
+export type MenuChoice = "produce" | "edit" | "setup" | "doctor";
+
+/**
+ * What each menu entry runs. Produce is the exception — it needs answers
+ * before it has an argv, so it returns null and the caller hands off to the
+ * wizard.
+ */
+export function menuArgv(choice: MenuChoice): string[] | null {
+  if (choice === "produce") return null;
+  // Edit with NO argument is deliberate: that is the project picker over
+  // recent runs (R17 §83), which is exactly what somebody who reached a menu
+  // instead of typing a command needs.
+  return [choice];
+}
+
+export async function chooseFromMenu(): Promise<MenuChoice> {
+  assertInteractive("main menu");
+  intro("ossclip");
+  return unwrap(
+    await select({
+      message: "What do you want to do?",
+      options: [
+        { value: "produce", label: "Produce a video", hint: "cut, caption, frame, render" },
+        { value: "edit", label: "Edit a produced project", hint: "pick from recent runs" },
+        { value: "setup", label: "Set up my install", hint: "ffmpeg, whisper, the model" },
+        { value: "doctor", label: "Check what's missing" },
+      ],
+    }),
+  ) as MenuChoice;
+}

package/src/interactive/offer-editor.ts

@@ -0,0 +1,71 @@
+import { loadConfig, saveConfigPatch, type OpenEditorPref } from "@ossclip/core";
+import type { ProduceResult } from "../produce";
+import { answerToDecision, decideOpenEditor, type OpenEditorAnswer } from "./prefs";
+import { isInteractive, select, unwrap } from "./prompts";
+import { renderCommand } from "./render";
+
+/**
+ * The offer at the end of a produce run. The user who prompted this work
+ * asked "how can I open the editor?" BEFORE running anything — the answer
+ * belongs at the moment there is finally something to open.
+ */
+export async function offerEditor(
+  result: ProduceResult,
+  opts: { flag: boolean | undefined; port: number },
+): Promise<void> {
+  const pref: OpenEditorPref = loadConfig().openEditorAfterProduce ?? "ask";
+  const decision = decideOpenEditor({
+    flag: opts.flag,
+    pref,
+    interactive: isInteractive(),
+    rendered: result.rendered,
+  });
+
+  if (decision === "skip") return;
+
+  let open = decision === "open";
+  if (decision === "ask") {
+    const answer = unwrap(
+      await select({
+        message: "Open the editor on this project?",
+        options: [
+          { value: "yes", label: "Yes" },
+          { value: "no", label: "No" },
+          { value: "always", label: "Yes, and stop asking" },
+          { value: "never", label: "No, and stop asking" },
+        ],
+      }),
+    ) as OpenEditorAnswer;
+
+    // The mapping itself lives in prefs.ts, where four answers are asserted
+    // without a TTY — this file is I/O and a manual walk was its only cover.
+    const decided = answerToDecision(answer);
+    if (decided.pref !== undefined) {
+      const path = saveConfigPatch({ openEditorAfterProduce: decided.pref });
+      // Say where the answer went, and how to take it back — a preference
+      // saved silently is one the user cannot find again.
+      console.log(`▸ saved openEditorAfterProduce="${decided.pref}" to ${path}`);
+    }
+    open = decided.open;
+  }
+
+  if (!open) return;
+
+  const { startEditServer, resolveEditorPageDir } = await import("../edit");
+  const pageDir = resolveEditorPageDir();
+  if (pageDir === null) {
+    // Not fatal here: the render succeeded. Say what is missing and stop.
+    // Through renderCommand like every other `ossclip edit <path>` we print:
+    // hand-built, this one quoted nothing, so a workdir with a space in it
+    // printed a command that fails.
+    console.log(
+      "▸ editor UI isn't built — run `pnpm build` once, then " +
+        renderCommand(["edit", result.workdir]),
+    );
+    return;
+  }
+  const server = await startEditServer(result.workdir, { port: opts.port, pageDir });
+  console.log(`▸ editor at ${server.url}`);
+  const { openInBrowser } = await import("../open");
+  openInBrowser(server.url);
+}

package/src/interactive/pick-workdir.ts

@@ -0,0 +1,21 @@
+import { basename } from "node:path";
+import type { Candidate } from "./resolve-workdir";
+import { assertInteractive, select, unwrap } from "./prompts";
+
+/**
+ * The "several runs under .ossclip" rung. Newest first is already guaranteed
+ * by resolveWorkdir; this only renders the choice.
+ */
+export async function pickWorkdir(candidates: Candidate[]): Promise<string> {
+  assertInteractive("workdir picker");
+  return unwrap(
+    await select({
+      message: "Several produce runs here — which one?",
+      options: candidates.map((c, i) => ({
+        value: c.path,
+        label: basename(c.path),
+        hint: i === 0 ? "most recent" : undefined,
+      })),
+    }),
+  ) as string;
+}

package/src/interactive/prefs.ts

@@ -0,0 +1,51 @@
+import type { OpenEditorPref } from "@ossclip/core";
+
+export type OpenEditorDecision = "open" | "skip" | "ask";
+
+/**
+ * Whether a finished produce run opens the editor, asks, or says nothing.
+ *
+ * Pure so the whole precedence order is tested without a produce run: flags
+ * beat the stored preference, the stored preference beats asking, and no TTY
+ * means never ask.
+ */
+export function decideOpenEditor(i: {
+  flag: boolean | undefined;
+  pref: OpenEditorPref;
+  interactive: boolean;
+  rendered: boolean;
+}): OpenEditorDecision {
+  // An explicit flag is a deliberate instruction and wins outright — including
+  // over `rendered`, because the editor reads render-props.json, which a
+  // --no-render run does write.
+  if (i.flag === true) return "open";
+  if (i.flag === false) return "skip";
+  // Above the stored preference, not below it: a persisted "always" (or
+  // OSSCLIP_OPEN_EDITOR=always) is not a per-run instruction, and starting a
+  // long-lived edit server in `ossclip produce take.mp4 > build.log 2>&1`
+  // holds the event loop open with nobody there to see it or close it. Only
+  // the explicit flag above may do that.
+  if (!i.interactive) return "skip";
+  // Otherwise a run with no render has nothing to look at, so the offer is noise.
+  if (!i.rendered) return "skip";
+  if (i.pref === "always") return "open";
+  if (i.pref === "never") return "skip";
+  return "ask";
+}
+
+export type OpenEditorAnswer = "yes" | "no" | "always" | "never";
+
+/**
+ * What each answer to the end-of-run offer means: whether to open now, and
+ * the preference to persist if the answer was one of the two that stop the
+ * asking. Pure so all four are asserted without a prompt — the interactive
+ * path is then only the I/O around it.
+ */
+export function answerToDecision(answer: OpenEditorAnswer): {
+  pref?: OpenEditorPref;
+  open: boolean;
+} {
+  const open = answer === "yes" || answer === "always";
+  if (answer === "always" || answer === "never") return { pref: answer, open };
+  return { open };
+}

package/src/interactive/produce-argv.ts

@@ -0,0 +1,57 @@
+/**
+ * Wizard answers → the argv a user could have typed.
+ *
+ * This is the load-bearing shape of the whole interactive layer: the wizard
+ * produces ARGUMENTS, not a ProduceOptions, so the zod parses in program.ts
+ * stay the only validation path and the printed command is the executed one.
+ */
+
+export interface ProduceExtras {
+  clip?: number;
+  sourceFit?: "cover" | "contain";
+  speaker?: string;
+  whisperModel?: string;
+  blooperMarker?: string;
+  sourceIsEdited?: boolean;
+  llm?: "claude" | "claude-cli" | "gemini" | "mock";
+}
+
+export interface ProduceAnswers {
+  input: string;
+  aspect: "9:16" | "16:9";
+  cleanup: "exact" | "light" | "standard" | "aggressive";
+  graphics: boolean;
+  intent?: string;
+  out?: string;
+  extras: ProduceExtras;
+}
+
+export function produceArgv(a: ProduceAnswers): string[] {
+  const argv = ["produce", a.input];
+
+  // A flag whose value equals the default is NEVER emitted. A wizard run
+  // where every answer was the default must teach `ossclip produce <file>`
+  // and nothing more — anything longer becomes a command line the user
+  // copies forever without knowing which parts mattered.
+  if (a.aspect !== "9:16") argv.push("--aspect", a.aspect);
+  if (a.cleanup !== "standard") argv.push("--cleanup", a.cleanup);
+  if (a.out) argv.push("--out", a.out);
+
+  if (a.graphics) {
+    argv.push("--produce");
+    // Intent feeds the producer brain, which only runs under --produce —
+    // emitting it alone would be a flag with nothing to act on.
+    if (a.intent) argv.push("--intent", a.intent);
+  }
+
+  const e = a.extras;
+  if (e.clip !== undefined) argv.push("--clip", String(e.clip));
+  if (e.sourceFit === "contain") argv.push("--source-fit", "contain");
+  if (e.speaker) argv.push("--speaker", e.speaker);
+  if (e.whisperModel) argv.push("--whisper-model", e.whisperModel);
+  if (e.blooperMarker) argv.push("--blooper-marker", e.blooperMarker);
+  if (e.sourceIsEdited === true) argv.push("--source-is-edited");
+  if (e.llm) argv.push("--llm", e.llm);
+
+  return argv;
+}