@drakulavich/kesha-voice-kit 1.24.0 → 1.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.24.0",
+  "version": "1.24.1",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {

package/src/cli/dispatch.ts

@@ -52,6 +52,30 @@ function isFalsey(v: string): boolean {
 const USER_FORCED_NO_COLOR =
   process.env.NO_COLOR !== undefined && !isFalsey(process.env.NO_COLOR);
 
+/**
+ * Strip a boolean global flag out of rawArgs so citty never sees it. Matches
+ * any of `names` bare (sets the flag) and the `--name=<value>` form for the
+ * long names (`<falsey>` explicitly turns the flag back off).
+ */
+function stripBooleanFlag(
+  rawArgs: string[],
+  names: string[],
+): { value: boolean; rawArgs: string[] } {
+  const valuedPrefixes = names.filter((n) => n.startsWith("--")).map((n) => `${n}=`);
+  let value = false;
+  const cleaned: string[] = [];
+  for (const arg of rawArgs) {
+    if (names.includes(arg)) {
+      value = true;
+    } else if (valuedPrefixes.some((prefix) => arg.startsWith(prefix))) {
+      value = !isFalsey(arg.slice(arg.indexOf("=") + 1));
+    } else {
+      cleaned.push(arg);
+    }
+  }
+  return { value, rawArgs: cleaned };
+}
+
 /**
  * Decide whether ANSI colors should be disabled (#531) and return rawArgs with
  * any `--no-color[=value]` token stripped so citty never sees it.
@@ -65,19 +89,9 @@ export function resolveColorMode(
   rawArgs: string[],
   env: { CI?: string } = process.env as { CI?: string },
 ): { disableColor: boolean; rawArgs: string[] } {
-  let flag = false;
-  const cleaned: string[] = [];
-  for (const arg of rawArgs) {
-    if (arg === "--no-color") {
-      flag = true;
-    } else if (arg.startsWith("--no-color=")) {
-      flag = !isFalsey(arg.slice("--no-color=".length));
-    } else {
-      cleaned.push(arg);
-    }
-  }
+  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--no-color"]);
   const ci = env.CI !== undefined && !isFalsey(env.CI);
-  return { disableColor: flag || ci, rawArgs: cleaned };
+  return { disableColor: value || ci, rawArgs: cleaned };
 }
 
 /**
@@ -87,18 +101,8 @@ export function resolveColorMode(
  * subcommand that doesn't declare it never sees the flag.
  */
 export function resolveQuietMode(rawArgs: string[]): { quiet: boolean; rawArgs: string[] } {
-  let flag = false;
-  const cleaned: string[] = [];
-  for (const arg of rawArgs) {
-    if (arg === "--quiet" || arg === "-q") {
-      flag = true;
-    } else if (arg.startsWith("--quiet=")) {
-      flag = !isFalsey(arg.slice("--quiet=".length));
-    } else {
-      cleaned.push(arg);
-    }
-  }
-  return { quiet: flag, rawArgs: cleaned };
+  const { value, rawArgs: cleaned } = stripBooleanFlag(rawArgs, ["--quiet", "-q"]);
+  return { quiet: value, rawArgs: cleaned };
 }
 
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {

package/src/cli/install.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { errorMessage } from "../error-utils";
 import { downloadEngine } from "../engine-install";
 import { getEngineBinPath, getEngineCapabilities } from "../engine";
 import { renderInstallPlan } from "../install-plan";
@@ -111,7 +112,7 @@ function finishInstallDiagnostic(
     });
     diagnosticLog.finish(status);
   } catch (err) {
-    log.debug(`install diagnostic log finish dropped: ${err instanceof Error ? err.message : String(err)}`);
+    log.debug(`install diagnostic log finish dropped: ${errorMessage(err)}`);
   }
 }
 
@@ -161,7 +162,7 @@ export async function performInstall(
     await maybeAskForStar(getEngineBinPath(), packageVersion, log);
     finishInstallDiagnostic(diagnosticLog, startedAt, "success");
   } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = errorMessage(err);
     finishInstallDiagnostic(diagnosticLog, startedAt, "failed", errorKind);
     log.error(message);
     process.exit(1);
