@kuralle-syrinx/cli 4.4.0

package/src/cli.test.ts

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { main, type CliIO } from "./cli.js";
+import { EXIT_CODES } from "./exit-codes.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(HERE, "__fixtures__");
+
+function captureIO(): { io: CliIO; stdout: string[]; stderr: string[] } {
+  const stdout: string[] = [];
+  const stderr: string[] = [];
+  return { io: { stdout: (l) => stdout.push(l), stderr: (l) => stderr.push(l) }, stdout, stderr };
+}
+
+describe("main — global flags", () => {
+  it("--help prints usage to stdout and exits SUCCESS", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["--help"], io);
+    expect(code).toBe(EXIT_CODES.SUCCESS);
+    expect(stdout.join("\n")).toContain("USAGE");
+    expect(stdout.join("\n")).toContain("EXIT CODES");
+  });
+
+  it("no arguments prints usage (same as --help)", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main([], io);
+    expect(code).toBe(EXIT_CODES.SUCCESS);
+    expect(stdout.join("\n")).toContain("USAGE");
+  });
+
+  it("--version prints just the version and exits SUCCESS", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["--version"], io);
+    expect(code).toBe(EXIT_CODES.SUCCESS);
+    expect(stdout).toHaveLength(1);
+    expect(stdout[0]).toMatch(/^\d+\.\d+\.\d+/);
+  });
+});
+
+describe("main — usage errors", () => {
+  it("an unknown command exits USAGE and, with --json, stays parseable on stdout", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["frobnicate", "--json"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    expect(stdout).toHaveLength(1);
+    const parsed = JSON.parse(stdout[0]!) as { ok: boolean; error: { code: string } };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error.code).toBe("USAGE");
+  });
+
+  it("without --json, an unknown command prints nothing to stdout and the error to stderr", async () => {
+    const { io, stdout, stderr } = captureIO();
+    const code = await main(["frobnicate"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    expect(stdout).toHaveLength(0);
+    expect(stderr.join("\n")).toContain("frobnicate");
+  });
+
+  it("console/chat/listen are explicitly rejected — this CLI is not a console", async () => {
+    for (const verb of ["console", "chat", "listen"]) {
+      const { io } = captureIO();
+      const code = await main([verb], io);
+      expect(code).toBe(EXIT_CODES.USAGE);
+    }
+  });
+
+  it("turn without --in exits USAGE", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["turn", "--agent", "whatever#x", "--json"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    const parsed = JSON.parse(stdout[0]!) as { error: { code: string } };
+    expect(parsed.error.code).toBe("USAGE");
+  });
+
+  it("turn without --agent exits USAGE — the CLI brings no provider of its own", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["turn", "--in", "/tmp/whatever.wav", "--json"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    const parsed = JSON.parse(stdout[0]!) as { error: { code: string; message: string } };
+    expect(parsed.error.code).toBe("USAGE");
+    expect(parsed.error.message).toContain("--agent");
+  });
+
+  it("turn --agent pointing at a nonexistent module fails USAGE with a message naming what could not be resolved — no stack trace, no silent fallback", async () => {
+    const { io, stdout, stderr } = captureIO();
+    const code = await main(["turn", "--in", "/tmp/whatever.wav", "--agent", "./does/not/exist.ts#nope", "--json"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    expect(stdout).toHaveLength(1);
+    const parsed = JSON.parse(stdout[0]!) as { ok: boolean; error: { code: string; message: string } };
+    expect(parsed.ok).toBe(false);
+    expect(parsed.error.code).toBe("USAGE");
+    expect(parsed.error.message).toContain("does/not/exist.ts");
+    expect(stderr.join("\n")).not.toContain("at "); // no stack trace leaked for a documented failure class
+  });
+
+  it("text without a message exits USAGE", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["text", "--agent", "whatever#x", "--json"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    const parsed = JSON.parse(stdout[0]!) as { error: { code: string } };
+    expect(parsed.error.code).toBe("USAGE");
+  });
+
+  it("text without --agent exits USAGE", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["text", "hi", "--json"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+    const parsed = JSON.parse(stdout[0]!) as { error: { code: string; message: string } };
+    expect(parsed.error.code).toBe("USAGE");
+    expect(parsed.error.message).toContain("--agent");
+  });
+
+  it("an unrecognised flag exits USAGE rather than throwing past the CLI", async () => {
+    const { io } = captureIO();
+    const code = await main(["doctor", "--not-a-real-flag"], io);
+    expect(code).toBe(EXIT_CODES.USAGE);
+  });
+});
+
+describe("main — end to end through --agent, no live provider", () => {
+  it("text --agent <fixture> resolves the caller's own module and drives a real turn", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["text", "hi", "--agent", `${join(FIXTURES, "good-text-agent.mjs")}#createSession`, "--json"], io);
+    expect(code).toBe(EXIT_CODES.SUCCESS);
+    const parsed = JSON.parse(stdout[0]!) as { ok: boolean; reply: string; agent: string };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.reply).toBe("Hello from the fake agent.");
+    expect(parsed.agent).toContain("createSession");
+  });
+});
+
+describe("main — doctor", () => {
+  it("doctor --json emits one parseable object and always exits SUCCESS", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["doctor", "--json"], io);
+    expect(code).toBe(EXIT_CODES.SUCCESS);
+    expect(stdout).toHaveLength(1);
+    const parsed = JSON.parse(stdout[0]!) as { ok: boolean; verb: string };
+    expect(parsed.ok).toBe(true);
+    expect(parsed.verb).toBe("doctor");
+  });
+
+  it("doctor without --json prints a human summary, not JSON", async () => {
+    const { io, stdout } = captureIO();
+    const code = await main(["doctor"], io);
+    expect(code).toBe(EXIT_CODES.SUCCESS);
+    expect(() => JSON.parse(stdout[0]!)).toThrow();
+  });
+});

