@drakulavich/kesha-voice-kit 1.29.1 → 1.30.0

package/NOTICES.md

@@ -19,7 +19,7 @@ see [speechbrain/lang-id-voxlingua107-ecapa](https://huggingface.co/speechbrain/
 ### Silero VAD v5 (opt-in: `kesha install --vad`)
 
 Voice activity detection. MIT. Authored by [Silero Team](https://github.com/snakers4/silero-vad).
-Pinned to the `v6.2.1` tag.
+Pinned to a commit (the `v6.2.1` tag's target at the time of pinning).
 
 ## Models downloaded by `kesha install --tts`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/kesha-voice-kit",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "description": "Give your tools a voice — speech to text and back, 25 languages, up to ~19× faster than Whisper. On your machine.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     }
   },
   "keshaEngine": {
-    "version": "1.24.11"
+    "version": "1.25.0"
   },
   "scripts": {
     "test": "bun test --timeout 30000",
@@ -109,6 +109,7 @@
   "overrides": {
     "hono": "^4.12.25",
     "fast-uri": "^3.1.5",
-    "ip-address": "^10.3.1"
+    "ip-address": "^10.3.1",
+    "smol-toml": "1.7.2"
   }
 }

package/src/cli/command-session.ts

@@ -4,6 +4,7 @@ import type {
   DiagnosticLogSession,
   DiagnosticSessionStatus,
 } from "../diagnostic-log";
+import { setEngineDebugSink } from "../engine/events";
 import { errorMessage } from "../error-utils";
 import { log } from "../log";
 import { createStatsRecorder } from "../stats";
@@ -46,12 +47,22 @@ export async function runCommandSession(
   };
   session.diagnosticLog.event("command.start", { command, ...startFields });
 
+  setEngineDebugSink((event) =>
+    session.diagnosticLog.event("engine.debug", {
+      t_ms: event.t_ms,
+      event: event.event ?? null,
+      message: event.message,
+      fields: event.fields === undefined ? null : JSON.stringify(event.fields),
+    }),
+  );
   let outcome: CommandOutcome;
   try {
     outcome = await body(session);
   } catch (err) {
     closeSessionQuietly(session, command, { status: "failed", itemCount: 0 });
     throw err;
+  } finally {
+    setEngineDebugSink(null);
   }
 
   // A flush error must not displace a failure the command already has to report (Greptile P1/P2 on #607).

package/src/cli/init.ts

@@ -2,13 +2,15 @@ import { defineCommand } from "citty";
 import { confirm, multiselect, isCancel, cancel } from "@clack/prompts";
 import { installCommandTokens, renderInstallPlan } from "../install-plan";
 import { log } from "../log";
+import { errorMessage } from "../error-utils";
+import { exitCodeFor } from "../engine/events";
 import { getEngineCapabilities } from "../engine";
 import {
   installableTtsLangs,
   performInstall,
   resolveBackendFlag,
   resolveNoCacheFlag,
-  unavailableBackendError,
+  unavailableBackendRefusal,
 } from "./install";
 import type { SharedInstallArgs } from "./types";
 
@@ -176,10 +178,10 @@ export async function promptInitSelection(
 
 /** Mirrors the guard in `performInstall`: a preview must not describe an install this platform rejects (#684). */
 async function printPlan(selection: InitSelection): Promise<boolean> {
-  const backendError = unavailableBackendError(selection.backend);
+  const backendError = unavailableBackendRefusal(selection.backend);
   if (backendError) {
-    log.error(backendError);
-    process.exitCode = 2;
+    log.error(errorMessage(backendError));
+    process.exitCode = exitCodeFor(backendError);
     return false;
   }
   log.info(

package/src/cli/install.ts

@@ -1,8 +1,9 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
-import { installEngine } from "../engine-install";
+import { assertPlatformCanInstall, installEngine } from "../engine-install";
 import { engineTarget, isDarwinArm64 } from "../engine-targets";
 import { getEngineBinPath, getEngineCapabilities, type EngineCapabilities } from "../engine";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import { renderInstallPlan } from "../install-plan";
 import { maybeAskForStar } from "../star";
 import { log } from "../log";
@@ -171,6 +172,12 @@ function finishInstallDiagnostic(
   }
 }
 
+/** The refusal `install`, `install --plan` and `init --plan` all render the same way (#684). */
+export function unavailableBackendRefusal(backend: string | undefined): KeshaError | null {
+  const message = unavailableBackendError(backend);
+  return message ? new KeshaError("E_INVALID_ARG", message) : null;
+}
+
 /** Null when the requested backend is installable here. `KESHA_ENGINE_BIN` opts out — the user supplied their own engine. */
 export function unavailableBackendError(backend: string | undefined): string | null {
   const platformBackend = defaultBackendForPlatform();
@@ -197,11 +204,11 @@ export async function performInstall(options: PerformInstallOptions) {
   const { noCache, backend, ttsLangs, vad = false, diarize = false, plan = false, engineVersion } =
     options;
   // A plan for an unavailable backend previews what its own printed command rejects (#684).
-  const backendError = unavailableBackendError(backend);
+  const backendError = unavailableBackendRefusal(backend);
   if (plan) {
     if (backendError) {
-      log.error(backendError);
-      process.exitCode = 2;
+      log.error(errorMessage(backendError));
+      process.exitCode = exitCodeFor(backendError);
       return;
     }
     log.info(
@@ -225,16 +232,15 @@ export async function performInstall(options: PerformInstallOptions) {
       engineVersionOverride: engineVersion !== undefined,
     });
 
-    if (diarize && !(process.platform === "darwin" && process.arch === "arm64")) {
+    try {
+      assertPlatformCanInstall({ diarize });
+    } catch (err) {
       errorKind = "validation_failed";
-      throw new Error(
-        "--diarize is currently darwin-arm64 only " +
-        "(see https://github.com/drakulavich/kesha-voice-kit/issues/199).",
-      );
+      throw err;
     }
     if (backendError) {
       errorKind = "validation_failed";
-      throw new Error(backendError);
+      throw backendError;
     }
     await installEngine({ noCache, backend, ttsLangs, vad, diarize, version: engineVersion });
     await maybeAskForStar(getEngineBinPath(), packageVersion, log);
@@ -248,7 +254,7 @@ export async function performInstall(options: PerformInstallOptions) {
     const message = errorMessage(err);
     finishInstallDiagnostic(diagnosticLog, startedAt, "failed", errorKind);
     log.error(message);
-    process.exit(1);
+    process.exit(err instanceof KeshaError ? exitCodeFor(err) : 1);
   }
 }
 

package/src/cli/main.ts

@@ -2,7 +2,7 @@ import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
 import { existsSync, statSync } from "fs";
 import { detectAll } from "tinyld";
-import { preflightTranscribeWithSegments, transcribeWithSegments } from "../transcribe";
+import { transcribeWithSegments, validateTranscribeRequest } from "../transcribe";
 import { detectAudioLanguageEngine, detectTextLanguageEngine } from "../engine";
 import type { LangDetectResult } from "../engine";
 import { log } from "../log";
@@ -23,7 +23,7 @@ import { diagnosticSizeBucket } from "../diagnostic-events";
 import { runCommandSession, type CommandSession } from "./command-session";
 import { USAGE_MESSAGE } from "./dispatch";
 import type { CliContext } from "./context";
-import { ENGINE_CODES, extractEngineErrorCode, TS_NATIVE_CODES } from "../error-codes";
+import { KeshaError } from "../engine/events";
 
 interface MainCommandArgs {
   _: string[];
@@ -301,26 +301,25 @@ async function processFile(
   const { stats, diagnosticLog } = recorders;
 
   if (!existsSync(file)) {
-    stats.recordError("input", new Error("File not found"), TS_NATIVE_CODES.INPUT_NOT_FOUND);
+    const err = new KeshaError("E_INPUT_NOT_FOUND", "File not found");
+    stats.recordError("input", err, err.code);
     diagnosticLog.event("input.missing", {
       command: "transcribe",
-      error_code: TS_NATIVE_CODES.INPUT_NOT_FOUND,
+      error_code: err.code,
     });
-    log.error(`${file}: error [${TS_NATIVE_CODES.INPUT_NOT_FOUND}]: File not found`);
-    return { ok: false, error: { file, code: TS_NATIVE_CODES.INPUT_NOT_FOUND, message: "File not found" } };
+    log.error(`${file}: ${errorMessage(err)}`);
+    return { ok: false, error: { file, code: err.code, message: err.message } };
   }
 
   if (isDirectoryPath(file)) {
-    stats.recordError("input", new Error("is a directory"), TS_NATIVE_CODES.INVALID_ARG);
+    const err = new KeshaError("E_INVALID_ARG", "is a directory (expected an audio file)");
+    stats.recordError("input", err, err.code);
     diagnosticLog.event("input.invalid", {
       command: "transcribe",
-      error_code: TS_NATIVE_CODES.INVALID_ARG,
+      error_code: err.code,
     });
-    log.error(`${file}: error [${TS_NATIVE_CODES.INVALID_ARG}]: is a directory (expected an audio file)`);
-    return {
-      ok: false,
-      error: { file, code: TS_NATIVE_CODES.INVALID_ARG, message: "is a directory (expected an audio file)" },
-    };
+    log.error(`${file}: ${errorMessage(err)}`);
+    return { ok: false, error: { file, code: err.code, message: err.message } };
   }
 
   const inputArtifact = artifactFromFile(file, "input_audio");
@@ -343,7 +342,7 @@ async function processFile(
     else write();
   };
   try {
-    await preflightTranscribeWithSegments({ vad: vadMode, timestamps, speakers, itn });
+    await validateTranscribeRequest({ vad: vadMode, timestamps, speakers, itn });
     progress = reportProgress
       ? createPercentProgress(`Transcribing ${file}`, {
           estimatedTotalMs: speakers ? 60 * 60 * 1000 : 30 * 60 * 1000,
@@ -394,8 +393,8 @@ async function processFile(
     return { ok: true, result };
   } catch (err: unknown) {
     progress?.stop();
+    const code = err instanceof KeshaError ? err.code : "E_TRANSCRIBE_FAILED";
     const stderrText = errorMessage(err);
-    const code = extractEngineErrorCode(stderrText) ?? ENGINE_CODES.TRANSCRIBE_FAILED;
     stats.recordError("transcribe", err, code);
     diagnosticLog.event("engine.exit", {
       command: "transcribe",

package/src/cli/record.ts

@@ -1,14 +1,16 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import {
   isEngineInstalled,
-  preflightRecordLive,
   recordEngine,
+  validateRecordRequest,
   type LiveAutoStopOptions,
   type RecordTarget,
 } from "../engine";
 import { installHint } from "../install-hint";
 import { log } from "../log";
+import { getPendingSignalExitCode, waitForPendingSignalCleanup } from "../process-tree";
 
 export interface RecordArgs {
   out?: string;
@@ -203,11 +205,16 @@ export const recordCommand = defineCommand({
       process.exit(1);
     }
     try {
-      if (resolved.target.live) await preflightRecordLive(resolved.target.autoStop !== undefined);
+      await validateRecordRequest(resolved.target, resolved.maxSeconds);
       await recordEngine(resolved.target, resolved.maxSeconds);
     } catch (err) {
+      const signalExitCode = getPendingSignalExitCode();
+      if (signalExitCode !== null) {
+        await waitForPendingSignalCleanup();
+        process.exit(signalExitCode);
+      }
       log.error(errorMessage(err));
-      process.exit(1);
+      process.exit(err instanceof KeshaError ? exitCodeFor(err) : 1);
     }
   },
 });

package/src/cli/say.ts

@@ -1,17 +1,10 @@
 import { defineCommand } from "citty";
 import { errorMessage } from "../error-utils";
-import {
-  getEngineBinPath,
-  isEngineInstalled,
-  spawnEngineProcess,
-  spawnStdioWithDebugFd,
-} from "../engine";
-import { installHint } from "../install-hint";
-import { registerProcessTree } from "../process-tree";
+import { exitCodeFor, KeshaError } from "../engine/events";
 import { log } from "../log";
 import {
+  listVoiceIds,
   say,
-  SayError,
   SUPPORTED_SAMPLE_RATES,
   type SayFormat,
   type SayOptions,
@@ -216,16 +209,16 @@ async function synthesizeAndEmit(
       },
     };
   } catch (err) {
-    const code = err instanceof SayError ? err.code : "E_INTERNAL";
-    const exitCode = err instanceof SayError ? err.exitCode : 4;
+    const code = err instanceof KeshaError ? err.code : "E_INTERNAL";
+    const exitCode = exitCodeFor(err);
     stats.recordError("tts", err, code);
-    log.error(err instanceof SayError ? err.stderr.trim() || err.message : errorMessage(err));
+    log.error(errorMessage(err));
     return {
       status: "failed",
       itemCount: 1,
       exitCode,
       finishFields: {
-        errorKind: err instanceof SayError ? "say_error" : "error",
+        errorKind: err instanceof KeshaError ? "say_error" : "error",
         exitCode,
         error_code: code,
       },
@@ -290,26 +283,15 @@ export const sayCommand = defineCommand({
   async run({ args }) {
     if (args.debug) log.debugEnabled = true;
     if (args["list-voices"]) {
-      if (!isEngineInstalled()) {
-        log.error(`kesha-engine not installed. run: ${installHint()}`);
-        process.exit(1);
-      }
-      // The engine prints the list directly — just relay its stdout + exit code.
-      const proc = spawnEngineProcess(
-        getEngineBinPath(),
-        ["say", "--list-voices"],
-        spawnStdioWithDebugFd(["inherit", "inherit", "inherit"]),
-      );
-      // Register so a Ctrl-C during a cold Engine load terminates it and exits 130/143 (#939);
-      // dispose before the process.exit below so the registration never outlives the run.
-      const tree = registerProcessTree(proc);
-      let exitCode: number;
+      let ids: string[];
       try {
-        exitCode = await proc.exited;
-      } finally {
-        tree.dispose();
+        ids = await listVoiceIds({ onProgress: (line) => log.status(line) });
+      } catch (err) {
+        log.error(errorMessage(err));
+        process.exit(exitCodeFor(err));
       }
-      process.exit(exitCode);
+      await Bun.write(Bun.stdout, ids.map((id) => `${id}\n`).join(""));
+      process.exit(0);
     }
 
     const flags = resolveSayFlags(args);

package/src/doctor.ts

@@ -34,7 +34,6 @@ const KNOWN_ENV_KEYS = [
   "KESHA_MODEL_MIRROR",
   "KESHA_STATS_DB",
   "KESHA_DEBUG",
-  "KESHA_DEBUG_FD",
   "KESHA_KOKORO_COMPUTE_UNITS",
   "KESHA_DIARIZE_COMPUTE_UNITS",
   "KESHA_DIARIZE_TIMEOUT_SECS",
@@ -221,6 +220,8 @@ async function collectEngine(redact: boolean): Promise<DoctorReport["engine"]> {
     probeError = `binary is present but does not run (${health.detail}); re-run \`kesha install\``;
   } else if (health.status === "mute") {
     probeError = `${health.detail}; re-run \`kesha install\``;
+  } else if (health.status === "protocol") {
+    probeError = health.detail;
   } else if (health.status === "ok") {
     capabilities = health.capabilities;
   }

package/src/engine/describe.ts

@@ -0,0 +1,227 @@
+import { KeshaError } from "./events";
+
+export const PROTOCOL_VERSION = 4;
+
+export type Gate = null | string | string[];
+
+export interface FlagSchema {
+  gate: Gate;
+  requires?: string[];
+  conflicts?: string[];
+  whenUngated?: "reject" | "drop";
+  values?: string;
+}
+
+export interface CommandSchema {
+  flags: Record<string, FlagSchema>;
+}
+
+export interface TtsLanguageCapability {
+  code: string;
+  engines: string[];
+}
+
+export interface EngineCapabilities {
+  protocolVersion: number;
+  backend: string;
+  features: string[];
+  tts?: { languages: TtsLanguageCapability[] };
+}
+
+export interface DescribeDocument {
+  protocolVersion: number;
+  backend: string;
+  profile: string;
+  features: string[];
+  commands: Record<string, CommandSchema>;
+  tts?: { languages: TtsLanguageCapability[] };
+}
+
+const UPGRADE_CLI = "bun add -g @drakulavich/kesha-voice-kit@latest";
+
+/** Remedies validateArgv attaches when a flag's gate is missing; keyed `<command> --<flag>`. */
+const GATE_HINTS: Record<string, string> = {
+  "transcribe --speakers":
+    "speaker diarization is darwin-arm64 only (https://github.com/drakulavich/kesha-voice-kit/issues/199)",
+  "transcribe --itn": `the installed engine predates the written-form pass; run \`${UPGRADE_CLI}\`, then \`kesha install\``,
+  "record --live":
+    "live transcription needs the CoreML engine on Apple Silicon; elsewhere record to a file, then transcribe it: `kesha record --out note.wav` and `kesha note.wav`",
+  "record --auto-stop": "live auto-stop needs a newer CoreML engine with Silero VAD endpointing; run `kesha install`",
+};
+
+/** Remedies validateArgv attaches when two present flags conflict; keyed `<command> --<flag> --<other>`. */
+const CONFLICT_HINTS: Record<string, string> = {
+  "transcribe --speakers --no-vad":
+    "speaker labels attach to VAD-windowed speech segments, and disabling VAD leaves the whole file as one segment with nothing to label; drop --no-vad (VAD engages automatically for --speakers), or drop --speakers",
+};
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+function parseGate(value: unknown): Gate | undefined {
+  if (value === null || typeof value === "string") return value;
+  if (isStringArray(value)) return value;
+  return undefined;
+}
+
+function parseFlag(raw: unknown): FlagSchema | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const o = raw as Record<string, unknown>;
+  if (!("gate" in o)) return null;
+  const gate = parseGate(o.gate);
+  if (gate === undefined) return null;
+  const flag: FlagSchema = { gate };
+  if (o.requires !== undefined) {
+    if (!isStringArray(o.requires)) return null;
+    flag.requires = o.requires;
+  }
+  if (o.conflicts !== undefined) {
+    if (!isStringArray(o.conflicts)) return null;
+    flag.conflicts = o.conflicts;
+  }
+  if (o.whenUngated !== undefined) {
+    if (o.whenUngated !== "reject" && o.whenUngated !== "drop") return null;
+    flag.whenUngated = o.whenUngated;
+  }
+  if (o.values !== undefined) {
+    if (typeof o.values !== "string") return null;
+    flag.values = o.values;
+  }
+  return flag;
+}
+
+function parseCommands(raw: unknown): Record<string, CommandSchema> | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const commands: Record<string, CommandSchema> = {};
+  for (const [name, entry] of Object.entries(raw as Record<string, unknown>)) {
+    const flagsRaw = (entry as { flags?: unknown } | null)?.flags;
+    if (!flagsRaw || typeof flagsRaw !== "object" || Array.isArray(flagsRaw)) return null;
+    const flags: Record<string, FlagSchema> = {};
+    for (const [flagName, flagRaw] of Object.entries(flagsRaw as Record<string, unknown>)) {
+      const flag = parseFlag(flagRaw);
+      if (!flag) return null;
+      flags[flagName] = flag;
+    }
+    commands[name] = { flags };
+  }
+  return commands;
+}
+
+function parseTtsLanguages(raw: unknown): TtsLanguageCapability[] | null {
+  const languages = (raw as { languages?: unknown } | null | undefined)?.languages;
+  if (!Array.isArray(languages)) return null;
+  const out: TtsLanguageCapability[] = [];
+  for (const entry of languages) {
+    const l = entry as Record<string, unknown> | null;
+    if (typeof l?.code !== "string" || !isStringArray(l.engines)) return null;
+    out.push({ code: l.code, engines: l.engines });
+  }
+  return out;
+}
+
+/** A non-null return means the engine described itself; every field the CLI reads is rebuilt, never cast (#647, #928). */
+export function parseDescribe(parsed: unknown): DescribeDocument | null {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const { protocolVersion, backend, profile, features, commands, tts } = parsed as Record<string, unknown>;
+  if (typeof protocolVersion !== "number") return null;
+  if (typeof backend !== "string" || typeof profile !== "string") return null;
+  if (!isStringArray(features)) return null;
+  const parsedCommands = parseCommands(commands);
+  if (!parsedCommands) return null;
+  const doc: DescribeDocument = { protocolVersion, backend, profile, features, commands: parsedCommands };
+  if (tts !== undefined) {
+    const languages = parseTtsLanguages(tts);
+    if (!languages) return null;
+    doc.tts = { languages };
+  }
+  return doc;
+}
+
+export function protocolMismatch(doc: DescribeDocument, binPath: string): KeshaError | null {
+  if (doc.protocolVersion === PROTOCOL_VERSION) return null;
+  const stale = doc.protocolVersion < PROTOCOL_VERSION;
+  return new KeshaError(
+    "E_ENGINE_PROTOCOL",
+    `kesha-engine at ${binPath} speaks protocol ${doc.protocolVersion}; this CLI speaks protocol ${PROTOCOL_VERSION}`,
+    {
+      hint: stale
+        ? "run `kesha install` to fetch the engine this CLI expects"
+        : `the engine is newer than this CLI; run \`${UPGRADE_CLI}\``,
+      versionMismatch: true,
+    },
+  );
+}
+
+export function describeToCapabilities(doc: DescribeDocument): EngineCapabilities {
+  const caps: EngineCapabilities = {
+    protocolVersion: doc.protocolVersion,
+    backend: doc.backend,
+    features: doc.features,
+  };
+  if (doc.tts) caps.tts = doc.tts;
+  return caps;
+}
+
+function gateSatisfied(gate: Gate, features: string[]): boolean {
+  if (gate === null) return true;
+  if (typeof gate === "string") return features.includes(gate);
+  return gate.some((f) => features.includes(f));
+}
+
+function gateText(gate: Gate): string {
+  return typeof gate === "string" ? gate : `one of ${(gate as string[]).join(", ")}`;
+}
+
+function flagNameAt(argv: string[], index: number): string | null {
+  const token = argv[index]!;
+  if (!token.startsWith("--") || token === "--") return null;
+  const eq = token.indexOf("=");
+  return (eq === -1 ? token : token.slice(0, eq)).slice(2);
+}
+
+/** Checks an engine argv (subcommand first) against the describe document; unknown flags, absent gates, missing requires and present conflicts are E_INVALID_ARG, a whenUngated: drop flag is removed with one warning. */
+export function validateArgv(argv: string[], doc: DescribeDocument): { argv: string[]; warnings: string[] } {
+  const command = argv[0] ?? "";
+  const schema = doc.commands[command];
+  if (!schema) {
+    throw new KeshaError("E_INVALID_ARG", `kesha-engine has no \`${command}\` subcommand`);
+  }
+  const build = `${doc.backend}/${doc.profile}`;
+  const present = new Set<string>();
+  const drop = new Set<number>();
+  const warnings: string[] = [];
+  for (let i = 1; i < argv.length; i++) {
+    if (argv[i] === "--") break;
+    const name = flagNameAt(argv, i);
+    if (name === null) continue;
+    const flag = schema.flags[name];
+    if (!flag) {
+      throw new KeshaError("E_INVALID_ARG", `kesha-engine ${command} does not accept --${name}`);
+    }
+    if (!gateSatisfied(flag.gate, doc.features)) {
+      const needs = `--${name} needs ${gateText(flag.gate)}, which this kesha-engine build (${build}) does not provide`;
+      if (flag.whenUngated === "drop") {
+        drop.add(i);
+        warnings.push(`${needs}; the flag was ignored`);
+        continue;
+      }
+      throw new KeshaError("E_INVALID_ARG", needs, { hint: GATE_HINTS[`${command} --${name}`] });
+    }
+    present.add(name);
+  }
+  for (const name of present) {
+    const flag = schema.flags[name]!;
+    for (const req of flag.requires ?? []) {
+      if (!present.has(req)) throw new KeshaError("E_INVALID_ARG", `--${name} requires --${req}`);
+    }
+    for (const other of flag.conflicts ?? []) {
+      if (present.has(other)) {
+        throw new KeshaError("E_INVALID_ARG", `--${name} cannot be combined with --${other}`, {
+          hint: CONFLICT_HINTS[`${command} --${name} --${other}`],
+        });
+      }
+    }
+  }
+  return { argv: argv.filter((_, i) => !drop.has(i)), warnings };
+}