ossclip 0.1.4 → 0.1.6

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;
+}

package/src/setup/setup.ts

@@ -0,0 +1,233 @@
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { CONFIG_DIR, loadConfig, saveConfigPatch, type OssclipConfig } from "@ossclip/core";
+import { MODELS, WHISPER_BUILD_HINT, modelUrl, type BinaryAsset } from "./manifest";
+import { formatPlan, managedBinDir, planSetup, type SetupProbes, type SetupStep } from "./plan";
+import { download, progressLine } from "./download";
+import { extractArchive, findFile, markExecutable } from "./extract";
+import { promptForProvider } from "./provider";
+
+/**
+ * `ossclip setup` — the whole install, one command (§90: the install cliff
+ * is the adoption ceiling; this is the ramp). Downloads pinned static
+ * ffmpeg and prebuilt whisper.cpp where upstream publishes them, brews on
+ * macOS, fetches the transcription model with resume + checksum, offers to
+ * save an LLM key, and records absolute paths in ~/.ossclip/config.json so
+ * nothing touches PATH — that last part is the entire Windows story.
+ *
+ * Setup fills gaps and never takes over a working install: whatever
+ * already runs is left exactly where it is. It ends by running the real
+ * doctor, because setup's definition of done is doctor's definition of
+ * healthy.
+ */
+
+export interface SetupCliOptions {
+  model?: string;
+  skipLlm: boolean;
+  force: boolean;
+  yes: boolean;
+}
+
+const probeBin = (bin: string, arg: string): Promise<boolean> =>
+  new Promise((resolve) => {
+    // Existence is the question, not exit code (same contract as doctor).
+    const child = spawn(bin, [arg], { stdio: "ignore" });
+    child.on("error", () => resolve(false));
+    child.on("exit", () => resolve(true));
+  });
+
+export async function setup(opts: SetupCliOptions): Promise<void> {
+  const cfg = loadConfig();
+  const model = opts.model ?? cfg.model;
+  const probes: SetupProbes = {
+    binRuns: probeBin,
+    exists: existsSync,
+    platform: process.platform,
+    arch: process.arch,
+    env: process.env,
+  };
+  const steps = await planSetup(cfg, probes, {
+    configDir: CONFIG_DIR,
+    model,
+    force: opts.force,
+    skipLlm: opts.skipLlm,
+  });
+
+  console.log("ossclip setup — plan:\n");
+  console.log(formatPlan(steps));
+  console.log("");
+
+  const interactive = process.stdin.isTTY === true && !opts.yes;
+  const needsWork = steps.some((s) => s.status !== "satisfied");
+  const failures: string[] = [];
+  const rl = interactive
+    ? createInterface({ input: process.stdin, output: process.stdout })
+    : null;
+  try {
+    if (needsWork && rl) {
+      const answer = (await rl.question("Proceed? [Y/n] ")).trim().toLowerCase();
+      if (answer === "n" || answer === "no") {
+        console.log("▸ nothing changed.");
+        return;
+      }
+    }
+
+    const patch: Partial<OssclipConfig> = {};
+    for (const step of steps) {
+      // One step failing (a dropped download, a brew hiccup) must not throw
+      // away the others' work — record it, keep going, save what succeeded,
+      // and let the closing doctor run print the remaining fixes.
+      try {
+        await runStep(step);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        failures.push(`${step.kind}: ${msg}`);
+        console.error(`✗ ${step.kind} failed: ${msg}`);
+      }
+    }
+
+    async function runStep(step: SetupStep): Promise<void> {
+      switch (step.kind) {
+        case "ffmpeg":
+          if (step.status === "download" && step.asset) {
+            const [ffmpegBin, ffprobeBin] = step.asset.bins;
+            if (!ffmpegBin || !ffprobeBin) throw new Error("manifest bug: ffmpeg asset needs two bins");
+            const dir = await provision("ffmpeg", step.asset);
+            patch.ffmpegPath = mustFind(dir, ffmpegBin);
+            patch.ffprobePath = mustFind(dir, ffprobeBin);
+            await verifyRuns(patch.ffmpegPath, "-version", "ffmpeg");
+            await verifyRuns(patch.ffprobePath, "-version", "ffprobe");
+            console.log(`▸ ffmpeg ready: ${patch.ffmpegPath}`);
+          } else if (step.status === "brew") {
+            await brewInstall(step.hint ?? "ffmpeg");
+            await verifyRuns("ffmpeg", "-version", "ffmpeg");
+          } else if (step.status === "manual") {
+            console.log(`✗ ffmpeg needs a manual step: ${step.hint}`);
+          }
+          break;
+        case "whisper":
+          if (step.status === "download" && step.asset) {
+            const [whisperBin] = step.asset.bins;
+            if (!whisperBin) throw new Error("manifest bug: whisper asset needs a bin");
+            const dir = await provision("whisper", step.asset);
+            const bin = mustFind(dir, whisperBin);
+            // The probe matters here more than anywhere: a prebuilt that
+            // doesn't run on this libc must fail NOW with the build recipe,
+            // not half-configured at first transcription.
+            await verifyRuns(bin, "--help", "whisper-cli", WHISPER_BUILD_HINT);
+            patch.whisperPath = bin;
+            console.log(`▸ whisper-cli ready: ${bin}`);
+          } else if (step.status === "brew") {
+            await brewInstall(step.hint ?? "whisper-cpp");
+            await verifyRuns("whisper-cli", "--help", "whisper-cli", WHISPER_BUILD_HINT);
+          } else if (step.status === "manual") {
+            console.log(`✗ whisper-cli needs a manual step: ${step.hint}`);
+          }
+          break;
+        case "model":
+          if (step.status === "download") {
+            const modelPath = isAbsolute(model)
+              ? model
+              : join(cfg.modelDir, `ggml-${model}.bin`);
+            const info = MODELS[model];
+            if (!info) {
+              console.log(
+                `▸ ${model} isn't in the pinned table — downloading without a checksum.`,
+              );
+            }
+            console.log(`▸ downloading ggml-${model}.bin${info ? ` (~${info.sizeMB} MB)` : ""}…`);
+            await download(modelUrl(model), modelPath, {
+              sha1: info?.sha1,
+              onProgress: progressLine(`ggml-${model}.bin`),
+            });
+            console.log(`▸ model ready: ${modelPath}`);
+            if (opts.model && opts.model !== cfg.model) patch.model = opts.model;
+          } else if (step.status === "manual") {
+            console.log(`✗ model needs a manual step: ${step.hint}`);
+          }
+          break;
+        case "provider":
+          if (step.status === "prompt" && rl) {
+            await promptForProvider(
+              { ask: (q) => rl.question(q), say: (l) => console.log(l) },
+              CONFIG_DIR,
+            );
+          } else if (step.status === "prompt") {
+            console.log(
+              "▸ no LLM provider configured (non-interactive run) — needed for --produce only; " +
+                "set ANTHROPIC_API_KEY or GEMINI_API_KEY when you want it.",
+            );
+          }
+          break;
+      }
+    }
+
+    if (Object.keys(patch).length > 0) {
+      const path = saveConfigPatch(patch);
+      console.log(`▸ recorded in ${path}`);
+    }
+  } finally {
+    rl?.close();
+  }
+
+  // Setup's exit criterion is doctor's: all green, or the exact fix per line.
+  console.log("");
+  const { runDoctor, formatDoctor, realProbes } = await import("../doctor");
+  const { resolveEditorPageDir } = await import("../edit");
+  const checks = await runDoctor(loadConfig(), realProbes(resolveEditorPageDir()));
+  console.log(formatDoctor(checks));
+  if (failures.length > 0) process.exitCode = 1;
+}
+
+/** Download an asset (with resume) and extract it under the managed bin dir. */
+async function provision(kind: string, asset: BinaryAsset): Promise<string> {
+  const archive = join(CONFIG_DIR, "downloads", basename(new URL(asset.url).pathname));
+  const destDir = join(managedBinDir(CONFIG_DIR), `${kind}-${asset.version}`);
+  console.log(`▸ downloading ${basename(archive)} (~${asset.sizeMB} MB)…`);
+  await download(asset.url, archive, {
+    sha256: asset.sha256,
+    onProgress: progressLine(basename(archive)),
+  });
+  rmSync(destDir, { recursive: true, force: true });
+  mkdirSync(destDir, { recursive: true });
+  await extractArchive(archive, destDir);
+  for (const bin of asset.bins) {
+    const found = findFile(destDir, bin);
+    if (found) markExecutable(found);
+  }
+  // The archive did its job; ~160 MB of zip has no second life.
+  rmSync(archive, { force: true });
+  return destDir;
+}
+
+function mustFind(dir: string, bin: string): string {
+  const found = findFile(dir, bin);
+  if (!found) {
+    throw new Error(
+      `extracted archive doesn't contain ${bin} — upstream layout changed; ` +
+        "please open an issue with this output",
+    );
+  }
+  return found;
+}
+
+async function verifyRuns(bin: string, arg: string, name: string, hint?: string): Promise<void> {
+  if (await probeBin(bin, arg)) return;
+  throw new Error(
+    `${name} was installed but doesn't run on this machine (${bin}).` +
+      (hint ? `\nFallback: ${hint}` : ""),
+  );
+}
+
+function brewInstall(formula: string): Promise<void> {
+  console.log(`▸ brew install ${formula}…`);
+  return new Promise((resolve, reject) => {
+    const child = spawn("brew", ["install", formula], { stdio: "inherit" });
+    child.on("error", (e) => reject(new Error(`brew failed to start: ${e.message}`)));
+    child.on("exit", (code) =>
+      code === 0 ? resolve() : reject(new Error(`brew install ${formula} exited ${code}`)),
+    );
+  });
+}