replay-self-healing-cli 0.1.0

package/src/cli.mjs

@@ -0,0 +1,1680 @@
+import { spawn } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs, { constants as fsConstants } from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const SCHEMA_VERSION = '1.0.0';
+const KNOWN_COMMANDS = new Set(['capture', 'heal', 'help', 'report', 'validate']);
+const DEFAULT_EVENT_ALIASES = {
+  completed: 'run_completed',
+  failed: 'run_failed',
+  message: 'assistant_message',
+  tool_end: 'tool_completed',
+  tool_finish: 'tool_completed',
+  tool_start: 'tool_started'
+};
+const RUNNER_DISCOVERY_CANDIDATES = [
+  '.replay/runner.mjs',
+  '.replay/runner.js',
+  '.replay/runner.cjs',
+  '.replay/runner'
+];
+
+class ReplayCliError extends Error {
+  constructor({
+    code,
+    details,
+    example,
+    expected,
+    howToFix,
+    message,
+    path: errorPath,
+    received
+  }) {
+    super(message);
+    this.name = 'ReplayCliError';
+    this.code = code;
+    this.details = details;
+    this.example = example;
+    this.expected = expected;
+    this.howToFix = howToFix;
+    this.path = errorPath;
+    this.received = received;
+  }
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function safeJsonParse(content, contextCode = 'E_INVALID_JSON') {
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new ReplayCliError({
+      code: contextCode,
+      message: 'Invalid JSON content.',
+      details: error?.message,
+      received: content.slice(0, 500),
+      howToFix: 'Fix the JSON syntax and try again.'
+    });
+  }
+}
+
+function compactDate() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function isoNow() {
+  return new Date().toISOString();
+}
+
+function randomShortId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+function sanitizePrompt(prompt) {
+  return String(prompt)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40);
+}
+
+function outputJson(data) {
+  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+}
+
+function outputError(error) {
+  if (error instanceof ReplayCliError) {
+    process.stderr.write(
+      `${JSON.stringify(
+        {
+          error: {
+            code: error.code,
+            details: error.details,
+            example: error.example,
+            expected: error.expected,
+            howToFix: error.howToFix,
+            message: error.message,
+            path: error.path,
+            received: error.received
+          }
+        },
+        null,
+        2
+      )}\n`
+    );
+
+    return;
+  }
+
+  process.stderr.write(
+    `${JSON.stringify(
+      {
+        error: {
+          code: 'E_UNHANDLED',
+          message: error?.message || 'Unexpected failure',
+          details: error?.stack
+        }
+      },
+      null,
+      2
+    )}\n`
+  );
+}
+
+function parseArgs(argv) {
+  const args = [...argv];
+  let command = 'capture';
+
+  if (args[0] && KNOWN_COMMANDS.has(args[0])) {
+    command = args.shift();
+  } else if (args[0] === '-h' || args[0] === '--help') {
+    command = 'help';
+    args.shift();
+  }
+
+  const options = {
+    heal: true,
+    json: true,
+    timeoutMs: 120000
+  };
+  const positionals = [];
+
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index];
+
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+
+    if (token === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (token === '--no-heal') {
+      options.heal = false;
+      continue;
+    }
+
+    if (token === '--json') {
+      options.json = true;
+      continue;
+    }
+
+    if (token === '--runner') {
+      options.runner = args[++index];
+      continue;
+    }
+
+    if (token === '--out') {
+      options.out = args[++index];
+      continue;
+    }
+
+    if (token === '--context') {
+      options.context = args[++index];
+      continue;
+    }
+
+    if (token === '--context-file') {
+      options.contextFile = args[++index];
+      continue;
+    }
+
+    if (token === '--id') {
+      options.id = args[++index];
+      continue;
+    }
+
+    if (token === '--in') {
+      options.in = args[++index];
+      continue;
+    }
+
+    if (token === '--timeout-ms') {
+      options.timeoutMs = Number(args[++index]);
+      continue;
+    }
+
+    throw new ReplayCliError({
+      code: 'E_UNKNOWN_FLAG',
+      message: `Unknown flag: ${token}`,
+      howToFix: 'Use `replay help` to see supported flags.'
+    });
+  }
+
+  if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+    throw new ReplayCliError({
+      code: 'E_TIMEOUT_INVALID',
+      message: '--timeout-ms must be a positive integer.',
+      path: '--timeout-ms',
+      expected: 'positive number',
+      received: options.timeoutMs
+    });
+  }
+
+  return { command, options, positionals };
+}
+
+function printHelp() {
+  outputJson({
+    commands: {
+      capture: 'Capture one prompt into raw + healed replay artifacts (default command).',
+      heal: 'Re-heal replay artifacts from a file or directory.',
+      report: 'Generate summary metrics from replay artifact files.',
+      validate: 'Validate replay artifact files.'
+    },
+    examples: [
+      'replay "What are my top holdings?"',
+      'echo "What changed today?" | replay',
+      'replay capture "Summarize my risk" --timeout-ms 90000',
+      'replay validate --in .replay/artifacts',
+      'replay heal --in .replay/artifacts --out .replay/healed',
+      'replay report --in .replay/artifacts'
+    ],
+    notes: [
+      'No --runner required by default. Runner discovery order: REPLAY_RUNNER env, .replay/runner.mjs, .replay/runner.js, .replay/runner.cjs, .replay/runner, package.json script replay:runner.',
+      'No --out required by default. Output defaults to .replay/artifacts/YYYY-MM-DD.',
+      'This utility has zero dependencies and uses only Node.js built-in modules.'
+    ]
+  });
+}
+
+async function ensureDir(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+async function readPromptFromStdin() {
+  if (process.stdin.isTTY) {
+    return '';
+  }
+
+  const chunks = [];
+
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+
+  return Buffer.concat(chunks).toString('utf-8').trim();
+}
+
+async function resolvePrompt(positionals) {
+  const directPrompt = positionals.join(' ').trim();
+
+  if (directPrompt) {
+    return directPrompt;
+  }
+
+  const stdinPrompt = await readPromptFromStdin();
+
+  if (stdinPrompt) {
+    return stdinPrompt;
+  }
+
+  throw new ReplayCliError({
+    code: 'E_PROMPT_REQUIRED',
+    message: 'No prompt was provided.',
+    path: '$.prompt',
+    expected: 'non-empty string',
+    received: '',
+    howToFix: 'Pass a prompt as an argument or pipe one via stdin.',
+    example: 'replay "What are my top 5 holdings?"'
+  });
+}
+
+async function resolveContext({ context, contextFile }) {
+  if (context && contextFile) {
+    throw new ReplayCliError({
+      code: 'E_CONTEXT_CONFLICT',
+      message: 'Use only one of --context or --context-file.',
+      howToFix: 'Provide inline JSON with --context OR a file path with --context-file.'
+    });
+  }
+
+  if (context) {
+    const parsed = safeJsonParse(context, 'E_CONTEXT_JSON_INVALID');
+
+    if (!isObject(parsed)) {
+      throw new ReplayCliError({
+        code: 'E_CONTEXT_SHAPE_INVALID',
+        message: 'Context must be a JSON object.',
+        expected: 'object',
+        received: typeof parsed,
+        path: '--context'
+      });
+    }
+
+    return parsed;
+  }
+
+  if (contextFile) {
+    const absolutePath = path.resolve(process.cwd(), contextFile);
+    let content;
+
+    try {
+      content = await fsp.readFile(absolutePath, 'utf-8');
+    } catch {
+      throw new ReplayCliError({
+        code: 'E_CONTEXT_FILE_NOT_FOUND',
+        message: `Context file does not exist: ${absolutePath}`,
+        path: '--context-file',
+        howToFix: 'Provide an existing JSON file path.'
+      });
+    }
+
+    const parsed = safeJsonParse(content, 'E_CONTEXT_JSON_INVALID');
+
+    if (!isObject(parsed)) {
+      throw new ReplayCliError({
+        code: 'E_CONTEXT_SHAPE_INVALID',
+        message: 'Context file content must be a JSON object.',
+        expected: 'object',
+        received: typeof parsed,
+        path: '--context-file'
+      });
+    }
+
+    return parsed;
+  }
+
+  return {};
+}
+
+async function discoverRunner(cwd, explicitRunner) {
+  const sources = [];
+
+  if (explicitRunner) {
+    const runner = await toRunnerSpec(explicitRunner, cwd, 'flag');
+    return { runner, sources };
+  }
+
+  if (process.env.REPLAY_RUNNER) {
+    const runner = await toRunnerSpec(process.env.REPLAY_RUNNER, cwd, 'env');
+    return { runner, sources };
+  }
+
+  for (const candidate of RUNNER_DISCOVERY_CANDIDATES) {
+    const absolute = path.resolve(cwd, candidate);
+    sources.push(absolute);
+
+    if (await exists(absolute)) {
+      const runner = await toRunnerSpec(absolute, cwd, 'file');
+      return { runner, sources };
+    }
+  }
+
+  const packageJsonPath = path.resolve(cwd, 'package.json');
+  if (await exists(packageJsonPath)) {
+    const packageJson = safeJsonParse(
+      await fsp.readFile(packageJsonPath, 'utf-8'),
+      'E_PACKAGE_JSON_INVALID'
+    );
+
+    if (isObject(packageJson?.scripts) && packageJson.scripts['replay:runner']) {
+      const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+      return {
+        runner: {
+          args: ['run', '--silent', 'replay:runner', '--'],
+          command: npmCommand,
+          display: 'npm run --silent replay:runner --',
+          source: 'package.json#scripts.replay:runner',
+          type: 'npm-script'
+        },
+        sources
+      };
+    }
+  }
+
+  throw new ReplayCliError({
+    code: 'E_RUNNER_NOT_FOUND',
+    message: 'No runner was discovered.',
+    details: {
+      checked: sources,
+      envVar: 'REPLAY_RUNNER',
+      packageScript: 'replay:runner'
+    },
+    howToFix:
+      'Create .replay/runner.mjs, set REPLAY_RUNNER, or add package.json script replay:runner.',
+    example: 'mkdir -p .replay && cp examples/runner.mjs .replay/runner.mjs'
+  });
+}
+
+async function toRunnerSpec(value, cwd, source) {
+  const resolved = path.isAbsolute(value) ? value : path.resolve(cwd, value);
+
+  if (!(await exists(resolved))) {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_PATH_NOT_FOUND',
+      message: `Runner path does not exist: ${resolved}`,
+      path: '$.runner',
+      howToFix: 'Point --runner or REPLAY_RUNNER to an existing file.'
+    });
+  }
+
+  const ext = path.extname(resolved);
+
+  if (ext === '.ts') {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_UNSUPPORTED_EXTENSION',
+      message: 'TypeScript runner files are not supported without a runtime wrapper.',
+      expected: '.mjs, .js, .cjs, or executable file',
+      received: ext,
+      howToFix:
+        'Compile the runner to JavaScript, use .mjs, or wire a replay:runner package script.'
+    });
+  }
+
+  if (['.mjs', '.js', '.cjs'].includes(ext)) {
+    return {
+      args: [resolved],
+      command: process.execPath,
+      display: `${process.execPath} ${resolved}`,
+      source,
+      type: 'node-file'
+    };
+  }
+
+  try {
+    await fsp.access(resolved, fsConstants.X_OK);
+  } catch {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_NOT_EXECUTABLE',
+      message: `Runner is not executable: ${resolved}`,
+      path: '$.runner',
+      howToFix:
+        'Make the file executable (`chmod +x`) or use a .mjs/.js/.cjs runner file.'
+    });
+  }
+
+  return {
+    args: [],
+    command: resolved,
+    display: resolved,
+    source,
+    type: 'executable'
+  };
+}
+
+async function exists(targetPath) {
+  try {
+    await fsp.access(targetPath, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runRunner({ payload, runner, timeoutMs }) {
+  return new Promise((resolve, reject) => {
+    const startedAt = Date.now();
+    const child = spawn(runner.command, runner.args, {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+
+      setTimeout(() => {
+        if (!child.killed) {
+          child.kill('SIGKILL');
+        }
+      }, 3000);
+    }, timeoutMs);
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk.toString('utf-8');
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString('utf-8');
+    });
+
+    child.on('error', (error) => {
+      clearTimeout(timeout);
+      reject(
+        new ReplayCliError({
+          code: 'E_RUNNER_START_FAILED',
+          message: `Runner process failed to start: ${runner.display}`,
+          details: error?.message,
+          howToFix: 'Verify the runner path and execution permissions.'
+        })
+      );
+    });
+
+    child.on('close', (exitCode, signal) => {
+      clearTimeout(timeout);
+      resolve({
+        durationMs: Date.now() - startedAt,
+        exitCode,
+        signal,
+        stderr,
+        stdout,
+        timedOut
+      });
+    });
+
+    child.stdin.write(`${JSON.stringify(payload)}\n`);
+    child.stdin.end();
+  });
+}
+
+function recoverJsonObject(text) {
+  const value = text.trim();
+
+  if (!value) {
+    return undefined;
+  }
+
+  const candidates = [];
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  let start = -1;
+
+  for (let index = 0; index < value.length; index++) {
+    const char = value[index];
+
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      escaped = true;
+      continue;
+    }
+
+    if (char === '"') {
+      inString = !inString;
+      continue;
+    }
+
+    if (inString) {
+      continue;
+    }
+
+    if (char === '{') {
+      if (depth === 0) {
+        start = index;
+      }
+
+      depth += 1;
+      continue;
+    }
+
+    if (char === '}') {
+      depth -= 1;
+
+      if (depth === 0 && start >= 0) {
+        candidates.push(value.slice(start, index + 1));
+        start = -1;
+      }
+    }
+  }
+
+  return candidates[candidates.length - 1];
+}
+
+function parseRunnerOutput(rawStdout) {
+  const trimmed = rawStdout.trim();
+
+  if (!trimmed) {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_EMPTY_STDOUT',
+      message: 'Runner wrote no stdout output.',
+      howToFix: 'Runner must return one JSON object on stdout.'
+    });
+  }
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    const recovered = recoverJsonObject(trimmed);
+
+    if (!recovered) {
+      throw new ReplayCliError({
+        code: 'E_RUNNER_INVALID_JSON',
+        message: 'Runner stdout is not valid JSON.',
+        received: trimmed.slice(0, 1000),
+        howToFix: 'Print exactly one JSON object to stdout.',
+        example:
+          '{"status":"ok","response":"...","events":[{"type":"run_started"}]}'
+      });
+    }
+
+    try {
+      return JSON.parse(recovered);
+    } catch {
+      throw new ReplayCliError({
+        code: 'E_RUNNER_INVALID_JSON',
+        message: 'Runner stdout contains JSON-like text but parsing failed.',
+        received: recovered.slice(0, 1000),
+        howToFix: 'Ensure the JSON object is syntactically valid.'
+      });
+    }
+  }
+}
+
+function ensureArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function extractResponseFromEvents(events) {
+  const assistantEvent = [...events]
+    .reverse()
+    .find((event) => event?.type === 'assistant_message');
+
+  const payload = assistantEvent?.payload;
+
+  if (!isObject(payload)) {
+    return undefined;
+  }
+
+  if (typeof payload.response === 'string') {
+    return payload.response;
+  }
+
+  if (typeof payload.message === 'string') {
+    return payload.message;
+  }
+
+  if (typeof payload.text === 'string') {
+    return payload.text;
+  }
+
+  return undefined;
+}
+
+function normalizeRunnerResult(runnerResult, runnerStderr) {
+  if (!isObject(runnerResult)) {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_OUTPUT_SHAPE',
+      message: 'Runner output must be a JSON object.',
+      expected: 'object',
+      received: typeof runnerResult
+    });
+  }
+
+  const normalizationIssues = [];
+
+  let status = runnerResult.status;
+
+  if (status !== 'ok' && status !== 'error') {
+    if (isObject(runnerResult.error)) {
+      status = 'error';
+      normalizationIssues.push({
+        code: 'W_STATUS_INFERRED_FROM_ERROR',
+        message: 'Status was missing/invalid and was inferred as error.'
+      });
+    } else if (typeof runnerResult.response === 'string') {
+      status = 'ok';
+      normalizationIssues.push({
+        code: 'W_STATUS_INFERRED_FROM_RESPONSE',
+        message: 'Status was missing/invalid and was inferred as ok.'
+      });
+    } else {
+      throw new ReplayCliError({
+        code: 'E_RUNNER_STATUS_INVALID',
+        message: 'Runner output field `status` must be `ok` or `error`.',
+        path: '$.status',
+        expected: '"ok" | "error"',
+        received: runnerResult.status,
+        howToFix:
+          'Return `status: "ok"` for success or `status: "error"` for failures.'
+      });
+    }
+  }
+
+  let events = runnerResult.events;
+  if (events === undefined) {
+    events = [];
+    normalizationIssues.push({
+      code: 'W_EVENTS_DEFAULTED_EMPTY',
+      message: 'Missing events field. Defaulted to [].'
+    });
+  }
+
+  if (!Array.isArray(events)) {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_EVENTS_INVALID',
+      message: 'Runner output field `events` must be an array.',
+      path: '$.events',
+      expected: 'array',
+      received: typeof events,
+      howToFix: 'Return `events: []` when there are no events.'
+    });
+  }
+
+  let response = runnerResult.response;
+
+  if (status === 'ok') {
+    if (typeof response !== 'string') {
+      response = extractResponseFromEvents(events);
+
+      if (typeof response === 'string') {
+        normalizationIssues.push({
+          code: 'W_RESPONSE_INFERRED_FROM_EVENTS',
+          message: 'Response was inferred from assistant_message event payload.'
+        });
+      } else {
+        throw new ReplayCliError({
+          code: 'E_RUNNER_RESPONSE_MISSING',
+          message: 'Runner output requires `response` string when status is `ok`.',
+          path: '$.response',
+          expected: 'string',
+          received: typeof runnerResult.response,
+          howToFix: 'Set `response` to the final assistant message text.'
+        });
+      }
+    }
+  }
+
+  let error = runnerResult.error;
+
+  if (status === 'error') {
+    if (!isObject(error)) {
+      error = {
+        code: 'RUNNER_ERROR_UNSPECIFIED',
+        message: runnerStderr?.trim() || 'Runner returned status=error without error details.',
+        retryable: false
+      };
+      normalizationIssues.push({
+        code: 'W_ERROR_OBJECT_DEFAULTED',
+        message: 'Error object missing. A default error payload was generated.'
+      });
+    }
+
+    if (typeof error.message !== 'string' || error.message.length === 0) {
+      error.message = 'Runner returned status=error without a message.';
+      normalizationIssues.push({
+        code: 'W_ERROR_MESSAGE_DEFAULTED',
+        message: 'Error message was missing. A default message was generated.'
+      });
+    }
+
+    if (typeof error.code !== 'string' || error.code.length === 0) {
+      error.code = 'RUNNER_ERROR';
+      normalizationIssues.push({
+        code: 'W_ERROR_CODE_DEFAULTED',
+        message: 'Error code was missing. Defaulted to RUNNER_ERROR.'
+      });
+    }
+  }
+
+  let sources = runnerResult.sources;
+  if (!Array.isArray(sources)) {
+    sources = [];
+    if (runnerResult.sources !== undefined) {
+      normalizationIssues.push({
+        code: 'W_SOURCES_DEFAULTED_EMPTY',
+        message: 'sources was not an array. Defaulted to [].'
+      });
+    }
+  }
+
+  let usage = runnerResult.usage;
+  if (!isObject(usage)) {
+    usage = {};
+  }
+
+  return {
+    error,
+    events,
+    framework:
+      typeof runnerResult.framework === 'string' ? runnerResult.framework : 'custom',
+    normalizationIssues,
+    response,
+    sources: sources.filter((source) => {
+      return typeof source === 'string' && source.length > 0;
+    }),
+    status,
+    usage: {
+      costUsd: typeof usage.costUsd === 'number' ? usage.costUsd : undefined,
+      inputTokens:
+        typeof usage.inputTokens === 'number' ? usage.inputTokens : undefined,
+      outputTokens:
+        typeof usage.outputTokens === 'number' ? usage.outputTokens : undefined
+    }
+  };
+}
+
+function buildRawArtifact({ execution, payload, runner }) {
+  return {
+    artifactType: 'replay_raw_capture',
+    id: payload.runId,
+    payload,
+    process: {
+      durationMs: execution.durationMs,
+      exitCode: execution.exitCode,
+      signal: execution.signal,
+      stderr: execution.stderr,
+      timedOut: execution.timedOut
+    },
+    runner,
+    schemaVersion: SCHEMA_VERSION,
+    stdout: execution.stdout,
+    timestamp: isoNow()
+  };
+}
+
+function baseReplayArtifact({ normalizedResult, payload, rawExecution, runner }) {
+  return {
+    artifactType: 'replay',
+    createdAt: isoNow(),
+    error: normalizedResult.status === 'error' ? normalizedResult.error : undefined,
+    events: normalizedResult.events,
+    framework: normalizedResult.framework,
+    id: payload.runId,
+    prompt: payload.prompt,
+    query: payload.query,
+    runner: {
+      command: runner.display,
+      source: runner.source,
+      type: runner.type
+    },
+    schemaVersion: SCHEMA_VERSION,
+    sources: normalizedResult.sources,
+    status: normalizedResult.status,
+    timestamp: payload.timestamp,
+    usage: normalizedResult.usage,
+    response: normalizedResult.status === 'ok' ? normalizedResult.response : '',
+    runtime: {
+      runnerDurationMs: rawExecution.durationMs
+    }
+  };
+}
+
+function normalizeEventType(type, aliasMap) {
+  if (typeof type !== 'string') {
+    return undefined;
+  }
+
+  return aliasMap[type] || type;
+}
+
+function normalizeEventTimestamp(value, fallback) {
+  if (typeof value !== 'string') {
+    return fallback;
+  }
+
+  const parsed = Date.parse(value);
+
+  if (Number.isNaN(parsed)) {
+    return fallback;
+  }
+
+  return new Date(parsed).toISOString();
+}
+
+function stableStringify(value) {
+  if (!isObject(value) && !Array.isArray(value)) {
+    return JSON.stringify(value);
+  }
+
+  return JSON.stringify(value, Object.keys(value).sort());
+}
+
+function healReplayArtifact(artifact, rules) {
+  const healed = structuredClone(artifact);
+  const healLog = [];
+  const aliasMap = {
+    ...DEFAULT_EVENT_ALIASES,
+    ...(isObject(rules?.eventAliases) ? rules.eventAliases : {})
+  };
+
+  if (!Array.isArray(healed.events)) {
+    healed.events = [];
+    healLog.push({
+      code: 'H_EVENTS_DEFAULTED_EMPTY',
+      message: 'Top-level events was not an array. Defaulted to [].',
+      path: '$.events'
+    });
+  }
+
+  const normalizedEvents = [];
+
+  for (const [index, event] of healed.events.entries()) {
+    if (!isObject(event)) {
+      healLog.push({
+        code: 'H_EVENT_DROPPED_NON_OBJECT',
+        message: `Dropped events[${index}] because it was not an object.`,
+        path: `$.events[${index}]`
+      });
+      continue;
+    }
+
+    const normalizedType = normalizeEventType(event.type, aliasMap);
+
+    if (!normalizedType) {
+      healLog.push({
+        code: 'H_EVENT_DROPPED_MISSING_TYPE',
+        message: `Dropped events[${index}] because type was missing/invalid.`,
+        path: `$.events[${index}].type`
+      });
+      continue;
+    }
+
+    const normalizedEvent = {
+      payload: isObject(event.payload) ? event.payload : {},
+      runId:
+        typeof event.runId === 'string' && event.runId.length > 0
+          ? event.runId
+          : healed.id,
+      seq:
+        Number.isInteger(event.seq) && event.seq > 0
+          ? event.seq
+          : normalizedEvents.length + 1,
+      timestamp: normalizeEventTimestamp(event.timestamp, healed.timestamp),
+      type: normalizedType
+    };
+
+    if (!isObject(event.payload) && event.payload !== undefined) {
+      healLog.push({
+        code: 'H_EVENT_PAYLOAD_DEFAULTED_OBJECT',
+        message: `events[${index}].payload was not an object. Defaulted to {}.`,
+        path: `$.events[${index}].payload`
+      });
+    }
+
+    if (event.type !== normalizedType) {
+      healLog.push({
+        code: 'H_EVENT_TYPE_ALIASED',
+        message: `Mapped event type ${event.type} -> ${normalizedType}.`,
+        path: `$.events[${index}].type`
+      });
+    }
+
+    normalizedEvents.push(normalizedEvent);
+  }
+
+  normalizedEvents.sort((left, right) => {
+    if (left.seq !== right.seq) {
+      return left.seq - right.seq;
+    }
+
+    return Date.parse(left.timestamp) - Date.parse(right.timestamp);
+  });
+
+  const dedupedEvents = [];
+
+  for (const event of normalizedEvents) {
+    const previous = dedupedEvents.at(-1);
+
+    if (
+      previous &&
+      previous.type === event.type &&
+      previous.runId === event.runId &&
+      previous.timestamp === event.timestamp &&
+      stableStringify(previous.payload) === stableStringify(event.payload)
+    ) {
+      healLog.push({
+        code: 'H_EVENT_DEDUPED',
+        message: `Deduplicated repeated event type ${event.type}.`,
+        path: '$.events'
+      });
+      continue;
+    }
+
+    dedupedEvents.push(event);
+  }
+
+  healed.events = dedupedEvents;
+
+  const hasRunStarted = healed.events.some((event) => {
+    return event.type === 'run_started';
+  });
+
+  if (!hasRunStarted) {
+    healed.events.unshift({
+      payload: {},
+      runId: healed.id,
+      seq: 1,
+      timestamp: healed.timestamp,
+      type: 'run_started'
+    });
+    healLog.push({
+      code: 'H_RUN_STARTED_INSERTED',
+      message: 'Inserted synthetic run_started event.',
+      path: '$.events'
+    });
+  }
+
+  const hasAssistantMessage = healed.events.some((event) => {
+    return event.type === 'assistant_message';
+  });
+
+  if (!hasAssistantMessage && healed.status === 'ok' && healed.response) {
+    healed.events.push({
+      payload: {
+        response: healed.response
+      },
+      runId: healed.id,
+      seq: healed.events.length + 1,
+      timestamp: healed.timestamp,
+      type: 'assistant_message'
+    });
+    healLog.push({
+      code: 'H_ASSISTANT_MESSAGE_INSERTED',
+      message: 'Inserted synthetic assistant_message event from final response.',
+      path: '$.events'
+    });
+  }
+
+  const hasTerminalEvent = healed.events.some((event) => {
+    return event.type === 'run_completed' || event.type === 'run_failed';
+  });
+
+  if (!hasTerminalEvent) {
+    healed.events.push({
+      payload: {},
+      runId: healed.id,
+      seq: healed.events.length + 1,
+      timestamp: healed.timestamp,
+      type: healed.status === 'error' ? 'run_failed' : 'run_completed'
+    });
+    healLog.push({
+      code: 'H_TERMINAL_EVENT_INSERTED',
+      message: 'Inserted missing terminal event.',
+      path: '$.events'
+    });
+  }
+
+  for (let index = 0; index < healed.events.length; index++) {
+    const nextSeq = index + 1;
+
+    if (healed.events[index].seq !== nextSeq) {
+      healLog.push({
+        code: 'H_SEQ_RENUMBERED',
+        message: `Renumbered event sequence ${healed.events[index].seq} -> ${nextSeq}.`,
+        path: `$.events[${index}].seq`
+      });
+      healed.events[index].seq = nextSeq;
+    }
+  }
+
+  healed.toolCalls = healed.events
+    .filter((event) => {
+      return event.type === 'tool_completed';
+    })
+    .map((event) => {
+      const payload = event.payload || {};
+
+      return {
+        durationMs:
+          typeof payload.durationMs === 'number' && payload.durationMs >= 0
+            ? payload.durationMs
+            : 0,
+        status: payload.status === 'error' ? 'error' : 'ok',
+        toolName:
+          typeof payload.toolName === 'string' && payload.toolName.length > 0
+            ? payload.toolName
+            : typeof payload.name === 'string' && payload.name.length > 0
+              ? payload.name
+              : 'unknown_tool'
+      };
+    });
+
+  const runStartedEvent = healed.events.find((event) => {
+    return event.type === 'run_started';
+  });
+  const assistantMessageEvent = healed.events.find((event) => {
+    return event.type === 'assistant_message';
+  });
+  const terminalEvent = [...healed.events].reverse().find((event) => {
+    return event.type === 'run_completed' || event.type === 'run_failed';
+  });
+
+  const runStartMs = Date.parse(runStartedEvent?.timestamp || healed.timestamp);
+  const runEndMs = Date.parse(terminalEvent?.timestamp || healed.timestamp);
+
+  healed.timings = {
+    assistantMessageTimestamp: assistantMessageEvent?.timestamp,
+    endToEndLatencyMs:
+      Number.isFinite(runStartMs) && Number.isFinite(runEndMs)
+        ? Math.max(0, runEndMs - runStartMs)
+        : healed.runtime?.runnerDurationMs,
+    runCompletedTimestamp: terminalEvent?.timestamp,
+    runStartedTimestamp: runStartedEvent?.timestamp
+  };
+
+  healed.healing = {
+    issues: healLog,
+    issuesCount: healLog.length,
+    rulesVersion: rules?.version || 'default'
+  };
+
+  return {
+    healLog,
+    healed
+  };
+}
+
+function validateReplayArtifact(artifact, filePath) {
+  const errors = [];
+
+  if (!isObject(artifact)) {
+    errors.push({
+      code: 'E_ARTIFACT_SHAPE_INVALID',
+      message: 'Artifact must be a JSON object.',
+      path: '$',
+      expected: 'object',
+      received: typeof artifact
+    });
+
+    return errors;
+  }
+
+  if (artifact.artifactType !== 'replay') {
+    errors.push({
+      code: 'E_ARTIFACT_TYPE_INVALID',
+      message: 'artifactType must be "replay".',
+      path: '$.artifactType',
+      expected: '"replay"',
+      received: artifact.artifactType
+    });
+  }
+
+  if (artifact.schemaVersion !== SCHEMA_VERSION) {
+    errors.push({
+      code: 'E_SCHEMA_VERSION_UNSUPPORTED',
+      message: `schemaVersion must be ${SCHEMA_VERSION}.`,
+      path: '$.schemaVersion',
+      expected: SCHEMA_VERSION,
+      received: artifact.schemaVersion
+    });
+  }
+
+  if (typeof artifact.id !== 'string' || artifact.id.length === 0) {
+    errors.push({
+      code: 'E_ARTIFACT_ID_INVALID',
+      message: 'id must be a non-empty string.',
+      path: '$.id',
+      expected: 'non-empty string',
+      received: artifact.id
+    });
+  }
+
+  if (artifact.status !== 'ok' && artifact.status !== 'error') {
+    errors.push({
+      code: 'E_ARTIFACT_STATUS_INVALID',
+      message: 'status must be "ok" or "error".',
+      path: '$.status',
+      expected: '"ok" | "error"',
+      received: artifact.status
+    });
+  }
+
+  if (!Array.isArray(artifact.events)) {
+    errors.push({
+      code: 'E_ARTIFACT_EVENTS_INVALID',
+      message: 'events must be an array.',
+      path: '$.events',
+      expected: 'array',
+      received: typeof artifact.events
+    });
+  } else {
+    for (const [index, event] of artifact.events.entries()) {
+      if (!isObject(event)) {
+        errors.push({
+          code: 'E_ARTIFACT_EVENT_INVALID',
+          message: 'Each event must be an object.',
+          path: `$.events[${index}]`,
+          expected: 'object',
+          received: typeof event
+        });
+        continue;
+      }
+
+      if (typeof event.type !== 'string' || event.type.length === 0) {
+        errors.push({
+          code: 'E_ARTIFACT_EVENT_TYPE_INVALID',
+          message: 'Each event.type must be a non-empty string.',
+          path: `$.events[${index}].type`,
+          expected: 'non-empty string',
+          received: event.type
+        });
+      }
+
+      if (!Number.isInteger(event.seq) || event.seq <= 0) {
+        errors.push({
+          code: 'E_ARTIFACT_EVENT_SEQ_INVALID',
+          message: 'Each event.seq must be a positive integer.',
+          path: `$.events[${index}].seq`,
+          expected: 'positive integer',
+          received: event.seq
+        });
+      }
+
+      if (typeof event.timestamp !== 'string' || Number.isNaN(Date.parse(event.timestamp))) {
+        errors.push({
+          code: 'E_ARTIFACT_EVENT_TIMESTAMP_INVALID',
+          message: 'Each event.timestamp must be a valid ISO-8601 string.',
+          path: `$.events[${index}].timestamp`,
+          expected: 'ISO-8601 timestamp string',
+          received: event.timestamp
+        });
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return errors.map((error) => {
+      return {
+        ...error,
+        file: filePath
+      };
+    });
+  }
+
+  return [];
+}
+
+async function writeJsonFile(targetPath, data) {
+  await ensureDir(path.dirname(targetPath));
+  await fsp.writeFile(targetPath, `${JSON.stringify(data, null, 2)}\n`, 'utf-8');
+}
+
+function defaultOutputDirectory(cwd) {
+  return path.resolve(cwd, '.replay', 'artifacts', compactDate());
+}
+
+function artifactStem(runId, prompt) {
+  const promptPart = sanitizePrompt(prompt) || 'prompt';
+  const now = isoNow().replace(/[:.]/g, '-');
+  return `${now}_${promptPart}_${runId.slice(-8)}`;
+}
+
+async function readHealRules(cwd) {
+  const rulesPath = path.resolve(cwd, '.replay', 'heal.rules.json');
+
+  if (!(await exists(rulesPath))) {
+    return {
+      rules: {
+        eventAliases: DEFAULT_EVENT_ALIASES,
+        version: 'default'
+      },
+      source: 'default'
+    };
+  }
+
+  const raw = await fsp.readFile(rulesPath, 'utf-8');
+  const parsed = safeJsonParse(raw, 'E_HEAL_RULES_INVALID_JSON');
+
+  if (!isObject(parsed)) {
+    throw new ReplayCliError({
+      code: 'E_HEAL_RULES_SHAPE_INVALID',
+      message: '.replay/heal.rules.json must be a JSON object.',
+      path: '.replay/heal.rules.json'
+    });
+  }
+
+  return {
+    rules: {
+      eventAliases: isObject(parsed.eventAliases)
+        ? parsed.eventAliases
+        : DEFAULT_EVENT_ALIASES,
+      version: typeof parsed.version === 'string' ? parsed.version : 'custom'
+    },
+    source: rulesPath
+  };
+}
+
+async function collectJsonFiles(inputPath) {
+  const absolutePath = path.resolve(process.cwd(), inputPath);
+
+  if (!(await exists(absolutePath))) {
+    throw new ReplayCliError({
+      code: 'E_INPUT_PATH_NOT_FOUND',
+      message: `Input path does not exist: ${absolutePath}`,
+      path: '--in',
+      howToFix: 'Provide an existing file or directory path.'
+    });
+  }
+
+  const stat = await fsp.stat(absolutePath);
+
+  if (stat.isFile()) {
+    if (!absolutePath.endsWith('.json')) {
+      throw new ReplayCliError({
+        code: 'E_INPUT_FILE_NOT_JSON',
+        message: 'Input file must end with .json.',
+        path: '--in',
+        received: absolutePath
+      });
+    }
+
+    return [absolutePath];
+  }
+
+  if (!stat.isDirectory()) {
+    throw new ReplayCliError({
+      code: 'E_INPUT_NOT_FILE_OR_DIR',
+      message: 'Input must be a file or directory.',
+      path: '--in',
+      received: absolutePath
+    });
+  }
+
+  const files = [];
+
+  async function walk(directory) {
+    const entries = await fsp.readdir(directory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const absolute = path.resolve(directory, entry.name);
+
+      if (entry.isDirectory()) {
+        await walk(absolute);
+      } else if (entry.isFile() && absolute.endsWith('.json')) {
+        files.push(absolute);
+      }
+    }
+  }
+
+  await walk(absolutePath);
+
+  return files.sort();
+}
+
+async function captureCommand({ options, positionals }) {
+  const cwd = process.cwd();
+  const prompt = await resolvePrompt(positionals);
+  const context = await resolveContext(options);
+  const { runner } = await discoverRunner(cwd, options.runner);
+  const { rules, source: healRulesSource } = await readHealRules(cwd);
+
+  const outputDir = options.out
+    ? path.resolve(cwd, options.out)
+    : defaultOutputDirectory(cwd);
+
+  await ensureDir(outputDir);
+
+  const runId = options.id || `run_${Date.now()}_${randomShortId()}`;
+  const payload = {
+    context,
+    prompt,
+    query: prompt,
+    runId,
+    timestamp: isoNow()
+  };
+
+  const execution = await runRunner({
+    payload,
+    runner,
+    timeoutMs: options.timeoutMs
+  });
+
+  const stem = artifactStem(runId, prompt);
+  const rawPath = path.resolve(outputDir, `${stem}.raw.json`);
+  const rawArtifact = buildRawArtifact({
+    execution,
+    payload,
+    runner
+  });
+
+  await writeJsonFile(rawPath, rawArtifact);
+
+  if (execution.timedOut) {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_TIMEOUT',
+      message: `Runner exceeded timeout (${options.timeoutMs}ms).`,
+      details: {
+        rawArtifact: rawPath,
+        timeoutMs: options.timeoutMs
+      },
+      howToFix:
+        'Increase --timeout-ms, optimize your runner, or return partial error output earlier.'
+    });
+  }
+
+  if (execution.exitCode !== 0) {
+    throw new ReplayCliError({
+      code: 'E_RUNNER_EXIT_NON_ZERO',
+      message: `Runner exited with non-zero code: ${execution.exitCode}`,
+      details: {
+        exitCode: execution.exitCode,
+        rawArtifact: rawPath,
+        stderr: execution.stderr.slice(-2000)
+      },
+      howToFix: 'Fix the runner process error and retry the command.'
+    });
+  }
+
+  const parsedOutput = parseRunnerOutput(execution.stdout);
+  const normalizedResult = normalizeRunnerResult(parsedOutput, execution.stderr);
+  const replayArtifact = baseReplayArtifact({
+    normalizedResult,
+    payload,
+    rawExecution: execution,
+    runner
+  });
+
+  const preHealPath = path.resolve(outputDir, `${stem}.artifact.json`);
+  await writeJsonFile(preHealPath, replayArtifact);
+
+  let healedResult = {
+    healLog: [],
+    healed: replayArtifact
+  };
+
+  if (options.heal) {
+    healedResult = healReplayArtifact(replayArtifact, rules);
+  }
+
+  const healedPath = path.resolve(outputDir, `${stem}.healed.json`);
+  const healLogPath = path.resolve(outputDir, `${stem}.heal-log.json`);
+  await writeJsonFile(healedPath, healedResult.healed);
+  await writeJsonFile(healLogPath, {
+    artifactId: runId,
+    generatedAt: isoNow(),
+    healRulesSource,
+    issues: healedResult.healLog,
+    schemaVersion: SCHEMA_VERSION
+  });
+
+  const validationErrors = validateReplayArtifact(healedResult.healed, healedPath);
+
+  if (validationErrors.length > 0) {
+    throw new ReplayCliError({
+      code: 'E_HEALED_ARTIFACT_INVALID',
+      message: 'Healed artifact failed validation.',
+      details: {
+        errors: validationErrors,
+        healedPath
+      },
+      howToFix: 'Update runner output to include valid status/response/events fields.'
+    });
+  }
+
+  outputJson({
+    artifactId: runId,
+    command: 'capture',
+    healIssues: healedResult.healLog,
+    normalizationIssues: normalizedResult.normalizationIssues,
+    ok: true,
+    paths: {
+      artifact: preHealPath,
+      healLog: healLogPath,
+      healed: healedPath,
+      raw: rawPath
+    },
+    status: normalizedResult.status
+  });
+}
+
+async function validateCommand({ options }) {
+  const inputPath = options.in || '.replay/artifacts';
+  const files = await collectJsonFiles(inputPath);
+  const report = {
+    checked: 0,
+    command: 'validate',
+    errors: [],
+    invalid: 0,
+    ok: true,
+    scanned: files.length,
+    skipped: 0,
+    valid: 0
+  };
+
+  for (const file of files) {
+    const content = await fsp.readFile(file, 'utf-8');
+    const parsed = safeJsonParse(content, 'E_ARTIFACT_JSON_INVALID');
+
+    if (parsed?.artifactType !== 'replay') {
+      report.skipped += 1;
+      continue;
+    }
+
+    report.checked += 1;
+
+    const validationErrors = validateReplayArtifact(parsed, file);
+
+    if (validationErrors.length > 0) {
+      report.invalid += 1;
+      report.errors.push(...validationErrors);
+    } else {
+      report.valid += 1;
+    }
+  }
+
+  report.ok = report.invalid === 0;
+  outputJson(report);
+
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+}
+
+async function healCommand({ options }) {
+  const cwd = process.cwd();
+  const inputPath = options.in || '.replay/artifacts';
+  const outDir = path.resolve(cwd, options.out || '.replay/healed');
+  const files = await collectJsonFiles(inputPath);
+  const { rules, source: healRulesSource } = await readHealRules(cwd);
+
+  await ensureDir(outDir);
+
+  const report = {
+    command: 'heal',
+    files: [],
+    healedCount: 0,
+    ok: true,
+    outDir,
+    sourceCount: files.length
+  };
+
+  for (const file of files) {
+    const content = await fsp.readFile(file, 'utf-8');
+    const parsed = safeJsonParse(content, 'E_ARTIFACT_JSON_INVALID');
+
+    if (parsed?.artifactType !== 'replay') {
+      report.files.push({
+        file,
+        skipped: true,
+        reason: 'artifactType is not replay'
+      });
+      continue;
+    }
+
+    const { healed, healLog } = healReplayArtifact(parsed, rules);
+    const outputFile = path.resolve(outDir, path.basename(file));
+    const healLogFile = path.resolve(
+      outDir,
+      path.basename(file, '.json') + '.heal-log.json'
+    );
+
+    await writeJsonFile(outputFile, healed);
+    await writeJsonFile(healLogFile, {
+      artifactId: healed.id,
+      generatedAt: isoNow(),
+      healRulesSource,
+      issues: healLog,
+      schemaVersion: SCHEMA_VERSION,
+      sourceFile: file
+    });
+
+    report.files.push({
+      file,
+      healIssues: healLog.length,
+      healedFile: outputFile,
+      healLogFile,
+      skipped: false
+    });
+    report.healedCount += 1;
+  }
+
+  outputJson(report);
+}
+
+async function reportCommand({ options }) {
+  const inputPath = options.in || '.replay/artifacts';
+  const files = await collectJsonFiles(inputPath);
+
+  const replayFiles = [];
+  for (const file of files) {
+    const content = await fsp.readFile(file, 'utf-8');
+    const parsed = safeJsonParse(content, 'E_ARTIFACT_JSON_INVALID');
+
+    if (parsed?.artifactType === 'replay') {
+      replayFiles.push({
+        artifact: parsed,
+        file
+      });
+    }
+  }
+
+  if (replayFiles.length === 0) {
+    outputJson({
+      command: 'report',
+      ok: true,
+      summary: {
+        errors: 0,
+        noData: true,
+        ok: 0,
+        total: 0
+      }
+    });
+    return;
+  }
+
+  const latencies = replayFiles
+    .map(({ artifact }) => artifact.timings?.endToEndLatencyMs)
+    .filter((value) => typeof value === 'number');
+
+  const summary = {
+    averageLatencyMs:
+      latencies.length > 0
+        ? Math.round(
+            latencies.reduce((sum, value) => {
+              return sum + value;
+            }, 0) / latencies.length
+          )
+        : null,
+    error: replayFiles.filter(({ artifact }) => artifact.status === 'error').length,
+    ok: replayFiles.filter(({ artifact }) => artifact.status === 'ok').length,
+    total: replayFiles.length,
+    totalToolCalls: replayFiles.reduce((sum, { artifact }) => {
+      return sum + ensureArray(artifact.toolCalls).length;
+    }, 0)
+  };
+
+  outputJson({
+    command: 'report',
+    ok: true,
+    summary
+  });
+}
+
+async function run() {
+  const { command, options, positionals } = parseArgs(process.argv.slice(2));
+
+  if (command === 'help' || options.help) {
+    printHelp();
+    return;
+  }
+
+  if (command === 'capture') {
+    await captureCommand({ options, positionals });
+    return;
+  }
+
+  if (command === 'validate') {
+    await validateCommand({ options });
+    return;
+  }
+
+  if (command === 'heal') {
+    await healCommand({ options });
+    return;
+  }
+
+  if (command === 'report') {
+    await reportCommand({ options });
+    return;
+  }
+
+  throw new ReplayCliError({
+    code: 'E_COMMAND_UNKNOWN',
+    message: `Unknown command: ${command}`,
+    howToFix: 'Use `replay help` to see available commands.'
+  });
+}
+
+run().catch((error) => {
+  outputError(error);
+  process.exitCode = 1;
+});