@drakulavich/kesha-voice-kit 1.30.0 → 2.0.0

package/src/cli/stats.ts

@@ -64,7 +64,7 @@ export function runStatsAction(args: StatsCommandArgs): ActionResult {
     case "errors":
       return { ok: true, messages: info(renderErrors(getRecentErrors())) };
     case "export": {
-      const format = parseExportFormat(args.format ?? args.value ?? "json");
+      const format = parseExportFormat(args.format ?? args.value);
       if (!format) return { ok: false, error: "usage: kesha stats export --format json|csv" };
       return { ok: true, messages: [], stdout: exportStats(format) };
     }
@@ -135,12 +135,17 @@ export const statsCommand = defineCommand({
       description: "Export format: json | csv",
     },
   },
-  run({ args }: { args: StatsCommandArgs }) {
-    emitActionResult(runStatsAction(args));
+  run({ args, rawArgs }: { args: StatsCommandArgs; rawArgs: string[] }) {
+    emitActionResult(runStatsAction({ ...args, value: args.value ?? eatenNegativeNumber(rawArgs) }));
   },
 });
 
-function parseExportFormat(value: string): StatsExportFormat | null {
+// citty reads `-5` as a boolean flag named 5, so the value the user typed never reaches the action (Exploratory S5-F3).
+function eatenNegativeNumber(rawArgs: string[]): string | undefined {
+  return rawArgs.find((token) => /^-\d/.test(token));
+}
+
+function parseExportFormat(value: string | undefined): StatsExportFormat | null {
   return value === "json" || value === "csv" ? value : null;
 }
 

package/src/cli/support-bundle.ts

@@ -30,9 +30,9 @@ export const supportBundleCommand = defineCommand({
         output: args.output,
         includeLogs: Boolean(args["include-logs"]),
       });
-      log.success(`Created support bundle: ${bundle.path}`);
-      log.info(`Entries: ${bundle.entries.length}`);
-      log.info(`Size: ${bundle.sizeBytes} bytes`);
+      log.status(`Created support bundle: ${bundle.path}`);
+      log.status(`Entries: ${bundle.entries.length}`);
+      log.status(`Size: ${bundle.sizeBytes} bytes`);
     } catch (err) {
       log.error(errorMessage(err));
       process.exit(1);

package/src/cli.ts

@@ -51,7 +51,7 @@ export {
   formatJsonOutput,
   formatTextOutput,
   formatTranscriptOutput,
-  formatVerboseOutput,
+  formatVerboseDiagnostics,
 } from "./format";
 export { formatToonOutput } from "./toon";
 export {

package/src/diagnostic-log.ts

@@ -1,4 +1,5 @@
 import { errorMessage } from "./error-utils";
+import { resolveStatePaths } from "./state-paths";
 import {
   closeSync,
   existsSync,
@@ -12,7 +13,6 @@ import {
   statSync,
   writeFileSync,
 } from "fs";
-import { homedir } from "os";
 import { dirname, join } from "path";
 import { log } from "./log";
 import { packageVersion } from "./package-info";
@@ -71,14 +71,7 @@ export interface DiagnosticLogSession {
 }
 
 export function resolveDiagnosticLogDir(): string {
-  if (process.env.KESHA_LOG_DIR) return process.env.KESHA_LOG_DIR;
-  if (process.platform === "darwin") return join(homedir(), "Library", "Logs", "kesha");
-  if (process.platform === "win32") {
-    const base = process.env.LOCALAPPDATA || join(homedir(), "AppData", "Local");
-    return join(base, "kesha", "logs");
-  }
-  const base = process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
-  return join(base, "kesha", "logs");
+  return resolveStatePaths().logDir.path;
 }
 
 export function resolveDiagnosticLogPath(): string {

package/src/doctor.ts

@@ -1,5 +1,5 @@
 import { existsSync } from "fs";
-import { cacheComponentPaths, isInsideDir } from "./cache-layout";
+import { cacheComponents, cacheTotalBytes } from "./cache-layout";
 import { errorMessage } from "./error-utils";
 import { humanBytes } from "./format";
 import { dirname, join } from "path";
@@ -12,9 +12,10 @@ import {
 } from "./engine-health";
 import { readInstalledEngineVersion } from "./engine-version-marker";
 import { keshaCacheDir } from "./paths";
+import { installedVoiceIds } from "./voice-inventory";
 import { engineVersion, packageName, packageVersion } from "./package-info";
 import { getStatsStatus, type StatsStatus } from "./stats";
-import { kokoroAneComponents } from "./kokoro-ane";
+import { kokoroAneComponents, kokoroTtsLanguages } from "./kokoro-ane";
 import { isCoremlBackend } from "./fluid-asr-cache";
 import {
   fluidExternalRoots,
@@ -22,6 +23,7 @@ import {
   type FluidExternalRoot,
 } from "./fluid-roots";
 import { diagnosticHomeDir, dirSizeBytes } from "./diagnostic-paths";
+import { collectStatusPaths, type StatusPaths } from "./status";
 import {
   getDiagnosticLogStatus,
   resolveDiagnosticLogDir,
@@ -29,6 +31,7 @@ import {
 } from "./diagnostic-log";
 
 const KNOWN_ENV_KEYS = [
+  "KESHA_HOME",
   "KESHA_ENGINE_BIN",
   "KESHA_CACHE_DIR",
   "KESHA_MODEL_MIRROR",
@@ -64,6 +67,15 @@ interface OptionalComponent extends PathSummary {
   runnable?: boolean;
   /** Staged asset sets only: required entries that are not on disk (#831). */
   missing?: string[];
+  /** Staged asset sets only: Kokoro languages with a voice pack under this path (T2-7). */
+  languagesStaged?: string[];
+}
+
+/** What the synthesis path can actually speak with, which no other section of the report states (T2-7). */
+export interface DoctorTts {
+  voices: string[];
+  languagesStaged: string[];
+  languagesMissing: string[];
 }
 
 type DoctorDiagnosticLogStatus = DiagnosticLogStatus & { error?: string };
@@ -118,9 +130,11 @@ export interface DoctorReport {
     grandTotalBytes: number;
   };
   optionalComponents: OptionalComponent[];
+  tts: DoctorTts;
   stats: StatsStatus | (Partial<StatsStatus> & { error: string });
   diagnosticLogs: DoctorDiagnosticLogStatus;
   env: Record<string, string | null>;
+  paths: StatusPaths;
 }
 
 function pathSummary(path: string): PathSummary {
@@ -231,7 +245,7 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
   return {
     path: redactPath(binPath, redact),
     installed,
-    versionMarker,
+    versionMarker: redactString("versionMarker", versionMarker, redact),
     pinnedVersion: engineVersion,
     versionState: engineVersionState(versionMarker, engineVersion),
     runnable: health.status !== "missing" && health.status !== "unusable",
@@ -256,14 +270,8 @@ function collectCache(
 ): DoctorReport["cache"] {
   const cache = keshaCacheDir();
   const binPath = getEngineBinPath();
-  const engineDir = dirname(dirname(binPath));
-  const components: CacheComponent[] = cacheComponentPaths(
-    cache,
-    engineDir,
-    isCoremlBackend(backend),
-  ).map((component) => ({ label: component.label, ...pathSummary(component.path) }));
-  const engineOutsideCache = isInsideDir(engineDir, cache) ? 0 : dirSizeBytes(engineDir);
-  const totalBytes = dirSizeBytes(cache) + engineOutsideCache;
+  const components: CacheComponent[] = cacheComponents(cache, binPath, isCoremlBackend(backend));
+  const totalBytes = cacheTotalBytes(cache, binPath);
   const externalRoots = fluidExternalRoots({ homeDir, cacheRoot: cache });
   const externalTotalBytes = fluidExternalTotalBytes(externalRoots);
 
@@ -324,6 +332,7 @@ async function collectOptionalComponents(
       exists: c.exists,
       sizeBytes: c.sizeBytes,
       missing: c.missing,
+      languagesStaged: c.languagesStaged,
     })),
     {
       // Diarization (#199) and Kokoro (#207) run in-engine now (native
@@ -339,6 +348,15 @@ async function collectOptionalComponents(
   return components.map((component) => redactComponent(component, redact));
 }
 
+async function collectTts(homeDir?: string): Promise<DoctorTts> {
+  const languages = kokoroTtsLanguages({ homeDir, cacheRoot: keshaCacheDir() });
+  return {
+    voices: await installedVoiceIds(),
+    languagesStaged: languages.staged,
+    languagesMissing: languages.missing,
+  };
+}
+
 function collectStats(redact: boolean): DoctorReport["stats"] {
   try {
     const status = getStatsStatus();
@@ -410,12 +428,33 @@ export async function collectDoctorReport(
     engine,
     cache: collectCache(redact, engine.capabilities?.backend, options.homeDir),
     optionalComponents: await collectOptionalComponents(redact, options.homeDir),
+    tts: await collectTts(options.homeDir),
     stats: collectStats(redact),
     diagnosticLogs: collectDiagnosticLogs(redact),
     env: collectEnv(redact),
+    paths: collectPaths(redact),
   };
 }
 
+function collectPaths(redact: boolean): StatusPaths {
+  const paths = collectStatusPaths();
+  const entry = (p: StatusPaths[keyof StatusPaths]) => ({ ...p, path: redactPath(p.path, redact) });
+  return { cache: entry(paths.cache), logs: entry(paths.logs), stats: entry(paths.stats), mcpAudio: entry(paths.mcpAudio) };
+}
+
+function formatPathsSection(paths: StatusPaths): string[] {
+  const row = (label: string, p: StatusPaths[keyof StatusPaths]) =>
+    `  ${label}: ${p.path}${p.source === "default" ? "" : ` (${p.source})`}`;
+  return [
+    "",
+    "Paths:",
+    row("Cache", paths.cache),
+    row("Logs", paths.logs),
+    row("Stats DB", paths.stats),
+    row("MCP audio", paths.mcpAudio),
+  ];
+}
+
 function formatComponentState(component: OptionalComponent): string {
   if (!component.exists) return "missing";
   if (component.runnable === false) return CORRUPT_STATE;
@@ -487,6 +526,16 @@ function formatOptionalSection(components: DoctorReport["optionalComponents"]):
   return lines;
 }
 
+function formatTtsSection(tts: DoctorTts): string[] {
+  return [
+    "",
+    "TTS:",
+    `  Voices: ${tts.voices.length === 0 ? "none" : tts.voices.join(", ")}`,
+    `  Languages staged: ${tts.languagesStaged.length === 0 ? "none" : tts.languagesStaged.join(", ")}`,
+    `  Languages missing a voice pack: ${tts.languagesMissing.length === 0 ? "none" : tts.languagesMissing.join(", ")}`,
+  ];
+}
+
 function formatStatsSection(stats: DoctorReport["stats"]): string[] {
   const lines = ["", "Stats:"];
   if ("error" in stats) {
@@ -539,8 +588,10 @@ export function formatDoctorReport(report: DoctorReport): string {
     "",
     ...formatCacheSection(report.cache),
     ...formatOptionalSection(report.optionalComponents),
+    ...formatTtsSection(report.tts),
     ...formatStatsSection(report.stats),
     ...formatDiagnosticLogsSection(report.diagnosticLogs),
+    ...formatPathsSection(report.paths),
     ...formatEnvSection(report.env),
   ];
 

package/src/engine/events.ts

@@ -215,6 +215,7 @@ const CLI_EXIT_CODES: Record<string, number> = {
   E_TEXT_EMPTY: 2,
   E_TEXT_TOO_LONG: 5,
   E_INTERNAL: 4,
+  E_INTERRUPTED: 130,
 };
 
 /** Process exit status for a failure: an engine-origin error exits with the subprocess's own status (4 when it left none), a CLI-origin one by its code; anything else is the uncoded 4. */
@@ -224,11 +225,29 @@ export function exitCodeFor(err: unknown): number {
   return err.exitCode ?? CLI_EXIT_CODES[err.code] ?? 1;
 }
 
+const MAX_QUOTED_LINE_CHARS = 200;
+
+/** A library line can carry the user's whole input back, so the quote is bounded and the transcript no longer repeats it (#T1-14). */
+function quoteInvalidLine(line: string): string {
+  const chars = Array.from(line);
+  return chars.length <= MAX_QUOTED_LINE_CHARS ? line : `${chars.slice(0, MAX_QUOTED_LINE_CHARS).join("")}…`;
+}
+
+/** One wording for an off-protocol line, whether it fails the run or only warns. */
+export function offProtocolLine(command: string, line: string): string {
+  return `kesha-engine ${command} wrote a line that is not a protocol event: "${quoteInvalidLine(line)}"`;
+}
+
 /** The KeshaError for a run that wrote a non-event line, reported an error event, or exited non-zero in silence; `stderr` is the transcript unless the caller substitutes one. */
 export function engineFailure(command: string, outcome: StderrOutcome, exitCode: number | undefined, stderr = outcome.stderr.trim()): KeshaError {
   const extra = { exitCode, stderr, origin: "engine" as const };
   if (outcome.invalid.length > 0) {
-    return new KeshaError("E_INTERNAL", `kesha-engine ${command} wrote a line that is not a protocol event: "${outcome.invalid[0]}"`, extra);
+    const rest = stderr.split("\n").filter((line) => !outcome.invalid.includes(line)).join("\n").trim();
+    return new KeshaError(
+      "E_INTERNAL",
+      offProtocolLine(command, outcome.invalid[0]!),
+      { ...extra, stderr: rest },
+    );
   }
   if (outcome.error) return new KeshaError(outcome.error.code, outcome.error.message, { ...extra, hint: outcome.error.hint });
   return new KeshaError("E_INTERNAL", `kesha-engine ${command} exited with code ${exitCode}`, extra);

package/src/engine/spawn.ts

@@ -0,0 +1,114 @@
+import { errorMessage } from "../error-utils";
+import { log } from "../log";
+import { abortOnSignal, engineAbortError, pendingInterruption, registerProcessTree } from "../process-tree";
+import { resolveStatePaths } from "../state-paths";
+import { PROTOCOL_VERSION } from "./describe";
+import { KeshaError, readEvents, type EventSinks, type StderrOutcome } from "./events";
+
+type SpawnStdioEntry = "inherit" | "pipe" | "ignore";
+type SpawnStdio = [SpawnStdioEntry, SpawnStdioEntry, SpawnStdioEntry];
+type EngineProcess = ReturnType<typeof Bun.spawn>;
+
+/** The env for a spawn whose stderr is parsed as protocol 4 events. */
+function protocolEnv(): Record<string, string | undefined> {
+  return { ...process.env, KESHA_PROTOCOL: String(PROTOCOL_VERSION) };
+}
+
+export function spawnHint(): string {
+  return process.env.KESHA_ENGINE_BIN
+    ? "KESHA_ENGINE_BIN points at it; fix the path or unset it and run `kesha install`"
+    : "run `kesha install`";
+}
+
+/** The engine reads only `KESHA_CACHE_DIR`; it gets the root the CLI resolved whenever that differs from the raw value. */
+function withResolvedCacheDir(env: Record<string, string | undefined>): Record<string, string | undefined> {
+  const cache = resolveStatePaths(env).cacheDir;
+  const raw = env.KESHA_CACHE_DIR;
+  if (cache.source === "default") {
+    if (raw === undefined) return env;
+    const { KESHA_CACHE_DIR: _empty, ...rest } = env;
+    return rest;
+  }
+  return raw === cache.path ? env : { ...env, KESHA_CACHE_DIR: cache.path };
+}
+
+/** `Bun.spawn` throws synchronously on ENOENT/EACCES; every launch failure becomes `E_ENGINE_SPAWN`. */
+function spawnEngineProcess(
+  binPath: string,
+  args: string[],
+  stdio: SpawnStdio,
+  env: Record<string, string | undefined> = process.env,
+): EngineProcess {
+  const interrupted = pendingInterruption();
+  if (interrupted) throw interrupted;
+  try {
+    // `env` is passed explicitly: Bun snapshots process.env at startup otherwise (#874).
+    return Bun.spawn([binPath, ...args], { detached: true, stdio, env: withResolvedCacheDir(env) });
+  } catch (err) {
+    throw new KeshaError("E_ENGINE_SPAWN", `failed to launch kesha-engine at ${binPath}: ${errorMessage(err)}`, {
+      hint: spawnHint(),
+    });
+  }
+}
+
+/** An engine that refuses the run before reading closes the pipe; that EPIPE is its answer, reported by the exit status and stderr. */
+async function writeEngineStdin(proc: EngineProcess, text: string): Promise<void> {
+  const sink = proc.stdin as Bun.FileSink;
+  try {
+    sink.write(text);
+    await sink.end();
+  } catch (err) {
+    log.debug(`stdin write failed: ${errorMessage(err)}`);
+  }
+}
+
+export interface EngineProcessOptions<T> {
+  /** `[stdin, stdout, stderr]`. A piped stderr is read as protocol 4 events and the engine is told so through its env. */
+  stdio: SpawnStdio;
+  /** Written to a piped stdin, which is then closed. */
+  stdin?: string;
+  /** Consumes a piped stdout; `proc` lets a relay stop the engine once nobody reads it. */
+  readStdout?: (stream: ReadableStream<Uint8Array>, proc: EngineProcess) => Promise<T>;
+  sinks?: EventSinks;
+  /** Aborting terminates the process tree, SIGKILL after a grace; an already-aborted signal is `E_INTERRUPTED` before any spawn. */
+  signal?: AbortSignal;
+}
+
+export interface EngineProcessRun<T> {
+  exitCode: number;
+  signalCode: string | null;
+  /** The signal fired while the engine ran: a caller's cancel, or a deadline it set with `AbortSignal.timeout`. */
+  aborted: boolean;
+  stdout: T;
+  events: StderrOutcome;
+}
+
+/** Spawns the engine (or a sidecar) as its own process tree and waits for it; the tree is unregistered however the run ends. */
+export async function runEngineProcess<T = undefined>(
+  binPath: string,
+  args: string[],
+  opts: EngineProcessOptions<T>,
+): Promise<EngineProcessRun<T>> {
+  if (opts.signal?.aborted) throw engineAbortError();
+  const startedAt = performance.now();
+  log.debug(`spawn ${binPath} ${args.join(" ")}`);
+  const eventsOnStderr = opts.stdio[2] === "pipe";
+  const proc = spawnEngineProcess(binPath, args, opts.stdio, eventsOnStderr ? protocolEnv() : process.env);
+  const tree = registerProcessTree(proc);
+  const cancel = abortOnSignal(tree, opts.signal);
+  try {
+    const [stdout, events, exitCode] = await Promise.all([
+      opts.readStdout?.(proc.stdout as ReadableStream<Uint8Array>, proc),
+      eventsOnStderr
+        ? readEvents(proc.stderr as ReadableStream<Uint8Array>, opts.sinks)
+        : { stderr: "", error: null, invalid: [] },
+      proc.exited,
+      opts.stdin === undefined ? undefined : writeEngineStdin(proc, opts.stdin),
+    ]);
+    log.debug(`exit=${exitCode} dt=${Math.round(performance.now() - startedAt)}ms args=${JSON.stringify(args)}`);
+    return { exitCode, signalCode: proc.signalCode, aborted: cancel.aborted, stdout: stdout as T, events };
+  } finally {
+    cancel.dispose();
+    tree.dispose();
+  }
+}

package/src/engine-health.ts

@@ -1,22 +1,14 @@
 import { existsSync } from "fs";
-import { errorMessage } from "./error-utils";
-import {
-  getDescribe,
-  getEngineBinPath,
-  spawnEngineProcess,
-  type EngineCapabilities,
-} from "./engine";
+import { ENGINE_PROBE_TIMEOUT_MS, getDescribe, getEngineBinPath, type EngineCapabilities } from "./engine";
 import { describeToCapabilities } from "./engine/describe";
 import { KeshaError } from "./engine/events";
-import { registerProcessTree } from "./process-tree";
+import { runEngineProcess } from "./engine/spawn";
 
 export type ExecutableHealth =
   | { status: "ok" }
   | { status: "missing" }
   | { status: "unusable"; detail: string };
 
-const PROBE_TIMEOUT_MS = 15_000;
-
 /**
  * Proves a downloaded binary actually executes — existence is not health (#770).
  *
@@ -28,39 +20,32 @@ const PROBE_TIMEOUT_MS = 15_000;
  * The timeout guards against a binary that starts but never exits; macOS Gatekeeper can take
  * several seconds to scan a freshly written binary on its first run, so it is generous.
  */
+/** Message plus hint, not the rendered error: a caller wrapping it would otherwise nest a second code line. */
+function spawnFailureDetail(err: unknown): string {
+  if (!(err instanceof Error)) return String(err);
+  return err instanceof KeshaError && err.hint ? `${err.message}; ${err.hint}` : err.message;
+}
+
 export async function probeExecutable(
   binPath: string,
   args: string[] = [],
 ): Promise<ExecutableHealth> {
   if (!existsSync(binPath)) return { status: "missing" };
 
-  let proc: ReturnType<typeof Bun.spawn>;
+  let run: Awaited<ReturnType<typeof runEngineProcess>>;
   try {
-    proc = spawnEngineProcess(binPath, args, ["ignore", "ignore", "ignore"]);
+    run = await runEngineProcess(binPath, args, {
+      stdio: ["ignore", "ignore", "ignore"],
+      signal: AbortSignal.timeout(ENGINE_PROBE_TIMEOUT_MS),
+    });
   } catch (err) {
-    return { status: "unusable", detail: errorMessage(err) };
-  }
-  const tree = registerProcessTree(proc);
-
-  let timedOut = false;
-  let forceKillTimer: Timer | undefined;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    tree.terminate();
-    forceKillTimer = tree.forceKillAfterGrace();
-  }, PROBE_TIMEOUT_MS);
-  try {
-    await proc.exited;
-  } finally {
-    clearTimeout(timer);
-    tree.dispose();
-    if (!timedOut && forceKillTimer) clearTimeout(forceKillTimer);
+    return { status: "unusable", detail: spawnFailureDetail(err) };
   }
 
-  if (timedOut) {
-    return { status: "unusable", detail: `no exit within ${PROBE_TIMEOUT_MS / 1000}s` };
+  if (run.aborted) {
+    return { status: "unusable", detail: `no exit within ${ENGINE_PROBE_TIMEOUT_MS / 1000}s` };
   }
-  if (proc.signalCode) return { status: "unusable", detail: `killed by ${proc.signalCode}` };
+  if (run.signalCode) return { status: "unusable", detail: `killed by ${run.signalCode}` };
   return { status: "ok" };
 }
 
@@ -73,36 +58,20 @@ export async function probeExecutable(
  */
 export async function readExecutableVersion(
   binPath: string,
-  timeoutMs = PROBE_TIMEOUT_MS,
+  timeoutMs = ENGINE_PROBE_TIMEOUT_MS,
 ): Promise<string | null> {
   if (!existsSync(binPath)) return null;
 
-  let proc: ReturnType<typeof Bun.spawn>;
+  let stdout: string;
   try {
-    proc = spawnEngineProcess(binPath, ["--version"], ["ignore", "pipe", "ignore"]);
+    ({ stdout } = await runEngineProcess(binPath, ["--version"], {
+      stdio: ["ignore", "pipe", "ignore"],
+      readStdout: (stream) => new Response(stream).text(),
+      signal: AbortSignal.timeout(timeoutMs),
+    }));
   } catch {
     return null;
   }
-  const tree = registerProcessTree(proc);
-
-  let timedOut = false;
-  let forceKillTimer: Timer | undefined;
-  const timer = setTimeout(() => {
-    timedOut = true;
-    tree.terminate();
-    forceKillTimer = tree.forceKillAfterGrace();
-  }, timeoutMs);
-  let stdout: string;
-  try {
-    [stdout] = await Promise.all([
-      new Response(proc.stdout as ReadableStream<Uint8Array>).text(),
-      proc.exited,
-    ]);
-  } finally {
-    clearTimeout(timer);
-    tree.dispose();
-    if (!timedOut && forceKillTimer) clearTimeout(forceKillTimer);
-  }
   return /(\d+\.\d+\.\d+[0-9A-Za-z.+-]*)/.exec(stdout)?.[1] ?? null;
 }
 
@@ -132,7 +101,7 @@ const MUTE_DETAIL = "reports no capabilities";
  * that could not be made to answer (`unusable`), not one that answered nothing (`mute`).
  */
 export async function engineFunctionalHealth(
-  timeoutMs = PROBE_TIMEOUT_MS,
+  timeoutMs = ENGINE_PROBE_TIMEOUT_MS,
 ): Promise<EngineFunctionalHealth> {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);