@openparachute/vault 0.7.4 → 0.7.5-rc.4

package/src/transcription/resolve-binary.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Binary resolution across the routes whisper.cpp actually arrives by.
+ *
+ * The case worth the most care is Homebrew: a launchd-supervised vault does
+ * NOT inherit a login shell's PATH, so on macOS `whisper-cli` is routinely
+ * installed and simultaneously invisible to the running daemon. Probing brew's
+ * prefixes explicitly is what stops "I installed it and it still says not
+ * configured" — the worst failure available here, because the operator did the
+ * work and got told no.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { join } from "path";
+import {
+  binaryNameFor,
+  candidateBinDirs,
+  managedBinDir,
+  managedModelDir,
+  resolveCliBinary,
+  resolveFfmpeg,
+} from "./resolve-binary.ts";
+
+/** An existsImpl that only knows about an explicit allow-list. */
+function only(...present: string[]) {
+  const set = new Set(present);
+  return (p: string) => set.has(p);
+}
+
+describe("binaryNameFor", () => {
+  test("maps engine → CLI name", () => {
+    expect(binaryNameFor("whisper")).toBe("whisper-cli");
+    expect(binaryNameFor("parakeet")).toBe("parakeet-cli");
+  });
+});
+
+describe("candidateBinDirs — the ladder", () => {
+  const env = { PARACHUTE_HOME: "/ph", PATH: "/usr/bin:/bin" } as NodeJS.ProcessEnv;
+
+  test("managed dir precedes brew, which precedes PATH", () => {
+    const dirs = candidateBinDirs({ env });
+    expect(dirs.indexOf("/ph/transcription/bin")).toBeLessThan(dirs.indexOf("/opt/homebrew/bin"));
+    expect(dirs.indexOf("/opt/homebrew/bin")).toBeLessThan(dirs.indexOf("/usr/bin"));
+  });
+
+  test("an explicit override leads everything", () => {
+    const dirs = candidateBinDirs({ env: { ...env, WHISPER_CPP_BIN_DIR: "/custom" } });
+    expect(dirs[0]).toBe("/custom");
+  });
+
+  test("brew prefixes are probed even when absent from PATH — the launchd case", () => {
+    // A launchd-supervised daemon gets a minimal PATH with no /opt/homebrew.
+    const dirs = candidateBinDirs({ env: { PATH: "/usr/bin:/bin" } as NodeJS.ProcessEnv });
+    expect(dirs).toContain("/opt/homebrew/bin");
+    expect(dirs).toContain("/usr/local/bin");
+  });
+
+  test("no duplicates, order preserved", () => {
+    const dirs = candidateBinDirs({
+      env: { PATH: "/usr/bin:/opt/homebrew/bin:/usr/bin" } as NodeJS.ProcessEnv,
+    });
+    expect(dirs.length).toBe(new Set(dirs).size);
+  });
+
+  test("an empty PATH doesn't produce empty-string dirs", () => {
+    const dirs = candidateBinDirs({ env: { PATH: "" } as NodeJS.ProcessEnv });
+    expect(dirs).not.toContain("");
+  });
+});
+
+describe("resolveCliBinary", () => {
+  const env = { PARACHUTE_HOME: "/ph", PATH: "/usr/bin" } as NodeJS.ProcessEnv;
+
+  test("finds a brew-installed binary a bare PATH lookup would miss", () => {
+    const got = resolveCliBinary("parakeet", {
+      env,
+      existsImpl: only("/opt/homebrew/bin/parakeet-cli"),
+    });
+    expect(got).toBe("/opt/homebrew/bin/parakeet-cli");
+  });
+
+  test("our managed install wins over a brew one", () => {
+    const got = resolveCliBinary("whisper", {
+      env,
+      existsImpl: only("/ph/transcription/bin/whisper-cli", "/opt/homebrew/bin/whisper-cli"),
+    });
+    expect(got).toBe("/ph/transcription/bin/whisper-cli");
+  });
+
+  test("the override beats everything", () => {
+    const got = resolveCliBinary("whisper", {
+      env: { ...env, WHISPER_CPP_BIN_DIR: "/custom" },
+      existsImpl: only("/custom/whisper-cli", "/ph/transcription/bin/whisper-cli"),
+    });
+    expect(got).toBe("/custom/whisper-cli");
+  });
+
+  test("returns an ABSOLUTE path, never a bare name", () => {
+    const got = resolveCliBinary("parakeet", { env, existsImpl: only("/usr/bin/parakeet-cli") });
+    // A bare name would be re-resolved against the spawn's PATH, which may
+    // differ from the one we probed.
+    expect(got?.startsWith("/")).toBe(true);
+  });
+
+  test("undefined when genuinely absent", () => {
+    expect(resolveCliBinary("whisper", { env, existsImpl: () => false })).toBeUndefined();
+  });
+
+  test("engine selects the binary — a whisper install doesn't satisfy parakeet", () => {
+    const deps = { env, existsImpl: only("/usr/bin/whisper-cli") };
+    expect(resolveCliBinary("whisper", deps)).toBe("/usr/bin/whisper-cli");
+    expect(resolveCliBinary("parakeet", deps)).toBeUndefined();
+  });
+});
+
+describe("resolveFfmpeg", () => {
+  test("uses the same ladder, so a brew ffmpeg is found under launchd too", () => {
+    const got = resolveFfmpeg({
+      env: { PATH: "/usr/bin" } as NodeJS.ProcessEnv,
+      existsImpl: only("/opt/homebrew/bin/ffmpeg"),
+    });
+    expect(got).toBe("/opt/homebrew/bin/ffmpeg");
+  });
+});
+
+describe("managed paths honour PARACHUTE_HOME", () => {
+  test("bin + model dirs sit under the ecosystem root", () => {
+    const env = { PARACHUTE_HOME: "/custom/root" } as NodeJS.ProcessEnv;
+    expect(managedBinDir(env)).toBe(join("/custom/root", "transcription", "bin"));
+    expect(managedModelDir(env)).toBe(join("/custom/root", "transcription", "models"));
+  });
+});

