ossclip 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "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",
@@ -36,9 +36,9 @@
     "commander": "^12.1.0",
     "tsx": "^4.19.0",
     "zod": "^3.25.76",
-    "@ossclip/renderer": "0.1.9",
-    "@ossclip/core": "0.1.9",
-    "@ossclip/scenes": "0.1.9"
+    "@ossclip/core": "0.1.11",
+    "@ossclip/renderer": "0.1.11",
+    "@ossclip/scenes": "0.1.11"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/edit.ts

@@ -390,11 +390,22 @@ export async function startEditServer(
           );
           if (!parsed.success) return send(500, { error: `command.json is not valid: ${parsed.error.message}` });
           const cmd = parsed.data;
+          // §129: heal legacy records at replay. Before the fix, wizard and
+          // bare-path runs recorded process.argv — the ORIGINAL invocation,
+          // missing the `produce` literal the re-entered parse actually ran —
+          // so replaying them verbatim dies at commander's front door with
+          // "error: unknown option '--llm'". produce is the ONLY command that
+          // ever writes command.json, so an args array not starting with
+          // "produce" can only be that bug: prepend the literal to
+          // reconstruct the command that ran. A modern record — and a legacy
+          // directly-typed `ossclip produce …` — already starts with it and
+          // is untouched.
+          const args = cmd.args[0] === "produce" ? cmd.args : ["produce", ...cmd.args];
           renderLines = [];
           renderExit = null;
           renderStartedAt = Date.now();
           renderCancelled = false;
