ossclip 0.1.24 → 0.1.26

package/src/interactive/thumbnail-approve.ts

@@ -0,0 +1,217 @@
+import { copyFile, writeFile } from "node:fs/promises";
+import {
+  ThumbnailConceptSchema,
+  approvedOverlayText,
+  buildThumbnailPrompt,
+  type GenerateThumbnailImageOptions,
+  type ThumbnailConcept,
+  type ThumbnailConceptApproved,
+} from "@ossclip/core";
+import { openInViewer } from "../open";
+import { select, text, unwrap } from "./prompts";
+
+/**
+ * The pre-render concept approval and the post-generation retry loop
+ * (thumbnail UX, 2026-08-16). Both exist for the same field incident class:
+ * the concept/image models make a judgement call the user only discovers
+ * AFTER a multi-minute render — approval moves the concept judgement before
+ * the render, the retry loop makes the image judgement cheap to redo.
+ *
+ * Every prompt goes through the injectable `ApprovePrompts` seam so the loop
+ * logic is testable with a scripted object — no TTY, no clack, the tty.ts
+ * doctrine applied one layer up. The default implementation wraps clack via
+ * ./prompts and inherits its cancel-exits-cleanly behavior (unwrap).
+ */
+
+export interface ApprovePrompts {
+  /** Returns the chosen option's value — already unwrapped, never a cancel symbol. */
+  select(opts: {
+    message: string;
+    options: { value: string; label: string; hint?: string }[];
+  }): Promise<string>;
+  /** Returns the typed text — already unwrapped. */
+  text(opts: { message: string; initialValue?: string; placeholder?: string }): Promise<string>;
+}
+
+/** The live clack-backed prompts; tests inject a scripted replacement. */
+export function clackApprovePrompts(): ApprovePrompts {
+  return {
+    select: async (opts) => unwrap(await select(opts)) as string,
+    text: async (opts) => unwrap(await text({ ...opts, defaultValue: "" })) as string,
+  };
+}
+
+/**
+ * The concept as the three lines the approval prompt displays. Pure so the
+ * formatting (overlay first — it is the one thing the viewer will read) is
+ * pinned without a TTY.
+ */
+export function formatConceptLines(concept: ThumbnailConcept): string[] {
+  return [
+    `  overlay: ${concept.overlayText}`,
+    `  scene:   ${concept.scene}`,
+    `  style:   ${concept.styleNotes}`,
+  ];
+}
+
+/**
+ * Re-validate a hand-edited concept: through the SAME schema the LLM's
+ * output takes (an edit is user input, parsed not coerced), plus
+ * `approvedOverlayText`'s WORD cap on the overlay — the schema caps
+ * characters, but overlay text at thumbnail size keeps a cover banner's 4-9
+ * word ceiling (§35), and an edit must not smuggle a paragraph past the cap
+ * the generated path enforces. The helper is thumbnailStep's exact
+ * treatment, shared so the image cache key never sees two spellings of one
+ * concept.
+ */
+export function editedConcept(fields: {
+  scene: string;
+  overlayText: string;
+  styleNotes: string;
+}): ThumbnailConcept {
+  const parsed = ThumbnailConceptSchema.parse(fields);
+  return { ...parsed, overlayText: approvedOverlayText(parsed.overlayText) };
+}
+
+export interface ApproveConceptArgs {
+  /**
+   * One concept call, note optional — produce injects the provider-backed
+   * call (with audience/brief steer and phase timing); tests inject a stub.
+   */
+  generateConcept: (note?: string) => Promise<ThumbnailConcept>;
+  /** A concept to present first (the workdir cache) — skips the initial call. */
+  initial?: ThumbnailConcept;
+  prompts?: ApprovePrompts;
+  log?: (line: string) => void;
+}
+
+/**
+ * The approval loop: display → use / edit / regenerate-with-note / skip.
+ * Returns what the caller writes into `thumbnail-concept-approved.json` —
+ * the approved concept, or `{skip: true}` so the post-render step (and every
+ * non-TTY replay) skips loudly instead of silently regenerating.
+ */
+export async function approveThumbnailConcept(
+  args: ApproveConceptArgs,
+): Promise<ThumbnailConceptApproved> {
+  const { prompts = clackApprovePrompts(), log = console.log } = args;
+  let concept = args.initial ?? (await args.generateConcept());
+  for (;;) {
+    log("▸ thumbnail concept:");
+    for (const line of formatConceptLines(concept)) log(line);
+    const choice = await prompts.select({
+      message: "Use this thumbnail concept?",
+      options: [
+        { value: "use", label: "use it" },
+        { value: "edit", label: "edit fields" },
+        { value: "regenerate", label: "regenerate with a note" },
+        { value: "skip", label: "skip thumbnail", hint: "the frame-grab cover stands" },
+      ],
+    });
+    if (choice === "use") return concept;
+    if (choice === "skip") return { skip: true };
+    if (choice === "edit") {
+      // Prefilled per field so an edit is a tweak, not a retype; the result
+      // loops back to the display so the user confirms what they typed.
+      concept = editedConcept({
+        overlayText: await prompts.text({
+          message: "Overlay text (3-6 punchy words)",
+          initialValue: concept.overlayText,
+        }),
+        scene: await prompts.text({ message: "Scene", initialValue: concept.scene }),
+        styleNotes: await prompts.text({ message: "Style notes", initialValue: concept.styleNotes }),
+      });
+      continue;
+    }
+    // regenerate: one note, one fresh concept call, back to the display.
+    const note = (
+      await prompts.text({
+        message: "What should the concept do differently?",
+        placeholder: "less abstract — show the actual terminal output",
+      })
+    ).trim();
+    concept = await args.generateConcept(note || undefined);
+  }
+}
+
+export interface ThumbnailRetryArgs {
+  /** The `<out>.thumbnail.png` the step wrote — overwritten on each retry. */
+  imagePath: string;
+  /** The workdir cache — overwritten too, or a warm re-run would revert the retry. */
+  imageCachePath: string;
+  /** The approved/generated concept — UNCHANGED across retries by design. */
+  concept: ThumbnailConcept;
+  apiKey: string;
+  model: string;
+  portrait: { data: string; mimeType: string };
+  /** The injected-generate seam (thumbnailStep's exactly) — tests never touch the SDK. */
+  generate: (opts: GenerateThumbnailImageOptions) => Promise<Uint8Array>;
+  /** The injected viewer seam (openInViewer's shape) — tests never spawn a viewer. */
+  open?: (path: string) => void;
+  prompts?: ApprovePrompts;
+  log?: (line: string) => void;
+}
+
+/**
+ * The post-generation retry loop: keep, or regenerate with a note. Each
+ * retry is ONE image call — the concept stays fixed and the note rides the
+ * image prompt as a must-honor revision (buildThumbnailPrompt's
+ * `revisionNote`) — and the loop asks again after every result, so the user
+ * can iterate until "keep". A failed retry keeps the previous image on disk
+ * (both files were only overwritten on success) and says so.
+ */
+export async function thumbnailRetryLoop(args: ThumbnailRetryArgs): Promise<void> {
+  const { prompts = clackApprovePrompts(), log = console.log, open = openInViewer } = args;
+  for (;;) {
+    // Show the image before EVERY keep/regenerate prompt — top of the loop,
+    // so each regeneration reopens the NEW file. The user is confirming what
+    // they see, not a path (thumbnail UX, 2026-08-17).
+    try {
+      open(args.imagePath);
+    } catch {
+      // A headless-ish env or a missing xdg-open must not kill an
+      // interactive confirm that can proceed on the printed path — same
+      // posture as openInBrowser's error handler.
+      log(`▸ could not open viewer — ${args.imagePath}`);
+    }
+    const choice = await prompts.select({
+      message: `Thumbnail written → ${args.imagePath}. Keep it?`,
+      options: [
+        { value: "keep", label: "keep" },
+        { value: "regenerate", label: "regenerate with a note" },
+      ],
+    });
+    if (choice === "keep") return;
+    const note = (
+      await prompts.text({
+        message: "What should change in the image?",
+        placeholder: "warmer lighting, less clutter behind me",
+      })
+    ).trim();
+    // An empty note would regenerate with zero new information — the same
+    // dice re-rolled at API cost. Re-ask instead of guessing what changed.
+    if (!note) continue;
+    try {
+      const bytes = await args.generate({
+        apiKey: args.apiKey,
+        model: args.model,
+        prompt: buildThumbnailPrompt(args.concept, true, note),
+        portrait: args.portrait,
+      });
+      // Cache first, then the destination — the same overwrite order a crash
+      // between the two degrades safest under: a stale destination beside a
+      // fresh cache self-heals on the next run's copy, the reverse would
+      // revert the user's retry on every warm re-run.
+      await writeFile(args.imageCachePath, bytes);
+      await copyFile(args.imageCachePath, args.imagePath);
+      log(`✓ thumbnail regenerated → ${args.imagePath}`);
+    } catch (err) {
+      // §132 posture verbatim from thumbnailStep: surface the API's message,
+      // never retry silently, and the previous image stands.
+      log(
+        `▸ thumbnail: regeneration failed (${err instanceof Error ? err.message : String(err)}) ` +
+          "— keeping the previous image",
+      );
+    }
+  }
+}