@@ -219,7 +220,7 @@ export const installCommand = defineCommand({
     try {
       ttsLangs = resolveTtsLangs({ tts: args.tts === true, positionals }, supported);
     } catch (err) {
-      log.error(err instanceof Error ? err.message : String(err));
+      log.error(errorMessage(err));
       process.exit(1);
     }
     await performInstall(

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { errorMessage } from "../error-utils";
 import { existsSync } from "fs";
 import { detect } from "tinyld";
 import { preflightTranscribeWithSegments, transcribeWithSegments } from "../transcribe";
@@ -435,7 +436,7 @@ export const mainCommand = defineCommand({
       } catch (err: unknown) {
         progress?.stop();
         hasError = true;
-        const stderrText = err instanceof Error ? err.message : String(err);
+        const stderrText = errorMessage(err);
         const code = extractEngineErrorCode(stderrText) ?? ENGINE_CODES.TRANSCRIBE_FAILED;
         stats.recordError("transcribe", err, code);
         diagnosticLog.event("engine.exit", {

package/src/cli/say.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { errorMessage } from "../error-utils";
 import { detectTextLanguageEngine, getEngineBinPath } from "../engine";
 import { log } from "../log";
 import { say, SayError, type SayFormat } from "../synth";
@@ -289,7 +290,7 @@ export const sayCommand = defineCommand({
         log.error(err.stderr.trim() || err.message);
         process.exit(err.exitCode);
       }
-      const message = err instanceof Error ? err.message : String(err);
+      const message = errorMessage(err);
       log.error(message);
       process.exit(4);
     }

package/src/cli/support-bundle.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { errorMessage } from "../error-utils";
 import { createSupportBundle } from "../support-bundle";
 import { log } from "../log";
 
@@ -33,7 +34,7 @@ export const supportBundleCommand = defineCommand({
       log.info(`Entries: ${bundle.entries.length}`);
       log.info(`Size: ${bundle.sizeBytes} bytes`);
     } catch (err) {
-      log.error(err instanceof Error ? err.message : String(err));
+      log.error(errorMessage(err));
       process.exit(1);
     }
   },

package/src/diagnostic-log.ts

@@ -1,3 +1,4 @@
+import { errorMessage } from "./error-utils";
 import {
   closeSync,
   existsSync,
@@ -232,7 +233,7 @@ export function createDiagnosticLogSession(): DiagnosticLogSession {
         appendDiagnosticLogLine(line, status);
         return true;
       } catch (err) {
-        log.debug(`diagnostic log event dropped: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`diagnostic log event dropped: ${errorMessage(err)}`);
         return false;
       }
     },

package/src/doctor.ts

@@ -1,4 +1,6 @@
 import { existsSync, statSync } from "fs";
+import { errorMessage } from "./error-utils";
+import { humanBytes } from "./format";
 import { dirname, join, sep } from "path";
 import {
   getEngineBinPath,
@@ -82,18 +84,6 @@ export interface DoctorReport {
   env: Record<string, string | null>;
 }
 
-function humanBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  const units = ["KB", "MB", "GB", "TB"];
-  let n = bytes / 1024;
-  let i = 0;
-  while (n >= 1024 && i < units.length - 1) {
-    n /= 1024;
-    i++;
-  }
-  return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;
-}
-
 function pathSummary(path: string): PathSummary {
   return {
     path,
@@ -194,7 +184,7 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
       capabilities = await getEngineCapabilities();
       if (!capabilities) probeError = "capabilities probe returned no data";
     } catch (err) {
-      probeError = err instanceof Error ? err.message : String(err);
+      probeError = errorMessage(err);
     }
   }
 
@@ -305,7 +295,7 @@ function collectStats(redact: boolean): DoctorReport["stats"] {
       : status;
   } catch (err) {
     return {
-      error: redactString("statsError", err instanceof Error ? err.message : String(err), redact) ?? "unknown",
+      error: redactString("statsError", errorMessage(err), redact) ?? "unknown",
     };
   }
 }
@@ -337,7 +327,7 @@ function collectDiagnosticLogs(redact: boolean): DoctorReport["diagnosticLogs"]
       maxBytes: 10 * 1024 * 1024,
       retain: 5,
       error:
-        redactString("diagnosticLogsError", err instanceof Error ? err.message : String(err), redact) ??
+        redactString("diagnosticLogsError", errorMessage(err), redact) ??
         "unknown",
     };
   }

package/src/engine-install.ts

@@ -1,4 +1,5 @@
 import { dirname, join } from "path";
+import { errorMessage } from "./error-utils";
 import { tmpdir } from "os";
 import { existsSync, mkdirSync, chmodSync, accessSync, constants, rmSync } from "fs";
 import {
@@ -6,6 +7,7 @@ import {
   getEngineCapabilities,
   TRANSCRIBE_DIARIZE_FEATURE,
 } from "./engine";
+import { isDarwinArm64 } from "./fluid-kokoro-cache";
 import { log } from "./log";
 import { engineVersion } from "./package-info";
 import { streamResponseToFile } from "./progress";
@@ -61,7 +63,7 @@ interface SidecarSpec {
   unavailableHint: string;
 }
 
-const SIDECARS: SidecarSpec[] = [
+export const SIDECARS: SidecarSpec[] = [
   {
     fileBasename: "say-avspeech",
     assetName: "say-avspeech-darwin-arm64",
@@ -110,7 +112,7 @@ export function cleanupRetiredSidecars(engineDir: string): string[] {
       removed.push(filename);
     } catch (e) {
       log.warn(
-        `Could not remove retired sidecar ${filename} (${e instanceof Error ? e.message : e}); continuing.`,
+        `Could not remove retired sidecar ${filename} (${errorMessage(e)}); continuing.`,
       );
     }
   }
@@ -163,7 +165,7 @@ function darwinTrustBinary(path: string, displayName: string): void {
     }
   } catch (e) {
     log.debug(
-      `codesign on ${displayName} threw: ${e instanceof Error ? e.message : e}`,
+      `codesign on ${displayName} threw: ${errorMessage(e)}`,
     );
   }
   try {
@@ -184,7 +186,7 @@ function darwinTrustBinary(path: string, displayName: string): void {
     }
   } catch (e) {
     log.debug(
-      `xattr -d on ${displayName} threw: ${e instanceof Error ? e.message : e}`,
+      `xattr -d on ${displayName} threw: ${errorMessage(e)}`,
     );
   }
   if (!codesignOk && !xattrOk) {
@@ -212,7 +214,7 @@ async function downloadSidecar(
   binPath: string,
   engineVersion: string,
 ): Promise<void> {
-  if (process.platform !== "darwin" || process.arch !== "arm64") return;
+  if (!isDarwinArm64()) return;
 
   const sidecarPath = join(dirname(binPath), spec.fileBasename);
   const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${spec.assetName}`;
@@ -222,7 +224,7 @@ async function downloadSidecar(
     res = await fetch(url, { redirect: "follow" });
   } catch (e) {
     log.warn(
-      `Could not fetch ${spec.displayName} (${e instanceof Error ? e.message : e}); ${spec.unavailableHint}.`,
+      `Could not fetch ${spec.displayName} (${errorMessage(e)}); ${spec.unavailableHint}.`,
     );
     return;
   }
@@ -248,13 +250,13 @@ async function downloadSidecar(
     log.success(`${spec.displayName} installed (${spec.availableHint}).`);
   } catch (e) {
     log.warn(
-      `${spec.displayName} install failed (${e instanceof Error ? e.message : e}); ${spec.unavailableHint}.`,
+      `${spec.displayName} install failed (${errorMessage(e)}); ${spec.unavailableHint}.`,
     );
   }
 }
 
 async function warmDarwinKokoro(binPath: string): Promise<void> {
-  if (process.platform !== "darwin" || process.arch !== "arm64") return;
+  if (!isDarwinArm64()) return;
   // Kokoro now runs in-engine (FluidAudio CoreML, system_kokoro) — warm it by
   // exercising the engine's own `say`, not a sidecar. The first synthesis
   // compiles/fetches FluidAudio's CoreML Kokoro cache.
@@ -312,7 +314,7 @@ async function warmDarwinKokoro(binPath: string): Promise<void> {
     );
   } catch (e) {
     log.warn(
-      `FluidAudio Kokoro warmup failed (${e instanceof Error ? e.message : e}); ` +
+      `FluidAudio Kokoro warmup failed (${errorMessage(e)}); ` +
         "first `kesha say en-*` may still be slow.",
     );
   } finally {
@@ -351,6 +353,120 @@ export interface InstallOptions {
   diarize?: boolean;
 }
 
+/**
+ * Cache-valid path: the binary at binPath already matches engineVersion.
+ * Re-trusts it and tops up any sidecars the cached install is missing.
+ */
+async function refreshCachedEngine(
+  binPath: string,
+  canWriteEngineDir: boolean,
+  noCache: boolean,
+): Promise<void> {
+  const engineDir = dirname(binPath);
+  if (noCache && !canWriteEngineDir) {
+    log.info(
+      `Engine binary at v${engineVersion} is on a read-only filesystem; --no-cache skipped for engine (still forwarded to model installs).`,
+    );
+  } else {
+    log.success(`Engine binary already installed (v${engineVersion}).`);
+  }
+  // Re-run the macOS trust step against the cached binary too. Reason:
+  // a user who upgraded to macOS 15+ Sequoia AFTER installing kesha
+  // would have a v<X> binary on disk with `com.apple.provenance` still
+  // attached, and `kesha install` would normally bail at "already
+  // installed" without healing the SIGKILL. Idempotent — re-signing
+  // an already-correctly-signed binary is a ~10 ms no-op; `xattr -d`
+  // on an absent attr is handled (exit 1 + "No such xattr" treated
+  // as success in `darwinTrustBinary`). Skipped on read-only
+  // filesystems (Nix-store installs) — no write access anyway.
+  if (canWriteEngineDir && existsSync(binPath)) {
+    darwinTrustBinary(binPath, "kesha-engine binary");
+  }
+  // Top up any sidecars missing from this cached install. Pre-#141 / pre-#199
+  // engines never shipped them, so a cache-valid binary may still need
+  // fetching. Run independent fetches concurrently — same shape as the
+  // cold path in fetchEngineBinary.
+  //
+  // Skip the top-up entirely when the engine sits in a read-only
+  // filesystem (e.g., a Nix-store install). Those installs stage the
+  // supported sidecars at build time; writing more is impossible, and
+  // attempting it would emit a confusing "install failed" warning for
+  // a feature the Nix README explicitly documents as unsupported
+  // (diarize on Nix needs network access at build time, which the
+  // sandbox forbids).
+  if (canWriteEngineDir) {
+    const missing = SIDECARS.filter(
+      (s) => !existsSync(join(engineDir, s.fileBasename)),
+    );
+    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
+    // The cache-valid branch also re-trusts any sidecars that already
+    // exist alongside the engine — same upgrade-to-Sequoia scenario as
+    // above. The `missing.map` above only handles NEW sidecars; this
+    // loop handles ALREADY-PRESENT ones.
+    for (const s of SIDECARS) {
+      const p = join(engineDir, s.fileBasename);
+      if (existsSync(p)) darwinTrustBinary(p, s.displayName);
+    }
+  }
+}
+
+/** Cold path: download the engine binary (and sidecars, concurrently). */
+async function fetchEngineBinary(
+  binPath: string,
+  installedVersion: string | null,
+): Promise<void> {
+  // Log why we're downloading — helps diagnose surprising re-downloads.
+  if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
+    log.progress(
+      `Upgrading engine v${installedVersion} → v${engineVersion}...`,
+    );
+  }
+  const binaryName = getEngineBinaryName();
+  const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${binaryName}`;
+
+  mkdirSync(dirname(binPath), { recursive: true });
+
+  // Kick off all sidecar fetches concurrently with the engine fetch. They
+  // target independent github.com release assets, so overlapping the HTTP
+  // round-trips saves ~15-30s on a cold install. Each sidecar is
+  // best-effort (404 on older engines, warn + continue) so a failure
+  // doesn't cascade into the engine path.
+  const sidecarPromises = SIDECARS.map((s) =>
+    downloadSidecar(s, binPath, engineVersion),
+  );
+  // Defense-in-depth: if the engine fetch throws below, attach no-op
+  // rejection handlers so we don't surface unhandledRejection errors
+  // from sidecar paths whose internal try/catch ever drifts. Logs from
+  // sidecars whose own work is still in flight will print when they
+  // complete; the engine error is what the user needs to see now.
+  const muteSidecarRejections = () =>
+    sidecarPromises.forEach((p) => p.catch(() => {}));
+
+  let res: Response;
+  try {
+    res = await fetch(url, { redirect: "follow" });
+  } catch (e) {
+    muteSidecarRejections();
+    throw new Error(
+      `Failed to fetch engine binary: ${errorMessage(e)}\n  Fix: Check your network connection and try again`,
+    );
+  }
+
+  if (!res.ok) {
+    muteSidecarRejections();
+    throw new Error(
+      `Failed to download engine binary (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
+    );
+  }
+
+  await streamResponseToFile(res, binPath, "kesha-engine binary");
+  chmodSync(binPath, 0o755);
+  darwinTrustBinary(binPath, "kesha-engine binary");
+  writeInstalledEngineVersion(binPath, engineVersion);
+  log.success(`Engine binary downloaded (v${engineVersion}).`);
+  await Promise.all(sidecarPromises);
+}
+
 export async function downloadEngine(
   noCache = false,
   backend?: string,
@@ -383,102 +499,9 @@ export async function downloadEngine(
   const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 
   if (cacheValid) {
-    if (noCache && !canWriteEngineDir) {
-      log.info(
-        `Engine binary at v${engineVersion} is on a read-only filesystem; --no-cache skipped for engine (still forwarded to model installs).`,
-      );
-    } else {
-      log.success(`Engine binary already installed (v${engineVersion}).`);
-    }
-    // Re-run the macOS trust step against the cached binary too. Reason:
-    // a user who upgraded to macOS 15+ Sequoia AFTER installing kesha
-    // would have a v<X> binary on disk with `com.apple.provenance` still
-    // attached, and `kesha install` would normally bail at "already
-    // installed" without healing the SIGKILL. Idempotent — re-signing
-    // an already-correctly-signed binary is a ~10 ms no-op; `xattr -d`
-    // on an absent attr is handled (exit 1 + "No such xattr" treated
-    // as success in `darwinTrustBinary`). Skipped on read-only
-    // filesystems (Nix-store installs) — no write access anyway.
-    if (canWriteEngineDir && existsSync(binPath)) {
-      darwinTrustBinary(binPath, "kesha-engine binary");
-    }
-    // Top up any sidecars missing from this cached install. Pre-#141 / pre-#199
-    // engines never shipped them, so a cache-valid binary may still need
-    // fetching. Run independent fetches concurrently — same shape as the
-    // cold path below.
-    //
-    // Skip the top-up entirely when the engine sits in a read-only
-    // filesystem (e.g., a Nix-store install). Those installs stage the
-    // supported sidecars at build time; writing more is impossible, and
-    // attempting it would emit a confusing "install failed" warning for
-    // a feature the Nix README explicitly documents as unsupported
-    // (diarize on Nix needs network access at build time, which the
-    // sandbox forbids).
-    if (canWriteEngineDir) {
-      const missing = SIDECARS.filter(
-        (s) => !existsSync(join(engineDir, s.fileBasename)),
-      );
-      await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
-      // The cache-valid branch also re-trusts any sidecars that already
-      // exist alongside the engine — same upgrade-to-Sequoia scenario as
-      // above. The `missing.map` above only handles NEW sidecars; this
-      // loop handles ALREADY-PRESENT ones.
-      for (const s of SIDECARS) {
-        const p = join(engineDir, s.fileBasename);
-        if (existsSync(p)) darwinTrustBinary(p, s.displayName);
-      }
-    }
+    await refreshCachedEngine(binPath, canWriteEngineDir, noCache);
   } else {
-    // Log why we're downloading — helps diagnose surprising re-downloads.
-    if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
-      log.progress(
-        `Upgrading engine v${installedVersion} → v${engineVersion}...`,
-      );
-    }
-    const binaryName = getEngineBinaryName();
-    const url = `https://github.com/${GITHUB_REPO}/releases/download/v${engineVersion}/${binaryName}`;
-
-    mkdirSync(dirname(binPath), { recursive: true });
-
-    // Kick off all sidecar fetches concurrently with the engine fetch. They
-    // target independent github.com release assets, so overlapping the HTTP
-    // round-trips saves ~15-30s on a cold install. Each sidecar is
-    // best-effort (404 on older engines, warn + continue) so a failure
-    // doesn't cascade into the engine path.
-    const sidecarPromises = SIDECARS.map((s) =>
-      downloadSidecar(s, binPath, engineVersion),
-    );
-    // Defense-in-depth: if the engine fetch throws below, attach no-op
-    // rejection handlers so we don't surface unhandledRejection errors
-    // from sidecar paths whose internal try/catch ever drifts. Logs from
-    // sidecars whose own work is still in flight will print when they
-    // complete; the engine error is what the user needs to see now.
-    const muteSidecarRejections = () =>
-      sidecarPromises.forEach((p) => p.catch(() => {}));
-
-    let res: Response;
-    try {
-      res = await fetch(url, { redirect: "follow" });
-    } catch (e) {
-      muteSidecarRejections();
-      throw new Error(
-        `Failed to fetch engine binary: ${e instanceof Error ? e.message : e}\n  Fix: Check your network connection and try again`,
-      );
-    }
-
-    if (!res.ok) {
-      muteSidecarRejections();
-      throw new Error(
-        `Failed to download engine binary (HTTP ${res.status})\n  Fix: Check https://github.com/${GITHUB_REPO}/releases for available versions`,
-      );
-    }
-
-    await streamResponseToFile(res, binPath, "kesha-engine binary");
-    chmodSync(binPath, 0o755);
-    darwinTrustBinary(binPath, "kesha-engine binary");
-    writeInstalledEngineVersion(binPath, engineVersion);
-    log.success(`Engine binary downloaded (v${engineVersion}).`);
-    await Promise.all(sidecarPromises);
+    await fetchEngineBinary(binPath, installedVersion);
   }
 
   if (backend) {

package/src/engine.ts

@@ -1,4 +1,5 @@
 import { existsSync, statSync } from "fs";
+import { errorMessage } from "./error-utils";
 import { join } from "path";
 import { installHint } from "./install-hint";
 import { log } from "./log";
@@ -280,7 +281,7 @@ export async function transcribeEngineWithSegments(
   try {
     return parseTranscriptionOutput(stdout);
   } catch (err: unknown) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = errorMessage(err);
     throw new Error(`${message}: ${stdout}`);
   }
 }

package/src/error-utils.ts

@@ -0,0 +1,4 @@
+/** Human-readable message from an unknown catch value. */
+export function errorMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/src/format.ts

@@ -60,3 +60,16 @@ export function formatJsonOutput(
     errors === undefined ? results : { results, errors };
   return JSON.stringify(payload, null, 2) + "\n";
 }
+
+/** Render a byte count as a human-readable size (e.g. "1.5 MB"). */
+export function humanBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let n = bytes / 1024;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i++;
+  }
+  return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;
+}

package/src/install-plan.ts

@@ -1,6 +1,8 @@
 import { existsSync, statSync } from "fs";
+import { humanBytes } from "./format";
 import { dirname, join } from "path";
 import { getEngineBinPath } from "./engine";
+import { SIDECARS } from "./engine-install";
 import { readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
 import { engineVersion, packageVersion } from "./package-info";
@@ -119,29 +121,30 @@ const DIARIZE_FILES: PlanFile[] = [
   },
 ];
 
-// Kokoro (#207) and diarization (#199) are in-engine now (native fluidaudio-rs),
-// so only AVSpeech and text-lang ship as separate Swift-sidecar assets.
-const DARWIN_SIDECARS: ReleaseAssetSpec[] = [
-  { assetName: "say-avspeech-darwin-arm64", sizeBytes: 63_056 },
-  { assetName: "kesha-textlang-darwin-arm64", sizeBytes: 57_648 },
-];
+// The sidecar list (and the asset-name → installed-filename mapping) lives in
+// SIDECARS in engine-install.ts; only the release-asset sizes are pinned here,
+// like the model tables above.
+const SIDECAR_ASSET_SIZES: Record<string, number> = {
+  "say-avspeech-darwin-arm64": 63_056,
+  "kesha-textlang-darwin-arm64": 57_648,
+};
+
+const DARWIN_SIDECARS = SIDECARS.map((s) => {
+  const sizeBytes = SIDECAR_ASSET_SIZES[s.assetName];
+  if (sizeBytes === undefined) {
+    // Fail fast at module load: a sidecar added to SIDECARS without a size
+    // entry here would otherwise silently render as "0 B" in the plan.
+    throw new Error(
+      `install-plan: missing release-asset size for sidecar "${s.assetName}"; add it to SIDECAR_ASSET_SIZES`,
+    );
+  }
+  return { assetName: s.assetName, fileBasename: s.fileBasename, sizeBytes };
+});
 
 function sumFiles(files: PlanFile[]): number {
   return files.reduce((sum, file) => sum + file.sizeBytes, 0);
 }
 
-function humanBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  const units = ["KB", "MB", "GB", "TB"];
-  let n = bytes / 1024;
-  let i = 0;
-  while (n >= 1024 && i < units.length - 1) {
-    n /= 1024;
-    i++;
-  }
-  return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;
-}
-
 function engineAssetForPlatform(): ReleaseAssetSpec | null {
   if (process.platform === "darwin" && process.arch === "arm64") {
     return { assetName: "kesha-engine-darwin-arm64", sizeBytes: 59_621_264 };
@@ -155,12 +158,6 @@ function engineAssetForPlatform(): ReleaseAssetSpec | null {
   return null;
 }
 
-function sidecarFilename(assetName: string): string {
-  if (assetName === "say-avspeech-darwin-arm64") return "say-avspeech";
-  if (assetName === "kesha-textlang-darwin-arm64") return "kesha-textlang";
-  return assetName;
-}
-
 function filesCached(cacheRoot: string, files: PlanFile[]): boolean {
   return files.every((file) => {
     const path = join(cacheRoot, file.relPath);
@@ -226,7 +223,7 @@ export async function renderInstallPlan(options: InstallPlanOptions = {}): Promi
         name: `Sidecar ${sidecar.assetName}`,
         source: `GitHub release v${engineVersion}`,
         sizeBytes: sidecar.sizeBytes,
-        cached: existsSync(join(engineDir, sidecarFilename(sidecar.assetName))),
+        cached: existsSync(join(engineDir, sidecar.fileBasename)),
         refresh: noCache,
       });
     }

package/src/mcp/tools.ts

@@ -1,4 +1,5 @@
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { errorMessage } from "../error-utils";
 import { z } from "zod";
 import { chmodSync, existsSync, readFileSync, statSync } from "fs";
 import { basename, join } from "path";
@@ -78,7 +79,7 @@ export function registerTools(server: McpServer): void {
           structuredContent: { uri, path: outPath, format: fmt, voice: resolvedVoice, bytes },
         };
       } catch (err) {
-        return { isError: true, content: [{ type: "text" as const, text: toToolError(err) }] };
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(err) }] };
       }
     },
   );
@@ -126,7 +127,7 @@ export function registerTools(server: McpServer): void {
           structuredContent: { text, segments: [] },
         };
       } catch (err) {
-        return { isError: true, content: [{ type: "text" as const, text: toToolError(err) }] };
+        return { isError: true, content: [{ type: "text" as const, text: errorMessage(err) }] };
       }
     },
   );
