ossclip 0.1.5 → 0.1.6

package/src/interactive/produce-wizard.ts

@@ -0,0 +1,180 @@
+import { basename } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { produceArgv, type ProduceAnswers, type ProduceExtras } from "./produce-argv";
+import { assertInteractive, confirm, intro, multiselect, select, text, unwrap } from "./prompts";
+
+/**
+ * The produce wizard. Twenty-five flags sorted into three tiers: six always
+ * asked, seven behind one "anything else?" multiselect, and twelve that stay
+ * flags-only because they are debug or internal surfaces.
+ *
+ * --clip-window is deliberately NOT offered: --clip runs write it into
+ * command.json so the editor's Render replays the same window without an LLM
+ * call. A human picking it from a menu is a corrupted replay, not a
+ * preference.
+ */
+
+const EXTRAS = [
+  { value: "graphicsClip", label: "Only the strongest N seconds of a long take", hint: "--clip" },
+  { value: "sourceFit", label: "Show the whole frame instead of cropping", hint: "--source-fit contain" },
+  { value: "speaker", label: "Say who is on camera", hint: "--speaker" },
+  { value: "whisperModel", label: "Pick a transcription model", hint: "--whisper-model" },
+  { value: "blooperMarker", label: "Cut flubbed takes on a spoken word", hint: "--blooper-marker" },
+  { value: "sourceIsEdited", label: "Source already has burned-in text", hint: "--source-is-edited" },
+  { value: "llm", label: "Choose the LLM provider", hint: "--llm" },
+] as const;
+
+/**
+ * `produce.ts`'s own §93b guard throws "--clip needs the producer's
+ * editorial judgement: add --produce" whenever `--clip` shows up without
+ * `--produce`. Offering "Only the strongest N seconds" to someone who just
+ * answered "no" to graphics is offering a menu item that is a guaranteed
+ * error nine prompts later — so the clip extra is only ever listed once
+ * graphics is already on. Exported and kept pure so this can be asserted
+ * without a TTY.
+ */
+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[]> {
+  assertInteractive("produce wizard");
+  intro("ossclip produce");
+
+  const input = unwrap(
+    await text({
+      message: "Video file",
+      placeholder: "./raw/take1.mp4",
+      validate: (v) => {
+        if (!v) return "a path is required";
+        if (!existsSync(v)) return `no such file: ${v}`;
+        if (!statSync(v).isFile()) return `${v} is a directory, not a video file`;
+        return undefined;
+      },
+    }),
+  ) as string;
+
+  const aspect = unwrap(
+    await select({
+      message: "Shape",
+      initialValue: "9:16",
+      options: [
+        { value: "9:16", label: "Vertical 9:16", hint: "shorts, reels" },
+        { value: "16:9", label: "Landscape 16:9", hint: "1920x1080" },
+      ],
+    }),
+  ) as ProduceAnswers["aspect"];
+
+  const cleanup = unwrap(
+    await select({
+      message: "How hard should it cut?",
+      initialValue: "standard",
+      options: [
+        { value: "exact", label: "exact", hint: "no cuts at all" },
+        { value: "light", label: "light" },
+        { value: "standard", label: "standard", hint: "recommended" },
+        { value: "aggressive", label: "aggressive" },
+      ],
+    }),
+  ) as ProduceAnswers["cleanup"];
+
+  const graphics = unwrap(
+    await confirm({ message: "Plan title cards and graphics with an LLM?", initialValue: false }),
+  ) as boolean;
+
+  // Only asked under graphics: the intent feeds the producer brain, which
+  // does not run otherwise.
+  const intent = graphics
+    ? (unwrap(
+        await text({
+          message: "What is the video about?",
+          placeholder: "educational video about agents",
+        }),
+      ) as string)
+    : undefined;
+
+  const defaultOut = `${basename(input).replace(/\.[^.]+$/, "")}.ossclip.mp4`;
+  const out = unwrap(
+    await text({ message: "Output file", placeholder: defaultOut, defaultValue: "" }),
+  ) as string;
+
+  const chosen = unwrap(
+    await multiselect({
+      message: "Anything else? (space to toggle, enter to accept)",
+      options: extrasFor(graphics),
+      required: false,
+    }),
+  ) as string[];
+
+  const extras: ProduceExtras = {};
+  if (chosen.includes("graphicsClip")) {
+    extras.clip = Number.parseFloat(
+      unwrap(
+        await text({
+          message: "How many seconds?",
+          placeholder: "60",
+          validate: (v) => {
+            const n = Number.parseFloat(v ?? "");
+            // Mirrors the CLI's own §93a guard: a zero or a typo must be
+            // rejected here rather than coerced into a NaN-length window.
+            return Number.isFinite(n) && n > 0 ? undefined : "a positive number of seconds";
+          },
+        }),
+      ) as string,
+    );
+  }
+  if (chosen.includes("sourceFit")) extras.sourceFit = "contain";
+  if (chosen.includes("sourceIsEdited")) extras.sourceIsEdited = true;
+  if (chosen.includes("speaker")) {
+    extras.speaker = unwrap(
+      await text({
+        message: "Who is on camera?",
+        placeholder: "Ahsan, host of Code with Ahsan",
+        // Prefilled from ~/.ossclip/config.json where set, so this answer
+        // persists through the config that already exists.
+        initialValue: cfg.speaker ?? "",
+      }),
+    ) as string;
+  }
+  if (chosen.includes("whisperModel")) {
+    extras.whisperModel = unwrap(
+      await select({
+        message: "Transcription model",
+        initialValue: "small.en",
+        options: [
+          { value: "base.en", label: "base.en", hint: "fastest, least accurate" },
+          { value: "small.en", label: "small.en", hint: "default" },
+          { value: "medium.en", label: "medium.en", hint: "slowest, most accurate" },
+        ],
+      }),
+    ) as string;
+  }
+  if (chosen.includes("blooperMarker")) {
+    extras.blooperMarker = unwrap(
+      await text({ message: "Which word marks a flubbed take?", placeholder: "blooper" }),
+    ) as string;
+  }
+  if (chosen.includes("llm")) {
+    extras.llm = unwrap(
+      await select({
+        message: "LLM provider",
+        options: [
+          { value: "claude-cli", label: "claude-cli", hint: "your logged-in Claude Code, no API charges" },
+          { value: "claude", label: "claude", hint: "needs ANTHROPIC_API_KEY" },
+          { value: "gemini", label: "gemini", hint: "needs GEMINI_API_KEY" },
+          { value: "mock", label: "mock", hint: "no LLM at all" },
+        ],
+      }),
+    ) as ProduceExtras["llm"];
+  }
+
+  return produceArgv({
+    input,
+    aspect,
+    cleanup,
+    graphics,
+    intent,
+    out: out || undefined,
+    extras,
+  });
+}