package/src/open.ts

@@ -1,24 +1,29 @@
 import { spawn } from "node:child_process";
+import { dirname } from "node:path";
 
 /**
- * Open a URL in the default browser, per platform. The old code spawned
- * macOS's `open` unconditionally — on Linux and Windows that ENOENT became
- * an unhandled 'error' event and took the whole edit server down with it.
+ * Open a target — URL or file path, every platform's opener treats them
+ * identically — in the OS default handler, per platform. The old code
+ * spawned macOS's `open` unconditionally — on Linux and Windows that ENOENT
+ * became an unhandled 'error' event and took the whole edit server down
+ * with it.
  *
  * Failure here is not an error: a headless box or WSL without a browser is
  * a normal place to run `ossclip edit` — print the URL and move on.
  */
 export function openCommand(
-  url: string,
+  target: string,
   platform: NodeJS.Platform,
 ): { bin: string; args: string[] } {
-  if (platform === "darwin") return { bin: "open", args: [url] };
+  if (platform === "darwin") return { bin: "open", args: [target] };
   if (platform === "win32") {
     // `start` is a cmd built-in, not an executable; the empty string is
-    // start's window-title slot so the URL isn't eaten as the title.
-    return { bin: "cmd", args: ["/c", "start", "", url] };
+    // start's window-title slot so the target isn't eaten as the title —
+    // load-bearing for file paths with spaces, which spawn quotes and
+    // `start` would otherwise read as its title argument.
+    return { bin: "cmd", args: ["/c", "start", "", target] };
   }
-  return { bin: "xdg-open", args: [url] };
+  return { bin: "xdg-open", args: [target] };
 }
 
 export function openInBrowser(url: string, platform: NodeJS.Platform = process.platform): void {
@@ -28,3 +33,54 @@ export function openInBrowser(url: string, platform: NodeJS.Platform = process.p
     console.log(`▸ couldn't open a browser here — open ${url} yourself`);
   });
 }