@@ -159,7 +160,7 @@ export function registerTools(server: McpServer): void {
           structuredContent: { voices },
         };
       } catch (err) {
-        return { isError: true, content: [{ type: "text" as const, text: `list_voices failed: ${toToolError(err)}` }] };
+        return { isError: true, content: [{ type: "text" as const, text: `list_voices failed: ${errorMessage(err)}` }] };
       }
     },
   );
@@ -189,12 +190,8 @@ export function registerTools(server: McpServer): void {
           structuredContent: { languages },
         };
       } catch (err) {
-        return { isError: true, content: [{ type: "text" as const, text: `list_languages failed: ${toToolError(err)}` }] };
+        return { isError: true, content: [{ type: "text" as const, text: `list_languages failed: ${errorMessage(err)}` }] };
       }
     },
   );
 }
-
-function toToolError(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}

package/src/stats.ts

@@ -1,4 +1,6 @@
 import { Database } from "bun:sqlite";
+import { errorMessage } from "./error-utils";
+import { humanBytes } from "./format";
 import { existsSync, mkdirSync, statSync } from "fs";
 import { homedir } from "os";
 import { dirname, extname, join } from "path";
@@ -148,7 +150,7 @@ function warnStatsWriteFailed(err: unknown): void {
     log.warn("warning: failed to write Kesha Stats; continuing without stats for this event");
     warnedStatsWriteFailed = true;
   }
