@drakulavich/kesha-voice-kit 1.15.1 → 1.17.0

package/README.md

@@ -18,6 +18,10 @@
 - **Rust engine** — single 20MB binary, no ffmpeg, no Python, no native Node addons
 - **OpenClaw-ready** — plug into your LLM agent as a voice processing skill
 
+<p align="center">
+  <img src="./demo.gif" alt="kesha demo — English + Russian transcription with automatic language detection" width="800">
+</p>
+
 ## Quick Start
 
 Runtime: **[Bun](https://bun.sh)** >= 1.3.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.15.1",
+  "version": "1.17.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.15.0"
+    "version": "1.17.0"
   },
   "scripts": {
     "test": "bun test",
@@ -38,6 +38,8 @@
     "test:integration": "bun test tests/integration/",
     "lint": "bunx tsc --noEmit",
     "lint:tsgo": "bunx tsgo --noEmit",
+    "check:workflows": "bun .github/scripts/check-workflows.ts",
+    "check:versions": "bun .github/scripts/check-versions.ts",
     "postinstall": "node scripts/postinstall.cjs"
   },
   "keywords": [
@@ -69,7 +71,8 @@
     "@types/bun": "latest",
     "@typescript/native-preview": "^7.0.0-dev.20260423.1",
     "fast-xml-parser": "^5.5.10",
-    "typescript": "^6.0.2"
+    "typescript": "^6.0.2",
+    "yaml": "^2.9.0"
   },
   "dependencies": {
     "@toon-format/toon": "^2.1.0",

package/src/cli/dispatch.ts

@@ -1,4 +1,5 @@
 import { runMain } from "citty";
+import { existsSync } from "fs";
 import { log } from "../log";
 import { suggestCommand } from "../suggest-command";
 import { installCommand } from "./install";
@@ -8,6 +9,10 @@ import { mainCommand } from "./main";
 
 const SUBCOMMANDS = ["install", "status", "say"];
 
+function isPathLike(arg: string): boolean {
+  return arg.includes(".") || arg.includes("/") || existsSync(arg);
+}
+
 export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
   const [firstArg, ...restArgs] = rawArgs;
 
@@ -26,14 +31,17 @@ export async function runCli(rawArgs = process.argv.slice(2)): Promise<void> {
     return;
   }
 
-  // Check for unknown subcommands (non-flag, non-file-path args)
-  if (firstArg && !firstArg.startsWith("-") && !firstArg.includes(".") && !firstArg.includes("/")) {
+  // Check for unknown subcommands (non-flag, non-file-path args).
+  // Extensionless existing files remain valid transcription inputs; missing
+  // bare tokens are more likely command typos and should not start the engine.
+  if (firstArg && !firstArg.startsWith("-") && !isPathLike(firstArg)) {
     const suggestion = suggestCommand(firstArg, SUBCOMMANDS);
+    log.error(`unknown command '${firstArg}'`);
     if (suggestion && suggestion !== firstArg) {
-      log.error(`unknown command '${firstArg}'`);
       log.warn(`(Did you mean ${suggestion}?)`);
-      process.exit(1);
     }
+    log.warn(`If this is an audio file, pass a path like './${firstArg}'.`);
+    process.exit(1);
   }
 
   await runMain(mainCommand, { rawArgs });

package/src/cli/main.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { existsSync } from "fs";
 import { detect } from "tinyld";
 import { transcribeWithSegments } from "../transcribe";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
@@ -206,6 +207,12 @@ export const mainCommand = defineCommand({
     const wantsLangId = !!(args.lang || args.verbose || wantsJson || wantsToon || wantsTranscript);
 
     for (const file of files) {
+      if (!existsSync(file)) {
+        hasError = true;
+        log.error(`${file}: File not found`);
+        continue;
+      }
+
       const startedAt = performance.now();
       try {
         // Run audio lang-id and transcription concurrently.

package/src/engine-install.ts

@@ -74,6 +74,20 @@ const SIDECARS: SidecarSpec[] = [
     availableHint: "--speakers available",
     unavailableHint: "--speakers unavailable",
   },
+  {
+    // Runtime resolver looks for plain `kesha-textlang` next to the engine
+    // (see `rust/src/text_lang.rs::helper_path`), not the platform-suffixed
+    // release-asset name. Mismatch is intentional: the asset name needs the
+    // suffix for GitHub-release uniqueness; the sidecar lookup wants the
+    // unsuffixed binary so the same Rust code path works on the build-time
+    // OUT_DIR baked fallback.
+    fileBasename: "kesha-textlang",
+    assetName: "kesha-textlang-darwin-arm64",
+    displayName: "Text-lang sidecar",
+    availableHint: "detect-text-lang fast path",
+    unavailableHint:
+      "detect-text-lang will fail until next `kesha install` (no swift -e fallback)",
+  },
 ];
 
 /**

package/src/engine.ts

@@ -50,18 +50,70 @@ export function isEngineInstalled(): boolean {
   return existsSync(getEngineBinPath());
 }
 
+/** A Bun.spawn `stdio` array entry: per-fd action or inherit-by-number. */
+type SpawnStdioEntry = "inherit" | "pipe" | "ignore" | number;
+
+/**
+ * Upper bound on the fd number we'll forward (#323 Greptile P2).
+ *
+ * The `stdio` array is index-addressed, so `KESHA_DEBUG_FD=1000000` would
+ * allocate a million-entry array of `"ignore"` strings before the spawn.
+ * 1024 is the conservative POSIX `RLIMIT_NOFILE` default — anything
+ * above it can't be open in the parent anyway, so capping is a no-op
+ * for legitimate users and a DoS guard for bogus input.
+ */
+const MAX_FORWARDED_FD = 1024;
+
+/**
+ * Build a `stdio` array for `Bun.spawn`, forwarding `KESHA_DEBUG_FD` (#321 F19).
+ *
+ * The engine's NDJSON debug sink looks for `KESHA_DEBUG_FD=N` and writes
+ * structured events to fd `N`. Bun.spawn closes all non-stdio fds in the
+ * child by default, so a bare `KESHA_DEBUG_FD=3 kesha ...` would propagate
+ * the env var but the kernel-level fd 3 wouldn't reach the engine — the
+ * sink would silently no-op.
+ *
+ * This helper forwards the parent's fd N to the same number in the child
+ * by extending the stdio array with `"ignore"` padding up to index N and
+ * setting `stdio[N] = N` (Bun's "inherit parent fd identity" form).
+ *
+ * Returns `base` unchanged when:
+ *   - `KESHA_DEBUG_FD` is unset / empty.
+ *   - The value isn't a non-negative integer.
+ *   - The value is 0/1/2 (covered by base stdin/stdout/stderr entries).
+ *
+ * Exported so `synth.ts` (the `kesha say` spawn site) can share the
+ * forwarding logic without duplicating the env-parse code.
+ */
+export function spawnStdioWithDebugFd(
+  base: [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry],
+): [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry, ...SpawnStdioEntry[]] {
+  const envFd = process.env.KESHA_DEBUG_FD;
+  if (!envFd) return base;
+  const fd = Number(envFd);
+  if (!Number.isInteger(fd) || fd < 3 || fd > MAX_FORWARDED_FD) return base;
+  const out: SpawnStdioEntry[] = [...base];
+  while (out.length < fd) out.push("ignore");
+  out[fd] = fd;
+  return out as [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry, ...SpawnStdioEntry[]];
+}
+
 async function runEngine(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> {
   const binPath = getEngineBinPath();
   const startedAt = performance.now();
   log.debug(`spawn ${binPath} ${args.join(" ")}`);
   const proc = Bun.spawn([binPath, ...args], {
-    stdout: "pipe",
-    stderr: "pipe",
+    stdio: spawnStdioWithDebugFd(["ignore", "pipe", "pipe"]),
   });
+  // `stdio: [...]` widens stdout/stderr into a union; indices 1/2 are
+  // pinned to "pipe" by the helper, so the narrow ReadableStream type
+  // is correct. Cast to drop the spurious `number` arm.
+  const stdoutStream = proc.stdout as ReadableStream<Uint8Array>;
+  const stderrStream = proc.stderr as ReadableStream<Uint8Array>;
 
   const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
+    new Response(stdoutStream).text(),
+    new Response(stderrStream).text(),
     proc.exited,
   ]);
 

package/src/star.ts

@@ -57,14 +57,13 @@ export function hasStarMarker(binPath: string): boolean {
 }
 
 /**
- * Prompt the user to star the repo if and only if `shouldShowStarPrompt`
- * agrees (first install + major-or-minor bumps, never on patch). Records
+ * Prompt the user to star the repo during `kesha install` if and only if
+ * `shouldShowStarPrompt` agrees (first install + major-or-minor bumps,
+ * never on patch). Records
  * the prompt against the current version up front so a single run never
  * prompts twice — failures from the gh subprocess below don't reopen the
- * gate. Shared by `kesha install` and `kesha status` so opt-in installs
- * (`--tts`, `--diarize`) and `status` reuse the same marker; a user who
- * saw the prompt on the base install won't see it again on the opt-in or
- * the status check.
+ * gate. Install variants (`--tts`, `--diarize`) reuse the same marker; status
+ * stays diagnostic-only and does not consume this slot.
  *
  * No-ops when the gate says skip, when `currentVersion` is null, or when
  * the user has already starred. When `gh` is missing or unauthenticated,

package/src/status.ts

@@ -3,11 +3,8 @@ import { homedir } from "os";
 import { join } from "path";
 import { isEngineInstalled, getEngineBinPath, getEngineCapabilities } from "./engine";
 import { log } from "./log";
-import { maybeAskForStar } from "./star";
 import pc from "picocolors";
 
-const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
-
 function humanBytes(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   const units = ["KB", "MB", "GB"];
@@ -55,7 +52,12 @@ export async function showStatus(): Promise<void> {
   log.info(formatStatusLine("Binary", installed ? binPath : null, installed));
 
   if (installed) {
-    const caps = await getEngineCapabilities();
+    let caps: Awaited<ReturnType<typeof getEngineCapabilities>> = null;
+    try {
+      caps = await getEngineCapabilities();
+    } catch {
+      caps = null;
+    }
     if (caps) {
       log.info(formatStatusLine("Backend", caps.backend, true));
       log.info(formatStatusLine("Protocol", `v${caps.protocolVersion}`, true));
@@ -91,14 +93,6 @@ export async function showStatus(): Promise<void> {
     log.warn('Run "kesha install" to download the engine and models.');
     return;
   }
-
-  // Star prompt at the very end. Same gate + marker as `kesha install`, so a
-  // user prompted by either path won't be re-prompted by the other within the
-  // same major.minor. Headless `kesha install` (no `gh`, or no tty) leaves no
-  // marker only when the prompt path itself errored out — readStarSeen still
-  // sees the marker in the common case.
-  const currentVersion = typeof pkg.version === "string" ? pkg.version : null;
-  await maybeAskForStar(binPath, currentVersion, log);
 }
 
 function showDiskUsage(binPath: string): void {

package/src/synth.ts

@@ -1,4 +1,10 @@
-import { getEngineBinPath, isEngineInstalled, getEngineCapabilities, type EngineCapabilities } from "./engine";
+import {
+  getEngineBinPath,
+  isEngineInstalled,
+  getEngineCapabilities,
+  spawnStdioWithDebugFd,
+  type EngineCapabilities,
+} from "./engine";
 import { log } from "./log";
 
 /**
@@ -109,21 +115,27 @@ export async function say(opts: SayOptions): Promise<Uint8Array> {
   const startedAt = performance.now();
   log.debug(`spawn ${getEngineBinPath()} ${args.join(" ")} (text: ${opts.text?.length ?? 0} chars)`);
   const proc = Bun.spawn([getEngineBinPath(), ...args], {
-    stdin: "pipe",
-    stdout: "pipe",
-    stderr: "pipe",
+    stdio: spawnStdioWithDebugFd(["pipe", "pipe", "pipe"]),
   });
+  // The `stdio: [...]` form widens stdin/stdout/stderr into a union
+  // (Bun.spawn can't infer that indices 0/1/2 are always "pipe" given
+  // the helper's return type). All three are guaranteed `FileSink` /
+  // `ReadableStream` here because the helper preserves index 0/1/2
+  // from the base tuple. Narrow back via cast.
+  const stdin = proc.stdin as Bun.FileSink;
+  const stdout = proc.stdout as ReadableStream<Uint8Array>;
+  const stderr = proc.stderr as ReadableStream<Uint8Array>;
 
   if (opts.text !== undefined && opts.text.length > 0) {
-    proc.stdin.write(opts.text);
-    await proc.stdin.end();
+    stdin.write(opts.text);
+    await stdin.end();
   } else {
-    await proc.stdin.end();
+    await stdin.end();
   }
 
   const [stdoutBuf, stderrText, exitCode] = await Promise.all([
-    new Response(proc.stdout).arrayBuffer(),
-    new Response(proc.stderr).text(),
+    new Response(stdout).arrayBuffer(),
+    new Response(stderr).text(),
     proc.exited,
   ]);
 

package/src/transcribe.ts

@@ -33,9 +33,10 @@ export async function transcribeWithSegments(
     throw new Error(
       "Error: No transcription backend is installed\n\n" +
       "╔══════════════════════════════════════════════════════════╗\n" +
-      "║ Please run the following command to get started:         ║\n" +
+      "║ Please run the following commands to get started:        ║\n" +
       "║                                                          ║\n" +
-      "║     bunx @drakulavich/kesha-voice-kit install               ║\n" +
+      "║     bun add -g @drakulavich/kesha-voice-kit              ║\n" +
+      "║     kesha install                                        ║\n" +
       "╚══════════════════════════════════════════════════════════╝",
     );
   }