@openparachute/vault 0.7.5-rc.4 → 0.7.5-rc.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.7.5-rc.4",
+  "version": "0.7.5-rc.6",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/cli.ts

@@ -175,6 +175,21 @@ import {
   type CliBuildResult,
 } from "./transcription/build.ts";
 import { downloadTo } from "./transcription/download.ts";
+import {
+  describeWhisperPlan,
+  planWhisperInstall,
+} from "./transcription/install-whisper-cpp.ts";
+import {
+  ensureBinaries,
+  ensureModel,
+  verifyTranscription,
+} from "./transcription/install-whisper-exec.ts";
+import {
+  binaryNameFor,
+  candidateBinDirs,
+  resolveCliBinary,
+  resolveFfmpeg,
+} from "./transcription/resolve-binary.ts";
 import { selectDefaultProvider, NOMINAL_SLACK_GB, type TierPlan } from "./transcription/tiers.ts";
 import {
   PYTHON_PROVIDERS,
@@ -3605,6 +3620,93 @@ function printTranscriptionPlan(plan: InstallPlan): void {
   console.log(`        ~${m.approxSizeMb}MB download, ~${m.approxRuntimeGb}GB peak RAM while transcribing`);
 }
 
+
+/**
+ * `parachute-vault transcription install` — the whisper.cpp path.
+ *
+ * Plan → binaries → model → VERIFY → activate. The verify step is the
+ * load-bearing one: the provider this replaces was activated by an install
+ * that never checked whether what it configured could run, which is how
+ * `TRANSCRIPTION_PROVIDER` came to point at a CLI that has never existed.
+ * `TRANSCRIPTION_PROVIDER` flips only after a real CLI transcribes a real
+ * file, so an install that reports success is one that works.
+ */
+async function runWhisperCppInstall(opts: {
+  modelId?: string;
+  dryRun: boolean;
+  yes: boolean;
+}): Promise<void> {
+  const plan = planWhisperInstall(opts.modelId, {
+    resolveExisting: (engine) => resolveCliBinary(engine),
+  });
+  for (const line of describeWhisperPlan(plan)) console.log(line);
+
+  if (!plan.supported) {
+    console.error("\nCan't install automatically on this host — see above.");
+    process.exit(1);
+  }
+  if (opts.dryRun) {
+    console.log("\n(dry run — nothing downloaded or changed)");
+    return;
+  }
+  if (!opts.yes) {
+    // Bun's global `confirm()` reads stdin. In a non-TTY — which is exactly
+    // how the unified setup script and any CI invocation call this — it would
+    // block forever, so require an explicit --yes there instead of hanging.
+    if (!process.stdin.isTTY) {
+      console.error(
+        "\nNot a terminal — re-run with --yes to install without confirmation.",
+      );
+      process.exit(1);
+    }
+    if (!confirm("\nProceed?")) {
+      console.log("Cancelled.");
+      return;
+    }
+  }
+
+  const log = (l: string) => console.log(`  ${l}`);
+
+  const bin = await ensureBinaries(plan, { log });
+  console.log(`${bin.ok ? "✓" : "✗"} ${bin.message}`);
+  if (!bin.ok) process.exit(1);
+
+  const model = await ensureModel(plan, { log });
+  console.log(`${model.ok ? "✓" : "✗"} ${model.message}`);
+  if (!model.ok) process.exit(1);
+
+  // Re-resolve AFTER install — a brew install just changed what's on disk.
+  const binPath = resolveCliBinary(plan.model.engine);
+  if (!binPath) {
+    console.error(
+      `✗ ${binaryNameFor(plan.model.engine)} still isn't resolvable after install. ` +
+        `Searched: ${candidateBinDirs().slice(0, 5).join(", ")}`,
+    );
+    process.exit(1);
+  }
+
+  const verified = await verifyTranscription(plan, binPath, { log });
+  console.log(`${verified.ok ? "✓" : "✗"} ${verified.message}`);
+  if (!verified.ok) {
+    console.error("\nNot activating — an install that can't transcribe isn't installed.");
+    process.exit(1);
+  }
+
+  setEnvVar("TRANSCRIPTION_PROVIDER", "whisper-cpp");
+  setEnvVar("TRANSCRIPTION_MODEL", plan.model.id);
+  console.log(`\n✓ Activated: whisper-cpp with ${plan.model.label}.`);
+
+  if (!resolveFfmpeg()) {
+    console.log(
+      "\n! ffmpeg isn't installed. Audio has to be transcoded to 16 kHz mono WAV before\n" +
+        "  transcription, so voice memos will fail until you install it:\n" +
+        "    macOS:  brew install ffmpeg\n" +
+        "    Debian: sudo apt install ffmpeg",
+    );
+  }
+  console.log("\nRestart the vault to apply (`parachute restart vault`).");
+}
+
 async function cmdTranscriptionInstall(args: string[]) {
   const dryRun = args.includes("--dry-run") || args.includes("--plan");
   const force = args.includes("--force");
@@ -3612,6 +3714,16 @@ async function cmdTranscriptionInstall(args: string[]) {
   const overrideModel = takeArgValue(args, "--model").value;
   const providerArg = takeArgValue(args, "--provider").value;
 
+  // whisper-cpp is the local path now, and the DEFAULT when no --provider is
+  // given. The legacy tier table below still serves an explicit
+  // `--provider transcribe-cpp|parakeet-mlx|onnx-asr`, but nothing routes
+  // there by default any more: transcribe-cpp's CLI has never shipped, and
+  // the Python providers need a venv plus a multi-GB model.
+  if (!providerArg || providerArg === "whisper-cpp") {
+    await runWhisperCppInstall({ modelId: overrideModel, dryRun, yes });
+    return;
+  }
+
   if (providerArg === "scribe-http") {
     // Just flip config back to the remote provider — no download.
     if (dryRun) {
@@ -3628,7 +3740,7 @@ async function cmdTranscriptionInstall(args: string[]) {
   if (providerArg) {
     if (!["transcribe-cpp", "parakeet-mlx", "onnx-asr"].includes(providerArg)) {
       console.error(
-        `Unknown --provider "${providerArg}". Valid: transcribe-cpp, parakeet-mlx, onnx-asr, scribe-http.`,
+        `Unknown --provider "${providerArg}". Valid: whisper-cpp (default), transcribe-cpp, parakeet-mlx, onnx-asr, scribe-http.`,
       );
       process.exit(1);
     }

package/src/transcription/install-whisper-cpp.test.ts

@@ -0,0 +1,228 @@
+/**
+ * The whisper.cpp install planner.
+ *
+ * Pure, so the whole host matrix is exercised without downloading anything.
+ * The cases that matter are the ones where a wrong answer is expensive: a
+ * platform with no prebuilt binaries must REFUSE with instructions rather than
+ * half-install, and an already-installed binary must short-circuit rather than
+ * triggering another package-manager round trip.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { DEFAULT_MODEL_ID } from "./models.ts";
+import {
+  describeWhisperPlan,
+  planBinaryStrategy,
+  planWhisperInstall,
+  WHISPER_CPP_VERSION,
+} from "./install-whisper-cpp.ts";
+
+const GB = 1024 * 1024 * 1024;
+const env = { PARACHUTE_HOME: "/ph" } as NodeJS.ProcessEnv;
+
+describe("planBinaryStrategy", () => {
+  test("macOS → Homebrew (upstream ships no macOS CLI tarball)", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "arm64",
+      totalRamBytes: 16 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("homebrew");
+    expect(s.kind === "homebrew" && s.formula).toBe("whisper-cpp");
+  });
+
+  test("macOS Intel also gets Homebrew — the formula covers both arches", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "x64",
+      totalRamBytes: 16 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("homebrew");
+  });
+
+  test("Linux x64 → the x64 release tarball, pinned to a version", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("tarball");
+    if (s.kind === "tarball") {
+      expect(s.assetName).toBe("whisper-bin-ubuntu-x64.tar.gz");
+      expect(s.url).toContain(`v${WHISPER_CPP_VERSION}`);
+    }
+  });
+
+  test("Linux arm64 → the arm64 tarball", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "arm64",
+      totalRamBytes: 8 * GB,
+      env,
+    }).binary;
+    expect(s.kind === "tarball" && s.assetName).toBe("whisper-bin-ubuntu-arm64.tar.gz");
+  });
+
+  test("an exotic Linux arch REFUSES with a pointer at the override", () => {
+    const s = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "riscv64",
+      totalRamBytes: 8 * GB,
+      env,
+    }).binary;
+    expect(s.kind).toBe("unsupported");
+    expect(s.kind === "unsupported" && s.reason).toMatch(/WHISPER_CPP_BIN_DIR/);
+  });
+
+  test("an unknown platform refuses rather than half-installing", () => {
+    const plan = planWhisperInstall(undefined, {
+      platform: "freebsd",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(plan.supported).toBe(false);
+    expect(plan.binary.kind).toBe("unsupported");
+  });
+
+  test("an already-installed binary short-circuits every package manager", () => {
+    const plan = planWhisperInstall(undefined, {
+      platform: "darwin",
+      arch: "arm64",
+      totalRamBytes: 16 * GB,
+      env,
+      resolveExisting: () => "/opt/homebrew/bin/parakeet-cli",
+    });
+    expect(plan.binary.kind).toBe("already-present");
+    expect(plan.supported).toBe(true);
+  });
+});
+
+describe("model selection", () => {
+  test("a capable box gets the recommended Parakeet", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(p.model.id).toBe(DEFAULT_MODEL_ID);
+    expect(p.modelExplicit).toBe(false);
+  });
+
+  test("a 2 GB VPS still gets Parakeet, not a step down to Whisper Tiny", () => {
+    // The common cheap-VPS tier. Parakeet q4 is 339 MB and comfortably fits;
+    // dropping to Whisper Tiny here would be a large accuracy loss for
+    // headroom the box didn't need.
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 2 * GB,
+      env,
+    });
+    expect(p.model.engine).toBe("parakeet");
+  });
+
+  test("a 1 GB box steps down rather than swapping itself to death", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 1 * GB,
+      env,
+    });
+    expect(p.model.sizeMb).toBeLessThan(150);
+  });
+
+  test("an explicit model is honoured over the RAM pick, with a warning", () => {
+    const p = planWhisperInstall("whisper-large-v3-turbo", {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 2 * GB,
+      env,
+    });
+    expect(p.model.id).toBe("whisper-large-v3-turbo");
+    expect(p.modelExplicit).toBe(true);
+    // Honoured, but the operator is told what they're in for.
+    expect(p.ramWarning).toBeTruthy();
+    expect(p.ramWarning).toMatch(/may swap or run slowly/);
+  });
+
+  test("no warning when the box comfortably fits the model", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 32 * GB,
+      env,
+    });
+    expect(p.ramWarning).toBeUndefined();
+  });
+
+  test("an unknown model id is refused, NOT silently defaulted", () => {
+    // Silently installing something else would leave the operator convinced
+    // they're running a model they aren't.
+    const p = planWhisperInstall("whisper-enormous", {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(p.supported).toBe(false);
+    expect(p.binary.kind === "unsupported" && p.binary.reason).toMatch(/unknown model id/);
+  });
+
+  test("paths honour PARACHUTE_HOME", () => {
+    const p = planWhisperInstall(undefined, {
+      platform: "linux",
+      arch: "x64",
+      totalRamBytes: 8 * GB,
+      env,
+    });
+    expect(p.modelPath.startsWith("/ph/transcription/models/")).toBe(true);
+    expect(p.binDir).toBe("/ph/transcription/bin");
+  });
+});
+
+describe("describeWhisperPlan", () => {
+  test("names the model, its size, and where it goes", () => {
+    const out = describeWhisperPlan(
+      planWhisperInstall(undefined, {
+        platform: "linux",
+        arch: "x64",
+        totalRamBytes: 8 * GB,
+        env,
+      }),
+    ).join("\n");
+    expect(out).toMatch(/Parakeet/);
+    expect(out).toMatch(/396 MB/);
+    expect(out).toMatch(/\/ph\/transcription\/models/);
+  });
+
+  test("an unsupported host explains itself rather than printing a plan", () => {
+    const out = describeWhisperPlan(
+      planWhisperInstall(undefined, {
+        platform: "freebsd",
+        arch: "x64",
+        totalRamBytes: 8 * GB,
+        env,
+      }),
+    ).join("\n");
+    expect(out).toMatch(/UNSUPPORTED/);
+    expect(out).toMatch(/WHISPER_CPP_BIN_DIR/);
+  });
+
+  test("the macOS line tells you what brew actually gives you", () => {
+    const out = describeWhisperPlan(
+      planWhisperInstall(undefined, {
+        platform: "darwin",
+        arch: "arm64",
+        totalRamBytes: 16 * GB,
+        env,
+      }),
+    ).join("\n");
+    expect(out).toMatch(/brew install whisper-cpp/);
+    expect(out).toMatch(/whisper-cli \+ parakeet-cli/);
+  });
+});

package/src/transcription/install-whisper-cpp.ts

@@ -0,0 +1,219 @@
+/**
+ * `parachute-vault transcription install` for the whisper.cpp provider.
+ *
+ * Split into a PURE planner and a thin executor. The planner takes the host's
+ * platform/arch/RAM and the operator's flags and answers "what would happen" —
+ * no network, no writes — so `--dry-run` and the tests exercise the whole
+ * decision matrix without downloading a byte.
+ *
+ * ## How the binaries arrive, per platform
+ *
+ * **macOS** — Homebrew, and only Homebrew. whisper.cpp publishes release
+ * tarballs for Linux and Windows but NOT macOS (the macOS artifact is an
+ * `.xcframework`, which is for embedding in an app, not a CLI to spawn). The
+ * formula is bottled for arm64 Tahoe/Sequoia/Sonoma, so `brew install
+ * whisper-cpp` is a fast binary download rather than a source build. With no
+ * brew on the box we refuse and say so plainly — pretending to have another
+ * route would just fail later and more confusingly.
+ *
+ * **Linux** — the release tarball, extracted into our own managed directory
+ * (`<root>/transcription/bin`) rather than anywhere system-wide. The tarball
+ * carries `whisper-cli`, `parakeet-cli`, and the `libggml*`/`libwhisper` shared
+ * objects they link against, so the whole set moves together and we never
+ * fight a distro's package manager.
+ *
+ * ## Why it verifies before declaring success
+ *
+ * The provider this replaces was configured by an install verb that never
+ * checked whether the thing it configured could run — which is exactly how
+ * `TRANSCRIPTION_PROVIDER=transcribe-cpp` came to point at a CLI that has
+ * never existed. So the last step here actually SPAWNS the CLI against a
+ * generated test clip and reads the transcript back. `TRANSCRIPTION_PROVIDER`
+ * flips only after that passes. An install that can't transcribe is an install
+ * that failed, and it should say so at install time rather than silently at
+ * the first voice memo.
+ */
+
+import { totalmem } from "os";
+import { join } from "path";
+import {
+  DEFAULT_MODEL_ID,
+  findModel,
+  pickDefaultModel,
+  type TranscriptionModel,
+} from "./models.ts";
+import { binaryNameFor, managedBinDir, managedModelDir } from "./resolve-binary.ts";
+
+/** whisper.cpp release the Linux tarballs are pulled from. */
+export const WHISPER_CPP_VERSION = "1.9.1";
+
+/** How the CLI binaries get onto this box. */
+export type BinaryStrategy =
+  | { kind: "homebrew"; formula: string }
+  | { kind: "tarball"; url: string; assetName: string }
+  | { kind: "already-present"; path: string }
+  | { kind: "unsupported"; reason: string };
+
+export interface WhisperInstallPlan {
+  platform: string;
+  arch: string;
+  totalRamGb: number;
+  /** The model to fetch + activate. */
+  model: TranscriptionModel;
+  /** Whether the operator named the model explicitly (skips the RAM warning). */
+  modelExplicit: boolean;
+  /** How to obtain `whisper-cli` / `parakeet-cli`. */
+  binary: BinaryStrategy;
+  /** Absolute destination for the model file. */
+  modelPath: string;
+  /** Directory binaries land in (tarball strategy) or are found in. */
+  binDir: string;
+  /** True when the plan can proceed. */
+  supported: boolean;
+  /** Set when the box has less RAM than the chosen model wants. */
+  ramWarning?: string;
+}
+
+export interface PlanDeps {
+  platform?: string;
+  arch?: string;
+  totalRamBytes?: number;
+  env?: NodeJS.ProcessEnv;
+  /** Existing binary probe — lets the plan report "already present". */
+  resolveExisting?: (engine: "whisper" | "parakeet") => string | undefined;
+}
+
+/**
+ * Decide how to get the binaries for this host.
+ *
+ * `already-present` short-circuits everything: an operator who ran `brew
+ * install whisper-cpp` themselves, or who is re-running install, shouldn't
+ * trigger another package-manager round trip.
+ */
+export function planBinaryStrategy(
+  model: TranscriptionModel,
+  deps: PlanDeps = {},
+): BinaryStrategy {
+  const platform = deps.platform ?? process.platform;
+  const arch = deps.arch ?? process.arch;
+
+  const existing = deps.resolveExisting?.(model.engine);
+  if (existing) return { kind: "already-present", path: existing };
+
+  if (platform === "darwin") {
+    // No macOS CLI tarball exists upstream — the macOS artifact is an
+    // xcframework for embedding, not a spawnable binary. Homebrew is the path.
+    return { kind: "homebrew", formula: "whisper-cpp" };
+  }
+
+  if (platform === "linux") {
+    const assetArch = arch === "arm64" || arch === "aarch64" ? "arm64" : arch === "x64" ? "x64" : null;
+    if (!assetArch) {
+      return {
+        kind: "unsupported",
+        reason: `no prebuilt whisper.cpp binaries for linux/${arch} — build whisper.cpp yourself and point WHISPER_CPP_BIN_DIR at the result`,
+      };
+    }
+    const assetName = `whisper-bin-ubuntu-${assetArch}.tar.gz`;
+    return {
+      kind: "tarball",
+      assetName,
+      url: `https://github.com/ggml-org/whisper.cpp/releases/download/v${WHISPER_CPP_VERSION}/${assetName}`,
+    };
+  }
+
+  return {
+    kind: "unsupported",
+    reason: `${platform} isn't supported for automatic install — install whisper.cpp yourself and point WHISPER_CPP_BIN_DIR at the directory holding ${binaryNameFor(model.engine)}`,
+  };
+}
+
+/**
+ * Build the full plan. Pure — safe to call for `--dry-run`.
+ *
+ * `modelId` undefined means "pick for this box": `pickDefaultModel` steps down
+ * from the recommended Parakeet on a machine that can't comfortably hold it.
+ * An explicitly-named model is honoured even when it's a stretch for the RAM,
+ * with a warning — the operator may know something we don't.
+ */
+export function planWhisperInstall(
+  modelId: string | undefined,
+  deps: PlanDeps = {},
+): WhisperInstallPlan {
+  const platform = deps.platform ?? process.platform;
+  const arch = deps.arch ?? process.arch;
+  const totalRamBytes = deps.totalRamBytes ?? totalmem();
+  const totalRamMb = Math.round(totalRamBytes / 1024 / 1024);
+  const env = deps.env ?? process.env;
+
+  const explicit = modelId !== undefined;
+  const model = explicit
+    ? findModel(modelId)
+    : pickDefaultModel(totalRamMb);
+
+  if (!model) {
+    // Unknown id — surface it as unsupported rather than silently defaulting,
+    // so a typo doesn't quietly install something else.
+    const fallback = findModel(DEFAULT_MODEL_ID)!;
+    return {
+      platform,
+      arch,
+      totalRamGb: Math.round((totalRamMb / 1024) * 10) / 10,
+      model: fallback,
+      modelExplicit: true,
+      binary: { kind: "unsupported", reason: `unknown model id "${modelId}"` },
+      modelPath: join(managedModelDir(env), fallback.filename),
+      binDir: managedBinDir(env),
+      supported: false,
+    };
+  }
+
+  const binary = planBinaryStrategy(model, deps);
+  const ramWarning =
+    totalRamMb < model.minRamMb
+      ? `${model.label} wants about ${Math.round(model.minRamMb / 1024)} GB of RAM and this box reports ${Math.round((totalRamMb / 1024) * 10) / 10} GB — it may swap or run slowly.`
+      : undefined;
+
+  return {
+    platform,
+    arch,
+    totalRamGb: Math.round((totalRamMb / 1024) * 10) / 10,
+    model,
+    modelExplicit: explicit,
+    binary,
+    modelPath: join(managedModelDir(env), model.filename),
+    binDir:
+      binary.kind === "already-present"
+        ? binary.path.slice(0, binary.path.lastIndexOf("/"))
+        : managedBinDir(env),
+    supported: binary.kind !== "unsupported",
+    ramWarning,
+  };
+}
+
+/** Human-readable plan, shared by `--dry-run` and the real run. */
+export function describeWhisperPlan(plan: WhisperInstallPlan): string[] {
+  const lines: string[] = [];
+  lines.push(`Host:   ${plan.platform}/${plan.arch}, ${plan.totalRamGb} GB RAM`);
+  lines.push(`Model:  ${plan.model.label} (${plan.model.sizeMb} MB)`);
+  lines.push(`        ${plan.model.note}`);
+  lines.push(`        → ${plan.modelPath}`);
+
+  switch (plan.binary.kind) {
+    case "already-present":
+      lines.push(`Engine: ${binaryNameFor(plan.model.engine)} already installed at ${plan.binary.path}`);
+      break;
+    case "homebrew":
+      lines.push(`Engine: brew install ${plan.binary.formula}  (installs whisper-cli + parakeet-cli)`);
+      break;
+    case "tarball":
+      lines.push(`Engine: download ${plan.binary.assetName}`);
+      lines.push(`        → ${plan.binDir}`);
+      break;
+    case "unsupported":
+      lines.push(`Engine: UNSUPPORTED — ${plan.binary.reason}`);
+      break;
+  }
+  if (plan.ramWarning) lines.push(`Note:   ${plan.ramWarning}`);
+  return lines;
+}