Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): use a healthy pinned Sherpa copy beside the CLI (#5095)
Miguel Ángelf6e419eb2956
diff --git a/packages/cli/src/commands/models.test.ts b/packages/cli/src/commands/models.test.tsindex 57a1ef49c1..f7c6ec7755 100644--- a/packages/cli/src/commands/models.test.ts+++ b/packages/cli/src/commands/models.test.ts@@ -1,6 +1,8 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import { CliRuntimeError, consumeCommandResult } from "../utils/commandResult.js";+const cachedRuntimePath =+ "/cache/optional/[email protected]/node_modules/sherpa-onnx-node/index.js";const sherpa = {SHERPA_RUNTIME_DIR: "/cache/optional/[email protected]",PARAKEET_MODEL_DIR: "/cache/parakeet/parakeet-tdt-0.6b-v3-int8",@@ -44,7 +46,10 @@ describe("models install parakeet --json", () => {consumeCommandResult();vi.spyOn(console, "log").mockImplementation(() => {});sherpa.sherpaUnsupportedReason.mockReturnValue(null);- sherpa.installSherpaRuntime.mockResolvedValue(true);+ sherpa.installSherpaRuntime.mockResolvedValue({+ installed: true,+ runtimePath: cachedRuntimePath,+ });sherpa.ensureParakeetModel.mockResolvedValue(false);});afterEach(() => vi.restoreAllMocks());@@ -58,6 +63,7 @@ describe("models install parakeet --json", () => {model: "parakeet-tdt-0.6b-v3",changed: true,runtimeDir: sherpa.SHERPA_RUNTIME_DIR,+ runtimePath: cachedRuntimePath,modelDir: sherpa.PARAKEET_MODEL_DIR,},});@@ -65,10 +71,24 @@ describe("models install parakeet --json", () => {});it("reports changed: false when the runtime loads and the model verifies", async () => {- sherpa.installSherpaRuntime.mockResolvedValue(false);+ sherpa.installSherpaRuntime.mockResolvedValue({+ installed: false,+ runtimePath: cachedRuntimePath,+ });expect((await install()).out).toMatchObject({ ok: true, changed: false });});+ it("reports a selected beside copy while retaining the cache destination", async () => {+ const runtimePath = "/bundle/node_modules/sherpa-onnx-node/index.js";+ sherpa.installSherpaRuntime.mockResolvedValue({ installed: false, runtimePath });+ expect((await install()).out).toMatchObject({+ ok: true,+ changed: false,+ runtimeDir: sherpa.SHERPA_RUNTIME_DIR,+ runtimePath,+ });+ });+it("reports a failed install as ok:false with exit 1", async () => {sherpa.ensureParakeetModel.mockRejectedValue(new Error("tokens.txt did not match"));expect(await install()).toEqual({diff --git a/packages/cli/src/commands/models.ts b/packages/cli/src/commands/models.tsindex b405daa91b..7fcee8c9f2 100644--- a/packages/cli/src/commands/models.ts+++ b/packages/cli/src/commands/models.ts@@ -43,18 +43,18 @@ function downloadProgress(spin: Spinner) {type Sherpa = typeof import("../whisper/sherpa.js");type Spinner = ReturnType<typeof clack.spinner> | null;-/** Installs what is missing; true when anything changed. */+/** Installs missing pieces and carries the selected runtime provenance into the result. */async function installMissing(sherpa: Sherpa, spin: Spinner, signal: AbortSignal) {- const runtimeInstalled = await sherpa.installSherpaRuntime({ signal });+ const runtime = await sherpa.installSherpaRuntime({ signal });spin?.message("Verifying the Parakeet model...");const modelFetched = await sherpa.ensureParakeetModel({signal,onBytes: downloadProgress(spin),});- return runtimeInstalled || modelFetched;+ return { changed: runtime.installed || modelFetched, runtimePath: runtime.runtimePath };}-/** A synchronous child's Ctrl-C shows as its error before the scope's listener runs. */+/** Cancellation can reach the child before the scope observes the signal. */const wasCancelled = (err: unknown, signal: AbortSignal, sherpa: Sherpa) =>signal.aborted || err instanceof sherpa.DecodeCancelled;@@ -68,12 +68,19 @@ async function installParakeet(json: boolean): Promise<void> {const cancellation = createRenderCancellationScope();spin?.start("Checking the sherpa-onnx runtime (installing it from npm if it does not load)...");try {- const changed = await installMissing(sherpa, spin, cancellation.signal);+ const { changed, runtimePath } = await installMissing(sherpa, spin, cancellation.signal);spin?.stop(c.success(changed ? "Parakeet installed" : "Parakeet is already installed"));if (json) {const { SHERPA_RUNTIME_DIR: runtimeDir, PARAKEET_MODEL_DIR: modelDir } = sherpa;console.log(- JSON.stringify({ ok: true, model: PARAKEET_MODEL_LABEL, changed, runtimeDir, modelDir }),+ JSON.stringify({+ ok: true,+ model: PARAKEET_MODEL_LABEL,+ changed,+ runtimeDir,+ runtimePath,+ modelDir,+ }),);}} catch (err) {diff --git a/packages/cli/src/commands/transcribe.test.ts b/packages/cli/src/commands/transcribe.test.tsindex e572d1c175..8f40d578cf 100644--- a/packages/cli/src/commands/transcribe.test.ts+++ b/packages/cli/src/commands/transcribe.test.ts@@ -1,8 +1,17 @@import { runCommand } from "citty";import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";-import { chmodSync, existsSync, writeFileSync, readFileSync, mkdtempSync, rmSync } from "node:fs";+import {+ chmodSync,+ mkdirSync,+ existsSync,+ writeFileSync,+ readFileSync,+ mkdtempSync,+ rmSync,+} from "node:fs";import { join } from "node:path";import { tmpdir } from "node:os";+import { pathToFileURL } from "node:url";import { WhisperUnavailableError } from "../whisper/manager.js";import { CliRuntimeError, consumeCommandResult } from "../utils/commandResult.js";@@ -18,10 +27,24 @@ vi.mock("../whisper/transcribe.js", () => ({// Engine selection: which runners look installed, and the sherpa decode child it spawns.const runners = { sherpa: false, mlx: false };-vi.mock("../whisper/sherpa.js", async (importOriginal) => ({- ...(await importOriginal<typeof import("../whisper/sherpa.js")>()),- sherpaParakeetInstalled: () => runners.sherpa,-}));+let runtimeDir: string;+vi.mock("../whisper/sherpa.js", async (importOriginal) => {+ const sherpa = await importOriginal<typeof import("../whisper/sherpa.js")>();+ return {+ ...sherpa,+ sherpaParakeetInstalled: () => runners.sherpa,+ transcribeWithSherpa: (+ wavPath: string,+ dir: string,+ options: Parameters<typeof sherpa.transcribeWithSherpa>[2],+ ) =>+ sherpa.transcribeWithSherpa(wavPath, dir, {+ ...options,+ runtimeDir,+ cliUrl: pathToFileURL(join(runtimeDir, "dist", "cli.js")).href,+ }),+ };+});const mlxMock = vi.fn();vi.mock("../whisper/parakeet.js", async (importOriginal) => ({...(await importOriginal<typeof import("../whisper/parakeet.js")>()),@@ -165,6 +188,12 @@ describe("transcribe command", () => {describe("engine selection", () => {beforeEach(() => {+ runtimeDir = mkdtempSync(join(tmpdir(), "hf-transcribe-runtime-"));+ dirs.push(runtimeDir);+ const pkg = join(runtimeDir, "node_modules", "sherpa-onnx-node");+ mkdirSync(pkg, { recursive: true });+ writeFileSync(join(pkg, "package.json"), JSON.stringify({ main: "index.js" }));+ writeFileSync(join(pkg, "index.js"), "module.exports = {};");transcribeMock.mockImplementation(async (_in: string, dir: string) =>fakeTranscript(dir, "whisper"),);diff --git a/packages/cli/src/utils/optionalPackages.test.ts b/packages/cli/src/utils/optionalPackages.test.tsindex e1c0a6e983..cf89c48859 100644--- a/packages/cli/src/utils/optionalPackages.test.ts+++ b/packages/cli/src/utils/optionalPackages.test.ts@@ -132,9 +132,9 @@ describe("loadOptionalPackage", () => {describe("a copy installed beside the CLI", () => {// node_modules/hyperframes/dist/cli.js with onnxruntime-node installed next to hyperframes.- function layout(version: string) {+ function layout(version: string, name = "onnxruntime-node") {const root = mkdtempSync(join(tmpdir(), "hf-beside-"));- const pkg = join(root, "node_modules", "onnxruntime-node");+ const pkg = join(root, "node_modules", name);mkdirSync(pkg, { recursive: true });writeFileSync(join(pkg, "package.json"), JSON.stringify({ version, main: "index.js" }));writeFileSync(join(pkg, "index.js"), `module.exports = { copy: "beside ${version}" };`);@@ -153,6 +153,27 @@ describe("a copy installed beside the CLI", () => {}});+ it.each(["1.13.8", "1.13.7"])("accepts only the Sherpa 1.13.8 pin, received %s", (version) => {+ const { root, cliUrl } = layout(version, "sherpa-onnx-node");+ try {+ const result = loadBesideCli("sherpa-onnx-node", cliUrl);+ if (version === "1.13.8") expect(result).toEqual({ copy: "beside 1.13.8" });+ else expect(result).toBeNull();+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("keeps a missing optional-package entry eligible for cache fallback", () => {+ const { root, cliUrl } = layout("1.21.1");+ try {+ rmSync(join(root, "node_modules", "onnxruntime-node", "index.js"));+ expect(loadBesideCli("onnxruntime-node", cliUrl)).toBeNull();+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });+it("ignores it when its manifest is unreadable, instead of throwing", () => {const { root, cliUrl } = layout(OPTIONAL_PACKAGES["onnxruntime-node"]);writeFileSync(join(root, "node_modules", "onnxruntime-node", "package.json"), "{ version: 1");diff --git a/packages/cli/src/utils/optionalPackages.ts b/packages/cli/src/utils/optionalPackages.tsindex 1eabc22bcc..3dbae58a44 100644--- a/packages/cli/src/utils/optionalPackages.ts+++ b/packages/cli/src/utils/optionalPackages.ts@@ -30,6 +30,13 @@ export const OPTIONAL_PACKAGES = {"@google/genai": "1.52.0",} as const satisfies Record<OptionalPackage, string>;+export const PINNED_PACKAGES = {+ ...OPTIONAL_PACKAGES,+ "sherpa-onnx-node": "1.13.8",+} as const;++type PinnedPackage = keyof typeof PINNED_PACKAGES;+export const CACHE_DIR = join(homedir(), ".cache", "hyperframes", "optional");export interface OptionalPackageDeps {@@ -53,7 +60,7 @@ export function installedOptionalPackageVersion(cacheDir = CACHE_DIR,cliUrl = import.meta.url,): string | null {- if (pinnedCopyBesideCli(name, cliUrl)) return OPTIONAL_PACKAGES[name];+ if (pinnedPackageBesideCli(name, cliUrl)?.resolution === "entry") return OPTIONAL_PACKAGES[name];const dir = optionalPackageDir(name, cacheDir);if (!isInstalled(dir, name)) return null;return (JSON.parse(readFileSync(manifestPath(dir, name), "utf-8")) as { version: string })@@ -113,28 +120,51 @@ export function isInstalled(dir: string, name: string): boolean {return existsSync(manifestPath(dir, name));}-export function loadInstalled(dir: string, name: string): unknown | null {+export function installedPackagePath(dir: string, name: string): string | null {if (!isInstalled(dir, name)) return null;- return createRequire(join(dir, "package.json"))(name);+ return createRequire(join(dir, "package.json")).resolve(name);}-function pinnedCopyBesideCli(name: OptionalPackage, cliUrl: string): boolean {+function loadInstalled(dir: string, name: string): unknown | null {+ const entry = installedPackagePath(dir, name);+ return entry === null ? null : createRequire(join(dir, "package.json"))(entry);+}++export function pinnedPackageBesideCli(+ name: PinnedPackage,+ cliUrl = import.meta.url,+): { resolution: "entry" | "package"; path: string } | null {const req = createRequire(cliUrl);try {- const entry = realpathSync(req.resolve(name));+ let entry: string;+ try {+ entry = realpathSync(req.resolve(name));+ } catch {+ const copy = (req.resolve.paths(name) ?? [])+ .map((dir) => join(dir, name))+ .find((dir) => existsSync(join(dir, "package.json")));+ return copy && hasPinnedVersion(copy, name)+ ? { resolution: "package", path: realpathSync(copy) }+ : null;+ }const copy = (req.resolve.paths(name) ?? []).map((dir) => join(dir, name)).find((dir) => existsSync(dir) && entry.startsWith(realpathSync(dir) + sep));- if (!copy) return false;- const manifest = readFileSync(join(copy, "package.json"), "utf-8");- return (JSON.parse(manifest) as { version?: string }).version === OPTIONAL_PACKAGES[name];+ if (!copy) return null;+ return hasPinnedVersion(copy, name) ? { resolution: "entry", path: entry } : null;} catch {- return false;+ return null;}}-export function loadBesideCli(name: OptionalPackage, cliUrl = import.meta.url): unknown | null {- return pinnedCopyBesideCli(name, cliUrl) ? createRequire(cliUrl)(name) : null;+function hasPinnedVersion(copy: string, name: PinnedPackage): boolean {+ const manifest = readFileSync(join(copy, "package.json"), "utf-8");+ return (JSON.parse(manifest) as { version?: string }).version === PINNED_PACKAGES[name];+}++export function loadBesideCli(name: PinnedPackage, cliUrl = import.meta.url): unknown | null {+ const copy = pinnedPackageBesideCli(name, cliUrl);+ return copy?.resolution === "entry" ? createRequire(cliUrl)(copy.path) : null;}export function runNpm(args: string[], signal?: AbortSignal): Promise<void> {diff --git a/packages/cli/src/whisper/sherpa.test.ts b/packages/cli/src/whisper/sherpa.test.tsindex 1250f69589..b44efdf3b6 100644--- a/packages/cli/src/whisper/sherpa.test.ts+++ b/packages/cli/src/whisper/sherpa.test.ts@@ -4,13 +4,15 @@ import {mkdirSync,mkdtempSync,readdirSync,+ readFileSync,rmSync,truncateSync,writeFileSync,} from "node:fs";import { tmpdir } from "node:os";import { basename, dirname, join } from "node:path";-import { afterEach, describe, expect, it, vi } from "vitest";+import { pathToFileURL } from "node:url";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";import type { DownloadOptions } from "../cloud/download.js";import {ensureParakeetModel,@@ -20,6 +22,7 @@ import {DecodeCancelled,sherpaRuntimeLoadError,sherpaUnsupportedReason,+ transcribeWithSherpa,type ModelFile,} from "./sherpa.js";@@ -41,6 +44,19 @@ function fakeDownload(served: Record<string, string>) {});}+/** A stand-in runtime in `root` whose entry point loads, or throws as a missing library does. */+const LOADS = "module.exports = {};";+const BROKEN = 'throw new Error("libonnxruntime.so: cannot open\\n shared object");';+function fakeRuntime(root: string, body: string, version = "1.13.8") {+ const pkg = join(root, "node_modules", "sherpa-onnx-node");+ mkdirSync(pkg, { recursive: true });+ writeFileSync(+ join(pkg, "package.json"),+ JSON.stringify({ name: "sherpa-onnx-node", main: "index.js", version }),+ );+ writeFileSync(join(pkg, "index.js"), body);+}+describe("installSherpaRuntime", () => {it.each([["darwin", "arm64", "[email protected]"],@@ -66,28 +82,23 @@ describe("installSherpaRuntime", () => {expect(args).toContain(sherpaPlatformPackage());});- /** A stand-in runtime in `root` whose entry point loads, or throws as a missing library does. */- const LOADS = "module.exports = {};";- const BROKEN = 'throw new Error("libonnxruntime.so: cannot open\\n shared object");';- function fakeRuntime(root: string, body: string) {- const pkg = join(root, "node_modules", "sherpa-onnx-node");- mkdirSync(pkg, { recursive: true });- writeFileSync(join(pkg, "package.json"), '{"name":"sherpa-onnx-node","main":"index.js"}');- writeFileSync(join(pkg, "index.js"), body);- }-it("reinstalls a runtime that is present but does not load", async () => {const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));try {fakeRuntime(dir, BROKEN);- expect(sherpaRuntimeLoadError(dir)).toBe("libonnxruntime.so: cannot open shared object");+ expect(await sherpaRuntimeLoadError(dir)).toBe(+ "libonnxruntime.so: cannot open shared object",+ );const run = vi.fn(async (args: string[]) =>fakeRuntime(args[args.indexOf("--prefix") + 1]!, LOADS),);- expect(await installSherpaRuntime({ run, dir })).toBe(true);+ expect(await installSherpaRuntime({ run, dir })).toEqual({+ installed: true,+ runtimePath: join(dir, "node_modules", "sherpa-onnx-node", "index.js"),+ });expect(run).toHaveBeenCalledTimes(1);- expect(sherpaRuntimeLoadError(dir)).toBeNull();+ expect(await sherpaRuntimeLoadError(dir)).toBeNull();} finally {rmSync(dir, { recursive: true, force: true });}@@ -98,7 +109,10 @@ describe("installSherpaRuntime", () => {try {fakeRuntime(dir, LOADS);const run = vi.fn();- expect(await installSherpaRuntime({ run, dir })).toBe(false);+ expect(await installSherpaRuntime({ run, dir })).toEqual({+ installed: false,+ runtimePath: join(dir, "node_modules", "sherpa-onnx-node", "index.js"),+ });expect(run).not.toHaveBeenCalled();} finally {rmSync(dir, { recursive: true, force: true });@@ -135,11 +149,24 @@ describe("installSherpaRuntime", () => {},);- it("reads its own probe timeout as a broken runtime, not a cancel, and says so", () => {+ it("reads its own probe timeout as a broken runtime, not a cancel, and says so", async () => {const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));try {fakeRuntime(dir, "Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5000);");- expect(sherpaRuntimeLoadError(dir, 300)).toBe("loading it timed out after 0.3 s");+ expect(await sherpaRuntimeLoadError(dir, 300)).toBe("loading it timed out after 0.3 s");+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it("reports timeout even when the runtime handles SIGTERM and exits zero", async () => {+ const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));+ try {+ fakeRuntime(+ dir,+ 'process.on("SIGTERM", () => process.exit(0)); require("node:net").createServer().listen(0, "127.0.0.1");',+ );+ expect(await sherpaRuntimeLoadError(dir, 300)).toBe("loading it timed out after 0.3 s");} finally {rmSync(dir, { recursive: true, force: true });}@@ -152,33 +179,179 @@ describe("installSherpaRuntime", () => {});});-describe("sherpaParakeetInstalled", () => {- it("counts a runtime that does not load, so transcribe reports it instead of skipping it", async () => {- const home = mkdtempSync(join(tmpdir(), "hf-sherpa-home-"));- vi.stubEnv("HOME", home);- vi.resetModules();- try {- const sherpa = await import("./sherpa.js");- const manifest = join(sherpa.SHERPA_RUNTIME_DIR, "node_modules", "sherpa-onnx-node");- mkdirSync(manifest, { recursive: true });- writeFileSync(join(manifest, "package.json"), "{}");- mkdirSync(sherpa.PARAKEET_MODEL_DIR, { recursive: true });- for (const [name, bytes] of [- ["encoder.int8.onnx", 652_184_281],- ["decoder.int8.onnx", 11_845_275],- ["joiner.int8.onnx", 6_355_277],- ["tokens.txt", 93_939],- ] as const) {- writeFileSync(join(sherpa.PARAKEET_MODEL_DIR, name), "");- truncateSync(join(sherpa.PARAKEET_MODEL_DIR, name), bytes);+describe("a pinned Sherpa copy beside the CLI", () => {+ let root: string;+ beforeEach(() => {+ root = mkdtempSync(join(tmpdir(), "hf-sherpa-beside-"));+ });+ afterEach(() => {+ vi.restoreAllMocks();+ rmSync(root, { recursive: true, force: true });+ });++ function layout(besideBody: string, cachedBody?: string) {+ const bundle = join(root, "bundle");+ const cache = join(root, "cache");+ fakeRuntime(bundle, besideBody);+ if (cachedBody !== undefined) fakeRuntime(cache, cachedBody);+ const cliUrl = pathToFileURL(join(bundle, "dist", "cli.js")).href;+ const pinnedPath = join(bundle, "node_modules", "sherpa-onnx-node", "index.js");+ return { cache, cliUrl, pinnedPath };+ }++ function decoder() {+ const parentMarker = join(root, "loaded-in-parent");+ return `+if (process.pid === ${process.pid}) require("node:fs").writeFileSync(${JSON.stringify(parentMarker)}, "");+module.exports = {+ readWave() { return { sampleRate: 100, samples: new Float32Array(100).fill(0.5) }; },+ OfflineRecognizer: class {+ createStream() { return { acceptWaveform() {} }; }+ decode() {}+ getResult() { return { tokens: [" hello"], timestamps: [0], durations: [1] }; }+ }+};`;+ }++ async function transcript(cache: string, cliUrl: string) {+ const out = join(root, "out");+ mkdirSync(out, { recursive: true });+ const onEvent = vi.fn();+ await transcribeWithSherpa(join(root, "speech.wav"), out, {+ signal: new AbortController().signal,+ runtimeDir: cache,+ cliUrl,+ onEvent,+ });+ const result = JSON.parse(readFileSync(join(out, "transcript.json"), "utf-8"));+ expect(result).toEqual([{ text: "hello", start: 0, end: 1 }]);+ const event = { type: "progress", phase: "transcription", model: "parakeet-tdt-0.6b-v3" };+ expect(onEvent.mock.calls).toEqual([+ [{ ...event, status: "started" }],+ [{ ...event, status: "completed" }],+ ]);+ expect(existsSync(join(root, "loaded-in-parent"))).toBe(false);+ }++ it("loads a pinned adjacent copy without a cache or npm install", async () => {+ const { cache, cliUrl, pinnedPath } = layout(LOADS);+ const run = vi.fn();+ expect(await sherpaRuntimeLoadError(cache, 60_000, cliUrl)).toBeNull();+ expect(await installSherpaRuntime({ dir: cache, cliUrl, run })).toEqual({+ installed: false,+ runtimePath: pinnedPath,+ });+ expect(run).not.toHaveBeenCalled();+ expect(existsSync(cache)).toBe(false);+ });++ it.skipIf(process.platform === "win32")(+ "cancels an in-flight probe without inspecting the cache",+ async () => {+ const cacheMarker = join(root, "cache-loaded");+ const { cache, cliUrl } = layout(+ 'require("node:net").createServer().listen(0, "127.0.0.1", () => process.kill(process.ppid, "SIGUSR2"));',+ `require("node:fs").writeFileSync(${JSON.stringify(cacheMarker)}, ""); module.exports = {};`,+ );+ const log = vi.spyOn(console, "error").mockImplementation(() => {});+ const controller = new AbortController();+ const abort = () => controller.abort();+ process.once("SIGUSR2", abort);+ try {+ await expect(+ sherpaRuntimeLoadError(cache, 300, cliUrl, controller.signal),+ ).rejects.toBeInstanceOf(DecodeCancelled);+ expect(existsSync(cacheMarker)).toBe(false);+ expect(log).not.toHaveBeenCalled();+ } finally {+ process.removeListener("SIGUSR2", abort);}- expect(sherpa.sherpaRuntimeLoadError()).not.toBeNull();- expect(sherpa.sherpaParakeetInstalled()).toBe(true);- } finally {- vi.unstubAllEnvs();- rmSync(home, { recursive: true, force: true });- }+ },+ );++ it("passes the pinned adjacent copy to the real decode worker", async () => {+ const { cache, cliUrl } = layout(decoder());+ await transcript(cache, cliUrl);+ });++ it("logs the broken pinned path once and decodes with the healthy cache", async () => {+ const { cache, cliUrl, pinnedPath } = layout(BROKEN, decoder());+ const log = vi.spyOn(console, "error").mockImplementation(() => {});+ await transcript(cache, cliUrl);+ expect(log).toHaveBeenCalledTimes(1);+ expect(log.mock.calls[0]?.[0]).toContain(pinnedPath);+ expect(log.mock.calls[0]?.[0]).toContain("libonnxruntime.so: cannot open shared object");+ expect(String(log.mock.calls[0]?.[0])).not.toContain("\n");});++ it("reports an accepted package with a missing entry and uses the healthy cache", async () => {+ const { cache, cliUrl, pinnedPath } = layout(LOADS, decoder());+ rmSync(pinnedPath);+ const log = vi.spyOn(console, "error").mockImplementation(() => {});+ await transcript(cache, cliUrl);+ expect(log).toHaveBeenCalledTimes(1);+ expect(log.mock.calls[0]?.[0]).toContain(dirname(pinnedPath));+ expect(log.mock.calls[0]?.[0]).toContain("Cannot find module");+ });++ it.each([undefined, BROKEN])(+ "logs the broken pinned path once and reports repair when no cache loads (%s)",+ async (cachedBody) => {+ const { cache, cliUrl, pinnedPath } = layout(BROKEN, cachedBody);+ const log = vi.spyOn(console, "error").mockImplementation(() => {});+ const out = join(root, "out");+ mkdirSync(out);+ await expect(+ transcribeWithSherpa(join(root, "speech.wav"), out, {+ signal: new AbortController().signal,+ runtimeDir: cache,+ cliUrl,+ }),+ ).rejects.toThrow(/hyperframes models install parakeet/);+ expect(log).toHaveBeenCalledTimes(1);+ expect(log.mock.calls[0]?.[0]).toContain(pinnedPath);+ expect(log.mock.calls[0]?.[0]).toContain("libonnxruntime.so: cannot open shared object");+ expect(readdirSync(out)).toEqual([]);+ },+ );+});++describe("sherpaParakeetInstalled", () => {+ it.each(["cache", "beside CLI"])(+ "counts a broken runtime in %s, so transcribe reports it instead of skipping it",+ async (location) => {+ const home = mkdtempSync(join(tmpdir(), "hf-sherpa-home-"));+ vi.stubEnv("HOME", home);+ vi.resetModules();+ try {+ const sherpa = await import("./sherpa.js");+ const bundle = join(home, "bundle");+ const cliUrl = pathToFileURL(join(bundle, "dist", "cli.js")).href;+ const manifest = join(+ location === "cache" ? sherpa.SHERPA_RUNTIME_DIR : bundle,+ "node_modules",+ "sherpa-onnx-node",+ );+ mkdirSync(manifest, { recursive: true });+ if (location === "cache") writeFileSync(join(manifest, "package.json"), "{}");+ else fakeRuntime(bundle, BROKEN);+ mkdirSync(sherpa.PARAKEET_MODEL_DIR, { recursive: true });+ for (const [name, bytes] of [+ ["encoder.int8.onnx", 652_184_281],+ ["decoder.int8.onnx", 11_845_275],+ ["joiner.int8.onnx", 6_355_277],+ ["tokens.txt", 93_939],+ ] as const) {+ writeFileSync(join(sherpa.PARAKEET_MODEL_DIR, name), "");+ truncateSync(join(sherpa.PARAKEET_MODEL_DIR, name), bytes);+ }+ expect(sherpa.sherpaParakeetInstalled(cliUrl)).toBe(true);+ } finally {+ vi.unstubAllEnvs();+ rmSync(home, { recursive: true, force: true });+ }+ },+ );});describe("ensureParakeetModel", () => {diff --git a/packages/cli/src/whisper/sherpa.ts b/packages/cli/src/whisper/sherpa.tsindex ce8436c8f0..e1285da8b1 100644--- a/packages/cli/src/whisper/sherpa.ts+++ b/packages/cli/src/whisper/sherpa.ts@@ -1,4 +1,4 @@-import { execFile, spawnSync, type ExecFileException } from "node:child_process";+import { execFile, spawn, type ExecFileException } from "node:child_process";import { createHash, randomUUID } from "node:crypto";import { createReadStream, mkdirSync, renameSync, rmSync, statSync } from "node:fs";import { homedir } from "node:os";@@ -8,6 +8,9 @@ import { downloadToFile } from "../cloud/download.js";import { stoppedByCancelSignal } from "../utils/renderCancellation.js";import {CACHE_DIR,+ PINNED_PACKAGES,+ pinnedPackageBesideCli,+ installedPackagePath,install,isInstalled,runNpm,@@ -29,7 +32,7 @@ import {} from "./transcribe.js";const RUNTIME = "sherpa-onnx-node";-const RUNTIME_VERSION = "1.13.8";+const RUNTIME_VERSION = PINNED_PACKAGES[RUNTIME];/** Per platform and arch, like the native package inside, so Rosetta never shadows arm64. */export const SHERPA_RUNTIME_DIR = join(CACHE_DIR,@@ -121,36 +124,109 @@ const nativePackageName = (platform: string, arch: string) =>`sherpa-onnx-${platform === "win32" ? "win" : platform}-${arch}`;const LOAD_RUNTIME = `try {- require("node:module").createRequire(process.env.HF_SHERPA_MANIFEST)("${RUNTIME}");+ require(process.env.HF_SHERPA_RUNTIME_PATH);} catch (e) {process.stderr.write(String(e && e.message).replace(/\\s+/g, " "));process.exitCode = 1;}`;-/** Loads it in a child as the decode worker does: null when it loads, else the loader's error. */-export function sherpaRuntimeLoadError(+/** Native bindings are probed only in a child, as they are loaded in the decode worker. */+function runtimeLoadError(+ runtimePath: string,+ timeoutMs: number,+ signal?: AbortSignal,+): Promise<string | null> {+ if (signal?.aborted)+ return Promise.reject(new DecodeCancelled("Parakeet runtime check cancelled"));+ return new Promise((resolve, reject) => {+ const probe = spawn(process.execPath, ["-e", LOAD_RUNTIME], {+ env: { ...process.env, HF_SHERPA_RUNTIME_PATH: runtimePath },+ stdio: ["ignore", "ignore", "pipe"],+ timeout: timeoutMs,+ signal,+ });+ let stderr = "";+ probe.stderr.setEncoding("utf8");+ probe.stderr.on("data", (chunk: string) => {+ stderr = bounded(stderr + chunk);+ });+ probe.on("error", (error) => {+ if (signal?.aborted) reject(new DecodeCancelled("Parakeet runtime check cancelled"));+ else resolve(bounded(error.message));+ });+ probe.on("close", (code, childSignal) => {+ if (+ signal?.aborted ||+ stoppedByCancelSignal({ code, signal: childSignal, killed: probe.killed })+ ) {+ reject(new DecodeCancelled("Parakeet runtime check cancelled"));+ return;+ }+ if (code === 0 && !probe.killed) {+ resolve(null);+ return;+ }+ let reason: string;+ if (probe.killed) reason = `loading it timed out after ${timeoutMs / 1000} s`;+ else if (childSignal) reason = `loading it crashed (${childSignal})`;+ else reason = `it exited ${code} with no output`;+ resolve(bounded(stderr.trim() || reason));+ });+ });+}++type RuntimeSelection =+ | { status: "ready"; path: string }+ | { status: "unavailable"; error: string };++async function cachedRuntime(+ dir: string,+ timeoutMs: number,+ signal?: AbortSignal,+): Promise<RuntimeSelection> {+ let path: string | null;+ try {+ path = installedPackagePath(dir, RUNTIME);+ } catch (err) {+ return {+ status: "unavailable",+ error: bounded(err instanceof Error ? err.message : String(err)),+ };+ }+ if (path === null)+ return { status: "unavailable", error: `${RUNTIME} is not installed in ${dir}` };+ const error = await runtimeLoadError(path, timeoutMs, signal);+ return error === null ? { status: "ready", path } : { status: "unavailable", error };+}++async function selectRuntime(+ dir: string,+ cliUrl: string,+ timeoutMs = 60_000,+ signal?: AbortSignal,+): Promise<RuntimeSelection> {+ if (signal?.aborted) throw new DecodeCancelled("Parakeet runtime check cancelled");+ const copy = pinnedPackageBesideCli(RUNTIME, cliUrl);+ if (copy !== null) {+ const path = copy.path;+ const error = await runtimeLoadError(path, timeoutMs, signal);+ if (error === null) return { status: "ready", path };+ console.error(+ `Parakeet runtime at ${path.replace(/\s+/g, " ")} did not load: ${error.replace(/\s+/g, " ")}`,+ );+ }+ return cachedRuntime(dir, timeoutMs, signal);+}++/** Returns the load failure after checking the pinned copy beside the CLI, then its cache. */+export async function sherpaRuntimeLoadError(dir = SHERPA_RUNTIME_DIR,timeoutMs = 60_000,-): string | null {- if (!isInstalled(dir, RUNTIME)) return `${RUNTIME} is not installed in ${dir}`;- const env = { ...process.env, HF_SHERPA_MANIFEST: join(dir, "package.json") };- const probe = spawnSync(process.execPath, ["-e", LOAD_RUNTIME], {- env,- encoding: "utf8",- stdio: ["ignore", "ignore", "pipe"],- timeout: timeoutMs,- });- if (probe.status === 0) return null;- // Ctrl-C reaches the probe too: a cancel, never proof that a working runtime is broken.- if (stoppedByCancelSignal(probe)) throw new DecodeCancelled("Parakeet install cancelled");- const timedOut = (probe.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";- return bounded(- probe.stderr?.trim() ||- (timedOut ? `loading it timed out after ${timeoutMs / 1000} s` : probe.error?.message) ||- (probe.signal- ? `loading it crashed (${probe.signal})`- : `it exited ${probe.status} with no output`),- );+ cliUrl = import.meta.url,+ signal?: AbortSignal,+): Promise<string | null> {+ const selected = await selectRuntime(dir, cliUrl, timeoutMs, signal);+ return selected.status === "ready" ? null : selected.error;}/** The native package, pinned too: the runtime's own optionalDependencies accept any 1.13.x. */@@ -158,33 +234,41 @@ export function sherpaPlatformPackage(platform = process.platform, arch = procesreturn `${nativePackageName(platform, arch)}@${RUNTIME_VERSION}`;}-/** Installs the runtime unless it already loads; true when it installed. */+/** Installs if needed and returns the healthy entry selected for native child loading. */export async function installSherpaRuntime({run = runNpm,signal,dir = SHERPA_RUNTIME_DIR,-}: { run?: typeof runNpm; signal?: AbortSignal; dir?: string } = {}): Promise<boolean> {- if (sherpaRuntimeLoadError(dir) === null) return false;+ cliUrl = import.meta.url,+}: {+ run?: typeof runNpm;+ signal?: AbortSignal;+ dir?: string;+ cliUrl?: string;+} = {}): Promise<{ installed: boolean; runtimePath: string }> {+ const present = await selectRuntime(dir, cliUrl, 60_000, signal);+ if (present.status === "ready") return { installed: false, runtimePath: present.path };// install() keeps any dir holding the runtime manifest, so a broken one goes first.rmSync(dir, { recursive: true, force: true });const native = sherpaPlatformPackage();await install(dir, RUNTIME, RUNTIME_VERSION, (args) => run([...args, native], signal));- const stillBroken = sherpaRuntimeLoadError(dir);- if (stillBroken) {+ const selected = await cachedRuntime(dir, 60_000, signal);+ if (selected.status === "unavailable") {throw new Error(- `The sherpa-onnx runtime was reinstalled but still does not load (${stillBroken}). Use --engine whisper for now.`,+ `The sherpa-onnx runtime was reinstalled but still does not load (${selected.error}). Use --engine whisper for now.`,);}- return true;+ return { installed: true, runtimePath: selected.path };}/*** Model sizes only (install verified the hashes). The runtime counts once its manifest is there, even* if broken: transcribe must then fail with the repair, not quietly pick whisper.*/-export function sherpaParakeetInstalled(): boolean {+export function sherpaParakeetInstalled(cliUrl = import.meta.url): boolean {return (- isInstalled(SHERPA_RUNTIME_DIR, RUNTIME) &&+ (pinnedPackageBesideCli(RUNTIME, cliUrl) !== null ||+ isInstalled(SHERPA_RUNTIME_DIR, RUNTIME)) &&PARAKEET_MODEL_FILES.every((f) =>statSync(join(PARAKEET_MODEL_DIR, f.name), { throwIfNoEntry: false })?.size === f.bytes,@@ -306,11 +390,15 @@ function failureReason(err: ExecFileException | null, stderr: string): string {}/** Decodes in a child process: onnxruntime aborts the whole process on some inputs, uncatchably. */-function decode(wavPath: string, signal: AbortSignal): Promise<SherpaWindow[]> {+function decode(+ wavPath: string,+ runtimePath: string,+ signal: AbortSignal,+): Promise<SherpaWindow[]> {const sourceMode = import.meta.url.endsWith(".ts");const worker = new URL(sourceMode ? "./sherpaWorker.ts" : "./sherpaWorker.js", import.meta.url);const args = [...(sourceMode ? ["--import", "tsx"] : []), fileURLToPath(worker)];- const input = { wavPath, runtimeDir: SHERPA_RUNTIME_DIR, config: recognizerConfig() };+ const input = { wavPath, runtimePath, config: recognizerConfig() };return new Promise((resolve, reject) => {execFile(process.execPath,@@ -356,6 +444,8 @@ export async function transcribeWithSherpa(options: {signal: AbortSignal;onProgress?: (message: string) => void;+ runtimeDir?: string;+ cliUrl?: string;onEvent?: (event: TranscribeProgress) => void;},): Promise<TranscribeResult> {@@ -366,7 +456,19 @@ export async function transcribeWithSherpa(model: PARAKEET_MODEL_LABEL,status: "started",});- const windows = await decode(wavPath, options.signal);+ if (options.signal.aborted) throw new DecodeCancelled("Transcription cancelled");+ const selected = await selectRuntime(+ options.runtimeDir ?? SHERPA_RUNTIME_DIR,+ options.cliUrl ?? import.meta.url,+ 60_000,+ options.signal,+ );+ if (selected.status === "unavailable") {+ throw new Error(+ `Parakeet runtime does not load (${selected.error}). Run hyperframes models install parakeet to repair it, or use --engine whisper.`,+ );+ }+ const windows = await decode(wavPath, selected.path, options.signal);const result = writeParakeetTranscript(dir, mergeWindowsToWords(windows));options.onEvent?.({type: "progress",diff --git a/packages/cli/src/whisper/sherpaWorker.test.ts b/packages/cli/src/whisper/sherpaWorker.test.tsindex 2a582b0371..18e19756dc 100644--- a/packages/cli/src/whisper/sherpaWorker.test.ts+++ b/packages/cli/src/whisper/sherpaWorker.test.ts@@ -41,7 +41,11 @@ module.exports = {`;function runWorker(runtimeDir: string, wavPath: string) {- const input = JSON.stringify({ wavPath, runtimeDir, config: {} });+ const input = JSON.stringify({+ wavPath,+ runtimePath: join(runtimeDir, "node_modules", "sherpa-onnx-node", "index.js"),+ config: {},+ });return new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve) => {execFile(process.execPath,@@ -102,7 +106,11 @@ describe("sherpaWorker", () => {"stops between windows once the CLI that spawned it is gone",async () => {const started = join(fakeRuntime(), "started");- const input = JSON.stringify({ wavPath: "long.wav", runtimeDir: root, config: {} });+ const input = JSON.stringify({+ wavPath: "long.wav",+ runtimePath: join(root, "node_modules", "sherpa-onnx-node", "index.js"),+ config: {},+ });// The shell waits for the first window, then exits, orphaning a 10-window decode.const shell =`"${process.execPath}" --import tsx "${WORKER}" >/dev/null 2>&1 & echo $!; ` +@@ -136,6 +144,8 @@ describe("sherpaWorker", () => {root = mkdtempSync(join(tmpdir(), "hf-sherpa-worker-"));const { code, stderr } = await runWorker(root, "speech.wav");expect(code).toBe(1);- expect(stderr).toContain(`${SHERPA_ERROR_PREFIX}sherpa-onnx-node is not installed in ${root}`);+ expect(stderr).toContain(+ `${SHERPA_ERROR_PREFIX}Cannot find module '${join(root, "node_modules", "sherpa-onnx-node", "index.js")}'`,+ );});});diff --git a/packages/cli/src/whisper/sherpaWorker.ts b/packages/cli/src/whisper/sherpaWorker.tsindex 45e91dce53..0764825c9d 100644--- a/packages/cli/src/whisper/sherpaWorker.ts+++ b/packages/cli/src/whisper/sherpaWorker.ts@@ -1,4 +1,4 @@-import { loadInstalled } from "../utils/optionalPackages.js";+import { createRequire } from "node:module";import {droppedSpeechGaps,silenceCuts,@@ -22,7 +22,7 @@ interface SherpaOnnx {};}-const { wavPath, runtimeDir, config } = JSON.parse(process.env.HYPERFRAMES_PARAKEET_INPUT ?? "{}");+const { wavPath, runtimePath, config } = JSON.parse(process.env.HYPERFRAMES_PARAKEET_INPUT ?? "{}");const parentPid = process.ppid;/** Leading silence moves the frame grid; 0.5 s recovered the dropped clause at every length tried. */@@ -46,8 +46,7 @@ function decodeWindow(}try {- const sherpa = loadInstalled(runtimeDir, "sherpa-onnx-node") as SherpaOnnx | null;- if (!sherpa) throw new Error(`sherpa-onnx-node is not installed in ${runtimeDir}`);+ const sherpa = createRequire(import.meta.url)(runtimePath) as SherpaOnnx;const recognizer = new sherpa.OfflineRecognizer(config);const wave = sherpa.readWave(wavPath);const cuts = silenceCuts(wave.samples, wave.sampleRate);