agenticreplay 0.1.0 → 0.1.2

package/packages/cli/test/api.test.ts

@@ -1,178 +0,0 @@
-import { execFile } from 'node:child_process';
-import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { promisify } from 'node:util';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { AgenticReplay } from '../src/api.js';
-import { AGENTICREPLAY_VERSION } from '../src/version.js';
-import { startResponsesModel } from './fixtures/responses-model.mjs';
-
-const run = promisify(execFile);
-const here = dirname(fileURLToPath(import.meta.url));
-const AGENT = join(here, 'fixtures', 'responses-agent.mjs');
-
-/**
- * Driving agenticreplay from code.
- *
- * Everything agenticreplay knows was reachable only by running a command and reading a terminal. `agenticreplay
- * show` computed a timeline and then formatted it away; `agenticreplay list` returned `void`. So an agent
- * — or a script, or a CI job — that wanted to ask "what diverged when I replayed that run?" had
- * to parse `info replay.done reused=2/2 exact=2 divergences=0` out of stdout.
- *
- * This is the same work the commands do, returning the data instead of printing it. The commands
- * render what it returns, so there is one source of truth and the terminal is a view of it.
- */
-describe('AgenticReplay — the programmatic API', () => {
-  let workspace: string;
-  let model: Awaited<ReturnType<typeof startResponsesModel>>;
-  let agenticreplay: AgenticReplay;
-
-  beforeEach(async () => {
-    workspace = await mkdtemp(join(tmpdir(), 'agenticreplay-api-'));
-    model = await startResponsesModel();
-    await run('git', ['init', '-q'], { cwd: workspace });
-    await run('git', ['config', 'user.email', 'test@example.com'], { cwd: workspace });
-    await run('git', ['config', 'user.name', 'Test'], { cwd: workspace });
-    await writeFile(join(workspace, 'auth.ts'), 'export const fixed = false;\n');
-    agenticreplay = new AgenticReplay({ cwd: workspace });
-  });
-
-  afterEach(async () => {
-    await model.close();
-    await rm(workspace, { recursive: true, force: true });
-  });
-
-  const record = () =>
-    agenticreplay.record({
-      adapter: 'generic-openai',
-      command: [process.execPath, AGENT],
-      upstream: { openai: model.url },
-    });
-
-  it('records a run and returns what it produced', async () => {
-    const result = await record();
-    expect(result.runId).toMatch(/^run_[0-9a-f]+$/);
-    expect(result.exitCode).toBe(0);
-    expect(result.events).toBeGreaterThan(4);
-    // `join`, not a literal: the assertion spelled the separator `/` and so only ever held on
-    // POSIX. The API returns a real path, and on Windows that is `.agenticreplay\runs\run_…`.
-    expect(result.runDir).toContain(join('.agenticreplay', 'runs'));
-  });
-
-  it('warns in the result, not only on a terminal, when nothing was captured', async () => {
-    // The empty-trace failure has to be visible to a caller that has no stdout to read.
-    const result = await agenticreplay.record({
-      adapter: 'generic-openai',
-      command: [process.execPath, join(here, 'fixtures', 'deaf-agent.mjs')],
-      upstream: { openai: model.url },
-    });
-    expect(result.modelExchanges).toBe(0);
-    expect(result.warnings.map((w) => w.event)).toContain('capture.empty');
-  });
-
-  it('lists runs as data, newest first', async () => {
-    const first = await record();
-    const runs = await agenticreplay.list();
-    expect(runs.map((r) => r.runId)).toContain(first.runId);
-    expect(runs[0]).toMatchObject({ runId: expect.any(String), dir: expect.any(String) });
-  });
-
-  it('returns an empty list rather than throwing in a workspace with no runs', async () => {
-    const empty = new AgenticReplay({ cwd: await mkdtemp(join(tmpdir(), 'agenticreplay-empty-')) });
-    await expect(empty.list()).resolves.toEqual([]);
-  });
-
-  it('returns the timeline `agenticreplay show` prints, as objects', async () => {
-    const recorded = await record();
-    const timeline = await agenticreplay.show(recorded.runId);
-
-    expect(timeline.runId).toBe(recorded.runId);
-    // Versioned, as the manifest records it: which adapter *version* produced a trace is the
-    // fact that matters when an adapter has rotted and a recording no longer replays.
-    //
-    // Against the constant rather than a literal. A hardcoded version here asserts nothing about
-    // the shape being tested and turns every release into a failing build — which is exactly what
-    // it did on the 0.1.1 bump, where the only change in the diff was the version itself.
-    expect(timeline.adapter).toBe(`generic-openai@${AGENTICREPLAY_VERSION}`);
-    expect(timeline.exitCode).toBe(0);
-    expect(timeline.events.length).toBeGreaterThan(4);
-    // The rows a caller actually wants to filter on.
-    const tool = timeline.events.find((e) => e.kind === 'TOOL');
-    expect(tool).toMatchObject({ seq: expect.any(Number), label: 'edit_file' });
-    expect(timeline.usage).toMatchObject({ input: expect.any(Number), output: expect.any(Number) });
-  });
-
-  it('resolves `last` the way the CLI does', async () => {
-    const recorded = await record();
-    expect((await agenticreplay.show('last')).runId).toBe(recorded.runId);
-    expect((await agenticreplay.show()).runId).toBe(recorded.runId);
-  });
-
-  it('gives a caller the raw events too, not only the rendered rows', async () => {
-    // A rendered row is a view. An agent asking "which tool call wrote that file" needs the event.
-    const recorded = await record();
-    const events = await agenticreplay.events(recorded.runId);
-    expect(events.some((e) => e.type === 'tool.call')).toBe(true);
-    expect(events.some((e) => e.type === 'fs.change')).toBe(true);
-  });
-
-  it('returns the checkpoints a fork can start from', async () => {
-    const recorded = await record();
-    const checkpoints = await agenticreplay.checkpoints(recorded.runId);
-    expect(checkpoints.length).toBeGreaterThan(0);
-    expect(checkpoints[0]).toMatchObject({ seq: expect.any(Number), turn: expect.any(Number) });
-  });
-
-  it('replays and returns the numbers, so nothing has to be scraped from a log line', async () => {
-    const recorded = await record();
-    const before = model.calls.length;
-
-    const replay = await agenticreplay.replay(recorded.runId);
-
-    expect(replay).toMatchObject({
-      runId: recorded.runId,
-      mode: 'exact',
-      canonicalExact: 2,
-      divergences: 0,
-      liveCalls: 0,
-      exitCode: 0,
-    });
-    expect(model.calls.length).toBe(before);
-  });
-
-  it('exports a self-contained file and says where it went', async () => {
-    const recorded = await record();
-    const target = join(workspace, 'bug.html');
-
-    const exported = await agenticreplay.export(recorded.runId, { out: target });
-
-    expect(exported.path).toBe(target);
-    expect(exported.bytes).toBeGreaterThan(1000);
-    expect(await readFile(target, 'utf8')).toContain(recorded.runId);
-  });
-
-  it('throws a real error naming the run, not a process exit', async () => {
-    // A library that calls process.exit is a library nobody can build on.
-    await expect(agenticreplay.show('run_doesnotexist')).rejects.toThrow(/run_doesnotexist/);
-  });
-
-  it('never writes to the terminal of the process that embedded it', async () => {
-    // The commands own stdout. The API must not, or a caller's own output is interleaved with
-    // agenticreplay's log lines and every JSON consumer downstream breaks.
-    const chunks: string[] = [];
-    const write = process.stdout.write.bind(process.stdout);
-    process.stdout.write = ((s: string) => {
-      chunks.push(String(s));
-      return true;
-    }) as typeof process.stdout.write;
-    try {
-      await record();
-      await agenticreplay.list();
-    } finally {
-      process.stdout.write = write;
-    }
-    expect(chunks.join('')).not.toContain('info recorded');
-  });
-});