-          const child = spawn(cmd.execPath, [...cmd.execArgv, cmd.script, ...cmd.args], {
+          const child = spawn(cmd.execPath, [...cmd.execArgv, cmd.script, ...args], {
             cwd: cmd.cwd,
             stdio: ["ignore", "pipe", "pipe"],
           });

package/src/interactive/produce-wizard.ts

@@ -50,29 +50,36 @@ export function extrasFor(graphics: boolean): (typeof EXTRAS)[number][] {
   return graphics ? [...EXTRAS] : EXTRAS.filter((e) => e.value !== "graphicsClip");
 }
 
-export async function produceWizard(cfg: { speaker?: string } = {}): Promise<string[]> {
+export async function produceWizard(cfg: { speaker?: string; input?: string } = {}): Promise<string[]> {
   assertInteractive("produce wizard");
   intro("ossclip produce");
 
-  const input = unwrap(
-    await text({
-      // Finding 1 (final-review fix wave): `ossclip produce <folder>` shipped
-      // (folder-input-brief.md) but this prompt still rejected a directory —
-      // the wizard was the only way in that couldn't do what the CLI could.
-      // A folder is concatenated by name (codepoint order, like `ls`); --sort
-      // mtime reorders it but stays a typed flag, not a wizard question (see
-      // the file-level comment above for why).
-      message: "Video file, or a folder of clips to concatenate (by name; --sort mtime is a typed flag)",
-      placeholder: "./raw/take1.mp4",
-      validate: (v) => {
-        if (!v) return "a path is required";
-        if (!existsSync(v)) return `no such path: ${v}`;
-        const st = statSync(v);
-        if (!st.isFile() && !st.isDirectory()) return `${v} is neither a video file nor a folder`;
-        return undefined;
-      },
-    }),
-  ) as string;
+  // Pre-supplied by bare `ossclip <path>` (0.1.9 first-contact, 2026-08-05):
+  // the user already TYPED the input on the command line, and the old flow
+  // dropped it and asked again — the re-ask is where "./Anyhropic c Compiler"
+  // became "./" (all of ~/Downloads). The router checks existence before the
+  // wizard ever opens, so a prefilled path skips the prompt entirely.
+  const input =
+    cfg.input ??
+    (unwrap(
+      await text({
+        // Finding 1 (final-review fix wave): `ossclip produce <folder>` shipped
+        // (folder-input-brief.md) but this prompt still rejected a directory —
+        // the wizard was the only way in that couldn't do what the CLI could.
+        // A folder is concatenated by name (codepoint order, like `ls`); --sort
+        // mtime reorders it but stays a typed flag, not a wizard question (see
+        // the file-level comment above for why).
+        message: "Video file, or a folder of clips to concatenate (by name; --sort mtime is a typed flag)",
+        placeholder: "./raw/take1.mp4",
+        validate: (v) => {
+          if (!v) return "a path is required";
+          if (!existsSync(v)) return `no such path: ${v}`;
+          const st = statSync(v);
+          if (!st.isFile() && !st.isDirectory()) return `${v} is neither a video file nor a folder`;
+          return undefined;
+        },
+      }),
+    ) as string);
 
   const aspect = unwrap(
     await select({

package/src/produce.ts

@@ -98,6 +98,7 @@ import {
 } from "@ossclip/core";
 import { recordRecentProject } from "./edit";
 import { editHint } from "./interactive/edit-hint";
+import { recordedProduceArgs } from "./replay-argv";
 import { renderCover, renderProduction } from "@ossclip/renderer";
 import {
   coverTextRect,
@@ -2092,18 +2093,24 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<P
   // provider (R16 §75). Pin the RESOLVED choice into the recorded args —
   // never the key itself; secrets stay out of the workdir — so a replay
   // uses the same configuration or fails loudly asking for it.
-  const recordedArgs = process.argv.slice(2);
-  if (provider && !recordedArgs.includes("--llm")) {
-    recordedArgs.push("--llm", providerName);
-  }
   // §93g: pin the RESOLVED window, exactly as §75 pinned the provider. The
   // editor's Render replays this argv; if replay re-asked the model and got a
   // slightly different window, every saved override — anchored to scene ids
   // and word indices — would land on the wrong words. The word range, not
   // just `--clip 60`, is what makes replay deterministic with zero LLM calls.
-  if (clipWindow && !recordedArgs.includes("--clip-window")) {
-    recordedArgs.push("--clip-window", `${clipWindow.startWord}:${clipWindow.endWord}`);
-  }
+  //
+  // §129: NOT process.argv. A wizard or bare-path run re-enters commander
+  // with a BUILT argv while process.argv still holds the original invocation
+  // (`ossclip <path>`, no `produce` literal, none of the wizard's answers) —
+  // recording process.argv shipped a command that replays as
+  // `ossclip <path> --llm …` and dies on "unknown option '--llm'".
+  // recordedProduceArgs prefers the argv the re-entry stashed and falls back
+  // to process.argv for a directly typed `ossclip produce …`, which stays
+  // byte-identical to what was always recorded.
+  const recordedArgs = recordedProduceArgs({
+    llm: provider ? providerName : undefined,
+    clipWindow: clipWindow ? `${clipWindow.startWord}:${clipWindow.endWord}` : undefined,
+  });
   await writeFile(
     join(work, "command.json"),
     JSON.stringify(

package/src/program.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { Command, InvalidArgumentError } from "commander";
 import { z } from "zod/v4";
@@ -7,6 +7,7 @@ import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { produce } from "./produce";
+import { setReplayArgv } from "./replay-argv";
 
 // Before anything reads a provider key (R16 §77) — including the auto-detect
 // order in `defaultProviderName`, which decides which model runs.
@@ -51,31 +52,95 @@ export function buildProgram(): Command {
   // Bare `ossclip` at a TTY opens the menu. Piped or in CI it prints help,
   // byte for byte what it printed before — a front door must not become a
   // hang for a script.
-  program.action(async () => {
-    const { isInteractive } = await import("./interactive/tty");
-    if (!isInteractive()) {
-      program.outputHelp();
-      return;
-    }
-    const { chooseFromMenu, menuArgv } = await import("./interactive/menu");
-    const choice = await chooseFromMenu();
-    const direct = menuArgv(choice);
-    const { renderCommand } = await import("./interactive/render");
-    if (direct !== null) {
-      // Echoed for the same reason the wizard echoes: the README promises
-      // "every choice prints the equivalent command before it runs, so the
-      // menu is also how you learn the flags", and three of the four entries
-      // printed nothing. The menu's whole pedagogical point is this line.
-      console.log(`\n▸ running:\n    ${renderCommand(direct)}\n`);
-      await program.parseAsync(["node", "ossclip", ...direct]);
-      return;
-    }
-    const { produceWizard } = await import("./interactive/produce-wizard");
-    const { loadConfig } = await import("@ossclip/core");
-    const argv = await produceWizard({ speaker: loadConfig().speaker });
-    console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
-    await program.parseAsync(["node", "ossclip", ...argv]);
-  });
+  //
+  // Bare `ossclip <path>` ROUTES (0.1.9 first-contact, 2026-08-05): with no
+  // argument declared here, commander's default allow-excess-args silently
+  // DROPPED the positional — `ossclip "./Anyhropic c Compiler"` opened the
+  // menu as if nothing had been typed, and the user re-answered the wizard's
+  // input prompt by hand, wrongly, with all of ~/Downloads. Commander
+  // dispatches registered subcommand names before this action ever runs, so
+  // `produce`/`edit`/… always win over path interpretation (a folder that
+  // happens to be NAMED `doctor` goes to the subcommand — acceptable);
+  // anything that lands here is a path or a typo, and a typo must be a loud
+  // error naming what was tried, never the menu.
+  program
+    .argument(
+      "[path]",
+      "an existing video file or clips folder — shorthand for `ossclip produce <path>`, " +
+        "with the wizard asking the remaining questions",
+    )
+    // Commander 12 allows excess args by default, which is the SECOND half of
+    // the field failure (review, Important): the report's path was typed
+    // UNQUOTED — `ossclip ./Anyhropic c Compiler` — and with excess args
+    // allowed, `c` and `Compiler` would vanish wordlessly the moment
+    // `./Anyhropic` happened to exist, producing the wrong scope. An unquoted
+    // multi-word path must be a loud error, never a partial run.
+    .allowExcessArguments(false)
+    .action(async (path: string | undefined) => {
+      const { isInteractive } = await import("./interactive/tty");
+      if (path !== undefined) {
+        if (!existsSync(path)) {
+          throw new Error(
+            `no such file or directory: ${path}\n` +
+              "  bare `ossclip <path>` produces an existing video file or clips folder;\n" +
+              "  run `ossclip --help` for the commands.",
+          );
+        }
+        const { renderCommand } = await import("./interactive/render");
+        // Both branches hand argv back through `program.parseAsync` — the same
+        // re-entry shape as the wizard paths below, for the same reason: the
+        // zod checks in the produce action must run on this input exactly as
+        // they do on a typed command line.
+        if (!isInteractive()) {
+          // No TTY means no wizard for the remaining questions, but the input
+          // IS supplied — a piped `ossclip <path>` is `ossclip produce <path>`.
+          const direct = ["produce", path];
+          console.log(`\n▸ running:\n    ${renderCommand(direct)}\n`);
+          // §129: THIS argv — not process.argv, which still says `ossclip
+          // <path>` with no `produce` literal — is the invocation
+          // command.json must record for the editor's Render to replay.
+          // Every parseAsync re-entry below stashes for the same reason.
+          setReplayArgv(direct);
+          await program.parseAsync(["node", "ossclip", ...direct]);
+          return;
+        }
+        const { produceWizard } = await import("./interactive/produce-wizard");
+        const { loadConfig } = await import("@ossclip/core");
+        const argv = await produceWizard({ speaker: loadConfig().speaker, input: path });
+        console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
+        setReplayArgv(argv); // §129
+        await program.parseAsync(["node", "ossclip", ...argv]);
+        return;
+      }
+      if (!isInteractive()) {
+        program.outputHelp();
+        return;
+      }
+      const { chooseFromMenu, menuArgv } = await import("./interactive/menu");
+      const choice = await chooseFromMenu();
+      const direct = menuArgv(choice);
+      const { renderCommand } = await import("./interactive/render");
+      if (direct !== null) {
+        // Echoed for the same reason the wizard echoes: the README promises
+        // "every choice prints the equivalent command before it runs, so the
+        // menu is also how you learn the flags", and three of the four entries
+        // printed nothing. The menu's whole pedagogical point is this line.
+        console.log(`\n▸ running:\n    ${renderCommand(direct)}\n`);
+        // §129: stashed even for non-produce choices — the invariant is that
+        // the stash always mirrors the parse being entered, and only
+        // produce's recording ever reads it (consume-on-read keeps a
+        // non-produce stash from leaking past this parse).
+        setReplayArgv(direct);
+        await program.parseAsync(["node", "ossclip", ...direct]);
+        return;
+      }
+      const { produceWizard } = await import("./interactive/produce-wizard");
+      const { loadConfig } = await import("@ossclip/core");
+      const argv = await produceWizard({ speaker: loadConfig().speaker });
+      console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
+      setReplayArgv(argv); // §129
+      await program.parseAsync(["node", "ossclip", ...argv]);
+    });
 
   program
     .command("produce")
@@ -211,6 +276,7 @@ export function buildProgram(): Command {
         console.log(`\n▸ running:\n    ${renderCommand(argv)}\n`);
         // Re-entering the SAME parse the flags take: the zod checks below run
         // on wizard output exactly as they do on a typed command line.
+        setReplayArgv(argv); // §129
         await program.parseAsync(["node", "ossclip", ...argv]);
         return;
       }

package/src/replay-argv.ts

@@ -0,0 +1,60 @@
+/**
+ * What command.json must record: the argv of the parse that ACTUALLY ran
+ * (§129).
+ *
+ * `produce` records its invocation into the workdir so the editor's Render
+ * button can replay it byte for byte. It used to record `process.argv`,
+ * which is the truth for exactly one entry point — a directly typed
+ * `ossclip produce …`. The wizard has always BUILT a produce argv and
+ * re-entered `program.parseAsync(["node", "ossclip", ...argv])`, and the
+ * bare-path route does the same; in both, process.argv still holds the
+ * ORIGINAL invocation — no `produce` literal, none of the wizard's answers —
+ * so every re-entered run recorded a command that replays as
+ * `ossclip <path> --llm …` and dies at commander's front door with
+ * "error: unknown option '--llm'" (§129's field artifact). The re-entry
+ * sites in program.ts stash the argv they are about to parse here; the
+ * recording prefers the stash and falls back to process.argv, which keeps
+ * the direct path byte-identical to what it always wrote.
+ */
+
+let stashed: string[] | null = null;
+
+/**
+ * Called by every parseAsync re-entry in program.ts, immediately before the
+ * parse, with the argv minus its ["node", "ossclip"] prefix. Copied so a
+ * caller reusing its array cannot retroactively edit the record.
+ */
+export function setReplayArgv(argv: string[]): void {
+  stashed = [...argv];
+}
+
+/**
+ * Consume-on-read (§129): commander 12 keeps option state across parseAsync
+ * calls (see the bare-`produce` refusal in program.ts), and a stash kept
+ * across parses would be the same trap one layer up — a menu choice that
+ * never reaches `produce` must not leave its argv behind for a later
+ * recording in the same process to mistake for its own.
+ */
+export function consumeReplayArgv(): string[] | null {
+  const argv = stashed;
+  stashed = null;
+  return argv;
+}
+
+/**
+ * The args `produce` writes into command.json: the argv of the parse that
+ * ran (stash for a re-entered wizard/bare-path run, process.argv for a
+ * directly typed one), plus the §75/§93g pins. The pins guard on
+ * `includes` so a flag the user actually typed — or a pin recorded by the
+ * run a replay is re-running — is never appended twice.
+ */
+export function recordedProduceArgs(pins: { llm?: string; clipWindow?: string }): string[] {
+  const args = consumeReplayArgv() ?? process.argv.slice(2);
+  if (pins.llm !== undefined && !args.includes("--llm")) {
+    args.push("--llm", pins.llm);
+  }
+  if (pins.clipWindow !== undefined && !args.includes("--clip-window")) {
+    args.push("--clip-window", pins.clipWindow);
+  }
+  return args;
+}