ossclip 0.1.25 → 0.1.27

package/src/edit.ts

@@ -25,14 +25,39 @@ import {
   // only when a regenerate actually runs.
   generateThumbnailImage,
   loadConfig,
+  outInsideInputFolderMessage,
+  outPathInsideInput,
   PORTRAIT_MIME_TYPES,
   portraitMimeType,
+  readCoverProvenance,
   thumbnailImageCacheName,
+  type CoverProvenance,
   type GenerateThumbnailImageOptions,
   type ThumbnailConcept,
   type ThumbnailConceptApproved,
 } from "@ossclip/core";
-import { artifactPath, expandHome } from "./paths";
+// Static, unlike the picker's `await import` above its call site: the picker
+// drags in @ossclip/core's process runner and llm-detect, worth deferring off
+// server startup — open.ts is node:child_process + node:path and pure command
+// building, with nothing to defer.
+import { revealInFileManager } from "./open";
+// The recorded-invocation reads live in cover.ts (2026-08-19): `ossclip
+// cover` needs the same out-resolution rule this server's thumbnail dest,
+// youtube markdown and reveal endpoint derive from, and two spellings of it
+// could disagree about which file a replay writes. cover.ts stays free of a
+// static @ossclip/renderer import for exactly this reason.
+import {
+  CoverAtSecondsSchema,
+  CoverFromSchema,
+  RecordedCommandSchema,
+  readRecordedCommand,
+  recordedArtifactPath as recordedArtifactPathIn,
+  recordedOutPath,
+  regenerateCover,
+  type CoverSeams,
+  type RecordedCommand,
+} from "./cover";
+import { expandHome } from "./paths";
 import {
   PORTRAIT_OVERRIDE_BASENAME,
   portraitExtensionForMime,
@@ -74,21 +99,6 @@ export function resolveEditorPageDir(): string | null {
  * replays the invocation `produce` recorded, never anything a client sent.
  */
 
-/**
- * The invocation `produce` recorded into the workdir (R11 Task 4.1).
- * Validated on read — it's a file on disk like any other user data — and the
- * ONLY thing `/api/render` will ever spawn: this server binds locally, but
- * accepting a client-supplied command would make it a remote shell.
- */
-const CommandSchema = z.object({
-  execPath: z.string(),
-  execArgv: z.array(z.string()).default([]),
-  script: z.string(),
-  args: z.array(z.string()),
-  cwd: z.string(),
-  out: z.string().optional(),
-});
-
 /** Ring-buffer cap for captured render output. */
 const RENDER_LOG_LINES = 200;
 export interface EditServer {
@@ -140,6 +150,12 @@ const MIME: Record<string, string> = {
   ".css": "text/css",
   ".json": "application/json",
   ".mp4": "video/mp4",
+  // The caption timing editor's waveform fetches `/media/audio.wav` (produce
+  // writes it into every workdir). `fetch` + `decodeAudioData` would accept
+  // the octet-stream fallback, but a future `<audio>` element would not, so
+  // the type is stated while the change is one line rather than a debugging
+  // session.
+  ".wav": "audio/wav",
 };
 
 /**
@@ -237,6 +253,17 @@ export async function startEditServer(
      * run never reads the runner's real ~/.ossclip/config.json (the
      * `recentDir` rule applied to reads). */
     loadCfg?: () => { youtube?: unknown; portrait?: unknown; thumbnailModel?: unknown };
+    /** File-manager reveal seam (the `generateThumbnail` pattern) — tests
+     * observe the revealed path instead of popping a real Finder/Explorer
+     * window on the runner. */
+    reveal?: (path: string) => void;
+    /**
+     * The cover render seam, exactly like `generateThumbnail` above. Without
+     * it `regenerateCover` lazily imports @ossclip/renderer and boots a
+     * headless browser — which `edit-server.test.ts` must never do, and which
+     * is also why cover.ts keeps that import lazy in the first place.
+     */
+    renderCover?: CoverSeams["renderCover"];
   } = {},
 ): Promise<EditServer> {
   // MUTABLE since R17 §83: the server can start with no project (the page
@@ -276,28 +303,13 @@ export async function startEditServer(
   // buy two.
   let thumbnailBusy = false;
   /** command.json's recorded invocation, or null when absent/corrupt — the
-   * thumbnail panel degrades to the config fallback rather than 500ing. */
-  const readCommandRecord = async (): Promise<z.infer<typeof CommandSchema> | null> => {
-    if (!existsSync(commandPath())) return null;
-    try {
-      const parsed = CommandSchema.safeParse(JSON.parse(await readFile(commandPath(), "utf8")));
-      return parsed.success ? parsed.data : null;
-    } catch {
-      return null;
-    }
-  };
-  /** `<out><ext>` from the recorded out (the top-level `out` when recorded,
-   * else the argv's -o/--out resolved against the recorded cwd — the
-   * replay's own resolution), or null when no out was ever recorded. Shared
-   * by the thumbnail dest and the youtube markdown — one spelling of the
-   * out-resolution rule, not two. */
-  const recordedArtifactPath = async (ext: string): Promise<string | null> => {
-    const cmd = await readCommandRecord();
-    if (!cmd) return null;
-    const out = cmd.out ?? lastFlagValue(cmd.args, ["-o", "--out"]);
-    if (out === undefined) return null;
-    return artifactPath(resolve(cmd.cwd, expandHome(out)), ext);
-  };
+   * thumbnail panel degrades to the config fallback rather than 500ing.
+   * Bound to the CURRENT workdir; the rule itself lives in cover.ts. */
+  const readCommandRecord = (): Promise<RecordedCommand | null> => readRecordedCommand(workdir!);
+  /** `<out><ext>` from the recorded out, or null when no out was ever
+   * recorded. Shared by the thumbnail dest and the youtube markdown. */
+  const recordedArtifactPath = (ext: string): Promise<string | null> =>
+    recordedArtifactPathIn(workdir!, ext);
   const thumbnailDestPath = (): Promise<string | null> => recordedArtifactPath(".thumbnail.png");
   /** Newest workdir file passing `test`, by mtime — the cache fallbacks. */
   const newestWorkdirFile = async (test: (name: string) => boolean): Promise<string | null> => {
@@ -329,6 +341,33 @@ export async function startEditServer(
       return null;
     }
   };
+  // ---- Cover regeneration (editor panel, 2026-08-19) ----------------------
+  // The cover is written on EVERY produce, `--youtube` or not, so this is not
+  // a YouTube-menu concern — it has its own top-bar button in the page. The
+  // panel round-trips through the workdir's `cover.json`, which is the same
+  // provenance `ossclip cover` reads and produce honours (`textSource:
+  // "user"`), so an edit made here survives into future renders with no new
+  // plumbing — the thumbnail block's approval-file contract, applied.
+  //
+  // One regeneration at a time: it can shell out to ffmpeg and it boots a
+  // headless browser, and a double-click must not run two renders at the same
+  // destination. `thumbnailBusy`'s rule, for the same reason.
+  let coverBusy = false;
+  /** Where the JPEG lives right now: the destination the last cover used,
+   * else `<recorded out>.cover.jpg`. Existence is the caller's check — a
+   * recorded destination that was never rendered is a real state (the panel
+   * shows a placeholder), not an error. */
+  const currentCoverImage = async (provenance: CoverProvenance | null): Promise<string | null> => {
+    if (provenance !== null && existsSync(provenance.out)) return provenance.out;
+    const dest = await recordedArtifactPath(".cover.jpg");
+    return dest !== null && existsSync(dest) ? dest : null;
+  };
+  /** mtime as the ts so the URL changes exactly when the file does — the
+   * thumbnail imageUrl's own cache-busting rule (a regenerate REPLACES the
+   * file behind this URL). */
+  const coverImageUrl = (image: string | null): string | null =>
+    image === null ? null : `/api/cover/image?ts=${Math.round(statSync(image).mtimeMs)}`;
+
   // ---- Portrait override (editor face swap, 2026-08-17) -------------------
   // A per-project `portrait-override.<ext>` in the workdir that outranks the
   // pin and the config (portrait-override.ts has the precedence argument).
@@ -622,7 +661,7 @@ export async function startEditServer(
           } catch {
             // ignore
           }
-          const parsed = CommandSchema.safeParse(
+          const parsed = RecordedCommandSchema.safeParse(
             JSON.parse(await readFile(commandPath(), "utf8")),
           );
           if (!parsed.success) return send(500, { error: `command.json is not valid: ${parsed.error.message}` });
@@ -638,6 +677,28 @@ export async function startEditServer(
           // directly-typed `ossclip produce …` — already starts with it and
           // is untouched.
           let args = cmd.args[0] === "produce" ? [...cmd.args] : ["produce", ...cmd.args];
+          // 2026-08-18 field cascade: mirror produce's own inside-the-input
+          // refusal at this boundary, so the failure is a 400 the page can
+          // show instead of a spawned child dying in the log tail. The input
+          // is derived from the RECORDED command only — the security stance
+          // above: beyond the out path it already controls, nothing the
+          // client sent may steer what this endpoint checks or touches.
+          // args[1] after the §129 heal is the recorded input positional;
+          // when a record put flags before the input, or the input no longer
+          // stats, the gate stays open and produce's own refusal still
+          // protects the replay.
+          if (customOut !== undefined && args[1] !== undefined) {
+            const inputAbs = resolve(cmd.cwd, expandHome(args[1]));
+            let inputIsFolder = false;
+            try {
+              inputIsFolder = statSync(inputAbs).isDirectory();
+            } catch {
+              // input gone/unreadable — the replay will fail on its own terms
+            }
+            if (inputIsFolder && outPathInsideInput(resolve(cmd.cwd, expandHome(customOut)), inputAbs)) {
+              return send(400, { error: outInsideInputFolderMessage(inputAbs) });
+            }
+          }
           if (customOut) {
             const filteredArgs: string[] = [];
             for (let i = 0; i < args.length; i++) {
@@ -657,6 +718,12 @@ export async function startEditServer(
           const child = spawn(cmd.execPath, [...cmd.execArgv, cmd.script, ...args], {
             cwd: cmd.cwd,
             stdio: ["ignore", "pipe", "pipe"],
+            // Which workdir's command.json this replay came from (2026-08-18
+            // field cascade, part 3): a re-keyed folder input makes produce
+            // derive a DIFFERENT workdir, silently abandoning the overrides
+            // saved here — produce compares against this and prints a loud ⚠
+            // into the log tail (replayWorkdirWarning, produce.ts).
+            env: { ...process.env, OSSCLIP_REPLAY_WORKDIR: workdir! },
           });
           renderChild = child;
           child.stdout?.on("data", pushLines);
@@ -693,6 +760,29 @@ export async function startEditServer(
           });
         }
 
+        if (url.pathname === "/api/reveal-output" && req.method === "POST") {
+          // Show the finished render in the file manager (2026-08-18). The
+          // path comes from command.json's recorded out and NOWHERE else —
+          // the request body is deliberately never read. The security stance
+          // at the top of this file: this server binds locally, but an
+          // endpoint that reveals (and one day might do more to) a
+          // client-named path is the same door as spawning a client-supplied
+          // command.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const cmd = await readCommandRecord();
+          const out = cmd === null ? null : recordedOutPath(cmd);
+          if (out === null) {
+            return send(412, { error: "no recorded output path in this workdir" });
+          }
+          if (!existsSync(out)) {
+            // Recorded but not rendered yet (or moved since) — a 404 the
+            // page treats as "nothing to show", not a failure.
+            return send(404, { error: `no output at ${out} yet` });
+          }
+          (opts.reveal ?? revealInFileManager)(out);
+          return send(200, { ok: true, path: out });
+        }
+
         if (url.pathname === "/api/overrides" && req.method === "PUT") {
           if (!workdir) return send(409, { error: "no workdir open" });
           const chunks: Buffer[] = [];
@@ -1048,6 +1138,109 @@ export async function startEditServer(
           return send(200, { ok: true, mdPath });
         }
 
+        if (url.pathname === "/api/cover" && req.method === "GET") {
+          // The cover panel's one status call (2026-08-19): the provenance to
+          // prefill and where the current image is. All reads — the panel
+          // owns no state on the server.
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const provenance = await readCoverProvenance(workdir);
+          const image = await currentCoverImage(provenance);
+          // Where a regeneration would WRITE. `coverDestination`'s canonical
+          // ladder: the destination the last cover used, else
+          // `<recorded out>.cover.jpg`. Neither means regenerateCover would
+          // throw for want of a destination, and the panel says so up front
+          // rather than after a click.
+          const outPath = provenance?.out ?? (await recordedArtifactPath(".cover.jpg"));
+          return send(200, {
+            status: outPath === null ? "unavailable" : "ready",
+            ...(outPath === null
+              ? { reason: "no-destination" as const }
+              : image === null
+                ? { reason: "never-rendered" as const }
+                : {}),
+            provenance,
+            outPath,
+            imageUrl: coverImageUrl(image),
+          });
+        }
+
+        if (url.pathname === "/api/cover/image" && req.method === "GET") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          const image = await currentCoverImage(await readCoverProvenance(workdir));
+          if (image === null) return send(404, { error: "no cover image" });
+          // Whole-file read + no-store, the thumbnail image endpoint's exact
+          // posture and for the same reason: a regenerate REPLACES the file
+          // behind a URL the panel busts with ?ts, and a cached 200 would show
+          // the old cover against the new ts on some proxies.
+          const bytes = await readFile(image);
+          res.writeHead(200, {
+            "content-type": "image/jpeg",
+            "cache-control": "no-store",
+            "content-length": String(bytes.length),
+          });
+          res.end(bytes);
+          return;
+        }
+
+        if (url.pathname === "/api/cover/regenerate" && req.method === "POST") {
+          if (!workdir) return send(409, { error: "no workdir open" });
+          // A regeneration can shell out to ffmpeg and it boots a headless
+          // browser — one at a time, a second is a 409 like a second render.
+          if (coverBusy) return send(409, { error: "a cover regeneration is already running" });
+          const chunks: Buffer[] = [];
+          for await (const c of req) chunks.push(c as Buffer);
+          // Three steerable values and NOTHING else. `atSec` rides the CLI's
+          // own schema so a negative seek is refused at both surfaces, and
+          // `from` rides the enum so a typo'd "finall" is a 400 rather than a
+          // cover quietly rebuilt from the wrong video (CLAUDE.md's
+          // --source-fit rule). Unknown keys are stripped by the parse, which
+          // is the load-bearing half of the paragraph below.
+          const parsed = z
+            .object({
+              text: z.string().optional(),
+              atSec: CoverAtSecondsSchema.optional(),
+              from: CoverFromSchema.optional(),
+            })
+            .safeParse(JSON.parse(Buffer.concat(chunks).toString() || "{}"));
+          if (!parsed.success) return send(400, { error: parsed.error.message });
+          coverBusy = true;
+          try {
+            // Every PATH is derived server-side — from command.json,
+            // cover.json and render-props.json — and never from the body: the
+            // stance the render and reveal endpoints already hold. This server
+            // binds locally, but an endpoint that WRITES a file wherever a
+            // client names is the same door as spawning a client-supplied
+            // command. Note the absent `outPath`: it exists on
+            // CoverRegenerateOptions for `ossclip cover --out`, and passing
+            // one through from here is exactly the bug this omission prevents.
+            const notes: string[] = [];
+            const provenance = await regenerateCover(
+              workdir,
+              { text: parsed.data.text, atSec: parsed.data.atSec, from: parsed.data.from },
+              { renderCover: opts.renderCover, log: (line) => notes.push(line) },
+            );
+            const image = await currentCoverImage(provenance);
+            // The notes ride back so the panel can show what the CLI PRINTS —
+            // a headline trimmed to nine words, or a re-picked frame. Silence
+            // on either is how a user ships a cover they did not write.
+            return send(200, {
+              ok: true,
+              provenance,
+              notes,
+              outPath: provenance.out,
+              imageUrl: coverImageUrl(image),
+            });
+          } catch (err) {
+            // 200 with ok:false, the thumbnail regenerate's posture: these
+            // failures are user-actionable sentences ("is the timestamp past
+            // the end?", "--from source needs cover.json") and the panel shows
+            // them inline VERBATIM rather than as a dead 500.
+            return send(200, { ok: false, error: err instanceof Error ? err.message : String(err) });
+          } finally {
+            coverBusy = false;
+          }
+        }
+
         if (url.pathname.startsWith("/media/")) {
           if (!workdir) return send(409, { error: "no workdir open" });
           const file = join(workdir, decodeURIComponent(url.pathname.slice("/media/".length)));

package/src/interactive/resolve-workdir.ts

@@ -106,10 +106,19 @@ export function resolveWorkdir(
  * 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.
+ *
+ * `command` is the subcommand the user actually ran: this ladder is shared
+ * with `ossclip cover`, and printing `ossclip edit <path>` to someone who
+ * typed `cover` sends them to a different command than the one they wanted.
+ * Defaults to "edit", the only caller when this was written.
  */
-export function candidateListMessage(dir: string, candidates: Candidate[]): string {
+export function candidateListMessage(
+  dir: string,
+  candidates: Candidate[],
+  command: string = "edit",
+): string {
   return (
     `several produce runs under ${dir} — name one:\n` +
-    candidates.map((c) => `  ${renderCommand(["edit", c.path])}`).join("\n")
+    candidates.map((c) => `  ${renderCommand([command, c.path])}`).join("\n")
   );
 }

package/src/open.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { dirname } from "node:path";
 
 /**
  * Open a target — URL or file path, every platform's opener treats them
@@ -46,3 +47,40 @@ export function openInViewer(path: string, platform: NodeJS.Platform = process.p
     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}`);
+  });
+}