package/src/cli.ts

@@ -0,0 +1,225 @@
+// SPDX-License-Identifier: MIT
+//
+// Argument parsing and verb dispatch. Never interactive: no prompts, no
+// spinners, no colour unless the stream is a TTY. Results go to stdout,
+// diagnostics to stderr — always, so --json output stays parseable.
+
+import { parseArgs } from "node:util";
+
+import { runDoctor } from "./doctor.js";
+import { CliError, EXIT_CODES, EXIT_CODE_TABLE, type ExitCode } from "./exit-codes.js";
+import { HELP_TEXT } from "./help.js";
+import { runTextCommand } from "./text-command.js";
+import { runTurnCommand } from "./turn-command.js";
+import { CLI_VERSION, warnOnVersionSkew } from "./version.js";
+
+export interface CliIO {
+  readonly stdout: (line: string) => void;
+  readonly stderr: (line: string) => void;
+}
+
+export const defaultIO: CliIO = {
+  stdout: (line) => {
+    process.stdout.write(`${line}\n`);
+  },
+  stderr: (line) => {
+    process.stderr.write(`${line}\n`);
+  },
+};
+
+function exitCodeName(code: ExitCode): string {
+  return EXIT_CODE_TABLE.find((row) => row.code === code)?.name ?? "UNKNOWN";
+}
+
+/** Best-effort pre-parse scan so even a usage error can honour --json, without depending on parseArgs succeeding. */
+function looksLikeJsonRequested(args: readonly string[]): boolean {
+  return args.includes("--json");
+}
+
+function reportSuccess(io: CliIO, json: boolean, verb: string, payload: Record<string, unknown>, prose: string): ExitCode {
+  if (json) {
+    io.stdout(JSON.stringify({ ok: true, verb, ...payload }));
+  } else {
+    io.stdout(prose);
+  }
+  return EXIT_CODES.SUCCESS;
+}
+
+function reportError(io: CliIO, json: boolean, verb: string, err: unknown): ExitCode {
+  const cliErr =
+    err instanceof CliError ? err : new CliError(EXIT_CODES.INTERNAL, err instanceof Error ? err.message : String(err));
+  if (cliErr.exitCode === EXIT_CODES.INTERNAL && err instanceof Error && err.stack) {
+    io.stderr(err.stack);
+  }
+  if (json) {
+    io.stdout(
+      JSON.stringify({
+        ok: false,
+        verb,
+        error: { code: exitCodeName(cliErr.exitCode), message: cliErr.message, ...(cliErr.details ?? {}) },
+      }),
+    );
+  } else {
+    io.stderr(`error: ${cliErr.message}`);
+  }
+  return cliErr.exitCode;
+}
+
+async function handleTurn(args: string[], io: CliIO): Promise<ExitCode> {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args,
+      options: {
+        in: { type: "string" },
+        agent: { type: "string" },
+        "session-dir": { type: "string" },
+        json: { type: "boolean", default: false },
+      },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    return reportError(io, looksLikeJsonRequested(args), "turn", new CliError(EXIT_CODES.USAGE, err instanceof Error ? err.message : String(err)));
+  }
+
+  const json = values.json === true;
+  if (!values.in) {
+    return reportError(io, json, "turn", new CliError(EXIT_CODES.USAGE, "turn requires --in <fixture.wav|fixture.json>"));
+  }
+  if (!values.agent) {
+    return reportError(
+      io,
+      json,
+      "turn",
+      new CliError(EXIT_CODES.USAGE, "turn requires --agent <module>#<export> — the CLI brings no providers of its own (see --help)"),
+    );
+  }
+
+  try {
+    const result = await runTurnCommand({
+      inputPath: values.in,
+      agentSpec: values.agent,
+      sessionDir: values["session-dir"],
+    });
+    const prose = [
+      `agent: ${result.agent}`,
+      `transcript: ${result.transcript || "(empty)"}`,
+      `reply: ${result.reply || "(empty)"}`,
+      `session: ${result.sessionDir}`,
+      result.assertion ? `assertion: match (expected "${result.assertion.expectedTranscript}")` : "assertion: none",
+    ].join("\n");
+    return reportSuccess(io, json, "turn", { ...result }, prose);
+  } catch (err) {
+    return reportError(io, json, "turn", err);
+  }
+}
+
+async function handleText(args: string[], io: CliIO): Promise<ExitCode> {
+  let values, positionals;
+  try {
+    ({ values, positionals } = parseArgs({
+      args,
+      options: {
+        agent: { type: "string" },
+        json: { type: "boolean", default: false },
+      },
+      strict: true,
+      allowPositionals: true,
+    }));
+  } catch (err) {
+    return reportError(io, looksLikeJsonRequested(args), "text", new CliError(EXIT_CODES.USAGE, err instanceof Error ? err.message : String(err)));
+  }
+
+  const json = values.json === true;
+  const message = positionals[0];
+  if (!message) {
+    return reportError(io, json, "text", new CliError(EXIT_CODES.USAGE, 'text requires a message: syrinx text "<message>" --agent <module>#<export>'));
+  }
+  if (!values.agent) {
+    return reportError(
+      io,
+      json,
+      "text",
+      new CliError(EXIT_CODES.USAGE, "text requires --agent <module>#<export> — the CLI brings no providers of its own (see --help)"),
+    );
+  }
+
+  try {
+    const result = await runTextCommand({ message, agentSpec: values.agent });
+    const prose = `agent: ${result.agent}\nreply: ${result.reply || "(empty)"}\nttft: ${String(result.ttftMs)}ms  total: ${String(result.totalMs)}ms`;
+    return reportSuccess(io, json, "text", { ...result }, prose);
+  } catch (err) {
+    return reportError(io, json, "text", err);
+  }
+}
+
+async function handleDoctor(args: string[], io: CliIO): Promise<ExitCode> {
+  let values;
+  try {
+    ({ values } = parseArgs({
+      args,
+      options: { agent: { type: "string" }, json: { type: "boolean", default: false } },
+      strict: true,
+      allowPositionals: false,
+    }));
+  } catch (err) {
+    return reportError(io, looksLikeJsonRequested(args), "doctor", new CliError(EXIT_CODES.USAGE, err instanceof Error ? err.message : String(err)));
+  }
+
+  const json = values.json === true;
+  const report = await runDoctor({ agentSpec: values.agent });
+  const prose = [
+    `syrinx cli ${report.cliVersion}  node ${report.node.version} (${report.node.platform})`,
+    `${report.core.package}: ${report.core.resolved ? `v${String(report.core.version)}` : "not installed"}${report.core.majorMismatch ? "  (major mismatch with CLI)" : ""}`,
+    "well-known provider keys (informational only):",
+    ...Object.entries(report.wellKnownProviderKeys).map(([key, present]) => `  ${key}: ${present ? "present" : "missing"}`),
+    ...(report.agent ? [`agent (${report.agent.spec}): ${report.agent.resolved ? `resolved -> ${String(report.agent.label)}` : `NOT resolved (${String(report.agent.error)})`}`] : []),
+    report.summary,
+  ].join("\n");
+  return reportSuccess(io, json, "doctor", { ...report }, prose);
+}
+
+export async function main(argv: readonly string[], io: CliIO = defaultIO): Promise<ExitCode> {
+  try {
+    warnOnVersionSkew(process.cwd());
+  } catch {
+    // Version-skew reporting is best-effort diagnostics; never let it block a command.
+  }
+
+  const [verb, ...rest] = argv;
+
+  if (verb === undefined || verb === "--help" || verb === "-h") {
+    io.stdout(HELP_TEXT);
+    return EXIT_CODES.SUCCESS;
+  }
+  if (verb === "--version" || verb === "-v") {
+    io.stdout(CLI_VERSION);
+    return EXIT_CODES.SUCCESS;
+  }
+
+  switch (verb) {
+    case "turn":
+      return handleTurn(rest, io);
+    case "text":
+      return handleText(rest, io);
+    case "doctor":
+      return handleDoctor(rest, io);
+    case "console":
+    case "chat":
+    case "listen":
+      return reportError(
+        io,
+        looksLikeJsonRequested(rest),
+        verb,
+        new CliError(EXIT_CODES.USAGE, `"${verb}" is not a syrinx command — this CLI is non-interactive by design (see --help). Use the Studio for that.`),
+      );
+    default:
+      return reportError(
+        io,
+        looksLikeJsonRequested(rest),
+        verb,
+        new CliError(EXIT_CODES.USAGE, `unknown command: ${verb} (see --help)`),
+      );
+  }
+}

