@startsimpli/llm 0.4.29 → 0.4.31

package/src/__tests__/refine.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ILLMProvider } from '../providers/interface';
+import type { GenerateOptions, LLMResponse } from '../types';
+import {
+  InvalidTriesError, RefineStepError, UnknownGateError, createGateRegistry, llmRefineStep, refineWithGates,
+} from '../refine';
+import type { RefineStep, StepInput } from '../refine';
+
+type Doc = { title: string; screens: number };
+
+/** Gates in the shape the anim loop has: a schema-ish one and a policy one. */
+const registry = () => {
+  const gates = createGateRegistry<Doc, { kind: string }>();
+  gates.register('title', (d) => (d.title.length > 3 ? ['title is too long'] : []));
+  gates.register('screens', (d) => (d.screens > 0 ? [`a skit expects no screens, found ${d.screens}`] : []));
+  return gates;
+};
+
+/** A step that answers call i with replies[i] (the last repeats) and records what it was handed. */
+const sequenced = (...replies: Array<Doc | Error | { result: Doc | null; errors?: string[]; costUsd?: number }>) => {
+  const calls: StepInput<Doc>[] = [];
+  const step: RefineStep<Doc> = async (input) => {
+    calls.push(structuredClone(input));
+    const r = replies[Math.min(calls.length - 1, replies.length - 1)];
+    if (r instanceof Error) throw r;
+    return 'title' in r ? { result: r, costUsd: 0.01, usage: { promptTokens: 100, completionTokens: 50, totalTokens: 150 }, model: 'm' } : r;
+  };
+  return { step, calls };
+};
+const good: Doc = { title: 'Ok', screens: 0 };
+const withScreen: Doc = { title: 'Ok', screens: 2 };
+const run = (step: RefineStep<Doc>, tries: number | null, extra: Record<string, unknown> = {}) =>
+  refineWithGates<Doc, { kind: string }>({ step, gates: registry(), tries, context: { kind: 'skit' }, ...extra });
+
+describe('refineWithGates: the loop', () => {
+  it('a result that passes every gate costs exactly one step call', async () => {
+    const { step, calls } = sequenced(good);
+    const out = await run(step, 3);
+    expect(out.passed).toBe(true);
+    expect(calls).toHaveLength(1);
+    expect(out.attempts).toHaveLength(1);
+    expect(out.attempts[0]).toMatchObject({ n: 1, report: [], result: good, passed: true });
+  });
+
+  it('the step receives the previous result and the gates failures as data', async () => {
+    const { step, calls } = sequenced(withScreen, good);
+    const out = await run(step, 3);
+    expect(out.passed).toBe(true);
+    expect(calls[0]).toMatchObject({ n: 1, previous: null, failures: [] });
+    expect(calls[1].previous).toEqual(withScreen);
+    expect(calls[1].failures).toEqual([{ gate: 'screens', failures: ['a skit expects no screens, found 2'] }]);
+    expect(out.attempts[0].passed).toBe(false);
+  });
+
+  it('tries=N makes N calls at most and returns every attempt', async () => {
+    const { step, calls } = sequenced(withScreen);
+    const out = await run(step, 3);
+    expect(out.passed).toBe(false);
+    expect(calls).toHaveLength(3);
+    expect(out.attempts.map((a) => a.n)).toEqual([1, 2, 3]);
+    expect(out.result).toEqual(withScreen);
+    expect((await run(sequenced(withScreen, good).step, 1)).passed).toBe(false);
+  });
+
+  it('tries=null loops until every gate passes, with no hidden cap', async () => {
+    const { step, calls } = sequenced(...Array(25).fill(withScreen), good);
+    const out = await run(step, null);
+    expect(out.passed).toBe(true);
+    expect(calls).toHaveLength(26);
+  });
+
+  it('a bad tries value is refused, not clamped, before any call', async () => {
+    const { step, calls } = sequenced(good);
+    for (const bad of [0, -1, 1.5, true as any, 'x' as any, undefined as any]) await expect(run(step, bad)).rejects.toBeInstanceOf(InvalidTriesError);
+    expect(calls).toHaveLength(0);
+  });
+
+  it('every attempt carries {result, report, cost} and the outcome tallies usage', async () => {
+    const { step } = sequenced(withScreen, good);
+    const out = await run(step, 3);
+    expect(out.attempts[0].cost).toMatchObject({ usd: 0.01, promptTokens: 100, completionTokens: 50 });
+    expect(out.cost.usd).toBeCloseTo(0.02, 6);
+    expect(out.tally).toMatchObject({ calls: 2, promptTokens: 200, completionTokens: 100 });
+  });
+
+  it('a step that throws is surfaced with the attempts so far, not retried', async () => {
+    const boom = new Error('network down');
+    const { step, calls } = sequenced(withScreen, boom, good);
+    const error = await run(step, 5).catch((e) => e);
+    expect(error).toBeInstanceOf(RefineStepError);
+    expect(error.cause).toBe(boom);
+    expect(error.attempts).toHaveLength(1);
+    expect(error.n).toBe(2);
+    expect(calls).toHaveLength(2);
+  });
+
+  it('a reply the step rejected, or no result, is a failure under the rejected-gate name and the loop goes on', async () => {
+    const { step, calls } = sequenced({ result: null, errors: ['not json'] }, good);
+    const out = await run(step, 2);
+    expect(out.passed).toBe(true);
+    expect(out.attempts[0].report).toEqual([{ gate: 'step', failures: ['not json'] }]);
+    expect(calls[1]).toMatchObject({ previous: null, failures: [{ gate: 'step', failures: ['not json'] }] });
+    const named = await run(sequenced({ result: null }).step, 1, { rejectedGate: 'schema' });
+    expect(named.attempts[0].report[0]).toMatchObject({ gate: 'schema' });
+  });
+
+  it('calls a step made in one try (e.g. per-scene regeneration) are counted', async () => {
+    const out = await run(async () => ({ result: good, calls: 3 }), 1);
+    expect(out.attempts[0].calls).toBe(3);
+  });
+});
+
+describe('refineWithGates: gates', () => {
+  it('are registered by name; the context reaches them; a new one plugs in; a named subset runs', async () => {
+    const seen: string[] = [];
+    const gates = registry();
+    gates.register('ctx', (_d, ctx) => { seen.push(ctx.kind); return []; });
+    const out = await refineWithGates({ step: sequenced(withScreen).step, gates, tries: 1, context: { kind: 'skit' } });
+    expect(seen).toEqual(['skit']);
+    expect(out.attempts[0].report.map((r) => r.gate)).toEqual(['screens']);
+    const only = await refineWithGates({ step: sequenced(withScreen).step, gates, tries: 1, context: { kind: 'skit' }, only: ['title'] });
+    expect(only.passed).toBe(true);
+  });
+
+  it('an unknown gate name throws before any step call', async () => {
+    const { step, calls } = sequenced(good);
+    await expect(run(step, 1, { only: ['nope'] })).rejects.toBeInstanceOf(UnknownGateError);
+    expect(calls).toHaveLength(0);
+  });
+
+  it('opt-in gates are registered but run only when named', async () => {
+    const gates = registry();
+    gates.register('storyboard', () => ['nobody on stage'], { optIn: true });
+    expect(gates.defaultNames()).toEqual(['title', 'screens']);
+    const base = { step: sequenced(good).step, gates, tries: 1, context: { kind: 'k' } };
+    expect((await refineWithGates(base)).passed).toBe(true);
+    expect((await refineWithGates({ ...base, step: sequenced(good).step, only: ['storyboard'] })).passed).toBe(false);
+  });
+
+  it('informational lines never fail a gate and are kept on the attempt', async () => {
+    const gates = createGateRegistry<Doc>();
+    gates.register('lint', () => [{ text: 'unrealized data: screens', level: 'info' }, { text: 'note', level: 'info' }]);
+    const out = await refineWithGates({ step: sequenced(good).step, gates, tries: 2 });
+    expect(out.passed).toBe(true);
+    expect(out.attempts[0].notes).toEqual([{ gate: 'lint', text: 'unrealized data: screens' }, { gate: 'lint', text: 'note' }]);
+    gates.register('mixed', () => [{ text: 'fine', level: 'info' }, { text: 'broken', level: 'defect' }]);
+    const failed = await refineWithGates({ step: sequenced(good).step, gates, tries: 1 });
+    expect(failed.attempts[0].report).toEqual([{ gate: 'mixed', failures: ['broken'] }]);
+  });
+
+  it('async gates work, and replace=false refuses a duplicate name', async () => {
+    const gates = createGateRegistry<Doc>();
+    gates.register('slow', async () => ['late']);
+    expect(() => gates.register('slow', () => [], { replace: false })).toThrow(/already registered/);
+    const out = await refineWithGates({ step: sequenced(good).step, gates, tries: 1 });
+    expect(out.attempts[0].report).toEqual([{ gate: 'slow', failures: ['late'] }]);
+  });
+});
+
+describe('llmRefineStep: an injectable client', () => {
+  const provider = (answers: string[]) => {
+    const generate = vi.fn(async (_u: string, _s: string, _o?: GenerateOptions): Promise<LLMResponse> => ({
+      content: answers.shift() ?? '{}', model: 'fake', usage: { promptTokens: 10, completionTokens: 5, totalTokens: 15 },
+    }));
+    return { name: 'fake', availableModels: ['fake'], defaultModel: 'fake', generate, isAvailable: () => true } as ILLMProvider & { generate: typeof generate };
+  };
+  const validate = (json: any) => (typeof json?.title === 'string'
+    ? { valid: true as const, data: { title: json.title, screens: json.screens ?? 0 } }
+    : { valid: false as const, errors: ['title: expected string'] });
+
+  it('sends the brief, previous result and failures as data, and feeds a rejected reply back as a failure', async () => {
+    const p = provider(['not json', JSON.stringify({ title: 'Ok' })]);
+    const step = llmRefineStep<Doc>({ provider: p, systemPrompt: 'sys', brief: 'a skit', validate });
+    const out = await refineWithGates({ step, gates: createGateRegistry<Doc>(), tries: 3 });
+    expect(out.passed).toBe(true);
+    expect(out.attempts[0].report[0].gate).toBe('step');
+    expect(p.generate).toHaveBeenCalledTimes(2);
+    const first = JSON.parse(p.generate.mock.calls[0][0]);
+    const second = JSON.parse(p.generate.mock.calls[1][0]);
+    expect(first).toEqual({ brief: 'a skit' });
+    expect(second.brief).toBe('a skit');
+    expect(second.gate_failures[0].gate).toBe('step');
+    expect(out.attempts[1].cost).toMatchObject({ promptTokens: 10, completionTokens: 5 });
+  });
+
+  it('a provider that throws is surfaced as a step error', async () => {
+    const p = provider([]);
+    p.generate.mockRejectedValueOnce(new Error('401'));
+    const step = llmRefineStep<Doc>({ provider: p, systemPrompt: 's', brief: 'b', validate });
+    await expect(refineWithGates({ step, gates: createGateRegistry<Doc>(), tries: 3 })).rejects.toBeInstanceOf(RefineStepError);
+  });
+});

