ossclip 0.1.16 → 0.1.18

package/README.md

@@ -31,6 +31,8 @@ ossclip produce podcast.mp4 --produce --clip 60 -o clip.mp4
 ossclip edit "<work directory>"
 ```
 
+**Not sure what to run?** `ossclip` with no arguments opens a menu, and every choice prints the equivalent command before it runs. Choose **produce a video** and the wizard's first question offers the newest videos in your working directory, Downloads and Movies (Videos on Linux and Windows); a **Browse…** row that opens your operating system's own file picker; and typing a path. Over SSH on macOS or Windows, or on a Linux box with no display or no `zenity`/`kdialog`, the Browse rows are simply not shown — there is no window to open. `OSSCLIP_NO_PICKER` set to a non-empty value hides them too, leaving suggestions and typing — truthiness, not presence, so an empty `OSSCLIP_NO_PICKER=` leaves the picker on.
+
 **Scope, honestly:** ossclip is at its best polishing a take you have already cut down. `--clip` selects a single strongest window from long-form input — one clip, not N.
 
 AI can make mistakes: the cut, the captions and every graphic are generated — review the output before publishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ossclip",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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/core": "0.1.16",
-    "@ossclip/renderer": "0.1.16",
-    "@ossclip/scenes": "0.1.16"
+    "@ossclip/core": "0.1.18",
+    "@ossclip/renderer": "0.1.18",
+    "@ossclip/scenes": "0.1.18"
   },
   "homepage": "https://github.com/AhsanAyaz/ossclip#readme",
   "bugs": {

package/src/interactive/ask-input.ts

@@ -0,0 +1,191 @@
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { livePickerDeps, pickPath, pickerAvailable, type PickMode } from "./picker";
+import { assertInteractive, select, text, unwrap } from "./prompts";
+import { rankSuggestions, scanLikelyDirs, type Suggestion } from "./suggest-inputs";
+
+/**
+ * "Which video?" — the first prompt of the wizard, and until §136 the one
+ * step a non-technical user could not get past: it demanded a typed path.
+ * Now it is a menu of the newest videos on the machine, a native picker, and
+ * typing, in that order.
+ *
+ * Every branch converges on `validateInputPath` rather than trusting its
+ * source. A picker result is not more trustworthy than typed text: the file
+ * can be deleted between the dialog closing and the path arriving, and
+ * "Browse for a folder" happily returns a folder with no video in it.
+ */
+
+export const BROWSE_FILE = "__browse_file__";
+export const BROWSE_FOLDER = "__browse_folder__";
+export const TYPE_PATH = "__type_path__";
+
+export type InputSource = "suggestion" | "picker" | "typed";
+
+/**
+ * Not a zod schema, deliberately: the house rule parses user values with zod
+ * because a typo must not silently coerce, and there is nothing to coerce
+ * here — this is a filesystem predicate (does it exist, is it a file or a
+ * folder), which zod cannot answer. The wording is carried over verbatim
+ * from the prompt this replaced.
+ *
+ * There is deliberately no extension whitelist, on any branch: typing a path
+ * was never extension-checked either, and ossclip accepts whatever ffmpeg can
+ * read — a list would reject legitimate containers.
+ */
+export function validateInputPath(v: string | undefined): string | undefined {
+  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;
+}
+
+export function inputChoices(
+  suggestions: Suggestion[],
+  canBrowse: boolean,
+): { value: string; label: string; hint?: string }[] {
+  const rows = suggestions.map((s) => ({ value: s.path, label: s.label, hint: s.hint }));
+  // Offering a "Browse…" row on a machine with no dialog to open is worse
+  // than not offering it — `pickerAvailable` has already probed, so the row
+  // simply does not exist when it cannot work.
+  if (canBrowse) {
+    rows.push(
+      { value: BROWSE_FILE, label: "Browse…", hint: "opens a file picker" },
+      { value: BROWSE_FOLDER, label: "Browse for a folder of clips", hint: "concatenated by name" },
+    );
+  }
+  rows.push({ value: TYPE_PATH, label: "Type a path", hint: "if you already know it" });
+  return rows;
+}
+
+let lastInputSource: InputSource | "argv" = "argv";
+
+/** Which branch produced the input, for the produce_completed event (§136). */
+export function noteInputSource(s: InputSource): void {
+  lastInputSource = s;
+}
+
+export function inputSourceUsed(): InputSource | "argv" {
+  return lastInputSource;
+}
+
+/**
+ * Module state outlives a single wizard, and "argv" is a real answer — the
+ * value the telemetry reads when `ossclip <path>` prefilled the input and
+ * `askInput` never ran. So a second run in the same process (a batch or REPL
+ * caller, and every test file, where module state persists across `it`s)
+ * would report the PREVIOUS run's branch with nothing to signal the staleness.
+ * Reset at the start of a run — or of a test — rather than trusting one
+ * invocation per process.
+ */
+export function resetInputSource(): void {
+  lastInputSource = "argv";
+}
+
+/**
+ * The seam. Same shape and same reason as `PickerDeps` (picker.ts) and
+ * `TtyDeps` (tty.ts): the branch logic is what has rules worth pinning — a
+ * cancelled dialog re-asks, every branch validates, each sets its own source —
+ * and none of that is reachable through a real `select` blocking on a human.
+ * `pickPath` is tested the same way through its own injected deps.
+ *
+ * Structural signatures rather than `typeof select`: clack's are generic, and
+ * a fake cannot satisfy an unresolved type parameter. Narrowing here is what
+ * makes the fakes writable, exactly as `PickerDeps` declares `hasBin` rather
+ * than `typeof binOnPath`.
+ */
+export interface AskInputDeps {
+  /** Probed once per run, not per loop — no dialog appears mid-prompt. */
+  canBrowse: boolean;
+  suggest: () => Promise<Suggestion[]>;
+  pick: (mode: PickMode) => Promise<string | undefined>;
+  select: (opts: {
+    message: string;
+    options: { value: string; label: string; hint?: string }[];
+  }) => Promise<string | symbol>;
+  text: (opts: {
+    message: string;
+    placeholder?: string;
+    validate?: (v: string | undefined) => string | undefined;
+  }) => Promise<string | symbol>;
+  /** Injected because the guard itself takes an injected check (tty.ts:58). */
+  assertInteractive: () => void;
+}
+
+export const liveAskInputDeps = (): AskInputDeps => ({
+  canBrowse: pickerAvailable(livePickerDeps()),
+  suggest: async () => rankSuggestions(await scanLikelyDirs(), Date.now(), homedir()),
+  pick: (mode) => pickPath(mode),
+  select,
+  text,
+  assertInteractive: () => assertInteractive("input prompt"),
+});
+
+const typePath = async (deps: AskInputDeps): Promise<string> =>
+  unwrap(
+    await deps.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 in produce-wizard.ts 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: validateInputPath,
+    }),
+  ) as string;
+
+export async function askInput(deps: AskInputDeps = liveAskInputDeps()): Promise<string> {
+  deps.assertInteractive();
+  const canBrowse = deps.canBrowse;
+  const suggestions = await deps.suggest();
+
+  // Nothing found and nowhere to browse: a one-row menu is pure noise, so go
+  // straight to the prompt this whole unit replaced.
+  if (suggestions.length === 0 && !canBrowse) {
+    noteInputSource("typed");
+    return typePath(deps);
+  }
+
+  // Loops rather than returns, because cancelling the OS dialog must land
+  // back on the menu — Escape in a Finder window means "not that one", not
+  // "abandon the run". Ctrl-C at the menu still exits via `unwrap`.
+  for (;;) {
+    const choice = unwrap(
+      await deps.select({ message: "Which video?", options: inputChoices(suggestions, canBrowse) }),
+    ) as string;
+
+    if (choice === TYPE_PATH) {
+      noteInputSource("typed");
+      return typePath(deps);
+    }
+
+    if (choice === BROWSE_FILE || choice === BROWSE_FOLDER) {
+      const picked = await deps.pick(choice === BROWSE_FOLDER ? "folder" : "file");
+      // An empty result conflates "cancelled" with "the backend failed
+      // silently" — no backend distinguishes them reliably (picker.ts), and
+      // `pickPath` has already printed the fallback notice in the failure
+      // case. Re-asking is the right next step either way.
+      if (picked === undefined) continue;
+      const problem = validateInputPath(picked);
+      if (problem !== undefined) {
+        console.log(`▸ ${problem}`);
+        continue;
+      }
+      noteInputSource("picker");
+      return picked;
+    }
+
+    // A suggestion. Still validated: the listing is a snapshot, and a file
+    // can be moved between the scan and the keypress.
+    const problem = validateInputPath(choice);
+    if (problem !== undefined) {
+      console.log(`▸ ${problem}`);
+      continue;
+    }
+    noteInputSource("suggestion");
+    return choice;
+  }
+}

package/src/interactive/picker.ts

@@ -0,0 +1,286 @@
+import { VIDEO_EXTENSIONS, run } from "@ossclip/core";
+import { binOnPath } from "../llm-detect";
+
+/**
+ * The native file/folder dialog (§136). Typing a path was the one step a
+ * non-technical user could not get past — the blocker was never the flags,
+ * it was the very first prompt.
+ *
+ * Split the way `open.ts` is split, and for the same reason: the platform
+ * matrix is decided by pure functions with a table test, so a Linux or
+ * Windows user is not the one who discovers the command was wrong. The
+ * `ossclip edit` crash that shipped in 0.1.4 for every non-macOS user is what
+ * this shape exists to prevent.
+ */
+
+export type PickMode = "file" | "folder";
+
+export interface PickerDeps {
+  platform: NodeJS.Platform;
+  env: NodeJS.ProcessEnv;
+  hasBin: (bin: string) => boolean;
+}
+
+export const livePickerDeps = (): PickerDeps => ({
+  platform: process.platform,
+  env: process.env,
+  hasBin: (bin) => binOnPath(bin),
+});
+
+/** `*.mov *.mp4 …` — the shape zenity and kdialog both want, space-joined. */
+const globs = (): string => VIDEO_EXTENSIONS.map((e) => `*.${e}`).join(" ");
+
+/**
+ * A PowerShell single-quoted string has exactly one escape: a literal `'` is
+ * written `''`. Nothing else is special in there — not `$`, not a backtick,
+ * not the `\` that fills every Windows path — which is why single quotes are
+ * what the script uses and why this is the whole escape rather than a table.
+ * `C:\Users\Ahsan's videos` is the case that makes it necessary.
+ */
+const psQuote = (s: string): string => s.replace(/'/g, "''");
+
+/**
+ * Is there a dialog to open at all? Probed rather than attempted, because
+ * offering a "Browse…" row that cannot work is worse than not offering it —
+ * the menu drops the row entirely when this is false.
+ */
+export function pickerAvailable(d: PickerDeps): boolean {
+  // Truthiness not presence, matching `isInteractive`'s treatment of CI.
+  if (d.env.OSSCLIP_NO_PICKER) return false;
+  // "Am I over SSH" is a PROXY for a signal these two platforms don't have
+  // (§136): neither macOS nor Windows exposes anything that says whether a
+  // reachable window server exists, so the remote-session hint is the best
+  // available stand-in. It has to be applied here, not just on darwin: macOS
+  // fails loudly — `choose file` returns -1743 (not authorized) — but Windows
+  // fails the dangerous way. It ships an in-box OpenSSH server, and
+  // ShowDialog() on a non-interactive window station blocks forever on a
+  // window nobody can see. `run()` has no timeout, so that is a CLI hung
+  // until Ctrl-C, the exact failure the -STA comment below exists to prevent.
+  //
+  // Note this deliberately does NOT cover Linux, which is handled below.
+  // osascript and WinForms are always installed, so there is nothing else to
+  // detect on either.
+  if (d.platform === "darwin" || d.platform === "win32") {
+    return !d.env.SSH_CONNECTION && !d.env.SSH_TTY;
+  }
+  // Linux is exempt from the SSH proxy above because it HAS the real signal.
+  // `ssh -X` sets DISPLAY=localhost:10.0 and zenity genuinely draws on the
+  // caller's local screen through the tunnel — a configuration that works.
+  // Layering the proxy on top of the evidence would override that evidence
+  // with a guess and break it.
+  //
+  // Both halves are required, and the display check is also what covers WSL
+  // without WSLg: zenity may well be installed there and still draw nowhere.
+  if (!d.env.DISPLAY && !d.env.WAYLAND_DISPLAY) return false;
+  return d.hasBin("zenity") || d.hasBin("kdialog");
+}
+
+export function pickerCommand(
+  d: PickerDeps,
+  mode: PickMode,
+  startDir?: string,
+): { bin: string; args: string[] } {
+  if (d.platform === "darwin") {
+    // Bare extensions, verified on macOS 26.3 — matching files stay
+    // selectable and the rest are dimmed. The UTI form {"public.movie"} was
+    // the alternative and is NOT used: its mkv coverage is unconfirmed, and
+    // mkv is in VIDEO_EXTENSIONS.
+    const types = VIDEO_EXTENSIONS.map((e) => `"${e}"`).join(",");
+    const clause =
+      mode === "folder"
+        ? 'choose folder with prompt "Pick a folder of clips"'
+        : `choose file with prompt "Pick your video" of type {${types}}`;
+    // startDir is always process.cwd(), never user text — but JSON.stringify
+    // still escapes it, because AppleScript string syntax is close enough to
+    // JSON's that this is the cheap correct thing rather than concatenation.
+    const loc = startDir === undefined ? "" : ` default location POSIX file ${JSON.stringify(startDir)}`;
+    return { bin: "osascript", args: ["-e", `POSIX path of (${clause}${loc})`] };
+  }
+
+  if (d.platform === "win32") {
+    // -STA is load-bearing: WinForms dialogs deadlock on the MTA thread that
+    // `powershell -Command` uses by default, and a deadlock here looks
+    // exactly like a hung CLI. `powershell` (5.1, in-box) rather than
+    // `pwsh`, which is not installed by default.
+    // startDir is honoured here too, under different property names on the
+    // two dialogs. Without it a Windows user standing in D:\shoots\raw opens
+    // at Desktop while darwin, zenity and kdialog all land in the project
+    // folder — the same flag, three platforms agreeing and one not.
+    const start =
+      startDir === undefined
+        ? ""
+        : mode === "folder"
+          ? // FolderBrowserDialog seeds its start folder from SelectedPath —
+            // the same property it hands the answer back in.
+            `$d.SelectedPath = '${psQuote(startDir)}'; `
+          : `$d.InitialDirectory = '${psQuote(startDir)}'; `;
+    const script =
+      mode === "folder"
+        ? "Add-Type -AssemblyName System.Windows.Forms; " +
+          "$d = New-Object System.Windows.Forms.FolderBrowserDialog; " +
+          start +
+          "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $d.SelectedPath }"
+        : "Add-Type -AssemblyName System.Windows.Forms; " +
+          "$d = New-Object System.Windows.Forms.OpenFileDialog; " +
+          `$d.Filter = 'Video|${VIDEO_EXTENSIONS.map((e) => `*.${e}`).join(";")}|All files|*.*'; ` +
+          start +
+          "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { $d.FileName }";
+    return { bin: "powershell", args: ["-NoProfile", "-STA", "-Command", script] };
+  }
+
+  // Linux. zenity first because it is the GTK/GNOME default and far more
+  // widely installed; kdialog is the KDE equivalent and its filter syntax is
+  // a DIFFERENT shape — `Name(*.ext)` parentheses, not zenity's pipe.
+  if (d.hasBin("zenity")) {
+    const args = [
+      "--file-selection",
+      mode === "folder" ? "--title=Pick a folder of clips" : "--title=Pick your video",
+    ];
+    if (mode === "folder") args.push("--directory");
+    else args.push(`--file-filter=Video | ${globs()}`, "--file-filter=All files | *");
+    // The trailing slash is what makes zenity read this as a starting
+    // DIRECTORY rather than a pre-filled filename.
+    if (startDir !== undefined) args.push(`--filename=${startDir}/`);
+    return { bin: "zenity", args };
+  }
+
+  if (mode === "folder") {
+    // --getexistingdirectory accepts a start dir and nothing else; passing a
+    // filter here is an error, not an ignored argument.
+    return { bin: "kdialog", args: ["--getexistingdirectory", startDir ?? "."] };
+  }
+  return {
+    bin: "kdialog",
+    args: ["--getopenfilename", startDir ?? ".", `Video files(${globs()})`],
+  };
+}
+
+/**
+ * Emptiness is the signal: no path came back. Exit codes cannot carry it —
+ * zenity and kdialog exit non-zero when dismissed, but PowerShell exits 0 and
+ * simply emits nothing, because the `if` guarding ShowDialog() just doesn't
+ * fire. So the caller passes `allowNonZero` and reads stdout, on every
+ * platform.
+ *
+ * What "no path came back" does NOT distinguish is a cancel from a silent
+ * backend failure — osascript hitting -1743 in a launchd or tmux context that
+ * sets neither SSH var, or Add-Type failing on a Windows box. That conflation
+ * is deliberate: no backend gives us a reliable way to tell the two apart
+ * (stderr is prose that varies by version and locale), and the caller's
+ * fallback is the typed-path prompt, which is the right next step either way.
+ */
+export function parsePickerResult(stdout: string): string | undefined {
+  const picked = stdout.trim();
+  return picked === "" ? undefined : picked;
+}
+
+/**
+ * How much of stderr a user is shown. A zenity or osascript failure is one
+ * short sentence, but a PowerShell one is a multi-line exception with a
+ * banner, and pasting that above a wizard prompt is its own kind of unusable.
+ */
+const MAX_STDERR_CHARS = 160;
+
+/**
+ * AppleScript's user-cancelled error. Escape in `choose file` raises -128,
+ * which osascript writes to STDERR and exits 1 — verified on darwin 25.3.0
+ * (§136): `osascript -e 'error "User canceled." number -128'` prints
+ * `6:22: execution error: User canceled. (-128)`. So on the most common
+ * platform a cancel is the LOUDEST empty-handed return, not the quietest.
+ */
+const OSASCRIPT_CANCEL = /\(-128\)/;
+
+/**
+ * Toolkit chatter, not failure. GTK and Qt print these on a perfectly good
+ * dialog — `Gtk-Message: … Failed to load module "canberra-gtk-module"`,
+ * `Gdk-CRITICAL`, `qt.qpa.wayland:`, `kf.kio…` — and they are still sitting in
+ * stderr when the user cancels. Matched per LINE rather than against the whole
+ * blob, so a real error arriving alongside chatter still surfaces (§136).
+ */
+const BENIGN_STDERR_PREFIXES = ["Gtk-Message:", "Gdk-", "qt.", "kf."];
+
+/**
+ * The one line to print when the dialog came back with nothing and stderr says
+ * something went wrong. `parsePickerResult` above explains why stdout alone
+ * cannot tell a cancel from a silent backend failure; stderr can, but only
+ * after the noise is stripped, and the noise is backend-specific (§136):
+ *
+ * - **osascript** is NOT silent on a cancel — it emits error -128 (above).
+ *   This was got wrong once, and the bug was that every Escape in the Finder
+ *   dialog told a user whose picker works perfectly that it was broken.
+ * - **zenity / kdialog** exit 1 with empty stdout and *usually* empty stderr,
+ *   but GTK and Qt leave launch chatter there routinely, cancel or not.
+ * - **PowerShell** is the only one the naive reading holds for: exit 0, empty
+ *   stdout, empty stderr, because the `if` guarding ShowDialog() just does not
+ *   fire.
+ *
+ * Deliberately NOT keyed on the exit code: this function is not given one, and
+ * PowerShell shows why it would be wrong anyway — it exits 0 on a cancel and
+ * would exit 0 on some failures too.
+ *
+ * Without a notice at all the user is in a feedback-free loop (§136, final
+ * review): a plain `ssh` into a box whose `~/.bashrc` exports `DISPLAY=:0`
+ * passes `pickerAvailable`, so `Browse…` is offered, prints "look for a new
+ * window", and returns to the menu with no window and no output — identically,
+ * forever, on every retry. The return value stays `undefined` either way; it
+ * was only ever the silence that was wrong.
+ *
+ * Pure so the wording is pinned without a dialog, which blocks on a human.
+ */
+export function pickerFailureNotice(
+  bin: string,
+  stdout: string,
+  stderr: string,
+): string | undefined {
+  if (parsePickerResult(stdout) !== undefined) return undefined;
+  if (OSASCRIPT_CANCEL.test(stderr)) return undefined;
+  const real = stderr
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l !== "" && !BENIGN_STDERR_PREFIXES.some((p) => l.startsWith(p)));
+  // First real line only: the rest is a stack or a usage dump on every backend
+  // that produces more than one.
+  const first = real[0];
+  if (first === undefined) return undefined; // a genuine cancel
+  const detail = first.length > MAX_STDERR_CHARS ? `${first.slice(0, MAX_STDERR_CHARS)}…` : first;
+  return `▸ ${bin} could not open a picker: ${detail} — type the path instead`;
+}
+
+/**
+ * Open the dialog and wait. The ONLY I/O in this module.
+ *
+ * The notice before the spawn is not decoration: a dialog that opens behind
+ * the terminal is indistinguishable from a hung CLI, and the wait here is
+ * unbounded by design — a human is deciding.
+ *
+ * The returned path is deliberately unvalidated (§136); `validateInputPath`
+ * owns existence and extension for the typed branch and this one alike, so
+ * the two cannot drift apart.
+ */
+export async function pickPath(
+  mode: PickMode,
+  deps: PickerDeps = livePickerDeps(),
+  startDir: string = process.cwd(),
+): Promise<string | undefined> {
+  const { bin, args } = pickerCommand(deps, mode, startDir);
+  console.log("▸ file picker open — look for a new window");
+  try {
+    // allowNonZero: a cancel exits non-zero on zenity and kdialog — and 0 with
+    // empty stdout on PowerShell (see parsePickerResult above, and §136). The
+    // flag covers the first shape; emptiness is what actually decides.
+    const { stdout, stderr } = await run(bin, args, { allowNonZero: true });
+    // A backend that started and then failed says so on stderr and nowhere
+    // else. Say it back, or the user is told to look for a window that will
+    // never appear and is given nothing to act on (§136).
+    const notice = pickerFailureNotice(bin, stdout, stderr);
+    if (notice !== undefined) console.log(notice);
+    return parsePickerResult(stdout);
+  } catch {
+    // `run` only rejects when the binary would not start. pickerAvailable
+    // said yes, so this is a broken install or a PATH that changed under us —
+    // fall through to typing rather than failing the whole wizard, the same
+    // call openInBrowser makes about a box with no browser on it.
+    console.log("▸ couldn't open a file picker here — type the path instead");
+    return undefined;
+  }
+}