+
+/**
+ * Open a file in the OS default viewer — the thumbnail confirm needs the
+ * user to SEE the image before answering keep/regenerate, not squint at a
+ * path. Same posture as openInBrowser: a missing xdg-open on a headless-ish
+ * box logs one line and the interactive flow proceeds on the printed path.
+ */
+export function openInViewer(path: string, platform: NodeJS.Platform = process.platform): void {
+  const { bin, args } = openCommand(path, platform);
+  const child = spawn(bin, args, { stdio: "ignore", detached: false });
+  child.on("error", () => {
+    console.log(`▸ could not open viewer — ${path}`);
+  });
+}
+
+/**
+ * REVEAL a file in the platform's file manager — select it, don't launch it.
+ * openCommand on a finished render would start PLAYING the video; the ask
+ * here is "show me where it landed". Syntax verified 2026-08-18, not guessed
+ * (the picker matrix's convention):
+ * - darwin: `open -R <file>` selects it in a Finder window.
+ * - win32: `explorer /select,<file>` — the switch and the path are ONE
+ *   comma-joined, unquoted argument. explorer.exe does its own command-line
+ *   parsing; passed as two arguments (or with the path quoted) it ignores
+ *   the switch and opens the default folder instead of selecting.
+ * - else: no cross-file-manager "select" verb exists on Linux, so open the
+ *   CONTAINING directory via xdg-open — the file is at least on screen.
+ */
+export function revealCommand(
+  file: string,
+  platform: NodeJS.Platform,
+): { bin: string; args: string[] } {
+  if (platform === "darwin") return { bin: "open", args: ["-R", file] };
+  if (platform === "win32") return { bin: "explorer", args: ["/select," + file] };
+  return { bin: "xdg-open", args: [dirname(file)] };
+}
+
+/** Same failure posture as openInBrowser (the 0.1.4 lesson: an unhandled
+ * 'error' event on a missing opener took the whole edit server down):
+ * swallow the spawn error and print the path — reveal is a courtesy, and a
+ * headless box without a file manager is a normal place to run this. */
+export function revealInFileManager(
+  file: string,
+  platform: NodeJS.Platform = process.platform,
+): void {
+  const { bin, args } = revealCommand(file, platform);
+  const child = spawn(bin, args, { stdio: "ignore", detached: false });
+  child.on("error", () => {
+    console.log(`▸ couldn't open a file manager here — the output is at ${file}`);
+  });
+}