package/src/__tests__/speech-captions-cli.test.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import { runCli } from '../speech/cli';
+
+const golden: Array<{ fn: string; input: any; expected: any }> = JSON.parse(readFileSync(join(__dirname, 'fixtures', 'captions-golden.json'), 'utf8'));
+const run = (argv: string[], body: unknown) => runCli(argv, { readStdin: async () => JSON.stringify(body) });
+
+describe('startsimpli-speech captions', () => {
+  it.each(golden.map((g, n) => [n, g] as const).filter(([, g]) => g.fn === 'cues_for_beat' || (g.fn === 'cues_from_words' && g.input.words.length)))(
+    'json format equals the Python cues (case %i)', async (_n, g) => {
+      const i = g.input;
+      const words = i.words?.map(({ word, ...r }: any) => ({ text: word, ...r }));
+      const res = await run(['captions', '--format', 'json'], {
+        words, text: i.text, duration: i.duration, offset: i.offset, clauseBreaks: i.clause_breaks, maxWords: i.max_words, maxChars: i.max_chars, maxGap: i.max_gap,
+      });
+      expect(res.exitCode).toBe(0);
+      expect((res.output as any).cues).toEqual(g.expected);
+    });
+
+  it('srt and vtt return the file text; holdGap and fps are applied', async () => {
+    const body = { words: [{ text: 'a', start: 0, end: 1 }, { text: 'b', start: 1.2, end: 2 }], maxWords: 1, holdGapS: 0.5, fps: 10 };
+    const srt = await run(['captions', '--format', 'srt'], body);
+    expect(srt.exitCode).toBe(0);
+    expect((srt.output as any).content).toContain('00:00:00,000 --> 00:00:01,200');
+    expect((srt.output as any).frames).toEqual([[0, 12], [12, 20]]);
+    expect(((await run(['captions', '--format', 'vtt'], body)).output as any).content.startsWith('WEBVTT')).toBe(true);
+  });
+
+  it('usage errors exit 2; unusable words exit 1 with a named error', async () => {
+    expect((await run(['captions', '--format', 'pdf'], { text: 'x', duration: 1 })).exitCode).toBe(2);
+    expect((await run(['captions', '--format', 'json'], {})).exitCode).toBe(2);
+    const bad = await run(['captions', '--format', 'json'], { words: [{ text: 'a', start: 2, end: 1 }] });
+    expect(bad).toMatchObject({ exitCode: 1, output: { error: { code: 'INVALID_WORDS' } } });
+  });
+});