package/src/transcription/resolve-binary.ts

@@ -0,0 +1,111 @@
+/**
+ * Where the whisper.cpp CLIs live, on a box we didn't install.
+ *
+ * The binaries arrive by more than one route and we should find them however
+ * they got there, because "it's installed but Parachute can't see it" is the
+ * worst version of this failure — the operator did the work and got told no.
+ *
+ * The ladder, first hit wins:
+ *
+ *   1. **`WHISPER_CPP_BIN_DIR`** — explicit operator override. Always wins;
+ *      an operator who set it has a reason.
+ *   2. **`<PARACHUTE_HOME>/transcription/bin/`** — where `transcription
+ *      install` puts the Linux release tarball's binaries. Ours, so we check
+ *      it before anything system-wide.
+ *   3. **Homebrew prefix** — `brew install whisper-cpp` is the macOS path and
+ *      lands in `/opt/homebrew/bin` (Apple Silicon) or `/usr/local/bin`
+ *      (Intel). Checked explicitly rather than relying on PATH because a
+ *      launchd-supervised daemon does NOT inherit a login shell's PATH, so
+ *      `whisper-cli` can be perfectly installed and still invisible to the
+ *      running vault. That's the single most likely way this breaks on a Mac.
+ *   4. **`PATH`** — the ordinary case on Linux, and the escape hatch for any
+ *      packaging we didn't anticipate.
+ *
+ * Returns absolute paths, never bare names, so the spawn can't be re-resolved
+ * against a different PATH than the one we probed.
+ */
+
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { delimiter, join } from "path";
+import type { TranscriptionEngine } from "./models.ts";
+
+/** Binary name for an engine. */
+export function binaryNameFor(engine: TranscriptionEngine): string {
+  return engine === "whisper" ? "whisper-cli" : "parakeet-cli";
+}
+
+/** Homebrew prefixes worth probing, most likely first. */
+const BREW_PREFIXES = ["/opt/homebrew", "/usr/local", "/home/linuxbrew/.linuxbrew"] as const;
+
+export interface ResolveBinaryDeps {
+  env?: NodeJS.ProcessEnv;
+  existsImpl?: (p: string) => boolean;
+}
+
+/** The ecosystem root, mirroring `config.ts`'s resolution. */
+function ecosystemRoot(env: NodeJS.ProcessEnv): string {
+  return env.PARACHUTE_HOME ?? join(homedir(), ".parachute");
+}
+
+/** Where `transcription install` writes downloaded binaries. */
+export function managedBinDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(ecosystemRoot(env), "transcription", "bin");
+}
+
+/** Where `transcription install` writes downloaded models. */
+export function managedModelDir(env: NodeJS.ProcessEnv = process.env): string {
+  return join(ecosystemRoot(env), "transcription", "models");
+}
+
+/**
+ * Every directory the ladder will probe, in order. Exported so the install
+ * verb and the admin UI can SHOW the operator where we looked — a "not found"
+ * that lists the searched paths is debuggable; one that doesn't isn't.
+ */
+export function candidateBinDirs(deps: ResolveBinaryDeps = {}): string[] {
+  const env = deps.env ?? process.env;
+  const dirs: string[] = [];
+
+  const override = env.WHISPER_CPP_BIN_DIR?.trim();
+  if (override) dirs.push(override);
+
+  dirs.push(managedBinDir(env));
+
+  for (const prefix of BREW_PREFIXES) dirs.push(join(prefix, "bin"));
+
+  for (const p of (env.PATH ?? "").split(delimiter)) {
+    const t = p.trim();
+    if (t.length > 0) dirs.push(t);
+  }
+
+  // Dedupe, preserving order.
+  return [...new Set(dirs)];
+}
+
+/**
+ * Resolve a CLI to an absolute path, or `undefined` when it isn't anywhere we
+ * look. See the module header for the ladder and why brew is probed explicitly.
+ */
+export function resolveCliBinary(
+  engine: TranscriptionEngine,
+  deps: ResolveBinaryDeps = {},
+): string | undefined {
+  const exists = deps.existsImpl ?? existsSync;
+  const name = binaryNameFor(engine);
+  for (const dir of candidateBinDirs(deps)) {
+    const candidate = join(dir, name);
+    if (exists(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** Resolve `ffmpeg` the same way. Same launchd-PATH problem, same fix. */
+export function resolveFfmpeg(deps: ResolveBinaryDeps = {}): string | undefined {
+  const exists = deps.existsImpl ?? existsSync;
+  for (const dir of candidateBinDirs(deps)) {
+    const candidate = join(dir, "ffmpeg");
+    if (exists(candidate)) return candidate;
+  }
+  return undefined;
+}

package/src/transcription/select.ts

@@ -29,8 +29,10 @@
 import { join } from "path";
 import { homedir } from "os";
 import { existsSync, readFileSync } from "fs";
+import { DEFAULT_MODEL_ID } from "./models.ts";
 
 export const TRANSCRIPTION_PROVIDERS = [
+  "whisper-cpp",
   "scribe-http",
   "transcribe-cpp",
   "parakeet-mlx",
@@ -54,9 +56,17 @@ export const DEFAULT_ONNX_ASR_MODEL = "nemo-parakeet-tdt-0.6b-v3";
 
 /**
  * Resolve the configured provider name. `TRANSCRIPTION_PROVIDER` selects it;
- * unset (or blank) ⇒ `scribe-http` (the behavior-preserving default). An
- * unrecognized value warns once and falls back to `scribe-http` rather than
- * failing boot — a typo shouldn't take transcription offline hard.
+ * unset (or blank) ⇒ `scribe-http`. An unrecognized value warns once and falls
+ * back rather than failing boot — a typo shouldn't take transcription offline
+ * hard.
+ *
+ * NOTE on the default: `scribe-http` remains the fallback for now because
+ * flipping it is a separate, riskier change — see the `whisper-cpp` entry in
+ * `models.ts`. On a box with nothing configured, `scribe-http` with no
+ * SCRIBE_URL means transcription doesn't run at all, which vault#643 now
+ * reports honestly instead of silently skipping. Making `whisper-cpp` the
+ * default is the follow-up, once `transcription install` can guarantee a
+ * runnable binary + model.
  */
 export function resolveTranscriptionProviderName(
   env: NodeJS.ProcessEnv = process.env,
@@ -395,3 +405,16 @@ export function onnxAsrInstalled(
   const bin = resolveOnnxAsrBin(env, deps);
   return !!bin && (deps.existsImpl ?? existsSync)(bin);
 }
+
+/**
+ * Resolve the configured model id for the `whisper-cpp` provider.
+ * `TRANSCRIPTION_MODEL` selects it; unset ⇒ the catalog default.
+ *
+ * Unlike the provider name, an unknown value is NOT silently coerced — the
+ * caller reports it, because a typo'd model id should be visible rather than
+ * quietly transcribing with something the operator didn't choose.
+ */
+export function resolveTranscriptionModelId(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.TRANSCRIPTION_MODEL?.trim();
+  return raw && raw.length > 0 ? raw : DEFAULT_MODEL_ID;
+}