package/src/paths.ts

@@ -0,0 +1,88 @@
+import { mkdirSync } from "node:fs";
+import { copyFile, rename, unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname } from "node:path";
+
+/**
+ * Out-path safety helpers (2026-08-16 field incident): the wizard's output
+ * prompt is a plain text input, and NO shell expands a wizard text input —
+ * a typed `~/Downloads/x.mp4` resolved against cwd, so the end-of-run rename
+ * ENOENT'd after a 50-minute render because `<cwd>/~/Downloads` never
+ * existed. Two defenses live here: tilde expansion applied at every
+ * user-supplied path's resolution site, and failing (or healing) a bad out
+ * path in the first second instead of at the final rename.
+ */
+
+/**
+ * Expand a leading `~` to the home directory. `~user` forms are deliberately
+ * left untouched — resolving another user's home needs /etc/passwd semantics
+ * we don't have, and a wrong guess would be worse than the literal path.
+ * `home` is injectable so the matrix is testable without the real homedir.
+ */
+export function expandHome(path: string, home: string = homedir()): string {
+  if (path === "~") return home;
+  if (path.startsWith("~/")) return home + path.slice(1);
+  return path;
+}
+
+/**
+ * mkdir -p the parent of a would-be output file. mkdir chosen over refusal:
+ * the path is the user's explicit intent and creating a folder is what they'd
+ * do by hand; a genuinely un-creatable path (permissions) still fails loudly
+ * — just upfront now, not after the render. `mkdirFn` is injectable so the
+ * test asserts the directory asked for without touching a filesystem.
+ */
+export function ensureParentDir(
+  filePath: string,
+  mkdirFn: (dir: string) => void = (dir) => mkdirSync(dir, { recursive: true }),
+): void {
+  mkdirFn(dirname(filePath));
+}
+
+/**
+ * `<out>.mp4` + `".cover.jpg"` → `<out>.cover.jpg`: the output's sibling
+ * artifact path, centralizing the replace idiom that lived (twice, and once
+ * stale — see the completion banner's call site) inline. The extension match
+ * excludes path separators on purpose: the bare-idiom regex `(\.[^.]+)?$`
+ * would treat a dotted DIRECTORY name as the extension of an extensionless
+ * output ("/out.v2/final" → "/out.cover.jpg", a file outside the folder the
+ * user chose). An input with no extension gains the suffix whole.
+ *
+ * Lives here rather than in produce.ts (its original home, 2026-08-17): the
+ * edit server derives `<out>.thumbnail.png` from command.json's recorded out
+ * and cannot import produce.ts — produce imports edit (recordRecentProject),
+ * and produce's import graph drags the renderer into a deliberately
+ * dependency-free server. produce.ts re-exports it for its existing callers.
+ */
+export function artifactPath(outPath: string, suffix: string): string {
+  return outPath.replace(/(\.[^./\\]+)?$/, suffix);
+}
+
+/** The rename/copy seam, injectable for the EXDEV test. */
+export interface MoveDeps {
+  rename: (from: string, to: string) => Promise<void>;
+  copyFile: (from: string, to: string) => Promise<void>;
+  unlink: (path: string) => Promise<void>;
+}
+
+const liveMoveDeps: MoveDeps = { rename, copyFile, unlink };
+
+/**
+ * `fs.rename` cannot cross volumes — an `--out` on an external drive throws
+ * EXDEV at the very end of the run (the sibling trap to the ENOENT above;
+ * ENOENT is prevented upfront by `ensureParentDir`). On EXDEV, fall back to
+ * copy+unlink; every other failure still throws, unchanged.
+ */
+export async function moveFile(
+  from: string,
+  to: string,
+  deps: MoveDeps = liveMoveDeps,
+): Promise<void> {
+  try {
+    await deps.rename(from, to);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== "EXDEV") throw err;
+    await deps.copyFile(from, to);
+    await deps.unlink(from);
+  }
+}