package/src/__tests__/speech-captions.test.ts

@@ -0,0 +1,136 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+import {
+  InvalidWordsError, assertValidWords, captionTiming, cueFrameRange, cuesForBeat, cuesFromText, cuesFromWords,
+  holdGaps, splitWhitespaceTokens, toSrt, toVtt, wordsAreProportional,
+} from '../speech';
+import type { TranscriptWord } from '../speech';
+
+type Golden = { fn: string; input: any; expected: any };
+const golden: Golden[] = JSON.parse(readFileSync(join(__dirname, 'fixtures', 'captions-golden.json'), 'utf8'));
+
+/** The Python code names a word's text `word`. */
+const toWords = (ws: any[] | null | undefined): TranscriptWord[] | undefined =>
+  ws?.map(({ word, ...rest }) => ({ text: word, ...rest }));
+const camel = (o: Record<string, any>, drop: string[]) => ({
+  ...(o.max_words !== undefined && { maxWords: o.max_words }),
+  ...(o.max_chars !== undefined && { maxChars: o.max_chars }),
+  ...(o.max_gap !== undefined && { maxGap: o.max_gap }),
+  ...(o.clause_breaks !== undefined && { clauseBreaks: o.clause_breaks }),
+  ...(o.offset !== undefined && { offset: o.offset }),
+  ...Object.fromEntries(Object.entries(o).filter(([k]) => drop.includes(k))),
+});
+
+const replay: Record<string, (i: any) => unknown> = {
+  cues_from_words: (i) => cuesFromWords(toWords(i.words)!, camel(i, [])),
+  cues_from_text: (i) => cuesFromText(i.text, i.duration, camel(i, [])),
+  cues_for_beat: (i) => cuesForBeat(toWords(i.words), i.text, i.duration, camel(i, [])),
+  hold_gaps: (i) => holdGaps(i.cues, i.max_gap_s),
+  cue_frame_range: (i) => cueFrameRange(i.cue, i.fps),
+  words_are_proportional: (i) => wordsAreProportional(toWords(i.words)!.map((w, n) => ({ ...w, ...(i.flagged ? { alignment: i.flagged } : {}), ...(i.words[n].alignment ? { alignment: i.words[n].alignment } : {}) })), { stepMax: i.step_max, minWords: i.min_words }),
+  check_words: (i) => {
+    try { assertValidWords(toWords(i.words)!); return { ok: true }; } catch (e) {
+      if (!(e instanceof InvalidWordsError)) throw e;
+      return { error: e.message };
+    }
+  },
+};
+
+describe('captions: parity with the Python implementation (golden)', () => {
+  it('has golden cases', () => expect(golden.length).toBeGreaterThanOrEqual(35));
+  it.each(golden.map((g, n) => [`${n} ${g.fn}`, g] as const))('%s', (_n, g) => {
+    expect(replay[g.fn](g.input)).toEqual(g.expected);
+  });
+});
+
+const w = (text: string, step = 0.3): TranscriptWord[] => text.split(' ').map((t, i) => ({ text: t, start: i * step, end: i * step + 0.25 }));
+
+describe('captions: cue building', () => {
+  it('splits at a clause end with at least two tokens before the cut, never mid-clause when it can avoid it', () => {
+    const text = 'Today the frog will hop three feet to the right, and the elephant will watch.';
+    expect(cuesFromWords(w(text), { clauseBreaks: true }).map((c) => c.text))
+      .toEqual(['Today the frog will hop three feet', 'to the right,', 'and the elephant will watch.']);
+    expect(cuesFromWords(w('I watched. It was a very good three feet.'), { clauseBreaks: true }).map((c) => c.text))
+      .toEqual(['I watched.', 'It was a very good three feet.']);
+    // a single-token head is not a cut ("Hi, there ..." keeps the limit split)
+    expect(cuesFromWords(w('Hi, one two three four five six seven'), { clauseBreaks: true }).map((c) => c.text)[0]).toBe('Hi, one two three four five six');
+  });
+  it('holdGaps fills gaps up to the limit and never moves a start or mutates its input', () => {
+    const cues = [{ start: 0, end: 1, text: 'a' }, { start: 1.2, end: 2, text: 'b' }, { start: 3.5, end: 4, text: 'c' }];
+    expect(holdGaps(cues, 0.6).map((c) => c.end)).toEqual([1.2, 2, 4]);
+    expect(holdGaps(cues, 0)).toEqual(cues);
+    expect(cues[0].end).toBe(1);
+  });
+  it('cueFrameRange rounds half to even like Python', () => {
+    expect(cueFrameRange({ start: 1.25, end: 2.75, text: '' }, 10)).toEqual([12, 28]);
+  });
+});
+
+describe('captions: word checks', () => {
+  it('proportional detection: evenly spread characters yes, real vendor alignment no', () => {
+    const even = 'one two three four five six seven eight nine ten'.split(' ').map((t, i, a) => {
+      const start = a.slice(0, i).reduce((s, x) => s + 0.06 * x.length + 0.06, 0);
+      return { text: t, start, end: start + 0.06 * t.length };
+    });
+    expect(wordsAreProportional(even)).toBe(true);
+    const real = [[0, .31], [.35, .52], [.55, 1.1], [1.4, 1.5], [1.52, 2.4], [2.45, 2.6], [2.9, 3.0], [3.02, 3.9]].map(([s, e], i) => ({ text: `word${i}`, start: s, end: e }));
+    expect(wordsAreProportional(real)).toBe(false);
+  });
+  it('assertValidWords rejects empty and disordered transcripts with a named error', () => {
+    expect(() => assertValidWords([])).toThrow(InvalidWordsError);
+    expect(() => assertValidWords([{ text: 'a', start: 1, end: 0.5 }])).toThrow(/ends before it starts/);
+    expect(() => assertValidWords([{ text: 'a', start: 1, end: 2 }, { text: 'b', start: 0.5, end: 3 }])).toThrow(/not in time order/);
+    expect(assertValidWords(w('a b'))).toHaveLength(2);
+  });
+  it('splitWhitespaceTokens shares a multi-word token time evenly', () => {
+    expect(splitWhitespaceTokens([{ text: 'a b', start: 0, end: 1 }, { text: '  ', start: 1, end: 2 }])).toEqual([
+      { text: 'a', start: 0, end: 0.5 }, { text: 'b', start: 0.5, end: 1 },
+    ]);
+  });
+  it('captionTiming is not_measured for proportional words, else reports start errors', () => {
+    const real = [[0, .31], [.35, .52], [.55, 1.1], [1.4, 1.5], [1.52, 2.4], [2.45, 2.6], [2.9, 3.0], [3.02, 3.9]].map(([s, e], i) => ({ text: `w${i}`, start: s, end: e }));
+    const exact = captionTiming([{ start: 0, end: 1.1, text: 'w0 w1 w2' }], real);
+    expect(exact).toMatchObject({ measured: true, n: 1, pass: true, max_abs_start_err_ms: 0 });
+    expect(captionTiming([{ start: 0.5, end: 1.1, text: 'w0 w1 w2' }], real)).toMatchObject({ pass: false });
+  });
+});
+
+/** A strict reader for the two formats, independent of the writer. */
+function parseCues(text: string, kind: 'srt' | 'vtt') {
+  const stamp = kind === 'srt' ? /^(\d\d):([0-5]\d):([0-5]\d),(\d{3})$/ : /^(\d\d):([0-5]\d):([0-5]\d)\.(\d{3})$/;
+  const ms = (s: string) => { const m = stamp.exec(s); if (!m) throw new Error(`bad timestamp ${s}`); return ((+m[1] * 60 + +m[2]) * 60 + +m[3]) * 1000 + +m[4]; };
+  let body = text;
+  if (kind === 'vtt') { if (!body.startsWith('WEBVTT\n\n')) throw new Error('missing WEBVTT header'); body = body.slice(8); }
+  if (!body.endsWith('\n')) throw new Error('no trailing newline');
+  return body.trimEnd().split('\n\n').map((block, n) => {
+    const lines = block.split('\n');
+    let i = 0;
+    if (kind === 'srt') { if (lines[i++] !== String(n + 1)) throw new Error(`bad index in ${block}`); }
+    const [a, arrow, b] = lines[i++].split(' ');
+    if (arrow !== '-->') throw new Error(`bad timing line in ${block}`);
+    const start = ms(a); const end = ms(b);
+    if (end <= start) throw new Error('end before start');
+    const cueText = lines.slice(i).join('\n');
+    if (!cueText || cueText.includes('\n\n')) throw new Error('empty cue text');
+    return { start: start / 1000, end: end / 1000, text: cueText };
+  });
+}
+
+describe('captions: SRT and VTT output', () => {
+  const cues = [{ start: 0, end: 1.2345, text: 'Hello there,' }, { start: 3661.5, end: 3662, text: 'second --> cue' }, { start: 3662, end: 3662.0004, text: 'x' }];
+  it.each([['srt', toSrt], ['vtt', toVtt]] as const)('%s parses back to the same cues (millisecond precision)', (kind, write) => {
+    const back = parseCues(write(cues), kind);
+    expect(back).toHaveLength(2 + 1);
+    expect(back[0]).toEqual({ start: 0, end: 1.235, text: 'Hello there,' });
+    expect(back[1].start).toBe(3661.5);
+  });
+  it('formats carry the right separators and header', () => {
+    expect(toSrt(cues)).toContain('00:00:00,000 --> 00:00:01,235');
+    expect(toVtt(cues).startsWith('WEBVTT\n\n00:00:00.000 --> 00:00:01.235')).toBe(true);
+  });
+  it('an end that rounds to its start is lifted one millisecond so the cue stays valid', () => {
+    expect(parseCues(toSrt(cues), 'srt')[2]).toEqual({ start: 3662, end: 3662.001, text: 'x' });
+  });
+});

