@drakulavich/kesha-voice-kit 1.13.0 → 1.15.0

package/README.md

@@ -22,49 +22,39 @@
 
 Runtime: **[Bun](https://bun.sh)** >= 1.3.0.
 
-```bash
-curl -fsSL https://bun.sh/install | bash   # skip if Bun is already installed
+Install Bun (skip if already installed) — pick one:
 
-bun install -g @drakulavich/kesha-voice-kit
-kesha install       # downloads engine + models
-kesha audio.ogg     # transcript to stdout
+```bash
+# Linux & macOS
+curl -fsSL https://bun.sh/install | bash       # upstream installer
+brew install oven-sh/bun/bun                   # Homebrew
 ```
 
-Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
-
-## Nix Install (Recommended)
-
-**Prerequisites:** [Nix](https://nixos.org/download/) with flakes enabled.
-
-### One-liner run (no install)
-```bash
-nix run github:drakulavich/kesha-voice-kit -- install
-nix run github:drakulavich/kesha-voice-kit -- audio.ogg
+```powershell
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
 ```
 
-### Install to profile (persistent)
+Then install Kesha:
+
 ```bash
-nix profile install github:drakulavich/kesha-voice-kit
+bun add -g @drakulavich/kesha-voice-kit
 kesha install       # downloads engine + models
 kesha audio.ogg     # transcript to stdout
 ```
 
-### Development shell
-```bash
-nix develop github:drakulavich/kesha-voice-kit
-# Now you have: rust, cargo, bun, protoc, cargo-make
-```
+Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
+
+## Nix Install
+
+Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
 
-### Build only
 ```bash
-nix build github:drakulavich/kesha-voice-kit#kesha-engine
-./result/bin/kesha-engine --help
+nix run github:drakulavich/kesha-voice-kit -- install      # downloads models (engine is bundled)
+nix run github:drakulavich/kesha-voice-kit -- audio.ogg    # transcribe
 ```
 
-**Why Nix?**
-- ✅ Reproducible builds across Linux/macOS
-- ✅ All native deps (onnxruntime, protobuf, abseil) handled automatically
-- ✅ No "works on my machine" — same `flake.nix` = identical results everywhere
+Full recipes (one-liner, profile install, engine-only, dev shell) live in [docs/nix-install.md](docs/nix-install.md).
 
 ## Speech-to-text
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.13.0",
+  "version": "1.15.0",
   "description": "Open-source voice toolkit. Speech-to-text (25 langs, ~19x faster than Whisper on Apple Silicon, ONNX fallback on CPU), text-to-speech (Kokoro + Vosk-TTS + ~180 macOS system voices, SSML), voice-activity detection, language detection (107 langs). Rust engine, OpenClaw skill.",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     ]
   },
   "keshaEngine": {
-    "version": "1.13.0"
+    "version": "1.15.0"
   },
   "scripts": {
     "test": "bun test",

package/src/cli/say.ts

@@ -1,31 +1,8 @@
 import { defineCommand } from "citty";
 import { detectTextLanguageEngine, getEngineBinPath } from "../engine";
 import { log } from "../log";
-import { say, SayError, type SayFormat } from "../say";
-
-/**
- * Darwin defaults to AVSpeech Milena — zero install, no model download required.
- * Linux/Windows fall through to Vosk-TTS `ru-vosk-m02` (male, per CLAUDE.md
- * "DEFAULT TTS VOICES MUST BE MALE"; replaces Piper-ruslan as of #213).
- */
-const RU_DARWIN_FALLBACK_VOICE = "macos-com.apple.voice.compact.ru-RU.Milena";
-
-/** Map a detected language code to a default voice id. Unknown / low-confidence → undefined. */
-export function pickVoiceForLang(
-  code: string | undefined,
-  confidence: number,
-  platform: NodeJS.Platform = process.platform,
-): string | undefined {
-  if (!code || confidence < 0.5) return undefined;
-  switch (code) {
-    case "en":
-      return "en-am_michael";
-    case "ru":
-      return platform === "darwin" ? RU_DARWIN_FALLBACK_VOICE : "ru-vosk-m02";
-    default:
-      return undefined;
-  }
-}
+import { say, SayError, type SayFormat } from "../synth";
+import { pickVoiceForLang } from "../voice-routing";
 
 /** Run NLLanguageRecognizer (via engine) on the text and pick a default voice. */
 async function autoRouteVoice(text: string): Promise<string | undefined> {

package/src/cli.ts

@@ -4,7 +4,8 @@
 // tests and lib.ts keep importing from "./cli" via these re-exports so the
 // public surface is unchanged.
 export { installCommand } from "./cli/install";
-export { sayCommand, pickVoiceForLang } from "./cli/say";
+export { sayCommand } from "./cli/say";
+export { pickVoiceForLang } from "./voice-routing";
 export { statusCommand } from "./cli/status";
 export { mainCommand, detectLanguage, checkLanguageMismatch } from "./cli/main";
 export { runCli } from "./cli/dispatch";

package/src/engine-install.ts

@@ -1,6 +1,10 @@
 import { dirname, join } from "path";
-import { existsSync, mkdirSync, chmodSync } from "fs";
-import { getEngineBinPath, getEngineCapabilities } from "./engine";
+import { existsSync, mkdirSync, chmodSync, accessSync, constants } from "fs";
+import {
+  getEngineBinPath,
+  getEngineCapabilities,
+  TRANSCRIBE_DIARIZE_FEATURE,
+} from "./engine";
 import { log } from "./log";
 import { streamResponseToFile } from "./progress";
 import {
@@ -72,6 +76,85 @@ const SIDECARS: SidecarSpec[] = [
   },
 ];
 
+/**
+ * Make a freshly-downloaded Mach-O runnable on macOS 15+ Sequoia.
+ *
+ * The release binaries ship `Signature=adhoc` (built via `cargo build`,
+ * no Apple Developer ID). When fetched via HTTPS into `~/.cache/...`,
+ * macOS attaches a `com.apple.provenance` xattr identifying the download
+ * source. Combined with stricter Gatekeeper policy on macOS 15+ Sequoia,
+ * the resulting "untrusted downloaded ad-hoc binary" is killed with
+ * SIGKILL on first invocation (exit 137), with no log line — Gatekeeper
+ * denies before Rust's main runs.
+ *
+ * Two independent fixes run in sequence; both are best-effort:
+ *
+ * 1. `codesign --force --sign - <path>` — re-applies the ad-hoc
+ *    signature with the user's own host identity, defeating the trust
+ *    mismatch.
+ * 2. `xattr -d com.apple.provenance <path>` — strips the provenance
+ *    marker entirely. Cheaper than codesign and works even when
+ *    `codesign` is absent from PATH (corporate-locked machine, minimal
+ *    CI image).
+ *
+ * Either step alone has unblocked the SIGKILL in field reports, so we
+ * run both. If both fail, surface the manual recovery commands in
+ * stderr. Linux/Windows paths never reach this function.
+ */
+function darwinTrustBinary(path: string, displayName: string): void {
+  if (process.platform !== "darwin") return;
+  let codesignOk = false;
+  let xattrOk = false;
+  try {
+    const proc = Bun.spawnSync(["codesign", "--force", "--sign", "-", path], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    codesignOk = proc.exitCode === 0;
+    if (!codesignOk) {
+      const stderr = new TextDecoder().decode(proc.stderr).trim();
+      log.debug(`codesign on ${displayName} exited ${proc.exitCode}: ${stderr}`);
+    }
+  } catch (e) {
+    log.debug(
+      `codesign on ${displayName} threw: ${e instanceof Error ? e.message : e}`,
+    );
+  }
+  try {
+    // `xattr -d` returns exit 1 with "No such xattr" if the attribute is
+    // already absent (e.g. the file was placed via `bun link` instead of
+    // downloaded). That's a success outcome for our purposes — the
+    // attribute we wanted gone is already gone — so treat exit 1 as ok.
+    const proc = Bun.spawnSync(
+      ["xattr", "-d", "com.apple.provenance", path],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const stderr = new TextDecoder().decode(proc.stderr).trim();
+    xattrOk =
+      proc.exitCode === 0 ||
+      (proc.exitCode === 1 && /No such xattr/i.test(stderr));
+    if (!xattrOk) {
+      log.debug(`xattr -d on ${displayName} exited ${proc.exitCode}: ${stderr}`);
+    }
+  } catch (e) {
+    log.debug(
+      `xattr -d on ${displayName} threw: ${e instanceof Error ? e.message : e}`,
+    );
+  }
+  if (!codesignOk && !xattrOk) {
+    // Single-quote the path in the manual-fix hint so spaces / shell
+    // metachars in `~/.cache/.../bin/...` don't break paste-into-shell.
+    // POSIX single-quote escape: close the quote, insert escaped `'`,
+    // re-open. Cheap and correct on bash/zsh.
+    const q = (p: string) => `'${p.replace(/'/g, `'\\''`)}'`;
+    log.warn(
+      `Could not unblock ${displayName} for macOS Gatekeeper (both codesign ` +
+        `and xattr failed); if the binary refuses to run, manually run: ` +
+        `codesign --force --sign - ${q(path)}  &&  xattr -d com.apple.provenance ${q(path)}`,
+    );
+  }
+}
+
 /**
  * Fetch a single Swift sidecar and place it next to the engine binary on
  * darwin-arm64. Best-effort: 404s (older engine versions predate this
@@ -115,6 +198,7 @@ async function downloadSidecar(
   try {
     await streamResponseToFile(res, sidecarPath, spec.displayName);
     chmodSync(sidecarPath, 0o755);
+    darwinTrustBinary(sidecarPath, spec.displayName);
     log.success(`${spec.displayName} installed (${spec.availableHint}).`);
   } catch (e) {
     log.warn(
@@ -151,19 +235,76 @@ export async function downloadEngine(
         : "unknown";
 
   const installedVersion = readInstalledEngineVersion(binPath);
-  const cacheValid =
-    !noCache && existsSync(binPath) && installedVersion === engineVersion;
+  const engineDir = dirname(binPath);
+
+  // Detect a read-only engine directory (e.g., a Nix-store install —
+  // `KESHA_ENGINE_BIN` points into `/nix/store/.../bin/`). Used twice
+  // below: to honor `--no-cache` only when the engine is writable, and
+  // to skip the sidecar top-up that would otherwise emit confusing
+  // "install failed" warnings for paths we physically can't write to.
+  let canWriteEngineDir = true;
+  if (existsSync(engineDir)) {
+    try {
+      accessSync(engineDir, constants.W_OK);
+    } catch {
+      canWriteEngineDir = false;
+    }
+  }
+
+  const versionMatches =
+    existsSync(binPath) && installedVersion === engineVersion;
+  // When the engine sits on a read-only filesystem at the matching
+  // version, `--no-cache` can't re-download it without an EROFS crash
+  // and there's nothing to refresh anyway — treat as cache-valid and
+  // forward `--no-cache` to the model install step below.
+  const cacheValid = versionMatches && (!noCache || !canWriteEngineDir);
 
   if (cacheValid) {
-    log.success(`Engine binary already installed (v${engineVersion}).`);
+    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.
-    const missing = SIDECARS.filter(
-      (s) => !existsSync(join(dirname(binPath), s.fileBasename)),
-    );
-    await Promise.all(missing.map((s) => downloadSidecar(s, binPath, engineVersion)));
+    //
+    // 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);
+      }
+    }
   } else {
     // Log why we're downloading — helps diagnose surprising re-downloads.
     if (existsSync(binPath) && installedVersion && installedVersion !== engineVersion) {
@@ -211,6 +352,7 @@ export async function downloadEngine(
 
     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);
@@ -225,6 +367,29 @@ export async function downloadEngine(
     }
   }
 
+  // Catch the case where the platform check passed (darwin-arm64) but the
+  // engine itself was built without `system_diarize` — e.g., the Nix build,
+  // which compiles `coreml,tts,system_tts` and intentionally omits diarize
+  // because the FluidAudio CoreML weights need network at build time and the
+  // Nix sandbox forbids it. Without this guard, `kesha-engine install
+  // --diarize` would fail with clap's generic "unexpected argument" error.
+  if (options.diarize) {
+    const caps = await getEngineCapabilities();
+    // Treat null (pre-capabilities-JSON engine, or capability probe failed)
+    // the same as an engine that advertised features but omitted ours —
+    // forwarding `--diarize` to a binary that doesn't understand it would
+    // surface as clap's generic "unexpected argument" error.
+    if (!caps || !caps.features.includes(TRANSCRIBE_DIARIZE_FEATURE)) {
+      throw new Error(
+        "--diarize is not supported by the installed engine: it was built " +
+          "without the 'system_diarize' feature (the Nix build is one such " +
+          "case — see docs/nix-install.md).\n" +
+          "  Fix: install via the npm release with `bun add -g @drakulavich/kesha-voice-kit`, " +
+          "which ships the diarize-enabled engine on darwin-arm64.",
+      );
+    }
+  }
+
   log.progress("Installing models...");
   const installArgs = [
     "install",

package/src/engine.ts

@@ -66,6 +66,15 @@ async function runEngine(args: string[]): Promise<{ stdout: string; stderr: stri
   ]);
 
   log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+
+  // #275 D4: surface engine stderr on the success path so warnings like
+  // `hint: audio is 180s`, `Model mirror active:`, and the dtrace lines
+  // emitted under KESHA_DEBUG=1 reach the user. On non-zero exit we leave
+  // the buffer for callers to fold into a thrown Error — otherwise the
+  // user would see the warning AND a duplicate inside the error message.
+  if (exitCode === 0 && stderr.length > 0) {
+    process.stderr.write(stderr.endsWith("\n") ? stderr : stderr + "\n");
+  }
   return { stdout: stdout.trim(), stderr: stderr.trim(), exitCode };
 }
 

package/src/lib.ts

@@ -9,7 +9,7 @@ import { downloadEngine } from "./engine-install";
 export type { TranscribeOptions };
 export type { TranscriptionOutput, TranscriptionSegment } from "./engine";
 export { downloadEngine as downloadModel };
-export { say, type SayOptions, SayError } from "./say";
+export { say, type SayOptions, SayError } from "./synth";
 
 /**
  * Encode a `TranscribeResult[]` as TOON (#138). Same data shape as the

package/src/log.ts

@@ -4,12 +4,28 @@ import pc from "picocolors";
  * Debug mode (#148): when `KESHA_DEBUG` is truthy OR the caller has flipped
  * `log.debugEnabled = true` (via `--debug`), `log.debug()` writes structured
  * trace lines to stderr. Otherwise it's a no-op. Stdout is never touched.
+ *
+ * Grammar (#275 D9): values that turn debug OFF — empty, `"0"`, `"false"`,
+ * `"no"`, `"off"`, all matched **case-insensitively** after trimming. Any
+ * other non-empty value turns debug ON. The Rust engine mirrors this list
+ * verbatim in `rust/src/debug.rs` so `KESHA_DEBUG=False` flips both sides
+ * the same direction.
  */
+const KESHA_DEBUG_OFF_VALUES = new Set(["", "0", "false", "no", "off"]);
+
 function envDebug(): boolean {
   const v = process.env.KESHA_DEBUG;
-  return !!v && v !== "0" && v.toLowerCase() !== "false";
+  if (v === undefined) return false;
+  return !KESHA_DEBUG_OFF_VALUES.has(v.trim().toLowerCase());
 }
 
+/**
+ * Module-load timestamp for relative-since-start prefixes on debug lines.
+ * The CLI runs nothing of substance before this file is imported, so this
+ * is effectively process-start. Recorded once.
+ */
+const PROCESS_T0_MS = performance.now();
+
 export const log = {
   info: (msg: string) => console.log(msg),
   success: (msg: string) => console.log(pc.green(msg)),
@@ -20,7 +36,15 @@ export const log = {
   debugEnabled: false,
   debug(msg: string): void {
     if (this.debugEnabled || envDebug()) {
-      console.error(pc.dim(`[debug] ${msg}`));
+      // `[debug +Nms]` prefix sits on the CLI process's own timeline so
+      // the reader can see when each line fired. The Rust engine emits
+      // the same `+Nms` shape from `rust/src/debug.rs::trace_fmt`, but
+      // anchored to its own process start — the two axes are
+      // independent. For "duration between two events on the same
+      // process", read the prefix difference; for cross-process spans,
+      // the spawn→exit `dt=Nms` inside the message remains authoritative.
+      const t = Math.round(performance.now() - PROCESS_T0_MS);
+      console.error(pc.dim(`[debug +${t}ms] ${msg}`));
     }
   },
 };

package/src/{say.ts → synth.ts}

@@ -41,8 +41,11 @@ export interface SayOptions {
   /**
    * Disable acronym auto-expansion for `ru-vosk-*` and `en-*` voices.
    * When true, passes `--no-expand-abbrev` to the engine (requires engine
-   * capability `tts.ru_acronym_expansion` or `tts.en_acronym_expansion`; silently dropped for older engines).
-   * `<say-as interpret-as="characters">` still works regardless of this flag.
+   * capability `tts.ru_acronym_expansion` or `tts.en_acronym_expansion`).
+   * On older engines that don't advertise the capability, the flag is
+   * dropped from argv and `log.warn` surfaces the drop on every
+   * invocation (post-#275 D3). `<say-as interpret-as="characters">`
+   * still works regardless of this flag.
    */
   noExpandAbbrev?: boolean;
 }
@@ -65,8 +68,12 @@ export function buildSayArgs(o: SayOptions, capabilities?: EngineCapabilities |
     if (supportsExpand) {
       args.push("--no-expand-abbrev");
     } else {
-      log.debug(
-        "kesha-engine does not advertise tts.ru_acronym_expansion or tts.en_acronym_expansion; dropping --no-expand-abbrev",
+      // CLAUDE.md "NEVER SWALLOW ERRORS": the user explicitly passed the flag.
+      // Silent drop with only `log.debug` made the flag look effective on old
+      // engines (#275 D3). Surface it as a warning so a CI script or human
+      // user sees the mismatch on every invocation, not only with --debug.
+      log.warn(
+        "--no-expand-abbrev requires kesha-engine ≥ 1.10.0 (advertises no tts.ru_acronym_expansion / tts.en_acronym_expansion capability); flag ignored",
       );
     }
   }
@@ -121,6 +128,14 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
   ]);
 
   log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms bytes=${stdoutBuf.byteLength}`);
+
+  // #275 D4: surface engine stderr on the success path so warnings like
+  // `Model mirror active:` and the dtrace lines emitted under
+  // KESHA_DEBUG=1 reach the user. Errors keep their existing path
+  // through `SayError.stderr` so we don't double-print.
+  if (exitCode === 0 && stderrText.length > 0) {
+    process.stderr.write(stderrText.endsWith("\n") ? stderrText : stderrText + "\n");
+  }
   if (exitCode !== 0) {
     throw new SayError(
       stderrText.trim() || `kesha-engine say exited ${exitCode}`,

package/src/voice-routing.ts

@@ -0,0 +1,23 @@
+/**
+ * Darwin defaults to AVSpeech Milena — zero install, no model download required.
+ * Linux/Windows fall through to Vosk-TTS `ru-vosk-m02` (male, per CLAUDE.md
+ * "DEFAULT TTS VOICES MUST BE MALE"; replaces Piper-ruslan as of #213).
+ */
+const RU_DARWIN_FALLBACK_VOICE = "macos-com.apple.voice.compact.ru-RU.Milena";
+
+/** Map a detected language code to a default voice id. Unknown / low-confidence → undefined. */
+export function pickVoiceForLang(
+  code: string | undefined,
+  confidence: number,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  if (!code || confidence < 0.5) return undefined;
+  switch (code) {
+    case "en":
+      return "en-am_michael";
+    case "ru":
+      return platform === "darwin" ? RU_DARWIN_FALLBACK_VOICE : "ru-vosk-m02";
+    default:
+      return undefined;
+  }
+}