package/src/doctor.test.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: MIT
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { runDoctor } from "./doctor.js";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = join(HERE, "__fixtures__");
+
+describe("runDoctor", () => {
+  it("never echoes key values, only presence", async () => {
+    const report = await runDoctor({
+      cwd: HERE,
+      env: { OPENAI_API_KEY: "sk-super-secret-value", DEEPGRAM_API_KEY: undefined },
+    });
+    expect(JSON.stringify(report)).not.toContain("sk-super-secret-value");
+    expect(report.wellKnownProviderKeys.OPENAI_API_KEY).toBe(true);
+    expect(report.wellKnownProviderKeys.DEEPGRAM_API_KEY).toBe(false);
+  });
+
+  it("treats a blank/whitespace-only key as absent", async () => {
+    const report = await runDoctor({ cwd: HERE, env: { OPENAI_API_KEY: "   " } });
+    expect(report.wellKnownProviderKeys.OPENAI_API_KEY).toBe(false);
+  });
+
+  it("reports the installed @kuralle-syrinx/core version from this workspace", async () => {
+    const report = await runDoctor({ cwd: HERE, env: {} });
+    expect(report.core.resolved).toBe(true);
+    expect(report.core.majorMismatch).toBe(false);
+  });
+
+  it("without --agent, reports no fixed provider requirement — just informational keys", async () => {
+    const report = await runDoctor({ cwd: HERE, env: {} });
+    expect(report.agent).toBeNull();
+    expect(report.summary).not.toMatch(/deepgram|cartesia|openai/i);
+  });
+
+  it("with --agent, resolves and reports the specific agent instead of a hardcoded set", async () => {
+    const ok = await runDoctor({ cwd: HERE, env: {}, agentSpec: `${join(FIXTURES, "good-text-agent.mjs")}#createSession` });
+    expect(ok.agent?.resolved).toBe(true);
+    expect(ok.agent?.label).toContain("createSession");
+
+    const bad = await runDoctor({ cwd: HERE, env: {}, agentSpec: join(FIXTURES, "does-not-exist.mjs") });
+    expect(bad.agent?.resolved).toBe(false);
+    expect(bad.agent?.error).toBeTruthy();
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: MIT
+//
+// `syrinx doctor` — reports what is configured and what is missing. Never prints
+// key values, only presence. Always exits SUCCESS: this verb diagnoses, it does
+// not assert.
+//
+// This CLI has no fixed provider set — it never constructs an STT/TTS/reasoner
+// itself (see --agent, agent-resolve.ts). So doctor cannot claim "ready for
+// turn"/"ready for text" against a hardcoded key list; it reports well-known
+// provider keys as informational only, and — when given --agent — reports
+// whether that specific agent module resolves.
+
+import { resolveAgentFactory } from "./agent-resolve.js";
+import { CliError } from "./exit-codes.js";
+import { CLI_VERSION, CORE_PACKAGE_NAME, checkCoreVersionSkew, majorOf } from "./version.js";
+
+/** Commonly used in the Syrinx ecosystem — shown for convenience only. The CLI itself does not require any of these; whatever --agent resolves to owns its own provider requirements. */
+export const WELL_KNOWN_PROVIDER_KEYS = ["DEEPGRAM_API_KEY", "OPENAI_API_KEY", "CARTESIA_API_KEY", "GEMINI_API_KEY", "ELEVENLABS_API_KEY", "GROK_API_KEY"] as const;
+
+export type WellKnownProviderKey = (typeof WELL_KNOWN_PROVIDER_KEYS)[number];
+
+export interface DoctorAgentReport {
+  readonly spec: string;
+  readonly resolved: boolean;
+  readonly label?: string;
+  readonly error?: string;
+}
+
+export interface DoctorReport {
+  readonly cliVersion: string;
+  readonly node: { readonly version: string; readonly platform: string };
+  readonly core: {
+    readonly package: string;
+    readonly resolved: boolean;
+    readonly version: string | undefined;
+    readonly cliMajor: string;
+    readonly coreMajor: string | undefined;
+    readonly majorMismatch: boolean;
+  };
+  /** Informational only — presence, never the value. This CLI does not require any specific set; see `agent`. */
+  readonly wellKnownProviderKeys: Readonly<Record<WellKnownProviderKey, boolean>>;
+  readonly agent: DoctorAgentReport | null;
+  readonly summary: string;
+}
+
+export interface RunDoctorOptions {
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly nodeVersion?: string;
+  readonly platform?: string;
+  /** `--agent <module>#<export>` — when given, doctor resolves (imports + finds the callable export) but does not invoke it, so checking doesn't require live provider access. */
+  readonly agentSpec?: string;
+}
+
+export async function runDoctor(opts: RunDoctorOptions = {}): Promise<DoctorReport> {
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const skew = checkCoreVersionSkew(cwd);
+
+  const wellKnownProviderKeys = Object.fromEntries(
+    WELL_KNOWN_PROVIDER_KEYS.map((key) => [key, Boolean(env[key]?.trim())]),
+  ) as Record<WellKnownProviderKey, boolean>;
+
+  let agent: DoctorAgentReport | null = null;
+  if (opts.agentSpec) {
+    try {
+      const resolved = await resolveAgentFactory(opts.agentSpec, cwd);
+      agent = { spec: opts.agentSpec, resolved: true, label: resolved.label };
+    } catch (err) {
+      agent = {
+        spec: opts.agentSpec,
+        resolved: false,
+        error: err instanceof CliError ? err.message : err instanceof Error ? err.message : String(err),
+      };
+    }
+  }
+
+  const summary = !skew.coreResolved
+    ? `${CORE_PACKAGE_NAME} is not installed in this project`
+    : agent
+      ? agent.resolved
+        ? `agent resolved: ${agent.label}`
+        : `agent could not be resolved: ${agent.error}`
+      : "pass --agent <module>#<export> to check whether a specific agent resolves; the provider keys above are informational only — this CLI does not require any specific set";
+
+  return {
+    cliVersion: CLI_VERSION,
+    node: { version: opts.nodeVersion ?? process.version, platform: opts.platform ?? process.platform },
+    core: {
+      package: CORE_PACKAGE_NAME,
+      resolved: skew.coreResolved,
+      version: skew.coreVersion,
+      cliMajor: majorOf(CLI_VERSION),
+      coreMajor: skew.coreVersion ? majorOf(skew.coreVersion) : undefined,
+      majorMismatch: skew.mismatch,
+    },
+    wellKnownProviderKeys,
+    agent,
+    summary,
+  };
+}

package/src/exit-codes.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+//
+// The exit-code contract an agent depends on. Every verb resolves to exactly one
+// of these — never collapsed to a bare 1 for "something went wrong". Documented
+// here once; `--help` and the README quote this table verbatim.
+
+export const EXIT_CODES = {
+  SUCCESS: 0,
+  INTERNAL: 1,
+  USAGE: 2,
+  CONFIG: 3,
+  BACKEND: 4,
+  ASSERTION: 5,
+} as const;
+
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+
+export const EXIT_CODE_TABLE: ReadonlyArray<{ readonly code: ExitCode; readonly name: string; readonly meaning: string }> = [
+  { code: EXIT_CODES.SUCCESS, name: "SUCCESS", meaning: "the command completed and, where applicable, any assertion matched" },
+  { code: EXIT_CODES.INTERNAL, name: "INTERNAL", meaning: "an unexpected error inside the CLI itself (not a usage or backend problem) — treat as a bug" },
+  { code: EXIT_CODES.USAGE, name: "USAGE", meaning: "bad invocation: unknown verb/flag, a missing required argument, or a fixture the CLI cannot honour (unsupported format, capture-config mismatch)" },
+  { code: EXIT_CODES.CONFIG, name: "CONFIG", meaning: "required provider configuration or API keys are missing" },
+  { code: EXIT_CODES.BACKEND, name: "BACKEND", meaning: "the agent or backend failed while running the turn (provider/network error, timeout, pipeline error)" },
+  { code: EXIT_CODES.ASSERTION, name: "ASSERTION", meaning: "a replayed fixture's transcript drifted from the expected transcript" },
+];
+
+/** A typed error carrying the exit code it should terminate the process with. */
+export class CliError extends Error {
+  readonly exitCode: ExitCode;
+  readonly details: Record<string, unknown> | undefined;
+
+  constructor(exitCode: ExitCode, message: string, details?: Record<string, unknown>) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}

package/src/fixture.test.ts

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { CliError, EXIT_CODES } from "./exit-codes.js";
+import { assertTranscript, loadFixture, normalizeTranscript } from "./fixture.js";
+
+describe("normalizeTranscript / assertTranscript", () => {
+  it("ignores case, punctuation, and extra whitespace", () => {
+    expect(normalizeTranscript("Hello,   World!")).toBe("hello world");
+    expect(assertTranscript("Hello, World!", "hello   world").match).toBe(true);
+  });
+
+  it("flags a real drift", () => {
+    const a = assertTranscript("book a flight to paris", "book a flight to london");
+    expect(a.match).toBe(false);
+    expect(a.expectedTranscript).toBe("book a flight to paris");
+    expect(a.actualTranscript).toBe("book a flight to london");
+  });
+});
+
+describe("loadFixture", () => {
+  let root: string;
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "syrinx-cli-fixture-"));
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, maxRetries: 3, force: true }).catch(() => {});
+  });
+
+  it("loads a well-formed sidecar and prefers a sibling captured.wav", async () => {
+    const sidecarPath = join(root, "turn.json");
+    await writeFile(
+      sidecarPath,
+      JSON.stringify({
+        format: "syrinx.fixture.v1",
+        audioFile: "turn.wav",
+        audio: { sampleRateHz: 16000, channels: 1, encoding: "pcm_s16le" },
+        expectedTranscript: "hi there",
+      }),
+    );
+    await writeFile(join(root, "captured.wav"), Buffer.from([1, 2, 3]));
+
+    const loaded = loadFixture(sidecarPath);
+    expect(loaded.sidecar.expectedTranscript).toBe("hi there");
+    expect(loaded.wavPath).toBe(join(root, "captured.wav"));
+  });
+
+  it("falls back to audioFile when no sibling captured.wav exists", async () => {
+    const sidecarPath = join(root, "turn.json");
+    await writeFile(
+      sidecarPath,
+      JSON.stringify({
+        format: "syrinx.fixture.v1",
+        audioFile: "turn.wav",
+        audio: { sampleRateHz: 16000, channels: 1, encoding: "pcm_s16le" },
+      }),
+    );
+    const loaded = loadFixture(sidecarPath);
+    expect(loaded.wavPath).toBe(join(root, "turn.wav"));
+  });
+
+  it("refuses an unrecognised format", async () => {
+    const sidecarPath = join(root, "turn.json");
+    await writeFile(
+      sidecarPath,
+      JSON.stringify({ format: "other.v1", audioFile: "turn.wav", audio: { sampleRateHz: 16000, channels: 1, encoding: "pcm_s16le" } }),
+    );
+    try {
+      loadFixture(sidecarPath);
+      expect.unreachable();
+    } catch (err) {
+      expect(err).toBeInstanceOf(CliError);
+      expect((err as CliError).exitCode).toBe(EXIT_CODES.USAGE);
+    }
+  });
+
+  it("refuses a capture config it cannot honestly replay (stereo / non-16kHz)", async () => {
+    const sidecarPath = join(root, "turn.json");
+    await writeFile(
+      sidecarPath,
+      JSON.stringify({ format: "syrinx.fixture.v1", audioFile: "turn.wav", audio: { sampleRateHz: 16000, channels: 2, encoding: "pcm_s16le" } }),
+    );
+    expect(() => loadFixture(sidecarPath)).toThrow(CliError);
+  });
+
+  it("refuses malformed JSON", async () => {
+    const sidecarPath = join(root, "turn.json");
+    await writeFile(sidecarPath, "{not json");
+    expect(() => loadFixture(sidecarPath)).toThrow(CliError);
+  });
+
+  it("refuses a missing file", () => {
+    expect(() => loadFixture(join(root, "nope.json"))).toThrow(CliError);
+  });
+});