agenticreplay 0.1.0 → 0.1.2

package/packages/cli/src/flags.ts

@@ -1,316 +0,0 @@
-import { NUMERIC, VALUELESS } from './args.js';
-import type { ParsedArgs } from './args.js';
-
-/**
- * Which flags each command accepts.
- *
- * The parser takes any flag it is given, which is right for parsing and wrong for a CLI: a
- * mistyped or invented flag was accepted in silence and simply had no effect, so a run that did
- * something other than what was asked reported success.
- *
- * Every entry below is a flag the code actually reads — collected from the `args.bool/str/num/list`
- * calls in each command and in the helpers it shares — not from what the documentation describes.
- * Building it the other way round is how a flag that never existed came to be recommended in the
- * first place, and a list that allows more than the code understands would rebuild exactly that.
- */
-export const GLOBAL = ['ci', 'json', 'verbose', 'color', 'help', 'version', 'h'] as const;
-
-/** Read by `config.ts` for any command that can reach a provider. */
-const UPSTREAM = ['upstream-anthropic', 'upstream-openai'] as const;
-
-/** Read by `tls-capture.ts`, which record, replay and compare all set up. */
-const TLS = ['tls-intercept', 'tls-hosts', 'max-body-bytes', 'max-buffered-bytes'] as const;
-
-/**
- * How much of a retrieval call's answer to keep. Only the commands that *make* one have it:
- * replay serves what a recording already holds, and cannot change what was stored then.
- */
-const RETRIEVAL = ['retrieval-store'] as const;
-
-export const BY_COMMAND: Record<string, readonly string[]> = {
-  quickstart: ['dir', 'full'],
-  // push/pull reach a gateway the user names. `--force` means two different deliberate overrides:
-  // on push, store despite a secret-scan finding; on pull, replace a local run that already exists.
-  //
-  // `--fs` belongs here because `pushCommand` reads it (`args.bool('fs')`) and the help text
-  // offers it. Leaving it out did not make push ignore the flag — it made push REFUSE it, before
-  // the implementation ever saw it, and the refusal named only the two flags that were listed. So
-  // the workspace snapshots could not be shipped by any invocation, every run on the gateway came
-  // back with `blob_count: 0`, and forking a pulled run died in `git read-tree` on a tree object
-  // that had never been sent. This list is meant to be counted from the `args.*` call sites; that
-  // one was missed.
-  push: ['gateway', 'force', 'fs'],
-  pull: ['gateway', 'force'],
-  record: ['fs', 'shell', 'agent-spans', 'mcp-config', ...RETRIEVAL, ...TLS, ...UPSTREAM],
-  attach: [
-    'for',
-    'bind',
-    'advertise',
-    'port',
-    'remote-ca-path',
-    'replay',
-    'loose',
-    ...RETRIEVAL,
-    ...TLS,
-    ...UPSTREAM,
-  ],
-  replay: [
-    'from',
-    'model',
-    'fs',
-    'in-place',
-    'worktree',
-    'loose',
-    'trace',
-    'port',
-    'ui',
-    'mcp-config',
-    'serialize',
-    ...TLS,
-    ...UPSTREAM,
-    'quiet',
-  ],
-  // `fs` because compare forks through the same code replay does, and that path reads
-  // `args.bool('fs', true)` twice: once for the checkpoint restore, once for the fork's own
-  // capture. Without the entry `agenticreplay compare --no-fs` was refused while `agenticreplay replay --no-fs`
-  // worked, for two spellings of the same fork.
-  compare: ['from', 'models', 'verify', 'share', 'loose', 'fs', ...TLS, ...UPSTREAM],
-  show: [],
-  checkpoints: [],
-  events: [],
-  // `inspect.ts` serves graph, export and ui from one file, so the flags of all three are read
-  // there. Reading a file rather than a command is how the first version of this list came to
-  // give `export` two flags and lose the three it needs — `--card`, `--graph-card` and `--to`
-  // are the picture commands the README documents, and rejecting them broke a working feature.
-  graph: ['to'],
-  export: ['o', 'out', 'card', 'graph-card', 'to'],
-  ui: ['port'],
-  scrub: ['match', 'matches', 'dry-run', 'drop-fs'],
-  // `--remote` asks the gateway instead of this directory. `--gateway` stays what it is for
-  // push and pull — an optional override of which host — rather than doubling as the switch, so
-  // that a configured destination needs no url typed at it. `--source` and `--limit` are the
-  // listing's own parameters, passed through rather than reimplemented here.
-  list: ['remote', 'gateway', 'source', 'limit'],
-  gc: ['older-than', 'keep', 'dry-run'],
-  doctor: [],
-  setup: ['gateway', 'key', 'key-env', 'models'],
-  models: [],
-  mcp: [],
-  help: [],
-};
-
-/** The closest known flag, for a name that is probably a typo rather than an invention. */
-function nearest(name: string, known: readonly string[]): string | undefined {
-  let best: { name: string; score: number } | undefined;
-  for (const candidate of known) {
-    // Prefix and containment both catch the realistic slips: `--worktre`, `--model-s`.
-    const prefix = candidate.startsWith(name) || name.startsWith(candidate) ? 2 : 0;
-    const contains = candidate.includes(name) || name.includes(candidate) ? 1 : 0;
-    const score = Math.max(prefix, contains);
-    if (score > 0 && (best === undefined || score > best.score)) best = { name: candidate, score };
-  }
-  return best?.name;
-}
-
-/**
- * Flags a command has only ALONGSIDE another.
- *
- * `agenticreplay list` lists this directory unless `--remote` asks the gateway, and `--gateway`, `--source`
- * and `--limit` mean something only to the gateway. Being on the list above let them past
- * `assertKnownFlags` unconditionally — and then the local listing ran and dropped every one of
- * them without a word. `agenticreplay list --gateway <url>` printed THIS directory's runs to someone who
- * had just named a host, which reads as that host's answer: the silently-ignored instruction this
- * file exists to refuse, let back in by the entry that added the flags.
- */
-const NEEDS: Record<string, { flags: readonly string[]; with: string; otherwise: string }> = {
-  list: {
-    flags: ['gateway', 'source', 'limit'],
-    with: 'remote',
-    otherwise:
-      'without it, agenticreplay list shows the runs in this directory and asks no gateway anything',
-  },
-};
-
-function assertCompanions(args: ParsedArgs): void {
-  const rule = NEEDS[args.command];
-  if (rule === undefined || args.bool(rule.with)) return;
-  const orphaned = rule.flags.filter((f) => args.has(f));
-  if (orphaned.length === 0) return;
-  throw new Error(
-    `${orphaned.map((f) => `--${f}`).join(', ')} ${orphaned.length === 1 ? 'asks' : 'ask'} ` +
-      `the gateway, and nothing here does: add --${rule.with}\n  ${rule.otherwise}`,
-  );
-}
-
-/**
- * Reject a flag this command does not have.
- *
- * Throws rather than warns. A flag is an instruction, and carrying on having ignored one produces
- * a run that did something other than what was asked while reporting success — which is the
- * failure this whole tool exists to make visible.
- */
-export function assertKnownFlags(args: ParsedArgs): void {
-  const allowed = BY_COMMAND[args.command];
-  // An unknown command is reported by the dispatcher, which can say more about it than this can.
-  if (allowed === undefined) return;
-  const known = [...allowed, ...GLOBAL];
-  const unknown = Object.keys(args.flags).filter((name) => !known.includes(name));
-  // Names first: "unknown flag --modle" is a better answer than "--modle needs a value".
-  if (unknown.length === 0) {
-    // Before the values: `--limit abc` without `--remote` is wrong for a reason that has nothing
-    // to do with `abc`, and that is the reason worth giving.
-    assertCompanions(args);
-    assertUsableValues(args, known);
-    return;
-  }
-
-  const [first] = unknown;
-  const suggestion = nearest(first!, known);
-  throw new Error(
-    `unknown flag ${dashed(first!)} for "agenticreplay ${args.command}"` +
-      (suggestion === undefined ? '' : `\n  did you mean --${suggestion}?`) +
-      `\n  flags for this command: ${allowed.length === 0 ? '(none)' : allowed.map((f) => `--${f}`).join(' ')}`,
-  );
-}
-
-/**
- * How many positional arguments each command reads.
- *
- * Counted from the `positionals[0]` call sites, the same way the flag list above is counted from
- * the `args.*` ones. `record` reads an agent name and the run commands read a selector; the seven
- * that read none genuinely take none — `attach` is configured entirely by flags, and `list`, `gc`,
- * `doctor`, `setup`, `models` and `mcp` take nothing at all.
- */
-const POSITIONALS: Record<string, number> = {
-  record: 1,
-  replay: 1,
-  compare: 1,
-  show: 1,
-  events: 1,
-  checkpoints: 1,
-  graph: 1,
-  export: 1,
-  // push defaults to the last run, like every other run-taking command; pull needs to be told
-  // which run to fetch, because "last" means nothing on a machine that has not seen it yet.
-  push: 1,
-  pull: 1,
-  ui: 1,
-  scrub: 1,
-  // Configured entirely by `--dir`, like `attach` below it.
-  quickstart: 0,
-  attach: 0,
-  list: 0,
-  gc: 0,
-  doctor: 0,
-  setup: 0,
-  models: 0,
-  mcp: 0,
-  help: 0,
-};
-
-/** Exposed so a test can hold {@link POSITIONALS} against the source it mirrors. */
-export const POSITIONAL_COUNTS: Readonly<Record<string, number>> = POSITIONALS;
-
-/**
- * Reject a positional argument the command does not read.
- *
- * The parser collects every token that is not a flag, and each command reads at most the first.
- * Anything past that was dropped in silence — and for `record` that is the worst shape available:
- * the arguments meant for the agent never reach it, the harness starts with none, and agenticreplay reports
- * a successful recording of a run that was never asked to do anything.
- *
- *   agenticreplay record codex exec "fix auth.ts"    ->  manifest argv: ["codex"]
- *
- * The agent's own arguments go after `--`, which is the one thing that message has to say. Counting
- * per command rather than allowing one everywhere matters for the seven that read none: `agenticreplay
- * attach claude` looks like it names the agent, and `--for` is what actually does.
- */
-export function assertNoStrayPositionals(args: ParsedArgs): void {
-  // An unknown command is the dispatcher's to report, as above.
-  const takes = POSITIONALS[args.command];
-  if (takes === undefined) return;
-  const stray = args.positionals.slice(takes);
-  if (stray.length === 0) return;
-
-  const quote = (a: string): string => (/\s/.test(a) ? `"${a}"` : a);
-  const listed = stray.map(quote).join(' ');
-  const takesLine =
-    takes === 0
-      ? `\n  "agenticreplay ${args.command}" takes no arguments; everything it needs is a flag`
-      : `\n  "agenticreplay ${args.command}" takes one: ${quote(args.positionals[0]!)}`;
-  // Only `record` hands its tail to something else, so only `record` can say where the tail goes.
-  const forAgent =
-    args.command === 'record'
-      ? `\n  arguments for the agent go after --: agenticreplay record ${quote(args.positionals[0]!)} -- ${listed}`
-      : '';
-  throw new Error(
-    `unexpected argument${stray.length > 1 ? 's' : ''} for "agenticreplay ${args.command}": ${listed}` +
-      takesLine +
-      forAgent,
-  );
-}
-
-/**
- * A flag as the person would have typed it.
- *
- * Every short flag here is one character, so the count of dashes follows from the length. Telling
- * someone `--o needs a value` when they typed `-o` sends them looking for a flag that does not
- * exist.
- */
-function dashed(name: string): string {
-  return name.length === 1 ? `-${name}` : `--${name}`;
-}
-
-/**
- * Reject a flag whose value cannot be honoured.
- *
- * `assertKnownFlags` settled the names; the values were still taken on trust. Every accessor falls
- * back in silence when a value is missing or of the wrong shape, so the instruction vanished and
- * the run reported success having done something else:
- *
- *   `--model` with nothing after it turned a fork into a plain replay, and the two models being
- *   compared agreed because only one of them ever ran. `--match a --match b` redacted `b` alone and
- *   reported its count as though that were the whole job. `--from four` replayed everything instead
- *   of forking at a checkpoint. `--json=maybe` turned JSON output off while it was being asked for.
- *
- * Same reasoning as `assertNoStrayPositionals` beside it, third part of the command line: an
- * instruction agenticreplay cannot carry out must not be carried past in silence.
- *
- * `agenticreplay gc --keep` checked its own by hand and was the only command that did. Doing it here is the
- * same check for all of them, and one place to fix when it is wrong.
- */
-function assertUsableValues(args: ParsedArgs, allowed: readonly string[]): void {
-  for (const name of Object.keys(args.flags)) {
-    const value = args.flags[name];
-
-    // Repeating a flag is how most CLIs take a list, so people write it. Say which form is one here
-    // rather than only saying no.
-    if (args.conflicting.has(name)) {
-      const listForm = [`${name}s`, `${name}es`].find((f) => allowed.includes(f));
-      throw new Error(
-        `${dashed(name)} given more than once, and only the last would have counted` +
-          (listForm === undefined
-            ? '\n  give it once'
-            : `\n  for several, use one --${listForm}: --${listForm} a,b,c`),
-      );
-    }
-
-    if (NUMERIC.has(name)) {
-      if (args.missingValue.has(name) || typeof value === 'string') {
-        throw new Error(`${dashed(name)} needs a number, like ${dashed(name)} 4`);
-      }
-      continue;
-    }
-
-    // `--flag`, `--flag=true` and `--no-flag` all arrive as a boolean. Anything else is a value on
-    // a switch, and the switch would then have read as off.
-    if (VALUELESS.has(name)) {
-      if (typeof value === 'string') {
-        throw new Error(`${dashed(name)} takes no value; it is either given or it is not`);
-      }
-      continue;
-    }
-
-    if (args.missingValue.has(name)) throw new Error(`${dashed(name)} needs a value`);
-  }
-}

