@drakulavich/kesha-voice-kit 1.14.0 → 1.15.1

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Kesha Voice Kit</h1>
 
 <p align="center">
-  <a href="https://github.com/drakulavich/kesha-voice-kit/actions/workflows/ci.yml"><img src="https://github.com/drakulavich/kesha-voice-kit/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://flakiness.io/Laputa/kesha-voice-kit"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fflakiness.io%2Fapi%2Fbadge%3Finput%3D%257B%2522badgeToken%2522%253A%2522badge-2IKMRRqUxh9P3w8Ym3Szf0%2522%257D" alt="Tests"></a>
   <a href="https://www.npmjs.com/package/@drakulavich/kesha-voice-kit"><img src="https://img.shields.io/npm/v/@drakulavich/kesha-voice-kit" alt="npm version"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
   <a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-f9f1e1?logo=bun" alt="Bun"></a>
@@ -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.1",
   "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/cli/main.ts

@@ -34,6 +34,69 @@ export function detectLanguage(text: string): string {
   return detect(text);
 }
 
+/**
+ * Pure validation + normalization of the output-format selection. Pulled
+ * out of the citty `run` handler so the contract is unit-testable without
+ * spawning the CLI binary; the handler just owns the side effects
+ * (log.error + process.exit) when this returns `{ ok: false }`.
+ *
+ * Inputs accept the three knobs the user can flip:
+ * - `--json` (boolean) — long-form alias for `--format json`
+ * - `--toon` (boolean) — long-form alias for `--format toon`
+ * - `--format <value>` — must be one of `transcript`, `json`, `toon`
+ *
+ * Mutex: `--json` and `--toon` cannot both be requested. Either via the
+ * booleans or `--format` cross-pollination (`--json --format toon` →
+ * error). The mutex check happens AFTER format validation, so unknown
+ * `--format` still surfaces with its own clearer error first.
+ */
+export type ResolvedOutputFormat =
+  | {
+      ok: true;
+      wantsJson: boolean;
+      wantsToon: boolean;
+      wantsTranscript: boolean;
+    }
+  | { ok: false; error: string };
+
+const SUPPORTED_FORMATS = ["transcript", "json", "toon"] as const;
+
+export function resolveOutputFormat(input: {
+  json?: boolean;
+  toon?: boolean;
+  format?: string;
+}): ResolvedOutputFormat {
+  if (input.format !== undefined && !SUPPORTED_FORMATS.includes(input.format as never)) {
+    return {
+      ok: false,
+      error: `unknown --format '${input.format}'. supported: ${SUPPORTED_FORMATS.join(", ")}`,
+    };
+  }
+  const wantsJson = !!input.json || input.format === "json";
+  const wantsToon = !!input.toon || input.format === "toon";
+  const wantsTranscript = input.format === "transcript";
+  if (wantsJson && wantsToon) {
+    return {
+      ok: false,
+      error: "--json and --toon are mutually exclusive (pick one output format).",
+    };
+  }
+  // `--format transcript` + boolean `--json` / `--toon` was previously
+  // accepted and silently produced the boolean's format (because the
+  // dispatch checked wantsJson/wantsToon first). Greptile P2 on #300
+  // flagged the silent override. Fail loudly with the same shape as
+  // the json/toon mutex — symmetric across all three formats.
+  if (wantsTranscript && (wantsJson || wantsToon)) {
+    return {
+      ok: false,
+      error:
+        "--format transcript is mutually exclusive with --json / --toon " +
+        "(pick one output format).",
+    };
+  }
+  return { ok: true, wantsJson, wantsToon, wantsTranscript };
+}
+
 export function checkLanguageMismatch(expected: string | undefined, detected: string): string | null {
   if (!expected || !detected || expected === detected) return null;
   return `warning: expected language "${expected}" but detected "${detected}"`;
@@ -76,7 +139,7 @@ export const mainCommand = defineCommand({
     },
     format: {
       type: "string",
-      description: "Output format: transcript (enriched text with lang/confidence)",
+      description: "Output format: transcript | json | toon (long-form alias for --json / --toon)",
     },
     lang: {
       type: "string",
@@ -102,21 +165,32 @@ export const mainCommand = defineCommand({
     if (args.debug) log.debugEnabled = true;
     const files = args._;
 
-    if ((args.json || args.format === "json") && args.toon) {
-      log.error("--json and --toon are mutually exclusive (pick one output format).");
+    // Validate `--format <value>` and normalize into the boolean flags
+    // that the rest of this handler consults. Routing happens in
+    // `resolveOutputFormat` so the contract is unit-testable without
+    // spawning the CLI; the handler just owns the side-effect arms
+    // (log.error + process.exit).
+    const fmt = resolveOutputFormat({
+      json: args.json,
+      toon: args.toon,
+      format: args.format,
+    });
+    if (!fmt.ok) {
+      log.error(fmt.error);
       process.exit(2);
     }
+    const { wantsJson, wantsToon, wantsTranscript } = fmt;
 
     if (args.vad && args["no-vad"]) {
       log.error("--vad and --no-vad are mutually exclusive.");
       process.exit(2);
     }
-    if (args.timestamps && !(args.json || args.toon || args.format === "json")) {
-      log.error("--timestamps requires --json, --toon, or --format json.");
+    if (args.timestamps && !(wantsJson || wantsToon)) {
+      log.error("--timestamps requires --json, --toon, or --format {json,toon}.");
       process.exit(2);
     }
-    if (args.speakers && !(args.json || args.toon || args.format === "json")) {
-      log.error("--speakers requires --json, --toon, or --format json.");
+    if (args.speakers && !(wantsJson || wantsToon)) {
+      log.error("--speakers requires --json, --toon, or --format {json,toon}.");
       process.exit(2);
     }
     const vadMode = args.vad ? "on" : args["no-vad"] ? "off" : "auto";
@@ -129,7 +203,7 @@ export const mainCommand = defineCommand({
     let hasError = false;
     const results: TranscribeResult[] = [];
 
-    const wantsLangId = !!(args.lang || args.verbose || args.json || args.toon || args.format === "transcript" || args.format === "json");
+    const wantsLangId = !!(args.lang || args.verbose || wantsJson || wantsToon || wantsTranscript);
 
     for (const file of files) {
       const startedAt = performance.now();
@@ -185,11 +259,11 @@ export const mainCommand = defineCommand({
       }
     }
 
-    if (args.json || args.format === "json") {
+    if (wantsJson) {
       process.stdout.write(formatJsonOutput(results));
-    } else if (args.toon) {
+    } else if (wantsToon) {
       process.stdout.write(formatToonOutput(results));
-    } else if (args.format === "transcript") {
+    } else if (wantsTranscript) {
       process.stdout.write(formatTranscriptOutput(results));
     } else if (args.verbose) {
       process.stdout.write(formatVerboseOutput(results));

package/src/cli.ts

@@ -7,7 +7,13 @@ export { installCommand } from "./cli/install";
 export { sayCommand } from "./cli/say";
 export { pickVoiceForLang } from "./voice-routing";
 export { statusCommand } from "./cli/status";
-export { mainCommand, detectLanguage, checkLanguageMismatch } from "./cli/main";
+export {
+  mainCommand,
+  detectLanguage,
+  checkLanguageMismatch,
+  resolveOutputFormat,
+} from "./cli/main";
+export type { ResolvedOutputFormat } from "./cli/main";
 export { runCli } from "./cli/dispatch";
 
 export type { TranscribeResult } from "./types";

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}`));
     }
   },
 };