package/src/portrait-override.ts

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { PORTRAIT_MIME_TYPES } from "@ossclip/core";
+import { expandHome } from "./paths";
+
+/**
+ * The per-project portrait override (editor face swap, 2026-08-17): a
+ * `portrait-override.<ext>` file in the workdir that outranks both the
+ * `--portrait` flag/pin and the config's `portrait`. One rule, spelled once,
+ * shared by produce.ts's resolution, thumbnail-panel.ts's pure matrix and
+ * edit.ts's endpoints.
+ *
+ * Lives in apps/cli rather than core because every consumer is here — core's
+ * thumbnailStep receives an already-resolved path — and in its own leaf
+ * module rather than produce.ts for the same reason `artifactPath` moved to
+ * paths.ts: edit.ts cannot import produce.ts (produce imports edit, and
+ * produce's import graph drags the renderer into a deliberately
+ * dependency-free server).
+ */
+
+export const PORTRAIT_OVERRIDE_BASENAME = "portrait-override";
+
+/** Which portrait a resolution picked — the panel labels the swap state
+ * from this, so the vocabulary is part of the contract. */
+export type PortraitSource = "override" | "flag" | "config";
+
+/**
+ * The workdir's override file, or null when none exists. Extensions are
+ * probed in PORTRAIT_MIME_TYPES key order, first hit wins — the POST
+ * endpoint enforces at most one override, so two can only mean a hand-copied
+ * file, and a deterministic table-order pick beats a readdir-order coin
+ * flip. `exists` is injectable so the extension matrix needs no filesystem.
+ */
+export function portraitOverridePath(
+  work: string,
+  exists: (path: string) => boolean = existsSync,
+): string | null {
+  for (const ext of Object.keys(PORTRAIT_MIME_TYPES)) {
+    const path = join(work, `${PORTRAIT_OVERRIDE_BASENAME}.${ext}`);
+    if (exists(path)) return path;
+  }
+  return null;
+}
+
+/**
+ * The override's filename extension for an uploaded mime type, or undefined
+ * when the type is outside the table the Gemini API accepts. Reverse lookup
+ * over PORTRAIT_MIME_TYPES so the two directions can never drift; for
+ * `image/jpeg`'s two spellings the first table key (`jpg`) wins.
+ */
+export function portraitExtensionForMime(mimeType: string): string | undefined {
+  return Object.keys(PORTRAIT_MIME_TYPES).find((ext) => PORTRAIT_MIME_TYPES[ext] === mimeType);
+}
+
+export interface ResolvedPortrait {
+  path: string;
+  source: PortraitSource;
+}
+
+/**
+ * The one portrait-precedence rule: workdir override > flag/pin > config.
+ * A per-project expression chosen in the editor must survive CLI re-renders,
+ * so the override beats even an explicit `--portrait` — the flag/config
+ * portrait is the fallback headshot, and a replay silently reverting the
+ * swapped face would undo the one thing the swap exists for.
+ *
+ * expandHome covers the flag and config paths (the 2026-08-16 tilde
+ * incident, paths.ts) but not the override, which is server-built and
+ * already absolute. The config side is `typeof`, never truthiness — the
+ * `portrait` posture: config.json is hand-edited and unparsed.
+ */
+export function resolvePortrait(args: {
+  overridePath: string | null;
+  flagPortrait: string | undefined;
+  cfgPortrait: unknown;
+  home?: string;
+}): ResolvedPortrait | undefined {
+  if (args.overridePath !== null) return { path: args.overridePath, source: "override" };
+  if (args.flagPortrait !== undefined) {
+    return { path: expandHome(args.flagPortrait, args.home), source: "flag" };
+  }
+  if (typeof args.cfgPortrait === "string") {
+    return { path: expandHome(args.cfgPortrait, args.home), source: "config" };
+  }
+  return undefined;
+}