agenticreplay 0.1.0 → 0.1.2

package/packages/cli/src/commands/doctor.ts

@@ -1,447 +0,0 @@
-import { execFile } from 'node:child_process';
-import { randomBytes } from 'node:crypto';
-import { mkdtemp, rm, stat, unlink, writeFile } from 'node:fs/promises';
-// Namespaced as well as named, because `statfs` is not present on every supported node build and
-// a missing named import from a builtin is a load-time error for the whole CLI.
-import * as fsPromises from 'node:fs/promises';
-import { createServer } from 'node:net';
-import { tmpdir } from 'node:os';
-import { delimiter, dirname, join } from 'node:path';
-import { promisify } from 'node:util';
-import { defaultAdapters } from '@agenticreplay/adapters';
-import { listRuns, agenticreplayDir } from '@agenticreplay/core';
-import { runGit } from '@agenticreplay/fs-capture';
-import { installShellShim, readShellFrames } from '@agenticreplay/shell-shim';
-import type { ParsedArgs } from '../args.js';
-import { RENDER_DEPS, missingRenderDeps } from '../rasterize.js';
-import type { Output } from '../out.js';
-import { formatBytes, runDirBytes } from './gc.js';
-import { shimIsRunnable } from '../mcp.js';
-
-const execFileAsync = promisify(execFile);
-
-export interface DoctorCheck {
-  name: string;
-  status: 'ok' | 'warn' | 'fail';
-  detail: string;
-  /** What to do about it. Mandatory in spirit for anything that is not ok. */
-  fix?: string;
-}
-
-export interface DoctorResult {
-  checks: DoctorCheck[];
-  ok: boolean;
-}
-
-const MIN_NODE_MAJOR = 24;
-const LOW_DISK_BYTES = 512 * 1024 * 1024;
-const BIG_STORE_BYTES = 1024 * 1024 * 1024;
-
-/**
- * `agenticreplay doctor` — will recording actually work here?
- *
- * AgenticReplay instruments an agent by putting environment variables in front of someone else's process
- * and shelling out to git. When that goes wrong the symptom appears inside the agent, minutes
- * later, as something that looks like the agent's fault. Every check here is one of those failure
- * modes, answered before the user spends an hour on it — so each is exercised for real (a port is
- * actually bound, a file is actually written) rather than inferred.
- */
-export async function doctorCommand(
-  args: ParsedArgs,
-  out: Output,
-  cwd = process.cwd(),
-): Promise<DoctorResult> {
-  const git = await checkGit();
-  const writable = await checkWritable(cwd);
-
-  const checks: DoctorCheck[] = [
-    checkNode(),
-    git.check,
-    await checkWorkspace(cwd, git.available),
-    writable.check,
-    await checkAgents(cwd),
-    await checkPort(),
-    await checkShellShim(),
-    await checkMcpShim(),
-    await checkRasteriser(),
-    await checkDisk(writable.probeDir),
-    await checkRuns(cwd),
-  ];
-
-  const failed = checks.filter((c) => c.status === 'fail');
-  const warned = checks.filter((c) => c.status === 'warn');
-  const ok = failed.length === 0;
-
-  out.table(
-    ['CHECK', 'STATUS', 'DETAIL'],
-    checks.map((c) => [c.name, c.status, c.detail]),
-  );
-
-  const trouble = [...failed, ...warned];
-  out.plain('');
-  if (trouble.length === 0) {
-    out.plain('  all clear — agenticreplay record <agent> should work here');
-  } else {
-    for (const check of trouble) {
-      out.plain(`  ${check.status} ${check.name}: ${check.fix ?? check.detail}`);
-    }
-  }
-
-  out.phase('doctor', { ok, checks: checks.length, failed: failed.length, warned: warned.length });
-  return { checks, ok };
-}
-
-function checkNode(): DoctorCheck {
-  const name = 'node version';
-  // Read at call time, never cached: the running version is the thing under test.
-  const version = process.version;
-  const major = Number(/^v?(\d+)/.exec(version)?.[1] ?? Number.NaN);
-  if (Number.isNaN(major)) {
-    return {
-      name,
-      status: 'warn',
-      detail: `cannot read a major version from ${version}`,
-      fix: `run agenticreplay on node ${MIN_NODE_MAJOR} or newer`,
-    };
-  }
-  if (major < MIN_NODE_MAJOR) {
-    return {
-      name,
-      status: 'fail',
-      detail: `${version} — agenticreplay needs node ${MIN_NODE_MAJOR} or newer`,
-      fix: `install node ${MIN_NODE_MAJOR}+ (nvm install ${MIN_NODE_MAJOR}) and run agenticreplay doctor again`,
-    };
-  }
-  return { name, status: 'ok', detail: version };
-}
-
-/**
- * Two capture layers that fail quietly.
- *
- * Both are shims — a PATH entry in front of `sh`/`bash`, and a rewritten MCP config launching a
- * JSON-RPC tee. When either cannot start, nothing goes wrong that anybody sees: the agent runs
- * perfectly, the run succeeds, and the trace is missing a layer, which you discover only when you
- * go looking for an exit code or a tool call that was never recorded. That is exactly the class of
- * failure `doctor` exists to move forward in time, so both are exercised for real rather than
- * inferred from a file existing.
- */
-async function checkShellShim(): Promise<DoctorCheck> {
-  const name = 'shell shim';
-  const dir = await mkdtemp(join(tmpdir(), 'agenticreplay-doctor-shim-'));
-  try {
-    // `framesPath` explicitly, so the frames land inside the directory this function already
-    // removes in its `finally`. Left to the default they would go to a transport of their own, which
-    // doctor has no teardown for — a check that leaks is a check nobody wants to run.
-    const shim = await installShellShim({
-      runDir: dir,
-      framesPath: join(dir, 'shell-frames.jsonl'),
-    });
-    // Run something through it, rather than trusting that writing the scripts was enough: the
-    // failure this catches is the compiled runner being absent from an installed package.
-    //
-    // Through the command processor on Windows, because that is the only way to reach the shim
-    // there. PATH cannot hold an extensionless script, so the shim is `sh.cmd` — and
-    // `execFile('sh', …)` goes to CreateProcess, which looks for `sh` and `sh.exe` and never
-    // `sh.cmd`. This check therefore walked past the shim to whichever `sh.exe` was further down
-    // PATH, found no frames, and told every Windows user that a working capture layer records
-    // nothing — advising them to turn it off with `--no-shell`. Naming `sh.cmd` directly is not
-    // the fix: node has refused to spawn a `.cmd` without a shell since CVE-2024-27980. The
-    // command processor is what resolves PATHEXT, so it is what has to do the resolving.
-    const env = { ...process.env, PATH: `${shim.dir}${delimiter}${process.env.PATH ?? ''}` };
-    const { stdout } =
-      process.platform === 'win32'
-        ? await execFileAsync(
-            process.env.ComSpec ?? 'cmd.exe',
-            ['/d', '/s', '/c', 'sh', '-c', 'printf ok'],
-            { env },
-          )
-        : await execFileAsync('sh', ['-c', 'printf ok'], { env });
-    if (stdout.trim() !== 'ok') {
-      return {
-        name,
-        status: 'warn',
-        detail: `the shim ran but returned ${JSON.stringify(stdout)}`,
-        fix: 'record with --no-shell; exit codes and timing will be missing from the trace',
-      };
-    }
-    const frames = await readShellFrames(shim.framesPath);
-    if (frames.length === 0) {
-      return {
-        name,
-        status: 'warn',
-        detail: 'commands pass through but nothing is captured',
-        fix: 'record with --no-shell rather than trusting a layer that records nothing',
-      };
-    }
-    // WINDOWS: THE COMMAND PROCESSOR REACHES THE SHIM, AND AN AGENT STARTING ITS OWN SHELL DOES NOT.
-    //
-    // The probe above goes through cmd.exe because nothing else resolves PATHEXT, which makes it
-    // the one launch path certain to find `sh.cmd` — a probe that could only ever say yes. An agent
-    // that spawns `sh` or `bash` by name goes to CreateProcess, finds the real `sh.exe`, and is
-    // never seen: driven through `agenticreplay record`, `child_process.spawn('bash')` ran its commands and
-    // the trace held none of them, while this line said "captured a test command". record.ts
-    // already says as much of Claude Code, as `shell.ineffective`; this check did not.
-    //
-    // So both questions are asked, and the answer says which is true. A partial answer is a
-    // warning, not a failure — and not the advice to switch the layer off that this check gave
-    // before it learned to use cmd.exe, because a shell started through cmd or PowerShell IS
-    // captured.
-    if (process.platform === 'win32') {
-      await execFileAsync('sh', ['-c', 'printf ok'], { env }).catch(() => undefined);
-      if ((await readShellFrames(shim.framesPath)).length === frames.length) {
-        return {
-          name,
-          status: 'warn',
-          detail: `${shim.shimmed.join(', ')} — captures a shell started through cmd.exe or PowerShell, not one an agent starts itself`,
-          fix:
-            'Windows runs a .cmd only through a shell, so an agent that spawns sh or bash directly ' +
-            '(Claude Code does) is not captured; agenticreplay record flags each such run as ' +
-            'shell.ineffective — record those with --no-shell',
-        };
-      }
-    }
-    return { name, status: 'ok', detail: `${shim.shimmed.join(', ')} — captured a test command` };
-  } catch (err) {
-    return {
-      name,
-      status: 'warn',
-      detail: String(err instanceof Error ? err.message : err).split('\n')[0] ?? 'unavailable',
-      fix: 'run `npm run build` if working from source, or record with --no-shell',
-    };
-  } finally {
-    await rm(dir, { recursive: true, force: true });
-  }
-}
-
-async function checkMcpShim(): Promise<DoctorCheck> {
-  const name = 'mcp shim';
-  const runnable = await shimIsRunnable();
-  return runnable
-    ? { name, status: 'ok', detail: 'runnable — pass --mcp-config <path> to use it' }
-    : {
-        name,
-        status: 'warn',
-        detail: 'the shim entry point cannot be launched',
-        fix: 'run `npm run build` if working from source; MCP calls will not be captured without it',
-      };
-}
-
-/** Through fs-capture's own runner, so this tests the git invocation recording will really make. */
-/**
- * Whether a card can be written as a PNG or a GIF.
- *
- * Never a failure. The raster toolchain is optional by design — `docs/media/README.md` keeps it
- * out of `package.json` so `npm ci` stays lean — and recording, replaying and SVG cards all work
- * without it. Reporting it is how someone finds out before they need it rather than at the moment
- * they ask for a `.png`.
- */
-async function checkRasteriser(): Promise<DoctorCheck> {
-  const name = 'card rasteriser';
-  const missing = await missingRenderDeps();
-  return missing.length === 0
-    ? { name, status: 'ok', detail: 'installed — cards can be written as .svg, .png or .gif' }
-    : {
-        name,
-        status: 'ok',
-        detail: 'not installed — cards can be written as .svg',
-        fix: `npm i --no-save ${RENDER_DEPS.join(' ')} to also write .png and .gif`,
-      };
-}
-
-async function checkGit(): Promise<{ check: DoctorCheck; available: boolean }> {
-  const name = 'git';
-  const res = await runGit(['--version']);
-  if (res.code === 0 && res.stdout.startsWith('git version')) {
-    return { check: { name, status: 'ok', detail: res.stdout.trim() }, available: true };
-  }
-  return {
-    check: {
-      name,
-      status: 'warn',
-      detail: 'not runnable here — filesystem capture and forked worktrees will be off',
-      fix: 'install git to get fs snapshots and checkpoints; otherwise record with --no-fs',
-    },
-    available: false,
-  };
-}
-
-async function checkWorkspace(cwd: string, gitAvailable: boolean): Promise<DoctorCheck> {
-  const name = 'git workspace';
-  const fix =
-    'git init here, or record from your project root — fs diffs are far more useful in a repo';
-
-  if (gitAvailable) {
-    const res = await runGit(['rev-parse', '--show-toplevel'], { cwd });
-    if (res.code === 0 && res.stdout.trim() !== '') {
-      return { name, status: 'ok', detail: res.stdout.trim() };
-    }
-    return { name, status: 'warn', detail: `${cwd} is not inside a git repo`, fix };
-  }
-
-  // Without git, answer the question from the filesystem rather than declining to answer it.
-  const root = await findRepoRoot(cwd);
-  return root === undefined
-    ? { name, status: 'warn', detail: `${cwd} is not inside a git repo`, fix }
-    : { name, status: 'ok', detail: `${root} (found by .git; git itself is not runnable)` };
-}
-
-/**
- * Writes a real file and removes it. `.agenticreplay` is created lazily by `record`, so when it does not
- * exist yet the directory that will have to hold it is what gets probed — and nothing is created.
- */
-async function checkWritable(cwd: string): Promise<{ check: DoctorCheck; probeDir: string }> {
-  const name = '.agenticreplay writable';
-  const target = agenticreplayDir(cwd);
-  const info = await stat(target).catch(() => null);
-
-  if (info !== null && !info.isDirectory()) {
-    return {
-      check: {
-        name,
-        status: 'fail',
-        detail: `${target} exists but is not a directory`,
-        fix: `move or remove ${target}; agenticreplay keeps every recorded run in it`,
-      },
-      probeDir: cwd,
-    };
-  }
-
-  const probeDir = info === null ? cwd : target;
-  const probe = join(probeDir, `.agenticreplay-doctor-${randomBytes(4).toString('hex')}.tmp`);
-  try {
-    await writeFile(probe, 'agenticreplay doctor', { mode: 0o600 });
-    await unlink(probe);
-  } catch (err) {
-    return {
-      check: {
-        name,
-        status: 'fail',
-        detail: `cannot write and clean up a file in ${probeDir}: ${messageOf(err)}`,
-        fix: `make ${probeDir} writable, or run agenticreplay from a directory you own`,
-      },
-      probeDir,
-    };
-  }
-  return {
-    check: {
-      name,
-      status: 'ok',
-      detail:
-        info === null
-          ? `${probeDir} is writable (.agenticreplay not created yet)`
-          : `${target} is writable`,
-    },
-    probeDir,
-  };
-}
-
-async function checkAgents(cwd: string): Promise<DoctorCheck> {
-  const name = 'agents detected';
-  const registry = defaultAdapters();
-  const found: string[] = [];
-  for (const id of registry.ids()) {
-    try {
-      if (await registry.get(id).detect(cwd)) found.push(id);
-    } catch {
-      // A detector that throws is a "no"; it must never take the diagnosis down with it.
-    }
-  }
-  if (found.length === 0) {
-    return {
-      name,
-      status: 'warn',
-      detail: 'none of the known agents were found on PATH or in this workspace',
-      fix: 'name the agent explicitly, or record any OpenAI-compatible one: agenticreplay record generic-openai -- <command>',
-    };
-  }
-  return { name, status: 'ok', detail: found.join(', ') };
-}
-
-async function checkPort(): Promise<DoctorCheck> {
-  const name = 'proxy port';
-  try {
-    const port = await bindEphemeral();
-    return { name, status: 'ok', detail: `bound 127.0.0.1:${port}, then released it` };
-  } catch (err) {
-    return {
-      name,
-      status: 'fail',
-      detail: `cannot bind a loopback port: ${messageOf(err)}`,
-      fix: 'agenticreplay records by proxying model traffic through 127.0.0.1 — allow loopback listeners (sandbox or firewall policy) before recording',
-    };
-  }
-}
-
-function bindEphemeral(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const server = createServer();
-    server.once('error', reject);
-    server.listen(0, '127.0.0.1', () => {
-      const address = server.address();
-      const port = typeof address === 'object' && address !== null ? address.port : 0;
-      server.close(() => {
-        if (port > 0) resolve(port);
-        else reject(new Error('listening socket reported no port'));
-      });
-    });
-  });
-}
-
-async function checkDisk(probeDir: string): Promise<DoctorCheck> {
-  const name = 'disk space';
-  if (typeof fsPromises.statfs !== 'function') {
-    return { name, status: 'ok', detail: 'skipped — statfs is unavailable on this node build' };
-  }
-  try {
-    const fs = await fsPromises.statfs(probeDir);
-    const free = Number(fs.bavail) * Number(fs.bsize);
-    if (free < LOW_DISK_BYTES) {
-      return {
-        name,
-        status: 'warn',
-        detail: `${formatBytes(free)} free where .agenticreplay lives`,
-        fix: 'free some space — one recorded run can reach tens of megabytes: agenticreplay gc --older-than 7d',
-      };
-    }
-    return { name, status: 'ok', detail: `${formatBytes(free)} free` };
-  } catch (err) {
-    return { name, status: 'ok', detail: `skipped — statfs failed: ${messageOf(err)}` };
-  }
-}
-
-async function checkRuns(cwd: string): Promise<DoctorCheck> {
-  const name = 'existing runs';
-  const runs = await listRuns(cwd);
-  if (runs.length === 0) return { name, status: 'ok', detail: 'none recorded here yet' };
-
-  let bytes = 0;
-  for (const run of runs) bytes += await runDirBytes(run.dir);
-  const detail = `${runs.length} run${runs.length === 1 ? '' : 's'}, ${formatBytes(bytes)}`;
-  if (bytes > BIG_STORE_BYTES) {
-    return {
-      name,
-      status: 'warn',
-      detail,
-      fix: 'agenticreplay gc --keep 20 --dry-run shows what could be reclaimed',
-    };
-  }
-  return { name, status: 'ok', detail };
-}
-
-async function findRepoRoot(from: string): Promise<string | undefined> {
-  let dir = from;
-  for (;;) {
-    const found = await stat(join(dir, '.git')).then(
-      () => true,
-      () => false,
-    );
-    if (found) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return undefined;
-    dir = parent;
-  }
-}
-
-function messageOf(err: unknown): string {
-  return err instanceof Error ? err.message : String(err);
-}