package/packages/cli/test/archive.test.ts

@@ -1,143 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { readArchive, writeArchive, type ArchiveEntry } from '../src/archive.js';
-
-/**
- * The archive format `agenticreplay push` speaks.
- *
- * A run is pushed as a zip because that is what the gateway's importer reads, and it is read back
- * by `agenticreplay pull`. Both directions live here so the pair is tested against each other rather than
- * against a fixture that could drift from either.
- *
- * Written by hand rather than with a library because the CLI takes no new runtime dependencies
- * (CONTRIBUTING, "Rules of the road") — zlib is a node builtin, and the subset of zip a trace needs
- * is small. The tests below are what makes hand-rolling it defensible.
- */
-describe('archive', () => {
-  const entries: ArchiveEntry[] = [
-    { name: 'run-1/manifest.json', bytes: new TextEncoder().encode('{"run_id":"run-1"}\n') },
-    { name: 'run-1/events.jsonl', bytes: new TextEncoder().encode('{"seq":1}\n{"seq":2}\n') },
-    { name: 'run-1/blobs/ab/abcd', bytes: new Uint8Array([0, 1, 2, 250, 255]) },
-  ];
-
-  it('round-trips every entry byte for byte', async () => {
-    const back = await readArchive(await writeArchive(entries));
-    expect(back.map((e) => e.name).sort()).toEqual(entries.map((e) => e.name).sort());
-    for (const original of entries) {
-      const found = back.find((e) => e.name === original.name);
-      expect(found, original.name).toBeDefined();
-      expect(Array.from(found!.bytes), original.name).toEqual(Array.from(original.bytes));
-    }
-  });
-
-  /**
-   * The one property the gateway actually enforces: it recomputes the integrity root over
-   * events.jsonl and refuses the push if it does not match the manifest. So the bytes on disk must
-   * survive the round trip EXACTLY — no re-serialising, no newline normalising, no re-ordering of
-   * JSON keys. A zip that merely produces equivalent JSON would pass the test above if it were
-   * written loosely, and be rejected by the server.
-   */
-  it('preserves bytes that a re-serialiser would change', async () => {
-    const awkward = new TextEncoder().encode('{"b":1,"a":2}\r\n{"z":[ 1,2 ]}\n\n');
-    const back = await readArchive(
-      await writeArchive([{ name: 'r/events.jsonl', bytes: awkward }]),
-    );
-    expect(Array.from(back[0]!.bytes)).toEqual(Array.from(awkward));
-  });
-
-  it('handles an empty entry and a large one', async () => {
-    const big = new Uint8Array(300_000);
-    for (let i = 0; i < big.length; i++) big[i] = (i * 7) % 256;
-    const back = await readArchive(
-      await writeArchive([
-        { name: 'r/empty', bytes: new Uint8Array(0) },
-        { name: 'r/big', bytes: big },
-      ]),
-    );
-    expect(back.find((e) => e.name === 'r/empty')!.bytes.length).toBe(0);
-    expect(Array.from(back.find((e) => e.name === 'r/big')!.bytes)).toEqual(Array.from(big));
-  });
-
-  it('refuses an archive whose central directory is not where the trailer says', async () => {
-    const good = await writeArchive(entries);
-    const corrupt = new Uint8Array(good);
-    // Rewrite the central-directory offset in the end-of-central-directory record.
-    const eocd = corrupt.length - 22;
-    new DataView(corrupt.buffer, corrupt.byteOffset).setUint32(eocd + 16, 0xfffffff0, true);
-    await expect(readArchive(corrupt)).rejects.toThrow(/central directory/i);
-  });
-
-  /**
-   * A zip's recorded offsets are relative to the start of the ARCHIVE, which need not be the start
-   * of the file — anything prepended shifts them all by a constant. Recovering that constant from
-   * the trailer is what makes such a file readable.
-   *
-   * This test exists because the first version of it did not: a probe that hard-coded the base to
-   * zero passed the whole suite, so the arithmetic was carrying no weight. Untested cleverness is
-   * worse than none, because it reads as deliberate.
-   */
-  it('reads an archive with bytes prepended to it', async () => {
-    const zip = await writeArchive(entries);
-    const prefixed = new Uint8Array(64 + zip.length);
-    prefixed.fill(0x5a, 0, 64);
-    prefixed.set(zip, 64);
-    const back = await readArchive(prefixed);
-    expect(back.map((e) => e.name).sort()).toEqual(entries.map((e) => e.name).sort());
-    const manifest = back.find((e) => e.name === 'run-1/manifest.json')!;
-    expect(new TextDecoder().decode(manifest.bytes)).toBe('{"run_id":"run-1"}\n');
-  });
-
-  it('refuses bytes that are not a zip at all', async () => {
-    await expect(readArchive(new TextEncoder().encode('not a zip'))).rejects.toThrow(/zip/i);
-  });
-
-  /**
-   * A trace archive names blobs by digest under blobs/<ab>/<sha>, so an entry name containing `..`
-   * or an absolute path is either a bug or an attack. `agenticreplay pull` writes what it reads to disk, so
-   * the check belongs here, at the point the name is parsed, rather than in the caller.
-   */
-  it('refuses entry names that would escape the run directory', async () => {
-    for (const name of ['../escape', '/abs/path', 'run/../../escape', 'a\\..\\b']) {
-      const zip = await writeArchive([{ name, bytes: new Uint8Array([1]) }]);
-      await expect(readArchive(zip), name).rejects.toThrow(/unsafe|name/i);
-    }
-  });
-
-  /**
-   * THE WRITER REFUSES WHAT ITS OWN FIELDS CANNOT HOLD.
-   *
-   * The EOCD carries the entry count in 16 bits, and writeArchive wrote
-   * `entries.length` into it unchecked. The failure is graded and the middle
-   * band is the dangerous one:
-   *
-   *   65535  -> the count IS the zip64 sentinel; readArchive refuses the file
-   *   65536  -> wraps to 0; readArchive returns no entries
-   *   70000  -> wraps to 4464; readArchive returns 4464 entries AND SUCCEEDS
-   *
-   * A run directory holds one file per unique content-addressed blob, so a
-   * long session with heavy tool output reaches these counts on its own. In
-   * that third band `agenticreplay push` sends a structurally corrupt archive and
-   * `agenticreplay pull` installs a fraction of the run reporting success — silent
-   * partial data loss, which is the one outcome this file's stated invariant
-   * ("entry bytes round-trip EXACTLY") rules out.
-   *
-   * Refusing is the fix, not zip64: the reader refuses zip64 too, so writing
-   * it would produce archives this CLI cannot read back.
-   */
-  it('refuses to write more entries than the trailer can count', async () => {
-    const many = (n: number) =>
-      Array.from({ length: n }, (_, i) => ({
-        name: `run-1/blobs/aa/${i}`,
-        bytes: new Uint8Array(0),
-      }));
-    // The sentinel itself, which the reader treats as zip64.
-    await expect(writeArchive(many(0xffff))).rejects.toThrow(/too many entries|65534/i);
-    // And the band that wraps to a plausible number and reads back short.
-    await expect(writeArchive(many(0x10000))).rejects.toThrow(/too many entries|65534/i);
-    // One below the sentinel is the largest archive the format can express,
-    // and must still be written — a bound that refuses valid input is a
-    // different bug in the same place.
-    const ok = await writeArchive(many(0xfffe));
-    const back = await readArchive(ok);
-    expect(back.length).toBe(0xfffe);
-  });
-});