package/src/__tests__/speech-cli.test.ts

@@ -0,0 +1,67 @@
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { resetMockSpeechBehavior, setMockSpeechBehavior } from '../speech';
+import { runCli } from '../speech/cli';
+
+afterEach(() => { resetMockSpeechBehavior(); vi.unstubAllEnvs(); });
+
+const run = (argv: string[], stdin = '{}') => {
+  vi.stubEnv('SPEECH_PROVIDER', 'mock');
+  return runCli(argv, { readStdin: async () => stdin });
+};
+const tmp = () => mkdtemp(join(tmpdir(), 'speech-cli-'));
+
+describe('startsimpli-speech', () => {
+  it('synthesize: JSON in on stdin, audio to --out, JSON result on stdout', async () => {
+    const dir = await tmp();
+    const out = join(dir, 'a.mp3');
+    const res = await run(['synthesize', '--out', out], JSON.stringify({ text: '[calm] hi you', voiceId: 'v' }));
+    expect(res.exitCode).toBe(0);
+    expect(res.output).toMatchObject({ audioPath: out, mimeType: 'audio/mpeg', provider: 'mock', usage: { characters: 13 } });
+    expect((res.output as any).words.map((w: any) => w.text)).toEqual(['hi', 'you']);
+    expect((res.output as any).audio).toBeUndefined();
+    expect((await readFile(out)).byteLength).toBe((res.output as any).bytes);
+  });
+
+  it('synthesize: --in file and flags override the request', async () => {
+    const dir = await tmp();
+    const input = join(dir, 'req.json');
+    await writeFile(input, JSON.stringify({ text: 'hi', voiceId: 'from-file' }));
+    const res = await run(['synthesize', '--in', input, '--out', join(dir, 'o.mp3'), '--voice', 'from-flag', '--voice-settings', '{"stability":0.2}']);
+    expect(res.exitCode).toBe(0);
+    expect((res.output as any).voiceId).toBe('from-flag');
+  });
+
+  it('transcribe: reads audioPath, infers the mime type, returns the transcript', async () => {
+    const dir = await tmp();
+    const audio = join(dir, 'n.m4a');
+    await writeFile(audio, new Uint8Array([1, 2, 3]));
+    setMockSpeechBehavior({ text: 'hello' });
+    const res = await run(['transcribe'], JSON.stringify({ audioPath: audio }));
+    expect(res).toMatchObject({ exitCode: 0, output: { text: 'hello', provider: 'mock' } });
+  });
+
+  it('a provider failure is JSON on stdout with exit 1 and the typed code', async () => {
+    setMockSpeechBehavior({ authError: true });
+    const res = await run(['synthesize', '--out', join(await tmp(), 'x.mp3')], '{"text":"hi"}');
+    expect(res).toMatchObject({ exitCode: 1, output: { error: { code: 'AUTHENTICATION_ERROR', retryable: false, statusCode: 401 } } });
+  });
+
+  it.each([
+    [[], '{}', /usage/],
+    [['sing'], '{}', /usage/],
+    [['synthesize'], '{"text":"hi"}', /--out/],
+    [['synthesize', '--out'], '{}', /needs a value/],
+    [['synthesize', '--bogus', 'x'], '{}', /unknown argument/],
+    [['synthesize', '--out', 'x'], 'not json', /JSON object/],
+    [['transcribe'], '{}', /audioPath/],
+    [['synthesize', '--out', 'x', '--voice-settings', '[1]'], '{"text":"hi"}', /voice-settings/],
+  ])('malformed command %j exits 2 with a message', async (argv, stdin, message) => {
+    const res = await run(argv as string[], stdin);
+    expect(res.exitCode).toBe(2);
+    expect((res.output as any).error.message).toMatch(message);
+  });
+});