Skip to content

Commit 7ab9fcd

Browse files
committed
fix(cli): repair a Parakeet runtime that fails to load, and read Ctrl-C after whisper
models install parakeet now loads the runtime in a child process, the way the decode worker does, and reinstalls it when that fails, so a missing shared library, a corrupt binary or missing runtime JS is repaired. It reports changed: false when the runtime loads. transcribe keeps its cheap manifest check. After a failure, transcribe lets the event loop turn once before reading the Ctrl-C scope, since a signal that landed during the synchronous whisper fallback is only handled then.
1 parent 1b4bd2b commit 7ab9fcd

7 files changed

Lines changed: 74 additions & 48 deletions

File tree

‎docs/packages/cli.mdx‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -319,8 +319,9 @@ npx hyperframes models install parakeet --json # one JSON result
319319
`parakeet` installs the sherpa-onnx runtime from npm and NVIDIA's Parakeet TDT
320320
0.6B v3 speech model (int8, about 640 MB, CC-BY-4.0) into
321321
`~/.cache/hyperframes`. Every file is checked against a pinned size and
322-
sha256. Re-running is a no-op on a good install and reinstalls any missing or
323-
corrupt part, including a runtime whose native binary is gone. It runs on macOS
322+
sha256. Re-running loads the runtime in a separate process and re-checks each
323+
model file's sha256, reinstalls whichever fails, and changes nothing on a good
324+
install. It runs on macOS
324325
(arm64, x64), Windows (x64, ia32) and Linux (x64, arm64, glibc 2.32 or newer),
325326
and refuses up front anywhere else. Ctrl-C stops the download and keeps no
326327
partial file.

‎packages/cli/src/commands/models.test.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ const sherpa = {
55
SHERPA_RUNTIME_DIR: "/cache/optional/[email protected]",
66
PARAKEET_MODEL_DIR: "/cache/parakeet/parakeet-tdt-0.6b-v3-int8",
77
sherpaUnsupportedReason: vi.fn(),
8-
sherpaRuntimeInstalled: vi.fn(),
98
installSherpaRuntime: vi.fn(),
109
ensureParakeetModel: vi.fn(),
1110
};
@@ -38,8 +37,7 @@ describe("models install parakeet --json", () => {
3837
consumeCommandResult();
3938
vi.spyOn(console, "log").mockImplementation(() => {});
4039
sherpa.sherpaUnsupportedReason.mockReturnValue(null);
41-
sherpa.sherpaRuntimeInstalled.mockReturnValue(false);
42-
sherpa.installSherpaRuntime.mockResolvedValue(undefined);
40+
sherpa.installSherpaRuntime.mockResolvedValue(true);
4341
sherpa.ensureParakeetModel.mockResolvedValue(false);
4442
});
4543
afterEach(() => vi.restoreAllMocks());
@@ -58,6 +56,11 @@ describe("models install parakeet --json", () => {
5856
expect(dispose).toHaveBeenCalled();
5957
});
6058