package/packages/cli/test/args.test.ts

@@ -1,164 +0,0 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { describe, expect, it } from 'vitest';
-import { parseArgs } from '../src/args.js';
-
-describe('flags that never take a value', () => {
-  /**
-   * The parser had no notion of a value-less flag: any flag followed by a non-flag token consumed
-   * it, and `bool()` then returned its fallback because the value was a string. So the flag was
-   * silently off *and* the positional was gone.
-   *
-   * Two of those are dangerous rather than merely wrong. `agenticreplay replay --worktree last` is
-   * documented as "never touches your files", and with `--worktree` swallowed it restores the
-   * recorded tree over the working directory instead. `agenticreplay record --tls-intercept codex` turns
-   * interception off and loses the agent name, so record auto-detects and may capture a different
-   * harness entirely. Neither warned.
-   *
-   * Flag-then-positional is the more natural order, and every existing test happened to put the
-   * flag last, which is why nothing caught it.
-   */
-  /*
-   * `--force` was registered in the other half of the flag contract (flags.ts: push and pull both
-   * take it) and read with `args.bool('force')`, but never added HERE — so it was value-taking,
-   * and the natural `agenticreplay push --force run_abc` swallowed the selector.
-   *
-   * That one is worse than the two above, because it DISCLOSES. With the selector gone,
-   * pushCommand falls back to `positionals[0] ?? 'last'` and packs a DIFFERENT recording — the
-   * newest one in the workspace — POSTs it to the gateway without `?force=1`, and prints
-   * `push.done run=<the other run>`. A success line naming a run the user did not ask for.
-   *
-   * The list this loop iterates is hand-written, which is exactly how the new flag missed it, so
-   * this is a poor fence — see the invariant test below, which derives the set instead.
-   */
-  it('leaves the positional alone and reads as true', () => {
-    for (const flag of [
-      '--worktree',
-      '--in-place',
-      '--loose',
-      '--ui',
-      '--dry-run',
-      '--verbose',
-      '--force',
-    ]) {
-      const args = parseArgs(['replay', flag, 'last']);
-      expect(args.positionals, `${flag} ate the positional`).toEqual(['last']);
-      expect(args.bool(flag.slice(2)), `${flag} did not read as true`).toBe(true);
-    }
-  });
-
-  it('keeps the agent name when interception is asked for', () => {
-    const args = parseArgs(['record', '--tls-intercept', 'codex']);
-    expect(args.positionals).toEqual(['codex']);
-    expect(args.bool('tls-intercept')).toBe(true);
-  });
-
-  it('still lets a value-taking flag take its value', () => {
-    const args = parseArgs(['compare', 'last', '--models', 'a,b', '--from', '4']);
-    expect(args.positionals).toEqual(['last']);
-    expect(args.list('models')).toEqual(['a', 'b']);
-    expect(args.num('from')).toBe(4);
-  });
-
-  it('still honours an explicit --flag=value for a boolean', () => {
-    expect(parseArgs(['replay', '--loose=false', 'last']).bool('loose')).toBe(false);
-    expect(parseArgs(['replay', '--no-worktree', 'last']).bool('worktree', true)).toBe(false);
-  });
-});
-
-describe('parseArgs', () => {
-  it('reads the command and its positionals', () => {
-    const a = parseArgs(['record', 'claude']);
-    expect(a.command).toBe('record');
-    expect(a.positionals).toEqual(['claude']);
-  });
-
-  it('parses long flags with = and with a following value', () => {
-    expect(parseArgs(['replay', 'last', '--model=gpt-5.2']).flags.model).toBe('gpt-5.2');
-    expect(parseArgs(['replay', 'last', '--model', 'gpt-5.2']).flags.model).toBe('gpt-5.2');
-  });
-
-  it('parses booleans and --no- negation', () => {
-    expect(parseArgs(['record', '--ui']).flags.ui).toBe(true);
-    expect(parseArgs(['record', '--no-fs']).flags.fs).toBe(false);
-  });
-
-  it('parses numbers where the value is numeric', () => {
-    expect(parseArgs(['replay', 'last', '--from', '17']).flags.from).toBe(17);
-  });
-
-  it('splits comma lists', () => {
-    expect(parseArgs(['compare', 'last', '--models', 'a,b,c']).list('models')).toEqual([
-      'a',
-      'b',
-      'c',
-    ]);
-  });
-
-  it('keeps everything after -- as passthrough argv for the child agent', () => {
-    const a = parseArgs(['record', 'claude', '--ui', '--', '--dangerously-skip', '-p', 'hi']);
-    expect(a.flags.ui).toBe(true);
-    expect(a.passthrough).toEqual(['--dangerously-skip', '-p', 'hi']);
-    expect(a.positionals).toEqual(['claude']);
-  });
-
-  it('supports short flags', () => {
-    expect(parseArgs(['export', 'last', '-o', 'bug.html']).flags.o).toBe('bug.html');
-  });
-
-  it('treats a bare invocation as the help command', () => {
-    expect(parseArgs([]).command).toBe('help');
-  });
-
-  it('does not swallow a negative number as a flag value', () => {
-    expect(parseArgs(['replay', 'last', '--from', '-1']).flags.from).toBe(-1);
-  });
-});
-
-/*
-THE VALUE-LESS SET IS DERIVED, NOT TRUSTED.
-
-Three flags have now shipped value-taking by accident — `--worktree`, `--tls-intercept`, and
-`--force` — and each time the fix was to add one more string to a hand-written list, and each time
-the NEXT flag missed it. The list and the flags are edited in different files by different changes,
-so nothing makes them agree.
-
-A flag is boolean by the way it is READ: `args.bool('x')`. That call is the declaration, so this
-derives the set from every such call across the CLI source and asserts each one is value-less. A
-flag added tomorrow is covered the day it is written, without anyone remembering this file.
-
-The failure it prevents is not cosmetic. A boolean flag that takes a value reads as FALSE while
-eating the next token, so the feature silently does not happen AND the argument disappears —
-`--worktree` restored over the working directory, `--tls-intercept` captured a different harness,
-`--force` pushed a different recording to a shared gateway and called it success.
-*/
-describe('every boolean flag is value-less', () => {
-  const SRC = join(import.meta.dirname, '..', 'src');
-
-  const sourceFiles = (dir: string): string[] =>
-    readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
-      const full = join(dir, e.name);
-      if (e.isDirectory()) return sourceFiles(full);
-      return e.isFile() && full.endsWith('.ts') ? [full] : [];
-    });
-
-  it('derives the set from every args.bool() call in the CLI', async () => {
-    const { VALUELESS } = await import('../src/args.js');
-    const read: { flag: string; file: string }[] = [];
-    for (const file of sourceFiles(SRC)) {
-      const src = readFileSync(file, 'utf8');
-      for (const m of src.matchAll(/\.bool\(\s*['"]([a-z][a-z0-9-]*)['"]/g)) {
-        read.push({ flag: m[1], file });
-      }
-    }
-
-    // A guard on the guard: a regex that stops matching would make this pass over nothing.
-    expect(read.length, 'found no args.bool() calls — the pattern has drifted').toBeGreaterThan(5);
-
-    const missing = read.filter((r) => !VALUELESS.has(r.flag));
-    expect(
-      missing.map((r) => `${r.flag} (${r.file.slice(SRC.length + 1)})`),
-      'these flags are read as booleans but can swallow the next token',
-    ).toEqual([]);
-  });
-});