-  const message = err instanceof Error ? err.message : String(err);
+  const message = errorMessage(err);
   log.debug(`stats write failed: ${message}`);
 }
 
@@ -170,23 +172,33 @@ export function createStatsRecorder(command: StatsCommandName): StatsRecorder {
   }
 }
 
-export function enableStats(): void {
+/** Open the stats DB (creating it if needed), run fn, always close. */
+function withStatsDb<T>(fn: (db: Database) => T): T {
   const db = openStatsDatabase(resolveStatsDbPath());
   try {
-    setSetting(db, "enabled", "1");
-    applyStatsRetention(db);
+    return fn(db);
   } finally {
     db.close();
   }
 }
 
+/** Like withStatsDb, but returns fallback() without creating the DB when none exists. */
+function withExistingStatsDb<T>(fallback: () => T, fn: (db: Database) => T): T {
+  if (!existsSync(resolveStatsDbPath())) return fallback();
+  return withStatsDb(fn);
+}
+
+export function enableStats(): void {
+  withStatsDb((db) => {
+    setSetting(db, "enabled", "1");
+    applyStatsRetention(db);
+  });
+}
+
 export function disableStats(): void {
-  const db = openStatsDatabase(resolveStatsDbPath());
-  try {
+  withStatsDb((db) => {
     setSetting(db, "enabled", "0");
-  } finally {
-    db.close();
-  }
+  });
 }
 
 export interface StatsStatus {
@@ -199,27 +211,22 @@ export interface StatsStatus {
 
 export function getStatsStatus(): StatsStatus {
   const dbPath = resolveStatsDbPath();
-  if (!existsSync(dbPath)) {
-    return {
+  return withExistingStatsDb<StatsStatus>(
+    () => ({
       enabled: false,
       dbPath,
       runCount: 0,
       exists: false,
       retentionDays: defaultRetentionDays(),
-    };
-  }
-  const db = openStatsDatabase(dbPath);
-  try {
-    return {
+    }),
+    (db) => ({
       enabled: getStatsEnabled(db),
       dbPath,
       runCount: Number((db.query("select count(*) as n from runs").get() as { n: number }).n),
       exists: true,
       retentionDays: getStatsRetentionDays(db),
-    };
-  } finally {
-    db.close();
-  }
+    }),
+  );
 }
 
 export interface StatsResetResult {
@@ -230,31 +237,27 @@ export interface StatsResetResult {
 }
 
 export function resetStats(): StatsResetResult {
-  const dbPath = resolveStatsDbPath();
-  if (!existsSync(dbPath)) {
-    return { runs: 0, artifacts: 0, stageTimings: 0, errors: 0 };
-  }
-  const db = openStatsDatabase(dbPath);
-  try {
-    let artifacts = 0;
-    let stageTimings = 0;
-    let errors = 0;
-    let runs = 0;
-    db.exec("begin");
-    try {
-      artifacts = runChanges(db, "delete from artifacts");
-      stageTimings = runChanges(db, "delete from stage_timings");
-      errors = runChanges(db, "delete from errors");
-      runs = runChanges(db, "delete from runs");
-      db.exec("commit");
-    } catch (err) {
-      db.exec("rollback");
-      throw err;
-    }
-    return { runs, artifacts, stageTimings, errors };
-  } finally {
-    db.close();
-  }
+  return withExistingStatsDb(
+    () => ({ runs: 0, artifacts: 0, stageTimings: 0, errors: 0 }),
+    (db) => {
+      let artifacts = 0;
+      let stageTimings = 0;
+      let errors = 0;
+      let runs = 0;
+      db.exec("begin");
+      try {
+        artifacts = runChanges(db, "delete from artifacts");
+        stageTimings = runChanges(db, "delete from stage_timings");
+        errors = runChanges(db, "delete from errors");
+        runs = runChanges(db, "delete from runs");
+        db.exec("commit");
+      } catch (err) {
+        db.exec("rollback");
+        throw err;
+      }
+      return { runs, artifacts, stageTimings, errors };
+    },
+  );
 }
 
 export interface StatsVacuumResult {
@@ -273,13 +276,10 @@ export function vacuumStats(): StatsVacuumResult {
       afterBytes: 0,
     };
   }
-  const db = openStatsDatabase(dbPath);
-  try {
+  withStatsDb((db) => {
     db.exec("pragma wal_checkpoint(TRUNCATE)");
     db.exec("vacuum");
-  } finally {
-    db.close();
-  }
+  });
   return {
     dbPath,
     beforeBytes,
@@ -291,13 +291,10 @@ export function setStatsRetentionDays(days: number | null): void {
   if (days !== null && (!Number.isInteger(days) || days < 1)) {
     throw new Error("Stats retention must be a positive whole number of days, or 'off'");
   }
-  const db = openStatsDatabase(resolveStatsDbPath());
-  try {
+  withStatsDb((db) => {
     setSetting(db, "retention_days", days === null ? "off" : String(days));
     applyStatsRetention(db);
-  } finally {
-    db.close();
-  }
+  });
 }
 
 export function exportStats(format: StatsExportFormat): string {
@@ -379,11 +376,8 @@ interface StatsRunTimingRow {
 }
 
 export function getWeekSummary(now = new Date()): StatsWeekSummary {
-  const dbPath = resolveStatsDbPath();
-  if (!existsSync(dbPath)) return emptyWeekSummary();
   const since = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000).toISOString();
-  const db = openStatsDatabase(dbPath);
-  try {
+  return withExistingStatsDb(emptyWeekSummary, (db) => {
     const stageRows = db.query(
       `select
         run_id as runId,
@@ -432,9 +426,7 @@ export function getWeekSummary(now = new Date()): StatsWeekSummary {
       hasInputDurationData: inputArtifacts.some((row) => typeof row.durationMs === "number"),
       slowestRuns: summarizeSlowestRuns(runRows, stageRows),
     };
-  } finally {
-    db.close();
-  }
+  });
 }
 
 export interface StatsRunExportRow {
@@ -491,11 +483,10 @@ export interface StatsErrorRow {
 }
 
 export function getRecentErrors(limit = 20): StatsErrorRow[] {
-  const dbPath = resolveStatsDbPath();
-  if (!existsSync(dbPath)) return [];
-  const db = openStatsDatabase(dbPath);
-  try {
-    const rows = db.query(
+  return withExistingStatsDb(
+    () => [],
+    (db) => {
+      const rows = db.query(
       `select
         e.occurred_at as occurredAt,
         r.command as command,
@@ -507,11 +498,10 @@ export function getRecentErrors(limit = 20): StatsErrorRow[] {
        left join runs r on r.id = e.run_id
        order by e.occurred_at desc
        limit ?`,
-    ).all(limit) as StatsErrorRow[];
-    return rows;
-  } finally {
-    db.close();
-  }
+      ).all(limit) as StatsErrorRow[];
+      return rows;
+    },
+  );
 }
 
 export function renderWeekSummary(summary: StatsWeekSummary): string {
@@ -779,15 +769,11 @@ function insertRun(db: Database, command: StatsCommandName): number {
 }
 
 function readStatsExport(): StatsExportData {
-  const dbPath = resolveStatsDbPath();
-  if (!existsSync(dbPath)) {
-    return emptyStatsExport(defaultRetentionDays());
-  }
-
-  const db = openStatsDatabase(dbPath);
-  try {
-    applyStatsRetention(db);
-    return {
+  return withExistingStatsDb(
+    () => emptyStatsExport(defaultRetentionDays()),
+    (db) => {
+      applyStatsRetention(db);
+      return {
       schemaVersion: SCHEMA_VERSION,
       exportedAt: new Date().toISOString(),
       retentionDays: getStatsRetentionDays(db),
@@ -839,11 +825,10 @@ function readStatsExport(): StatsExportData {
          from errors e
          left join runs r on r.id = e.run_id
          order by e.occurred_at asc, e.id asc`,
-      ).all() as StatsErrorRow[],
-    };
-  } finally {
-    db.close();
-  }
+        ).all() as StatsErrorRow[],
+      };
+    },
+  );
 }
 
 function emptyStatsExport(retentionDays: number | null): StatsExportData {
@@ -1200,18 +1185,6 @@ function orderBuckets(buckets: Map<string, number>, order: string[]): StatsCount
     .map((label) => ({ label, count: buckets.get(label) ?? 0 }));
 }
 
-function humanBytes(bytes: number): string {
-  if (bytes < 1024) return `${bytes} B`;
-  const units = ["KB", "MB", "GB", "TB"];
-  let n = bytes / 1024;
-  let i = 0;
-  while (n >= 1024 && i < units.length - 1) {
-    n /= 1024;
-    i++;
-  }
-  return `${n.toFixed(n >= 100 ? 0 : 1)} ${units[i]}`;
-}
-
 function humanDuration(ms: number): string {
   const seconds = Math.round(ms / 1000);
   if (seconds < 1) return `${ms}ms`;