package/src/interactive/prompts.ts

@@ -0,0 +1,6 @@
+/**
+ * Re-export surface for clack, so every interactive module imports prompts
+ * from one place and the dependency can be swapped without touching wizards.
+ */
+export { confirm, intro, isCancel, log, multiselect, outro, select, text } from "@clack/prompts";
+export { assertInteractive, isInteractive, unwrap } from "./tty";

package/src/interactive/render.ts

@@ -0,0 +1,30 @@
+/**
+ * Renders an argv into the command line a user could have typed. Printed as
+ * `▸ running:` before every wizard run, so the wizard is also a flags lesson.
+ *
+ * This takes the SAME array that gets executed. A wizard that teaches one
+ * command and runs another is worse than no wizard, and rendering from the
+ * executed array makes that failure unrepresentable rather than unlikely.
+ */
+
+// Deliberately an allowlist, not a "needs quoting" denylist: a character
+// nobody thought about ends up quoted (harmless) instead of unquoted (wrong).
+// Backslash and colon are in it so `D:\CWA\TiDB` — the exact shape of path
+// this feature exists for — renders bare rather than wrapped in quotes.
+const SAFE = /^[A-Za-z0-9._\-/\\:=@+,]+$/;
+
+export function quoteArg(arg: string, platform: NodeJS.Platform = process.platform): string {
+  if (SAFE.test(arg)) return arg;
+  if (platform === "win32") {
+    // cmd doubles an embedded quote. Backslashes are left alone — escaping
+    // them would corrupt every Windows path this prints.
+    return `"${arg.replace(/"/g, '""')}"`;
+  }
+  // POSIX single quotes have no escape character: close, emit an escaped
+  // quote, reopen.
+  return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+
+export function renderCommand(argv: string[], platform: NodeJS.Platform = process.platform): string {
+  return ["ossclip", ...argv].map((a) => quoteArg(a, platform)).join(" ");
+}

package/src/interactive/resolve-workdir.ts

@@ -0,0 +1,115 @@
+import { sep as hostSep } from "node:path";
+import { renderCommand } from "./render";
+
+/**
+ * Resolving what a user meant by `ossclip edit <path>`.
+ *
+ * The bug this exists for: `produce` writes into
+ * `<input dir>/.ossclip/<name>/`, `edit` wants that nested directory, and the
+ * old failure — "no render-props.json in <dir> — run `ossclip produce` there
+ * first" — named a fix the user had already performed. It also pointed away
+ * from `ossclip edit` with no argument, which has opened a picker over recent
+ * runs since R17 §83 and would have solved it instantly.
+ *
+ * Pure by construction: the caller passes a probe record and this decides.
+ * That keeps every rung testable without a filesystem.
+ */
+
+export interface Candidate {
+  path: string;
+  mtimeMs: number;
+}
+
+/**
+ * Why the probe came back empty, when it was not simply "nothing produced
+ * here yet". `missing` is ENOENT, `unreadable` is EACCES/EPERM — or any
+ * other errno, which is reported with its `code` rather than silently
+ * becoming "no output".
+ */
+export interface ProbeFailure {
+  reason: "missing" | "unreadable";
+  code?: string;
+}
+
+export interface WorkdirProbe {
+  /** Does `dir` itself hold a render-props.json? */
+  isWorkdir: boolean;
+  /** Directories under `dir/.ossclip/` that hold a render-props.json. */
+  candidates: Candidate[];
+  /**
+   * Absent when the path was read fine. The probe carries the fact; the
+   * words are this module's job — the alternative was a second channel of
+   * error state that only the caller could see.
+   */
+  reason?: ProbeFailure["reason"];
+  code?: string;
+}
+
+export type Resolution =
+  | { kind: "resolved"; workdir: string; via: "direct" | "nested" }
+  | { kind: "choose"; candidates: Candidate[] }
+  | { kind: "none"; message: string };
+
+export function resolveWorkdir(
+  dir: string,
+  probe: WorkdirProbe,
+  sep: string = hostSep,
+): Resolution {
+  // Checked BEFORE descending: a workdir that happens to contain its own
+  // .ossclip must not be skipped in favour of its children.
+  if (probe.isWorkdir) return { kind: "resolved", workdir: dir, via: "direct" };
+
+  const newestFirst = [...probe.candidates].sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const only = newestFirst[0];
+  if (only && newestFirst.length === 1) {
+    return { kind: "resolved", workdir: only.path, via: "nested" };
+  }
+  if (newestFirst.length > 1) return { kind: "choose", candidates: newestFirst };
+
+  // Before the layout explanation, because "no ossclip output under X — run
+  // produce" is a lie in both of these cases, and it is the exact lie this
+  // branch exists to kill. A typo'd path was told to produce into
+  // `<the typo>/your-video.mp4`, a path that can never exist; an unreadable
+  // one was told to redo a run that is sitting right there.
+  if (probe.reason === "missing") {
+    return {
+      kind: "none",
+      message:
+        `no such path: ${dir}\n\n` +
+        `  Nothing of yours is there to edit — check the spelling.\n\n` +
+        `  Or pick from recent runs:   ossclip edit`,
+    };
+  }
+  if (probe.reason === "unreadable") {
+    return {
+      kind: "none",
+      message:
+        `can't read ${dir}${probe.code === undefined ? "" : ` (${probe.code})`}\n\n` +
+        `  The path is there, but this user can't read it —\n` +
+        `  check its permissions and try again.`,
+    };
+  }
+
+  return {
+    kind: "none",
+    message:
+      `no ossclip output under ${dir}\n\n` +
+      `  produce writes into <video's folder>${sep}.ossclip${sep}<name>${sep} —\n` +
+      `  that nested folder is what \`edit\` wants, not the folder you ran produce in.\n\n` +
+      `  Produce one:                ossclip produce ${dir}${sep}your-video.mp4\n` +
+      `  Or pick from recent runs:   ossclip edit`,
+  };
+}
+
+/**
+ * The several-candidates message for a session with no TTY, where the
+ * interactive picker cannot run. Each line is rendered through
+ * renderCommand so a path containing a space pastes into a shell as ONE
+ * argument — an unquoted list defeats the only thing this branch is for.
+ */
+export function candidateListMessage(dir: string, candidates: Candidate[]): string {
+  return (
+    `several produce runs under ${dir} — name one:\n` +
+    candidates.map((c) => `  ${renderCommand(["edit", c.path])}`).join("\n")
+  );
+}

package/src/interactive/tty.ts

@@ -0,0 +1,62 @@
+import { cancel, isCancel } from "@clack/prompts";
+
+/**
+ * The ONE interactivity check in the codebase. Everything that might prompt
+ * asks this; nothing else sniffs `isTTY` directly. A second, subtly different
+ * check is how a CLI ends up hanging in somebody's CI waiting on an answer
+ * nobody can give.
+ */
+export interface TtyDeps {
+  env: NodeJS.ProcessEnv;
+  stdinIsTty: boolean;
+  stdoutIsTty: boolean;
+}
+
+const liveDeps = (): TtyDeps => ({
+  env: process.env,
+  // `isTTY` is `undefined` rather than `false` on a pipe — compare explicitly.
+  stdinIsTty: process.stdin.isTTY === true,
+  stdoutIsTty: process.stdout.isTTY === true,
+});
+
+export function isInteractive(deps: TtyDeps = liveDeps()): boolean {
+  // Truthiness, not presence: some shells export CI= (empty) merely because
+  // the variable is declared, and that must not silence prompts on a real
+  // terminal.
+  if (deps.env.OSSCLIP_NO_INTERACTIVE) return false;
+  if (deps.env.CI) return false;
+  return deps.stdinIsTty && deps.stdoutIsTty;
+}
+
+/**
+ * Cancelling is not a failure. Ctrl-C or Esc at any prompt exits 0 with the
+ * same wording `ossclip setup` already uses for the same situation — never a
+ * stack trace, never a half-run.
+ */
+const exitOnCancel = (): never => {
+  cancel("nothing changed.");
+  process.exit(0);
+};
+
+export function unwrap<T>(
+  value: T | symbol,
+  onCancel: () => never = exitOnCancel,
+  // Injected because clack's sentinel is a module-local Symbol("clack:cancel")
+  // that is never exported — a test cannot construct one, and Symbol.for()
+  // produces a look-alike with a different identity that isCancel rejects.
+  cancelled: (v: unknown) => boolean = isCancel,
+): T {
+  if (cancelled(value)) return onCancel();
+  return value as T;
+}
+
+/**
+ * Guards the prompt helpers themselves. Reaching a prompt without a TTY means
+ * a caller forgot to check `isInteractive()` — a programming error that should
+ * fail loudly in the test suite, not silently block a pipeline.
+ */
+export function assertInteractive(what: string, check: () => boolean = () => isInteractive()): void {
+  if (!check()) {
+    throw new Error(`internal: ${what} tried to prompt without a TTY`);
+  }
+}

package/src/interactive/workdir-probe.ts

@@ -0,0 +1,70 @@
+import { readdir, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { Candidate, ProbeFailure, WorkdirProbe } from "./resolve-workdir";
+
+/** The errno of a filesystem rejection, when it has one. */
+const errnoOf = (err: unknown): string | undefined => {
+  const code = (err as { code?: unknown } | null)?.code;
+  return typeof code === "string" ? code : undefined;
+};
+
+/**
+ * Which of the three situations a failed read was. Catching them as one is
+ * the founding bug of this branch in miniature: an unreadable directory got
+ * reported as "no ossclip output — run produce", which tells a user to redo
+ * work that is sitting right there.
+ *
+ * An unexpected class (ELOOP, ENOTDIR, …) is reported as unreadable rather
+ * than swallowed, and carries its code so the message names it instead of
+ * inventing a cause.
+ */
+const failureFor = (err: unknown): ProbeFailure => {
+  const code = errnoOf(err);
+  if (code === "ENOENT") return { reason: "missing", code };
+  return { reason: "unreadable", code };
+};
+
+/**
+ * The only filesystem in the workdir ladder. Kept deliberately thin so
+ * `resolveWorkdir` stays pure and every rung of the decision is tested
+ * without a temp directory.
+ */
+export async function probeWorkdir(target: string): Promise<{ dir: string; probe: WorkdirProbe }> {
+  const abs = resolve(target);
+
+  // Pointing at the video rather than its folder is a reasonable guess, and
+  // the runs live beside it — so a file target resolves to its parent.
+  let dir = abs;
+  try {
+    if ((await stat(abs)).isFile()) dir = dirname(abs);
+  } catch (err) {
+    // Not thrown: the "none" rung's message is a better error than a raw
+    // ENOENT — but it needs to know WHICH failure this was to say so.
+    return { dir: abs, probe: { isWorkdir: false, candidates: [], ...failureFor(err) } };
+  }
+
+  const isWorkdir = existsSync(join(dir, "render-props.json"));
+
+  const candidates: Candidate[] = [];
+  const nest = join(dir, ".ossclip");
+  let failure: ProbeFailure | undefined;
+  try {
+    for (const entry of await readdir(nest, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const path = join(nest, entry.name);
+      // A workdir is exactly "a directory a produce run wrote its props
+      // into" — the same definition edit.ts uses. A run killed mid-flight
+      // leaves a directory with no props, and offering it would 404 the page.
+      if (!existsSync(join(path, "render-props.json"))) continue;
+      candidates.push({ path, mtimeMs: (await stat(path)).mtimeMs });
+    }
+  } catch (err) {
+    // ENOENT is the ordinary "no .ossclip here" — an empty candidate list,
+    // not an error. A directory that exists and cannot be read is NOT that,
+    // and must not be described as if it were.
+    if (errnoOf(err) !== "ENOENT") failure = failureFor(err);
+  }
+
+  return { dir, probe: { isWorkdir, candidates, ...failure } };
+}

package/src/produce.ts

@@ -88,6 +88,7 @@ import {
   type Transcript,
 } from "@ossclip/core";
 import { recordRecentProject } from "./edit";
+import { editHint } from "./interactive/edit-hint";
 import { renderCover, renderProduction } from "@ossclip/renderer";
 import {
   coverTextRect,
@@ -96,6 +97,17 @@ import {
   routeAroundSourceText,
 } from "@ossclip/scenes/geometry";
 
+/**
+ * What a finished run tells its caller. The workdir is what the post-produce
+ * editor offer opens; `rendered` is false for a --no-render run, which has
+ * props but no video.
+ */
+export interface ProduceResult {
+  workdir: string;
+  out?: string;
+  rendered: boolean;
+}
+
 export interface ProduceOptions {
   out?: string;
   cleanup: CleanupLevel;
@@ -190,7 +202,7 @@ async function preflight(bin: string, hint: string): Promise<void> {
   }
 }
 
-export async function produce(inputArg: string, opts: ProduceOptions): Promise<void> {
+export async function produce(inputArg: string, opts: ProduceOptions): Promise<ProduceResult> {
   const cfg = loadConfig();
   const input = resolve(inputArg);
   if (!existsSync(input)) throw new Error(`input not found: ${input}`);
@@ -1392,7 +1404,8 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
 
   if (!opts.render) {
     console.log(`▸ skipping render (--no-render). Props at ${join(work, "render-props.json")}`);
-    return;
+    console.log(editHint(work));
+    return { workdir: work, rendered: false };
   }
 
   const outPath = resolve(opts.out ?? input.replace(/(\.[^.]+)?$/, ".ossclip.mp4"));
@@ -1536,4 +1549,6 @@ export async function produce(inputArg: string, opts: ProduceOptions): Promise<v
   // best-effort, so a read-only home dir never fails the render.
   await recordRecentProject(work);
   console.log(`✓ done → ${outPath}`);
+  console.log(editHint(work));
+  return { workdir: work, out: outPath, rendered: true };
 }