59+
it("reports changed: false when the runtime loads and the model verifies", async () => {
60+
sherpa.installSherpaRuntime.mockResolvedValue(false);
61+
expect((await install()).out).toMatchObject({ ok: true, changed: false });
62+
});
63+
6164
it("reports a failed install as ok:false with exit 1", async () => {
6265
sherpa.ensureParakeetModel.mockRejectedValue(new Error("tokens.txt did not match"));
6366
expect(await install()).toEqual({

‎packages/cli/src/commands/models.ts‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,13 @@ type Spinner = ReturnType<typeof clack.spinner> | null;
3737

3838
/** Installs what is missing; true when anything changed. */
3939
async function installMissing(sherpa: Sherpa, spin: Spinner, signal: AbortSignal) {
40-
const runtimeMissing = !sherpa.sherpaRuntimeInstalled();
41-
if (runtimeMissing) {
42-
spin?.message("Installing the sherpa-onnx runtime from npm...");
43-
await sherpa.installSherpaRuntime({ signal });
44-
}
40+
const runtimeInstalled = await sherpa.installSherpaRuntime({ signal });
4541
spin?.message("Verifying the Parakeet model...");
4642
const modelFetched = await sherpa.ensureParakeetModel({
4743
signal,
4844
onBytes: downloadProgress(spin),
4945
});
50-
return runtimeMissing || modelFetched;
46+
return runtimeInstalled || modelFetched;
5147
}
5248

5349
async function installParakeet(json: boolean): Promise<void> {
@@ -58,7 +54,7 @@ async function installParakeet(json: boolean): Promise<void> {
5854
const spin = json ? null : clack.spinner({ output: process.stderr });
5955
// Ctrl-C must stop a 650 MB download, not just print "Canceled" over it.
6056
const cancellation = createRenderCancellationScope();
61-
spin?.start("Checking the sherpa-onnx runtime...");
57+
spin?.start("Checking the sherpa-onnx runtime (installing it from npm if it does not load)...");
6258
try {
6359
const changed = await installMissing(sherpa, spin, cancellation.signal);
6460
spin?.stop(c.success(changed ? "Parakeet installed" : "Parakeet is already installed"));

‎packages/cli/src/commands/transcribe.test.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -204,9 +204,10 @@ describe("transcribe command", () => {
204204

205205
it("exits 130 when Ctrl-C stops the whisper fallback too", async () => {
206206
crashChild("SIGABRT");
207+
// A real signal reaches the listener only when the loop turns after the synchronous whisper run.
207208
transcribeMock.mockImplementation(async () => {
208-
process.emit("SIGINT");
209-
throw new Error("whisper-cli was killed by SIGINT");
209+
setImmediate(() => process.emit("SIGINT"));
210+
throw Object.assign(new Error("Command failed: whisper-cli"), { signal: "SIGINT" });
210211
});
211212
Object.assign(runners, { sherpa: true, mlx: false });
212213
const { exitCode, out } = await transcribeFails("auto");

‎packages/cli/src/commands/transcribe.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -418,6 +418,8 @@ async function transcribeAudio(
418418
);
419419
}
420420
} catch (err) {
421+
// A signal that landed during a synchronous whisper run is only handled once the loop turns.
422+
if (cancellation) await new Promise((resolve) => setImmediate(resolve));
421423
if (err instanceof DecodeCancelled || cancellation?.signal.aborted) {
422424
const message = "Transcription cancelled";
423425
if (opts.json) console.log(JSON.stringify({ ok: false, error: message }));

‎packages/cli/src/whisper/sherpa.test.ts‎

Lines changed: 38 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ import {
1717
installSherpaRuntime,
1818
SHERPA_RUNTIME_DIR,
1919
sherpaPlatformPackage,
20-
sherpaRuntimeInstalled,
20+
sherpaRuntimeLoads,
2121
sherpaUnsupportedReason,
2222
type ModelFile,
2323
} from "./sherpa.js";
@@ -56,35 +56,50 @@ describe("installSherpaRuntime", () => {
5656
throw new Error("stop before touching the cache");
5757
});
5858
const cancel = new AbortController();
59-
await installSherpaRuntime({ run, signal: cancel.signal }).catch(() => undefined);
59+
const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
60+
await installSherpaRuntime({ run, signal: cancel.signal, dir }).catch(() => undefined);
61+
rmSync(dir, { recursive: true, force: true });
6062
expect((run.mock.calls[0] as unknown[] | undefined)?.[1]).toBe(cancel.signal);
6163
const args = run.mock.calls[0]?.[0] as string[] | undefined;
6264
expect(args).toContain("[email protected]");
6365
expect(args).toContain(sherpaPlatformPackage());
6466
});
6567

66-
it("repairs a runtime whose native binary is missing instead of calling it installed", async () => {
68+
/** A stand-in runtime in `root` whose entry point loads, or throws as a missing library does. */
69+
function fakeRuntime(root: string, loads: boolean) {
70+
const pkg = join(root, "node_modules", "sherpa-onnx-node");
71+
mkdirSync(pkg, { recursive: true });
72+
writeFileSync(join(pkg, "package.json"), '{"name":"sherpa-onnx-node","main":"index.js"}');
73+
const body = loads
74+
? "module.exports = {};"
75+
: 'throw new Error("libonnxruntime.so: cannot open");';
76+
writeFileSync(join(pkg, "index.js"), body);
77+
}
78+
79+
it("reinstalls a runtime that is present but does not load", async () => {
6780
const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
68-
const native = sherpaPlatformPackage().replace(/@[^@]+$/, "");
69-
const manifest = (root: string, name: string) => {
70-
mkdirSync(join(root, "node_modules", name), { recursive: true });
71-
writeFileSync(join(root, "node_modules", name, "package.json"), `{"name":"${name}"}`);
72-
};
7381
try {
74-
manifest(dir, "sherpa-onnx-node");
75-
manifest(dir, native);
76-
expect(sherpaRuntimeInstalled(dir)).toBe(false);
77-
const run = vi.fn(async (args: string[]) => {
78-
const staging = args[args.indexOf("--prefix") + 1]!;
79-
manifest(staging, "sherpa-onnx-node");
80-
manifest(staging, native);
81-
writeFileSync(join(staging, "node_modules", native, "sherpa-onnx.node"), "binary");
82-
});
83-
84-
await installSherpaRuntime({ run, dir });
82+
fakeRuntime(dir, false);
83+
expect(sherpaRuntimeLoads(dir)).toBe(false);
84+
const run = vi.fn(async (args: string[]) =>
85+
fakeRuntime(args[args.indexOf("--prefix") + 1]!, true),
86+
);
87+
88+
expect(await installSherpaRuntime({ run, dir })).toBe(true);
8589
expect(run).toHaveBeenCalledTimes(1);
86-
expect(existsSync(join(dir, "node_modules", native, "sherpa-onnx.node"))).toBe(true);
87-
expect(sherpaRuntimeInstalled(dir)).toBe(true);
90+
expect(sherpaRuntimeLoads(dir)).toBe(true);
91+
} finally {
92+
rmSync(dir, { recursive: true, force: true });
93+
}
94+
});
95+
96+
it("leaves a runtime that loads alone", async () => {
97+
const dir = mkdtempSync(join(tmpdir(), "hf-sherpa-runtime-"));
98+
try {
99+
fakeRuntime(dir, true);
100+
const run = vi.fn();
101+
expect(await installSherpaRuntime({ run, dir })).toBe(false);
102+
expect(run).not.toHaveBeenCalled();
88103
} finally {
89104
rmSync(dir, { recursive: true, force: true });
90105
}
@@ -98,7 +113,7 @@ describe("installSherpaRuntime", () => {
98113
});
99114

100115
describe("sherpaParakeetInstalled", () => {
101-
it("counts a runtime missing its native binary, so transcribe reports it instead of skipping it", async () => {
116+
it("counts a runtime that does not load, so transcribe reports it instead of skipping it", async () => {
102117
const home = mkdtempSync(join(tmpdir(), "hf-sherpa-home-"));
103118
vi.stubEnv("HOME", home);
104119
vi.resetModules();
@@ -117,7 +132,7 @@ describe("sherpaParakeetInstalled", () => {
117132
writeFileSync(join(sherpa.PARAKEET_MODEL_DIR, name), "");
118133
truncateSync(join(sherpa.PARAKEET_MODEL_DIR, name), bytes);
119134
}
120-
expect(sherpa.sherpaRuntimeInstalled()).toBe(false);
135+
expect(sherpa.sherpaRuntimeLoads()).toBe(false);
121136
expect(sherpa.sherpaParakeetInstalled()).toBe(true);
122137
} finally {
123138
vi.unstubAllEnvs();

‎packages/cli/src/whisper/sherpa.ts‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
import { execFile, type ExecFileException } from "node:child_process";
1+
import { execFile, spawnSync, type ExecFileException } from "node:child_process";
22
import { createHash, randomUUID } from "node:crypto";
3-
import { createReadStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
3+
import { createReadStream, mkdirSync, renameSync, rmSync, statSync } from "node:fs";
44
import { homedir } from "node:os";
55
import { join } from "node:path";
66
import { fileURLToPath } from "node:url";
@@ -113,26 +113,34 @@ export function sherpaUnsupportedReason(host: Host = currentHost()): string | nu
113113
const nativePackageName = (platform: string, arch: string) =>
114114
`sherpa-onnx-${platform === "win32" ? "win" : platform}-${arch}`;
115115

116-
/** The runtime and the native binary its loader requires; either can be missing on its own. */
117-
export function sherpaRuntimeInstalled(dir = SHERPA_RUNTIME_DIR): boolean {
118-
const binary = join(dir, "node_modules", nativePackageName(process.platform, process.arch));
119-
return isInstalled(dir, RUNTIME) && existsSync(join(binary, "sherpa-onnx.node"));
116+
/** Loads it in a child as the decode worker does: only a load shows a missing library or bad binary. */
117+
export function sherpaRuntimeLoads(dir = SHERPA_RUNTIME_DIR): boolean {
118+
if (!isInstalled(dir, RUNTIME)) return false;
119+
const load = `require("node:module").createRequire(process.env.HF_SHERPA_MANIFEST)("${RUNTIME}")`;
120+
const env = { ...process.env, HF_SHERPA_MANIFEST: join(dir, "package.json") };
121+
return (
122+
spawnSync(process.execPath, ["-e", load], { env, stdio: "ignore", timeout: 60_000 }).status ===
123+
0
124+
);
120125
}
121126

122127
/** The native package, pinned too: the runtime's own optionalDependencies accept any 1.13.x. */
123128
export function sherpaPlatformPackage(platform = process.platform, arch = process.arch): string {
124129
return `${nativePackageName(platform, arch)}@${RUNTIME_VERSION}`;
125130
}
126131

127-
export function installSherpaRuntime({
132+
/** Installs the runtime unless it already loads; true when it installed. */
133+
export async function installSherpaRuntime({
128134
run = runNpm,
129135
signal,
130136
dir = SHERPA_RUNTIME_DIR,
131-
}: { run?: typeof runNpm; signal?: AbortSignal; dir?: string } = {}): Promise<void> {
132-
// install() keeps any dir holding the runtime manifest, so a half-installed one goes first.
133-
if (!sherpaRuntimeInstalled(dir)) rmSync(dir, { recursive: true, force: true });
137+
}: { run?: typeof runNpm; signal?: AbortSignal; dir?: string } = {}): Promise<boolean> {
138+
if (sherpaRuntimeLoads(dir)) return false;
139+
// install() keeps any dir holding the runtime manifest, so a broken one goes first.
140+
rmSync(dir, { recursive: true, force: true });
134141
const native = sherpaPlatformPackage();
135-
return install(dir, RUNTIME, RUNTIME_VERSION, (args) => run([...args, native], signal));
142+
await install(dir, RUNTIME, RUNTIME_VERSION, (args) => run([...args, native], signal));
143+
return true;
136144
}
137145

138146
/**

0 commit comments

Comments
 (0)