@drakulavich/kesha-voice-kit 1.14.0 → 1.15.0

package/README.md

@@ -22,9 +22,22 @@
 
 Runtime: **[Bun](https://bun.sh)** >= 1.3.0.
 
+Install Bun (skip if already installed) — pick one:
+
 ```bash
-curl -fsSL https://bun.sh/install | bash   # skip if Bun is already installed
+# Linux & macOS
+curl -fsSL https://bun.sh/install | bash       # upstream installer
+brew install oven-sh/bun/bun                   # Homebrew
+```
+
+```powershell
+# Windows
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+
+Then install Kesha:
 
+```bash
 bun add -g @drakulavich/kesha-voice-kit
 kesha install       # downloads engine + models
 kesha audio.ogg     # transcript to stdout
@@ -32,45 +45,16 @@ kesha audio.ogg     # transcript to stdout
 
 Air-gapped or behind a corporate mirror? See [docs/model-mirror.md](docs/model-mirror.md).
 
-## Nix Install (Recommended)
+## Nix Install
 
-**Prerequisites:** [Nix](https://nixos.org/download/) with flakes enabled. Supported systems: `aarch64-darwin`, `x86_64-linux`.
+Alternative reproducible-build path on `aarch64-darwin` / `x86_64-linux`:
 
-### One-liner run (no install)
 ```bash
 nix run github:drakulavich/kesha-voice-kit -- install      # downloads models (engine is bundled)
 nix run github:drakulavich/kesha-voice-kit -- audio.ogg    # transcribe
 ```
 
-`nix run` resolves to `apps.default` (the `kesha` Bun CLI), which has the engine binary baked in via `KESHA_ENGINE_BIN`, so there's no separate engine download.
-
-### Install to profile (persistent)
-```bash
-nix profile install github:drakulavich/kesha-voice-kit
-kesha install       # downloads models
-kesha audio.ogg     # transcript to stdout
-```
-
-`packages.default` ships the Bun CLI (`kesha`, `parakeet`) wired to the Nix-built engine. After `nix profile install`, both shims are on `PATH` and run transcription, language detection, and TTS (including `macos-*` AVSpeech voices on darwin-arm64) identically to the npm install. Speaker diarization (`kesha install --diarize` / `--speakers`) is not yet wired into the Nix build — the `kesha-diarize` Swift sidecar needs network-fetched FluidAudio at build time, which the Nix sandbox forbids; use the Bun install path (`bun add -g @drakulavich/kesha-voice-kit`) on darwin-arm64 if you need that feature (tracked alongside [#199](https://github.com/drakulavich/kesha-voice-kit/issues/199)).
-
-### Engine only (no Bun, no Node)
-For users who just want the Rust binary:
-```bash
-nix build github:drakulavich/kesha-voice-kit#kesha-engine
-./result/bin/kesha-engine --help
-./result/bin/kesha-engine --capabilities-json   # see which backends compiled in
-```
-
-### Development shell
-```bash
-nix develop github:drakulavich/kesha-voice-kit
-# Now you have: pinned rustc/cargo (via rust-overlay), bun, protoc, cmake, pkg-config, libclang
-```
-
-**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.14.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.14.0"
+    "version": "1.15.0"
   },
   "scripts": {
     "test": "bun test",

package/src/engine-install.ts

@@ -76,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
@@ -119,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(
@@ -187,6 +267,18 @@ export async function downloadEngine(
     } 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
@@ -204,6 +296,14 @@ export async function downloadEngine(
         (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.
@@ -252,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);
@@ -282,7 +383,7 @@ export async function downloadEngine(
       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 README's Nix Install section).\n" +
+          "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.",
       );

package/src/log.ts

@@ -19,6 +19,13 @@ function envDebug(): boolean {
   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)),
@@ -29,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}`));
     }
   },
 };