ossclip 0.1.3 → 0.1.5

package/src/setup/extract.ts

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+import { chmodSync, readdirSync, type Dirent } from "node:fs";
+import { join, win32 } from "node:path";
+
+/**
+ * Archive extraction without a single npm dependency: every platform we
+ * download for ships a `tar` that reads everything we download. GNU tar
+ * covers .tar.gz/.tar.xz on Linux; bsdtar (macOS, and Windows 10+ as
+ * %SystemRoot%\System32\tar.exe) additionally reads .zip.
+ *
+ * The Windows subtlety that cost a CI run (§117): a bare `tar` there is
+ * whichever one PATH finds first, and any machine with Git for Windows —
+ * every GitHub runner, and most developer boxes — puts MSYS **GNU** tar
+ * ahead of the system bsdtar. GNU tar cannot read a zip and exits 128. So
+ * on win32 the system bsdtar is tried by absolute path FIRST, and every
+ * candidate that fails for ANY reason falls through to the next: the
+ * original code only fell back when `spawn` itself errored, which a
+ * nonzero exit is not.
+ */
+
+/** Extractors to try, in order. Pure, so the ordering is unit-testable. */
+export function tarCandidates(
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
+  if (platform !== "win32") return ["tar"];
+  const systemRoot = env.SystemRoot ?? env.SYSTEMROOT ?? "C:\\Windows";
+  // `win32.join`, not `join`: this builds a Windows path and the planner is
+  // pure over an injected platform, so it must not pick separators from
+  // whatever host the tests happen to run on.
+  // Absolute bsdtar first, then whatever PATH has (an unusual box may only
+  // have one of them).
+  return [win32.join(systemRoot, "System32", "tar.exe"), "tar"];
+}
+
+const spawnOk = (bin: string, args: string[]): Promise<boolean> =>
+  new Promise((resolve) => {
+    const child = spawn(bin, args, { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", (code) => resolve(code === 0));
+  });
+
+export async function extractArchive(
+  archivePath: string,
+  destDir: string,
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  for (const bin of tarCandidates(platform, env)) {
+    if (await spawnOk(bin, ["-xf", archivePath, "-C", destDir])) return;
+  }
+  if (platform === "win32" && archivePath.endsWith(".zip")) {
+    const ok = await spawnOk("powershell", [
+      "-NoProfile",
+      "-Command",
+      `Expand-Archive -LiteralPath '${archivePath}' -DestinationPath '${destDir}' -Force`,
+    ]);
+    if (ok) return;
+    throw new Error(`neither tar nor Expand-Archive could extract ${archivePath}`);
+  }
+  throw new Error(`tar could not extract ${archivePath}`);
+}
+
+/**
+ * Find `basename` under `dir`, recursively. Release archives put binaries at
+ * different depths (`Release/whisper-cli.exe`, `<verdir>/bin/ffmpeg`) and
+ * those layouts are upstream's to change — searching beats hardcoding them.
+ */
+export function findFile(dir: string, basename: string): string | null {
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const e of entries) {
+    if (e.isFile() && e.name === basename) return join(dir, e.name);
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      const hit = findFile(join(dir, e.name), basename);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+/** POSIX archives usually preserve the execute bit; make sure of it. */
+export function markExecutable(path: string, platform: NodeJS.Platform = process.platform): void {
+  if (platform !== "win32") chmodSync(path, 0o755);
+}

package/src/setup/manifest.ts

@@ -0,0 +1,159 @@
+/**
+ * The acquisition table `ossclip setup` provisions from — pure data.
+ *
+ * Every entry is pinned to an exact upstream release and checksum, verified
+ * at pin time; setup refuses a download whose hash doesn't match. Nothing
+ * here ships inside the npm package — the GPL ffmpeg builds and the
+ * whisper.cpp binaries are downloaded onto the user's machine at the user's
+ * request, which keeps the MIT package's dependency graph clean.
+ *
+ * Bumping a pin: update url/version/sha256 together (BtbN publishes
+ * `checksums.sha256` per release; ggml-org assets are hashed by hand), and
+ * re-run the setup-e2e workflow. The manifest test asserts every supported
+ * platform×arch resolves to either an asset or an explicit manual hint.
+ */
+
+export interface BinaryAsset {
+  url: string;
+  sha256: string;
+  /** Extracted with `tar -xf` everywhere; win32 falls back to Expand-Archive for zips. */
+  archive: "zip" | "tar.gz" | "tar.xz";
+  /** Binary basenames to locate (recursively) after extraction. */
+  bins: string[];
+  /** Download size, for up-front disclosure. */
+  sizeMB: number;
+  license: "GPL" | "MIT";
+  version: string;
+}
+
+const BTBN =
+  "https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-07-29-13-36";
+const FFMPEG_VER = "n8.1.2-31-g8c9502e9b0";
+
+const WHISPER =
+  "https://github.com/ggml-org/whisper.cpp/releases/download/v1.9.1";
+const WHISPER_VER = "v1.9.1";
+
+/**
+ * Static ffmpeg+ffprobe per platform. macOS returns null: BtbN publishes no
+ * darwin assets, and brew is near-universal there — the planner falls back
+ * to it.
+ */
+export function ffmpegAsset(platform: NodeJS.Platform, arch: string): BinaryAsset | null {
+  const bins =
+    platform === "win32" ? ["ffmpeg.exe", "ffprobe.exe"] : ["ffmpeg", "ffprobe"];
+  const common = { bins, license: "GPL" as const, version: FFMPEG_VER };
+  if (platform === "win32" && arch === "x64") {
+    return {
+      ...common,
+      url: `${BTBN}/ffmpeg-${FFMPEG_VER}-win64-gpl-8.1.zip`,
+      sha256: "106d3f8e72b70e29f83983dbaa65efdfc5355716a5df675dc846e441929f7890",
+      archive: "zip",
+      sizeMB: 160,
+    };
+  }
+  if (platform === "win32" && arch === "arm64") {
+    return {
+      ...common,
+      url: `${BTBN}/ffmpeg-${FFMPEG_VER}-winarm64-gpl-8.1.zip`,
+      sha256: "ac46bdb0c9c619b107c7281a0cc6932a9419c4d6c3c8c36a259550f7fcee1a1a",
+      archive: "zip",
+      sizeMB: 107,
+    };
+  }
+  if (platform === "linux" && arch === "x64") {
+    return {
+      ...common,
+      url: `${BTBN}/ffmpeg-${FFMPEG_VER}-linux64-gpl-8.1.tar.xz`,
+      sha256: "9fb60ff01e6574258dc76efdf94f901a651582da67b8edcfd10e8860233b7ef4",
+      archive: "tar.xz",
+      sizeMB: 120,
+    };
+  }
+  if (platform === "linux" && arch === "arm64") {
+    return {
+      ...common,
+      url: `${BTBN}/ffmpeg-${FFMPEG_VER}-linuxarm64-gpl-8.1.tar.xz`,
+      sha256: "d8f9598a885db3deabd06af7f0f70c8565af27d29fadbcf746598c9306a0c3fa",
+      archive: "tar.xz",
+      sizeMB: 102,
+    };
+  }
+  return null;
+}
+
+/**
+ * Prebuilt whisper.cpp `whisper-cli` per platform. The Windows zip carries
+ * its DLLs beside the exe and the Ubuntu tarballs link their .so files via
+ * an `$ORIGIN` runpath, so both run straight out of the extracted directory
+ * (verified at pin time). macOS returns null — upstream ships no darwin CLI
+ * binary; brew's `whisper-cpp` covers it.
+ *
+ * Windows-on-ARM gets the x64 build: upstream publishes no arm64 zip, and
+ * Windows 11 runs x64 binaries under emulation.
+ */
+export function whisperAsset(platform: NodeJS.Platform, arch: string): BinaryAsset | null {
+  if (platform === "win32") {
+    // The BLAS build — meaningfully faster on small.en, worth the extra DLL.
+    return {
+      url: `${WHISPER}/whisper-blas-bin-x64.zip`,
+      sha256: "3c319eab3e87f85883e1ff3d14426c0a1986c661c5eb5985e8af431ed9c4f71f",
+      archive: "zip",
+      bins: ["whisper-cli.exe"],
+      sizeMB: 20,
+      license: "MIT",
+      version: WHISPER_VER,
+    };
+  }
+  if (platform === "linux" && arch === "x64") {
+    return {
+      url: `${WHISPER}/whisper-bin-ubuntu-x64.tar.gz`,
+      sha256: "f3bf3b4369a99b54665b0f19b88483b30de27f25963b0414235dea03198515c5",
+      archive: "tar.gz",
+      bins: ["whisper-cli"],
+      sizeMB: 9,
+      license: "MIT",
+      version: WHISPER_VER,
+    };
+  }
+  if (platform === "linux" && arch === "arm64") {
+    return {
+      url: `${WHISPER}/whisper-bin-ubuntu-arm64.tar.gz`,
+      sha256: "e0b66cd551ff6f2a28fabe3c6e89691eea037bb76833493abb9a71ca788994b3",
+      archive: "tar.gz",
+      bins: ["whisper-cli"],
+      sizeMB: 5,
+      license: "MIT",
+      version: WHISPER_VER,
+    };
+  }
+  return null;
+}
+
+/**
+ * ggml transcription models. Sizes and SHA-1 hashes come from upstream's
+ * models/README.md — upstream publishes SHA-1, so that's what we verify;
+ * it's an integrity check against truncated downloads, not a security
+ * boundary (the download is already pinned to a host and path over HTTPS).
+ */
+export interface ModelInfo {
+  sizeMB: number;
+  sha1: string;
+}
+
+export const MODELS: Record<string, ModelInfo> = {
+  "tiny.en": { sizeMB: 75, sha1: "c78c86eb1a8faa21b369bcd33207cc90d64ae9df" },
+  "base.en": { sizeMB: 142, sha1: "137c40403d78fd54d454da0f9bd998f78703390c" },
+  "small.en": { sizeMB: 466, sha1: "db8a495a91d927739e50b3fc1cc4c6b8f6c2d022" },
+  "medium.en": { sizeMB: 1536, sha1: "8c30f0e44ce9560643ebd10bbe50cd20eafd3723" },
+};
+
+export function modelUrl(name: string): string {
+  return `https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-${name}.bin`;
+}
+
+/** The exact build recipe printed when no prebuilt fits — one copy, not four. */
+export const WHISPER_BUILD_HINT =
+  "build whisper.cpp from source: git clone https://github.com/ggml-org/whisper.cpp && " +
+  "cd whisper.cpp && cmake -B build && cmake --build build -j --config Release " +
+  "(then point OSSCLIP_WHISPER at build/bin/whisper-cli)";

package/src/setup/plan.ts

@@ -0,0 +1,211 @@
+import { isAbsolute, join } from "node:path";
+import type { OssclipConfig } from "@ossclip/core";
+import { type BinaryAsset, MODELS, ffmpegAsset, modelUrl, whisperAsset } from "./manifest";
+
+/**
+ * The planning half of `ossclip setup` — pure over injected probes, like
+ * doctor (R18 §90a), so every branch is unit-testable without a network or
+ * a second OS. The IO half (download/extract/brew/prompt) lives in setup.ts.
+ *
+ * Ground rules:
+ *  - Anything that already works is `satisfied` and never touched. A user's
+ *    own ffmpeg on PATH, a hand-set OSSCLIP_WHISPER, a model already on
+ *    disk — setup's job is to fill gaps, not to take over working installs.
+ *  - `--force` re-provisions only what setup itself manages (paths under
+ *    `<configDir>/bin`, or bare names that were never resolved) — it must
+ *    never clobber a path the user pointed elsewhere on purpose.
+ *  - No platform gets silence: where no strategy applies, the step is
+ *    `manual` with the exact commands to run.
+ */
+
+export type StepKind = "ffmpeg" | "whisper" | "model" | "provider";
+export type StepStatus = "satisfied" | "download" | "brew" | "manual" | "prompt";
+
+export interface SetupStep {
+  kind: StepKind;
+  status: StepStatus;
+  /** What was found, or what will happen — one line for the plan table. */
+  detail: string;
+  /** Set when status === "download". */
+  asset?: BinaryAsset;
+  /** Download size when known (binary asset or known model). */
+  sizeMB?: number;
+  /** brew formula when status === "brew"; the manual fix when "manual". */
+  hint?: string;
+}
+
+export interface SetupProbes {
+  binRuns(bin: string, arg: string): Promise<boolean>;
+  exists(path: string): boolean;
+  platform: NodeJS.Platform;
+  arch: string;
+  env: NodeJS.ProcessEnv;
+}
+
+export interface SetupOptions {
+  /** Resolved `~/.ossclip` (injected so tests don't touch the real home). */
+  configDir: string;
+  model: string;
+  force: boolean;
+  skipLlm: boolean;
+}
+
+export const managedBinDir = (configDir: string): string => join(configDir, "bin");
+
+/** A path setup owns and may re-provision under --force. */
+const isManaged = (path: string, configDir: string): boolean =>
+  !isAbsolute(path) || path.startsWith(managedBinDir(configDir));
+
+export async function planSetup(
+  cfg: OssclipConfig,
+  p: SetupProbes,
+  opts: SetupOptions,
+): Promise<SetupStep[]> {
+  const steps: SetupStep[] = [];
+  const brewAvailable =
+    p.platform === "darwin" ? await p.binRuns("brew", "--version") : false;
+
+  // ffmpeg + ffprobe travel together: one archive provides both, and a
+  // machine with one but not the other is a broken install either way.
+  const ffmpegOk =
+    (await p.binRuns(cfg.ffmpegPath, "-version")) &&
+    (await p.binRuns(cfg.ffprobePath, "-version"));
+  const ffmpegForceable = isManaged(cfg.ffmpegPath, opts.configDir);
+  if (ffmpegOk && !(opts.force && ffmpegForceable)) {
+    steps.push({ kind: "ffmpeg", status: "satisfied", detail: cfg.ffmpegPath });
+  } else {
+    const asset = ffmpegAsset(p.platform, p.arch);
+    if (asset) {
+      steps.push({
+        kind: "ffmpeg",
+        status: "download",
+        detail: `static ffmpeg + ffprobe ${asset.version} (${asset.license} build)`,
+        asset,
+        sizeMB: asset.sizeMB,
+      });
+    } else if (brewAvailable) {
+      steps.push({
+        kind: "ffmpeg",
+        status: "brew",
+        detail: "ffmpeg + ffprobe via Homebrew",
+        hint: "ffmpeg",
+      });
+    } else {
+      steps.push({
+        kind: "ffmpeg",
+        status: "manual",
+        detail: "no automated path for this platform",
+        hint:
+          p.platform === "darwin"
+            ? "install Homebrew (https://brew.sh) then `brew install ffmpeg`, or set OSSCLIP_FFMPEG"
+            : "install ffmpeg from https://ffmpeg.org and set OSSCLIP_FFMPEG",
+      });
+    }
+  }
+
+  const whisperOk = await p.binRuns(cfg.whisperPath, "--help");
+  const whisperForceable = isManaged(cfg.whisperPath, opts.configDir);
+  if (whisperOk && !(opts.force && whisperForceable)) {
+    steps.push({ kind: "whisper", status: "satisfied", detail: cfg.whisperPath });
+  } else {
+    const asset = whisperAsset(p.platform, p.arch);
+    if (asset) {
+      steps.push({
+        kind: "whisper",
+        status: "download",
+        detail: `prebuilt whisper.cpp ${asset.version} (whisper-cli)`,
+        asset,
+        sizeMB: asset.sizeMB,
+      });
+    } else if (brewAvailable) {
+      steps.push({
+        kind: "whisper",
+        status: "brew",
+        detail: "whisper.cpp via Homebrew",
+        hint: "whisper-cpp",
+      });
+    } else {
+      steps.push({
+        kind: "whisper",
+        status: "manual",
+        detail: "no automated path for this platform",
+        hint:
+          p.platform === "darwin"
+            ? "install Homebrew (https://brew.sh) then `brew install whisper-cpp`, or set OSSCLIP_WHISPER"
+            : "see https://github.com/ggml-org/whisper.cpp — build from source, then set OSSCLIP_WHISPER",
+      });
+    }
+  }
+
+  // The model: same resolution produce and doctor use — absolute is a file
+  // path, a bare name lives in modelDir as ggml-<name>.bin. `--force` never
+  // re-downloads a present model; a corrupt one is deleted by hand.
+  const model = opts.model;
+  const modelPath = isAbsolute(model) ? model : join(cfg.modelDir, `ggml-${model}.bin`);
+  const known = MODELS[model];
+  if (p.exists(modelPath)) {
+    steps.push({ kind: "model", status: "satisfied", detail: modelPath });
+  } else if (isAbsolute(model)) {
+    steps.push({
+      kind: "model",
+      status: "manual",
+      detail: `configured model is an absolute path that doesn't exist: ${model}`,
+      hint: "put the file there, or set model to a name like small.en for setup to download",
+    });
+  } else {
+    steps.push({
+      kind: "model",
+      status: "download",
+      detail: `${modelUrl(model)} → ${modelPath}`,
+      sizeMB: known?.sizeMB,
+    });
+  }
+
+  // Provider, in doctor's detection order. Setup can save a key, but only
+  // ever interactively — never invented, never required (--skip-llm).
+  const provider = p.env.GEMINI_API_KEY
+    ? "gemini (GEMINI_API_KEY is set)"
+    : p.env.ANTHROPIC_API_KEY
+      ? "claude (ANTHROPIC_API_KEY is set)"
+      : (await p.binRuns("claude", "--version"))
+        ? "claude-cli (logged-in Claude Code)"
+        : null;
+  if (opts.skipLlm) {
+    steps.push({
+      kind: "provider",
+      status: "satisfied",
+      detail: provider ?? "skipped (--skip-llm) — needed for --produce only",
+    });
+  } else if (provider) {
+    steps.push({ kind: "provider", status: "satisfied", detail: provider });
+  } else {
+    steps.push({
+      kind: "provider",
+      status: "prompt",
+      detail: "no LLM provider found — setup will ask (Enter skips; only --produce needs one)",
+    });
+  }
+
+  return steps;
+}
+
+export function formatPlan(steps: SetupStep[]): string {
+  const lines = steps.map((s) => {
+    const mark = s.status === "satisfied" ? "✓" : "▸";
+    const size = s.sizeMB ? ` (~${s.sizeMB} MB)` : "";
+    const action =
+      s.status === "satisfied"
+        ? s.detail
+        : s.status === "download"
+          ? `download${size}: ${s.detail}`
+          : s.status === "brew"
+            ? `brew install ${s.hint}`
+            : s.status === "prompt"
+              ? s.detail
+              : `manual: ${s.hint}`;
+    return `${mark} ${s.kind.padEnd(10)} ${action}`;
+  });
+  const totalMB = steps.reduce((n, s) => n + (s.status === "download" ? (s.sizeMB ?? 0) : 0), 0);
+  if (totalMB > 0) lines.push(`\n  total download ~${totalMB} MB → everything lands under ~/.ossclip`);
+  return lines.join("\n");
+}

package/src/setup/provider.ts

@@ -0,0 +1,51 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/**
+ * The LLM-provider step of `ossclip setup`.
+ *
+ * A key is only ever taken interactively and saved to `~/.ossclip/.env` —
+ * the file `loadEnvFiles` (R16 §77) already reads last, so a shell export
+ * or a project `.env` still wins. Secrets stay out of config.json, which
+ * people paste into issues.
+ */
+
+export interface ProviderIO {
+  /** Ask one question, return the trimmed answer ("" for just-Enter). */
+  ask(question: string): Promise<string>;
+  say(line: string): void;
+}
+
+export async function promptForProvider(io: ProviderIO, configDir: string): Promise<void> {
+  io.say("");
+  io.say("An LLM provider is only needed for `--produce` (the graphics planner).");
+  io.say("Cutting + captions run fully local without one.");
+  io.say("  1) I have an Anthropic API key");
+  io.say("  2) I have a Google Gemini API key");
+  io.say("  3) I use Claude Code (already logged in — no key needed)");
+  io.say("  Enter) skip for now");
+  const choice = (await io.ask("Choice: ")).trim();
+  if (choice === "3") {
+    io.say("▸ nothing to save — ossclip finds the claude CLI on PATH by itself.");
+    return;
+  }
+  const envKey = choice === "1" ? "ANTHROPIC_API_KEY" : choice === "2" ? "GEMINI_API_KEY" : null;
+  if (!envKey) {
+    io.say("▸ skipped — `ossclip doctor` will remind you what --produce needs.");
+    return;
+  }
+  const value = (await io.ask(`${envKey}=`)).trim();
+  if (!value) {
+    io.say("▸ empty — skipped.");
+    return;
+  }
+  const envPath = saveProviderKey(configDir, envKey, value);
+  io.say(`▸ saved to ${envPath} (delete that line to revoke)`);
+}
+
+export function saveProviderKey(configDir: string, key: string, value: string): string {
+  const envPath = join(configDir, ".env");
+  mkdirSync(dirname(envPath), { recursive: true });
+  appendFileSync(envPath, `${key}=${value}\n`, { mode: 0o600 });
+  return envPath;
+}