package/src/interactive/produce-wizard.ts

@@ -1,5 +1,6 @@
 import { basename } from "node:path";
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
+import { askInput } from "./ask-input";
 import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-argv";
 import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
 
@@ -145,27 +146,10 @@ export async function produceWizard(
   // 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);
+  //
+  // Everything else now lives in ask-input.ts (§136): suggestions, the native
+  // picker, and typing, all converging on one validator.
+  const input = cfg.input ?? (await askInput());
 
   const aspect = unwrap(
     await select({

package/src/interactive/suggest-inputs.ts

@@ -0,0 +1,164 @@
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, extname, join } from "node:path";
+import { VIDEO_EXTENSIONS } from "@ossclip/core";
+
+/**
+ * The rows above "Browse…" in the input prompt (§136). A non-technical user
+ * has just hit record and wants the file they made thirty seconds ago; it is
+ * nearly always the newest video in the working directory, Downloads, or
+ * Movies. Offering it by name beats any picker.
+ *
+ * Deliberately stateless: no recents file to keep, migrate or privacy-audit,
+ * and — the reason that mattered — a recents list is EMPTY on the very first
+ * run, which is the exact run a new user needs the help on.
+ */
+
+export interface CandidateFile {
+  path: string;
+  mtimeMs: number;
+  size: number;
+}
+
+export interface Suggestion {
+  path: string;
+  label: string;
+  hint: string;
+}
+
+const VIDEO_EXT_SET = new Set<string>(VIDEO_EXTENSIONS);
+
+/**
+ * Base-1000 like Finder and Explorer report it, not base-1024.
+ *
+ * The thresholds are the ROUNDING boundary (999_500), not the unit boundary
+ * (1_000_000): `Math.round` carries into the next unit while a unit-boundary
+ * check has already committed to the current one, so a 999.7 MB screen
+ * recording printed "1000 MB" next to a sibling's "1.1 GB".
+ */
+export function humanSize(bytes: number): string {
+  if (bytes < 1_000) return `${bytes} B`;
+  if (bytes < 999_500) return `${Math.round(bytes / 1_000)} kB`;
+  if (bytes < 999_500_000) return `${Math.round(bytes / 1_000_000)} MB`;
+  return `${(bytes / 1_000_000_000).toFixed(1)} GB`;
+}
+
+export function relativeAge(msInput: number): string {
+  // A file copied off a camera with an unset clock carries an mtime years
+  // ahead, which reaches here as a NEGATIVE age. Clamped rather than special
+  // cased: "just now" is the honest label for "not older than now". Such
+  // files are deliberately still ranked (highest, by mtime) rather than
+  // filtered — a few seconds of clock skew is ordinary and the file is real.
+  const ms = Math.max(0, msInput);
+  if (ms < 60_000) return "just now";
+  if (ms < 3_600_000) return `${Math.floor(ms / 60_000)}m ago`;
+  if (ms < 86_400_000) return `${Math.floor(ms / 3_600_000)}h ago`;
+  return `${Math.floor(ms / 86_400_000)}d ago`;
+}
+
+export function tildeify(path: string, home: string): string {
+  return path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+
+export function likelyDirs(d: {
+  platform: NodeJS.Platform;
+  cwd: string;
+  home: string;
+}): string[] {
+  // Movies on macOS, Videos everywhere else — the OS's own recording default.
+  const media = join(d.home, d.platform === "darwin" ? "Movies" : "Videos");
+  return [...new Set([d.cwd, join(d.home, "Downloads"), media])];
+}
+
+export function rankSuggestions(
+  files: CandidateFile[],
+  nowMs: number,
+  home: string,
+  limit = 3,
+): Suggestion[] {
+  return files
+    .filter((file) => {
+      const name = basename(file.path);
+      if (name.startsWith(".")) return false;
+      // ossclip's own output. Cutting an already-cut video compounds the
+      // trims and is never what somebody means to do from this menu.
+      if (name.toLowerCase().endsWith(".ossclip.mp4")) return false;
+      // Case-folded before the lookup because VIDEO_EXTENSIONS is lowercase
+      // and cameras and screen recorders write `.MP4`/`.MOV` — the same fold
+      // `listFolderVideos` does, for the same reason.
+      return VIDEO_EXT_SET.has(extname(name).slice(1).toLowerCase());
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs)
+    .slice(0, limit)
+    .map((file) => ({
+      path: file.path,
+      label: tildeify(file.path, home),
+      hint: `${humanSize(file.size)} · ${relativeAge(nowMs - file.mtimeMs)}`,
+    }));
+}
+
+/** How many files to `stat` per directory. See the placement note below. */
+const MAX_STATS_PER_DIR = 2_000;
+
+/**
+ * The only filesystem in this module, and non-recursive on purpose: this
+ * runs before the first prompt paints, so a deep walk of somebody's
+ * Downloads would show up as the CLI hanging on startup.
+ */
+export async function scanLikelyDirs(
+  dirs: string[] = likelyDirs({ platform: process.platform, cwd: process.cwd(), home: homedir() }),
+): Promise<CandidateFile[]> {
+  const out: CandidateFile[] = [];
+  for (const dir of dirs) {
+    let names: string[];
+    try {
+      names = (await readdir(dir, { withFileTypes: true }))
+        // Symlinks are followed, matching `listFolderVideos` in concat.ts: a
+        // folder of symlinks into another drive is a normal way to stage
+        // takes. The `stat` below resolves the target, and a dangling link
+        // throws into the per-file catch there.
+        .filter((e) => e.isFile() || e.isSymbolicLink())
+        .map((e) => e.name)
+        // Case-folded because VIDEO_EXTENSIONS is lowercase and recorders
+        // write `.MP4`/`.MOV`, the same fold `listFolderVideos` does.
+        .filter((name) => VIDEO_EXT_SET.has(extname(name).slice(1).toLowerCase()))
+        // The cap sits AFTER the filter on purpose: `readdir` has already
+        // materialised every dirent, so capping before it saves no I/O and
+        // throws away videos at random — readdir order is filesystem order,
+        // not mtime, so the take recorded 30 seconds ago is as likely to land
+        // in the discarded tail as anything else. Here it bounds the only
+        // real cost, the per-file stat.
+        .slice(0, MAX_STATS_PER_DIR);
+    } catch {
+      // A missing ~/Movies or an unreadable directory is ordinary. The
+      // suggestions are a convenience; nothing here may fail the wizard.
+      continue;
+    }
+    // Stat'd in parallel: awaited one at a time, a directory of 400 clips on
+    // an SMB share or an iCloud "Optimize Storage" ~/Movies is seconds of
+    // dead terminal before the first prompt paints, which is the startup hang
+    // non-recursion alone does not prevent. try/catch inside each task rather
+    // than allSettled because the recovery is identical for every failure —
+    // drop that one file — and this keeps the settled result already typed.
+    const stats = await Promise.all(
+      names.map(async (name): Promise<CandidateFile | undefined> => {
+        const path = join(dir, name);
+        try {
+          const st = await stat(path);
+          // A symlink to a DIRECTORY named `takes.mp4` passes the dirent
+          // check above and stats fine; without this it would be offered
+          // carrying the directory's size and mtime. concat.ts:346-353 —
+          // the parity this module claims — resolves and drops it too.
+          if (!st.isFile()) return undefined;
+          return { path, mtimeMs: st.mtimeMs, size: st.size };
+        } catch {
+          // Raced with a delete between readdir and stat, or a dangling
+          // symlink — skips this file only, never the whole directory.
+          return undefined;
+        }
+      }),
+    );
+    for (const file of stats) if (file !== undefined) out.push(file);
+  }
+  return out;
+}

package/src/program.ts

@@ -7,6 +7,21 @@ import { CleanupLevelSchema, SceneComponentIdSchema } from "@ossclip/core";
 import { STUDIO_ENTRY } from "@ossclip/renderer";
 import { loadEnvFiles } from "./env";
 import { produce } from "./produce";
+// The one interactive import that is STATIC rather than `await import()`: the
+// `resetInputSource()` run boundary in `buildProgram` has to run synchronously
+// while the program is being built, and `buildProgram` cannot await. The graph
+// already loads @ossclip/renderer and @ossclip/scenes eagerly through
+// produce.ts, so clack riding along costs ~14ms on a ~320ms startup — cheap
+// enough not to trade for a racy fire-and-forget import (§136).
+//
+// Consequence worth stating for whoever edits ask-input.ts next: this module,
+// and everything it imports (picker.ts, prompts.ts → @clack/prompts,
+// suggest-inputs.ts), is now EAGER on every ossclip invocation — `--version`
+// and `doctor` included. A heavy dependency added there is no longer free.
+// Removing this line to "restore laziness" deletes the run boundary with it:
+// `input_source` would then report the PREVIOUS run's branch, and the only
+// test that notices is the buildProgram case in telemetry.test.ts.
+import { inputSourceUsed, resetInputSource } from "./interactive/ask-input";
 import { setReplayArgv } from "./replay-argv";
 import {
   bootstrapTelemetry,
@@ -38,6 +53,19 @@ const envFiles = loadEnvFiles();
 export function buildProgram(): Command {
   const program = new Command();
 
+  // §136: the input-source telemetry is module state, so something has to say
+  // when a RUN begins. Not the produce action — every wizard route re-enters
+  // that same action through `program.parseAsync` (§129), so a reset there
+  // fires on the re-entered parse, AFTER `askInput` recorded the branch, and
+  // `input_source` would read "argv" for every wizard run: the feature would
+  // measure exactly nothing. Nor is the process the boundary — a batch or REPL
+  // driver runs produce more than once, and the second run would report the
+  // first one's branch. The PROGRAM CONSTRUCTION is the boundary: commander 12
+  // keeps option state across parseAsync calls (see the bare-`produce` refusal
+  // below), so any batch has to rebuild the program per run anyway, which makes
+  // one reset per `buildProgram` exactly one per run in both cases.
+  resetInputSource();
+
   // Before dispatch, so the one-time first-run notice precedes any command's
   // own output. Inert in this repo's tests by construction: while POSTHOG_KEY
   // is the placeholder, bootstrap touches no disk and sends nothing (FINDINGS
@@ -433,6 +461,10 @@ export function buildProgram(): Command {
           render: opts.render !== false,
           source_duration_bucket: durationBucket(result.sourceDurationSec),
           scenes: result.sceneCount,
+          // Which branch of the input prompt was used — a branch name, never
+          // the path itself (§136). The picker exists because typing a path
+          // blocked non-technical users; this is how we find out if it helped.
+          input_source: inputSourceUsed(),
         });
         if (!telemetry.disabled) {
           telemetry.state.produceCount += 1;