package/packages/cli/src/fs-events.ts

@@ -1,103 +0,0 @@
-import type { TraceWriter } from '@agenticreplay/core';
-import type { FsCapture } from '@agenticreplay/fs-capture';
-import type { Output } from './out.js';
-import { snapshotWithRetry } from './snapshot.js';
-
-/**
- * Snapshot the workspace and write what changed.
- *
- * Shared by `agenticreplay record` and by a fork, which had none of this: a fork ran a live agent in a
- * worktree and recorded only the conversation, so its trace carried no `fs.snapshot` at all — and a
- * checkpoint is *derived* from a snapshot (spec §3). A run with no checkpoints cannot be forked, so
- * you could not fork a fork, and `agenticreplay compare last` straight after a fork failed with "this run
- * has no checkpoints" because `last` had resolved to the fork.
- *
- * Degrade, never abort: losing a snapshot costs one checkpoint, whereas throwing here would cost
- * the user the run they were in the middle of.
- */
-export async function appendSnapshot(
-  fs: FsCapture,
-  writer: TraceWriter,
-  out: Output,
-  turn: number,
-  options: { initial?: boolean } = {},
-): Promise<void> {
-  const outcome = await snapshotWithRetry(fs, turn);
-  if (!outcome.ok || !outcome.snapshot) {
-    out.warn('fs.snapshot_failed', { turn, attempts: outcome.attempts, error: outcome.error });
-    await writer.append({
-      type: 'note',
-      actor: 'agenticreplay',
-      turn,
-      attrs: { rule: 'fs_snapshot_skipped', attempts: outcome.attempts, error: outcome.error },
-    });
-    return;
-  }
-
-  const snap = outcome.snapshot;
-  // A declared artifact path that is a git checkout of its own — a cloned corpus under `dataset/`
-  // — cannot be stored here, and is dropped so the rest of the tree stays restorable. Said once
-  // per path: the whole reason `artifacts.capture` exists is that a recording missing its inputs
-  // looks exactly like a recording that has them until someone replays it somewhere else.
-  if (snap.skippedGitlinks !== undefined && snap.skippedGitlinks.length > 0) {
-    out.warn('fs.artifact_not_captured', {
-      paths: snap.skippedGitlinks.join(','),
-      why:
-        'these are git repositories of their own, and git stores them as a reference rather ' +
-        'than as their contents',
-      next:
-        'a replay elsewhere will not find them; remove the nested .git, or keep them outside ' +
-        'the declared artifact paths',
-    });
-  }
-  // A nested repository with no commit of its own is not in this snapshot and cannot be: git
-  // records an embedded repository by the id of its HEAD commit, and it has none. Said here for
-  // the reason the line above is said — a recording that quietly omits part of the workspace looks
-  // exactly like one that has all of it, right up until someone replays it. Once per path.
-  if (snap.uncommittedNested !== undefined && snap.uncommittedNested.length > 0) {
-    out.warn('fs.nested_not_captured', {
-      paths: snap.uncommittedNested.join(','),
-      why: 'these are git repositories of their own with no commit yet, so git has no id to record them by and this snapshot holds nothing of what is inside them',
-      next: 'commit inside them, or move them outside the workspace, if a replay needs their contents',
-    });
-  }
-
-  // A declared artifact path inside a nested repository is not in this snapshot and cannot be: git
-  // stages nothing inside another repository. Before this was said, the forced add either killed
-  // the snapshot — every turn, so the run held none — or quietly staged nothing, and the recording
-  // looked like it held the artifacts right up until a replay needed them. Once per path.
-  if (snap.forcedInsideNested !== undefined && snap.forcedInsideNested.length > 0) {
-    out.warn('fs.artifact_inside_repository', {
-      paths: snap.forcedInsideNested.map((entry) => entry.path).join(','),
-      inside: [...new Set(snap.forcedInsideNested.map((entry) => entry.repository))].join(','),
-      why: 'these declared artifact paths sit inside a git repository of their own, and git stages nothing inside another repository, so this snapshot holds none of them',
-      next: 'a replay cannot put them back and will refuse to reset them; keep the artifacts outside that repository',
-    });
-  }
-
-  await writer.append({
-    type: 'fs.snapshot',
-    actor: 'agenticreplay',
-    turn,
-    attrs: {
-      tree: snap.tree,
-      changes: snap.changes.length,
-      ...(options.initial === true ? { initial: true } : {}),
-    },
-  });
-  for (const change of snap.changes) {
-    await writer.append({
-      type: 'fs.change',
-      actor: 'agenticreplay',
-      turn,
-      attrs: {
-        path: change.path,
-        status: change.status,
-        insertions: change.insertions,
-        deletions: change.deletions,
-        // Only when true, so a trace is not littered with a false on every unremarkable change.
-        ...(change.eolOnly === true ? { eol_only: true } : {}),
-      },
-    });
-  }
-}

package/packages/cli/src/index.ts

@@ -1,17 +0,0 @@
-export * from './api.js';
-export * from './args.js';
-export * from './out.js';
-export * from './main.js';
-export * from './exchange-events.js';
-export * from './mcp.js';
-export * from './serial.js';
-export * from './snapshot.js';
-export * from './share-card.js';
-export * from './commands/record.js';
-export * from './commands/replay.js';
-export * from './commands/compare.js';
-export * from './commands/inspect.js';
-export * from './commands/scrub.js';
-export * from './commands/gc.js';
-export * from './commands/doctor.js';
-export * from './version.js';