api-tracer-kit 1.0.0

package/cli/server.mjs

@@ -0,0 +1,1576 @@
+#!/usr/bin/env node
+/**
+ * The console server: serves the UI and forwards test calls to the real API.
+ *
+ * Requests are forwarded from here rather than from the page for two reasons:
+ * the browser would be blocked by CORS, and the auth token would have to live
+ * in client-side JS. The token is written owner-only to the data directory so a
+ * restart does not sign you out, and `Sign out` deletes it.
+ *
+ * Nothing in here knows anything about a particular application. The catalog
+ * supplies the endpoints, the base URLs, the auth header and how to read a
+ * response envelope; the config file supplies the sign-in flow, if the API has
+ * one worth automating.
+ */
+import { createServer } from 'node:http';
+import { randomUUID, createHmac, randomInt, timingSafeEqual } from 'node:crypto';
+import { readFileSync, writeFileSync, appendFileSync, existsSync, mkdirSync, watchFile, rmSync } from 'node:fs';
+import { join, dirname, extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { importHar, importCurl, toComparablePath, matchEndpoint, parseQuery, redact } from './import.mjs';
+import { shapeOfBody, diffShapes, summarizeDrift } from './shape.mjs';
+import { buildReport, toMarkdown } from './report.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const WEB = join(HERE, 'web');
+/**
+ * Where the console keeps what it has learned. Defaults to `.api-tracer` in the
+ * project it was started from, so nothing is written inside the package and a
+ * second project gets its own captures.
+ */
+const DATA = process.env.API_TRACER_DATA
+  ? resolve(process.env.API_TRACER_DATA)
+  : resolve(process.cwd(), '.api-tracer');
+mkdirSync(DATA, { recursive: true });
+
+const CATALOG = join(DATA, 'endpoints.json');
+const RESULTS = join(DATA, 'results.json');
+const VARS = join(DATA, 'variables.json');
+const SAMPLES = join(DATA, 'samples.json');
+const CONTRACTS = join(DATA, 'contracts.json');
+const EXTRAS = join(DATA, 'uncatalogued.json');
+const LASTRUN = join(DATA, 'lastrun.json');
+const TOKENS = join(DATA, 'tokens.json');
+const RUNS = join(DATA, 'runs.jsonl');
+// a blank PORT would become 0 (a random port), so treat blank as unset
+const PORT = Number(process.env.PORT) || 4400;
+// deployed behind a proxy this needs 0.0.0.0; on a laptop it should stay local
+const HOST = process.env.HOST || '127.0.0.1';
+/**
+ * Origins allowed to post recordings. Localhost always works for local use; a
+ * deployed app origin has to be named explicitly, so a stray site cannot feed or
+ * read this console.
+ */
+const ALLOWED_ORIGINS = (process.env.ALLOWED_ORIGINS ?? '')
+  .split(',')
+  .map((o) => o.trim())
+  .filter(Boolean);
+/** mount point when served under a path, e.g. BASE_PATH=/api-console */
+const BASE_PATH = (process.env.BASE_PATH ?? '').replace(/\/+$/, '');
+/*
+ * Shared-instance guards. On a console several developers use, one person's click
+ * should not change what everyone else is recording or which API they are hitting.
+ */
+const LOCK_RECORDING = process.env.LOCK_RECORDING === '1';
+const LOCK_ENV = process.env.LOCK_ENV ?? '';
+
+/** optional gate; the recorder is exempt, since the app cannot send credentials */
+const AUTH_USER = process.env.CONSOLE_USER ?? '';
+const AUTH_PASS = process.env.CONSOLE_PASS ?? '';
+const BATCH_CONCURRENCY = 6;
+
+// importing this file (tests) must not start a server or hold the event loop open
+const isMain = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];
+
+/**
+ * An empty catalog is a valid state, not an error: a console pointed at a
+ * project it has not scanned yet still records live traffic, and every call it
+ * cannot explain becomes an endpoint of its own.
+ */
+const EMPTY_CATALOG = { scannedAt: null, baseUrls: {}, auth: { header: 'Authorization' }, endpoints: [] };
+
+function readCatalog() {
+  try {
+    const raw = JSON.parse(readFileSync(CATALOG, 'utf8'));
+    return { ...EMPTY_CATALOG, ...raw, auth: { ...EMPTY_CATALOG.auth, ...(raw.auth ?? {}) } };
+  } catch {
+    return { ...EMPTY_CATALOG };
+  }
+}
+
+let catalog = readCatalog();
+
+/**
+ * Replaces the loaded catalog. `api-tracer serve` uses this after reading a
+ * project's config, and it is how a test gets a known catalog in without
+ * writing one to disk first.
+ */
+export function useCatalog(next) {
+  catalog = { ...EMPTY_CATALOG, ...next, auth: { ...EMPTY_CATALOG.auth, ...(next?.auth ?? {}) } };
+  return catalog;
+}
+
+/** the config file, when the project has one; every field is optional */
+export function useConfig(next) {
+  config = { ...config, ...(next ?? {}) };
+  if (config.name) config.name = String(config.name);
+  return config;
+}
+let config = { name: 'API', login: null, envelope: undefined };
+
+// `yarn scan` while the server is up should take effect without a restart
+if (isMain)
+  watchFile(CATALOG, { interval: 1000 }, () => {
+    try {
+      catalog = readCatalog();
+      console.log(`catalog reloaded: ${catalog.endpoints.length} endpoints`);
+    } catch (e) {
+      console.warn(`catalog reload failed, keeping the old one: ${e.message}`);
+    }
+  });
+
+/**
+ * Tokens are kept so a restart does not make you sign in again. The file is
+ * written owner-only and lives in the gitignored data/ directory -- it is still a
+ * real credential on disk, so `Sign out` deletes it, and it is worth doing that
+ * on a shared machine.
+ */
+function loadStoredTokens() {
+  try {
+    const raw = JSON.parse(readFileSync(TOKENS, 'utf8'));
+    // older files were the bare header -> value map
+    return raw.tokens ? raw : { tokens: raw, owner: null };
+  } catch {
+    return { tokens: {}, owner: null };
+  }
+}
+
+function saveTokens() {
+  try {
+    if (!Object.keys(session.tokens).length) {
+      rmSync(TOKENS, { force: true });
+      return;
+    }
+    writeFileSync(
+      TOKENS,
+      `${JSON.stringify({ tokens: session.tokens, owner: session.tokenOwner }, null, 2)}\n`,
+      { mode: 0o600 },
+    );
+  } catch (e) {
+    console.warn(`could not save the token: ${e.message}`);
+  }
+}
+
+const stored = loadStoredTokens();
+
+const session = {
+  tokens: stored.tokens, // header name -> value, e.g. { AUTH_TOKEN: '...' }
+  env: LOCK_ENV || 'dev',
+  results: loadResults(), // endpoint id -> last result summary, for the dashboard
+  vars: loadVars(), // {{name}} -> value, filled by hand or captured from a response
+  samples: loadSamples(), // endpoint id -> real request seen in traffic
+  live: { on: true, count: 0, since: null, unmatched: [] }, // live recorder state
+  contracts: loadContracts(), // endpoint id -> { shape, at, from } baseline
+  extras: loadExtras(), // calls the app made that no service file explains
+  run: loadLastRun(), // the last run, kept so the home page can show it after a restart
+  tokenOwner: stored.owner, // who signed in, for a console more than one person uses
+};
+
+function loadLastRun() {
+  try {
+    return JSON.parse(readFileSync(LASTRUN, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** one line per finished run; the report's trend section reads these back */
+function recordRun() {
+  const scanned = catalog.endpoints.length;
+  const captured = catalog.endpoints.filter((e) => session.samples[e.id]).length;
+  const line = {
+    at: new Date().toISOString(),
+    env: session.env,
+    ran: session.run.done,
+    passed: session.run.passed,
+    failed: session.run.failed,
+    cancelled: session.run.cancelled,
+    captured,
+    coveragePct: scanned ? Math.round((captured / scanned) * 100) : 0,
+  };
+  try {
+    appendFileSync(RUNS, `${JSON.stringify(line)}\n`);
+  } catch (e) {
+    console.warn(`could not record the run: ${e.message}`);
+  }
+}
+
+function loadRuns() {
+  try {
+    return readFileSync(RUNS, 'utf8')
+      .split('\n')
+      .filter(Boolean)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null; // a truncated final line should not lose the history
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function saveLastRun() {
+  try {
+    writeFileSync(LASTRUN, `${JSON.stringify(session.run, null, 2)}\n`);
+  } catch (e) {
+    console.warn(`could not save the last run: ${e.message}`);
+  }
+}
+
+function loadExtras() {
+  try {
+    return JSON.parse(readFileSync(EXTRAS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveExtras() {
+  try {
+    writeFileSync(EXTRAS, `${JSON.stringify(session.extras, null, 2)}\n`);
+  } catch (e) {
+    console.warn(`could not save uncatalogued endpoints: ${e.message}`);
+  }
+}
+
+/**
+ * Everything the tracker knows about: what the scanner found in src/services,
+ * plus anything the app called that the scanner cannot explain. Recording only
+ * what we could match would quietly hide real traffic.
+ */
+const allEndpoints = () => [...catalog.endpoints, ...Object.values(session.extras)];
+const findEndpoint = (id) => allEndpoints().find((e) => e.id === id);
+
+/** turns an unexplained call into a first-class endpoint so it behaves like the rest */
+function adoptEndpoint(method, path) {
+  const id = `uncatalogued.${method} ${path}`;
+  session.extras[id] ??= {
+    id,
+    module: '(uncatalogued)',
+    name: `${method} ${path}`,
+    method,
+    subUrl: path,
+    holes: [],
+    usesParams: true,
+    usesData: MUTATING.has(method),
+    absolute: /^https?:\/\//.test(path),
+    customToken: null,
+    file: 'seen in traffic, not found in src/services',
+    line: 0,
+    usedIn: null,
+    uncatalogued: true,
+  };
+  saveExtras();
+  return session.extras[id];
+}
+
+function loadContracts() {
+  try {
+    return JSON.parse(readFileSync(CONTRACTS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveContracts() {
+  try {
+    writeFileSync(CONTRACTS, `${JSON.stringify(session.contracts, null, 2)}\n`);
+  } catch (e) {
+    console.warn(`could not save contracts: ${e.message}`);
+  }
+}
+
+/**
+ * Compares a response against the endpoint's baseline shape. The first good
+ * response becomes the baseline, so drift only ever reports a real change.
+ */
+function checkContract(id, bodyText, source) {
+  const shape = shapeOfBody(bodyText);
+  if (!shape) return undefined;
+
+  const baseline = session.contracts[id];
+  if (!baseline) {
+    session.contracts[id] = { shape, at: new Date().toISOString(), from: source };
+    saveContracts();
+    return undefined; // nothing to compare against yet
+  }
+
+  const diff = diffShapes(baseline.shape, shape);
+  if (!diff.drifted) {
+    if (baseline.pending) {
+      delete baseline.pending; // drift resolved itself, nothing left to accept
+      saveContracts();
+    }
+    return undefined;
+  }
+
+  // remember the drifted shape so "accept" needs no shape from the browser
+  baseline.pending = shape;
+  saveContracts();
+  return { ...diff, summary: summarizeDrift(diff), baselineAt: baseline.at };
+}
+
+function loadSamples() {
+  try {
+    return JSON.parse(readFileSync(SAMPLES, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveSamples() {
+  try {
+    writeFileSync(SAMPLES, `${JSON.stringify(session.samples, null, 2)}\n`);
+  } catch (e) {
+    console.warn(`could not save samples: ${e.message}`);
+  }
+}
+
+function loadVars() {
+  try {
+    return JSON.parse(readFileSync(VARS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveVars() {
+  try {
+    writeFileSync(VARS, `${JSON.stringify(session.vars, null, 2)}\n`);
+  } catch (e) {
+    console.warn(`could not save variables: ${e.message}`);
+  }
+}
+
+/** `{{patient_id}}` -> its stored value; unknown names are left alone so they stay visible */
+export function fillVars(text) {
+  return String(text ?? '').replace(/\{\{(\w+)\}\}/g, (whole, name) =>
+    session.vars[name] !== undefined ? String(session.vars[name]) : whole,
+  );
+}
+
+/**
+ * Reads a dotted path out of a response body: `data.0.id` walks arrays too.
+ * Returns undefined if any step is missing, which the caller reports.
+ */
+export function pluck(obj, path) {
+  return path
+    .split('.')
+    .reduce((acc, key) => (acc === null || acc === undefined ? undefined : acc[key]), obj);
+}
+
+function loadResults() {
+  try {
+    return JSON.parse(readFileSync(RESULTS, 'utf8'));
+  } catch {
+    return {}; // first run, or the file was cleared
+  }
+}
+
+/** best-effort: losing the results file must never sink a response */
+let saveTimer;
+function saveResults() {
+  clearTimeout(saveTimer);
+  // a bulk run writes 170 times in a few seconds; one write at the end is plenty
+  saveTimer = setTimeout(() => {
+    try {
+      writeFileSync(RESULTS, `${JSON.stringify(session.results, null, 2)}\n`);
+    } catch (e) {
+      console.warn(`could not save results: ${e.message}`);
+    }
+  }, 250);
+}
+
+const baseUrl = () =>
+  catalog.baseUrls[session.env] ?? catalog.baseUrls.dev ?? Object.values(catalog.baseUrls)[0] ?? '';
+
+/* -------------------------------------------------------------------- http */
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+function readBody(req) {
+  return new Promise((ok, fail) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      try {
+        ok(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
+      } catch (e) {
+        fail(new Error(`bad JSON body: ${e.message}`));
+      }
+    });
+    req.on('error', fail);
+  });
+}
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.woff2': 'font/woff2',
+  '.json': 'application/json; charset=utf-8',
+};
+
+function serveStatic(res, urlPath) {
+  const file = join(WEB, urlPath === '/' ? '/index.html' : urlPath);
+  if (!file.startsWith(WEB) || !existsSync(file)) return json(res, 404, { error: 'not found' });
+  res.writeHead(200, {
+    'content-type': MIME[extname(file)] ?? 'application/octet-stream',
+    // dev tool: never serve a stale app.js after an edit
+    'cache-control': 'no-store',
+  });
+  res.end(readFileSync(file));
+}
+
+/* ------------------------------------------------------------------- calls */
+
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * Serializes params the way axios does by default, so what we send matches what
+ * the app sends: arrays become `k[]=a&k[]=b`, nested objects become `k[sub]=v`.
+ */
+export function appendParams(url, params, prefix = '') {
+  for (const [rawKey, v] of Object.entries(params)) {
+    const key = prefix ? `${prefix}[${rawKey}]` : rawKey;
+    if (v === undefined || v === null || v === '') continue;
+    if (Array.isArray(v)) {
+      for (const item of v) {
+        if (item !== null && typeof item === 'object') appendParams(url, item, `${key}[]`);
+        else url.searchParams.append(`${key}[]`, String(item));
+      }
+    } else if (typeof v === 'object') {
+      appendParams(url, v, key);
+    } else {
+      url.searchParams.append(key, String(v));
+    }
+  }
+}
+
+/** builds the absolute URL, filling `${...}` holes with the supplied values */
+export function buildUrl(ep, holeValues = {}, params = {}, rawQuery = '', stringifyKey = '') {
+  let path = ep.subUrl;
+  for (const hole of ep.holes) {
+    path = path.replaceAll(`\${${hole.expr}}`, holeValues[hole.expr] ?? '');
+  }
+  const target = ep.absolute || /^https?:\/\//.test(path) ? path : `${baseUrl()}${path}`;
+  if (!/^https?:\/\//.test(target)) {
+    throw new Error(`no base URL for "${session.env}"; add baseUrls to the config or rerun the scan`);
+  }
+  const url = new URL(target);
+
+  // raw mode: the string is passed through untouched, so odd encodings survive
+  const raw = rawQuery.trim().replace(/^[?&]+/, '');
+  if (raw) return `${url.toString()}${url.search ? '&' : '?'}${raw}`;
+
+  // stringified mode: the whole object goes in one param as encoded JSON
+  if (stringifyKey) {
+    url.searchParams.set(stringifyKey, JSON.stringify(params));
+    return url.toString();
+  }
+
+  appendParams(url, params);
+  return url.toString();
+}
+
+/**
+ * Some APIs answer 200 with the real verdict in the body, e.g.
+ * `{ status: 801, success: false, message: "..." }`, so a 2xx alone is not
+ * enough to call an endpoint healthy. Which fields carry that verdict is read
+ * from the catalog, and an API without the convention simply has no envelope
+ * configured, in which case the HTTP status decides on its own.
+ */
+export function verdict(httpOk, parsed, envelope) {
+  const cfg = envelope ?? config.envelope ?? catalog.envelope;
+  if (cfg === false || !cfg) return { innerCode: undefined, ok: httpOk };
+
+  const codeFields = cfg.codeFields ?? ['status', 'code'];
+  const okField = cfg.okField ?? 'success';
+  const failFrom = cfg.failFrom ?? 400;
+
+  let innerCode;
+  for (const field of codeFields) {
+    if (typeof parsed?.[field] === 'number') {
+      innerCode = parsed[field];
+      break;
+    }
+  }
+  return {
+    innerCode,
+    ok: httpOk && !(typeof innerCode === 'number' && innerCode >= failFrom) && parsed?.[okField] !== false,
+  };
+}
+
+/**
+ * Sends the body the same way the app did. Several screens post FormData, and
+ * those endpoints reject a JSON body, so replaying one as JSON would fail for
+ * reasons that have nothing to do with the endpoint's health.
+ */
+function encodeBody(ep, data, bodyType, headers) {
+  if (!MUTATING.has(ep.method) || bodyType === 'none') return { headers };
+
+  if (bodyType === 'formdata') {
+    const form = new FormData();
+    for (const [k, v] of Object.entries(data ?? {})) {
+      for (const item of Array.isArray(v) ? v : [v]) form.append(k, String(item));
+    }
+    // fetch must set its own multipart boundary, so drop any JSON content-type
+    const { 'Content-Type': _drop, ...rest } = headers;
+    return { headers: rest, body: form };
+  }
+
+  if (bodyType === 'urlencoded') {
+    return {
+      headers: { ...headers, 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams(
+        Object.entries(data ?? {}).map(([k, v]) => [k, String(v)]),
+      ).toString(),
+    };
+  }
+
+  return { headers, body: JSON.stringify(data ?? {}) };
+}
+
+async function callEndpoint(spec) {
+  const ep = findEndpoint(spec.id);
+  if (!ep) throw new Error(`unknown endpoint ${spec.id}`);
+
+  // {{vars}} are substituted everywhere the user can type
+  const holes = Object.fromEntries(
+    Object.entries(spec.holes ?? {}).map(([k, v]) => [k, fillVars(v)]),
+  );
+  const params = JSON.parse(fillVars(JSON.stringify(spec.params ?? {})));
+  const data = JSON.parse(fillVars(JSON.stringify(spec.data ?? {})));
+  const url =
+    spec.url || buildUrl(ep, holes, params, fillVars(spec.rawQuery ?? ''), spec.stringifyKey ?? '');
+  const headers = { 'Content-Type': 'application/json' };
+  // third-party absolute URLs must not receive any of our tokens
+  if (!ep.absolute) {
+    if (ep.customToken === 'ACCESS_TOKEN') {
+      // the app signs a fresh JWT for these and sends no AUTH_TOKEN at all
+      headers.ACCESS_TOKEN = accessJwt();
+    } else {
+      const key = ep.customToken && ep.customToken !== 'CS token' ? ep.customToken : catalog.auth.header;
+      const token = session.tokens[key] ?? session.tokens[catalog.auth.header];
+      if (token) headers[key] = token;
+    }
+  }
+  Object.assign(headers, spec.headers ?? {});
+
+  const started = performance.now();
+  try {
+    const upstream = await fetch(url, {
+      method: ep.method,
+      ...encodeBody(ep, data, spec.bodyType ?? session.samples[ep.id]?.bodyType, headers),
+      signal: AbortSignal.timeout(spec.timeoutMs ?? 30_000),
+    });
+    const text = await upstream.text();
+    const ms = Math.round(performance.now() - started);
+
+    // the API answers 200 with an error code in the body often enough to matter
+    let parsed;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      /* not JSON */
+    }
+    const { ok, innerCode } = verdict(upstream.ok, parsed);
+    const drift = ok ? checkContract(ep.id, text, 'send') : undefined;
+
+    const result = {
+      id: ep.id,
+      url,
+      method: ep.method,
+      status: upstream.status,
+      innerCode,
+      ok,
+      ms,
+      size: Buffer.byteLength(text),
+      headers: Object.fromEntries(upstream.headers),
+      body: text,
+      drift,
+      origin: spec.origin,
+      at: new Date().toISOString(),
+    };
+    // capture rules turn this response into variables the next call can use
+    if (ok && spec.capture && parsed !== undefined) {
+      result.captured = {};
+      for (const [name, path] of Object.entries(spec.capture)) {
+        if (!name || !path) continue;
+        const value = pluck(parsed, path);
+        if (value === undefined || value === null || typeof value === 'object') {
+          result.captured[name] = { path, error: `nothing usable at ${path}` };
+        } else {
+          session.vars[name] = value;
+          result.captured[name] = { path, value };
+        }
+      }
+      saveVars();
+    }
+
+    session.results[ep.id] = summarize(result);
+    saveResults();
+    return result;
+  } catch (e) {
+    const ms = Math.round(performance.now() - started);
+    const message = e.name === 'TimeoutError' ? `timed out after ${ms}ms` : e.message;
+    const result = { id: ep.id, url, method: ep.method, status: null, ok: false, ms, size: 0, error: message, origin: spec.origin, at: new Date().toISOString() };
+    session.results[ep.id] = summarize(result);
+    saveResults();
+    return result;
+  }
+}
+
+const MAX_KEPT_BODY = 20_000;
+
+const summarize = (r) => {
+  const previous = session.results[r.id];
+  // a failure you cannot inspect afterwards is only half a report
+  const failure = r.ok
+    ? undefined
+    : {
+        status: r.status,
+        innerCode: r.innerCode,
+        error: r.error,
+        body: typeof r.body === 'string' ? r.body.slice(0, MAX_KEPT_BODY) : undefined,
+        url: r.url,
+        at: r.at,
+        from: r.origin ?? 'send',
+      };
+
+  return {
+    failure,
+    // set when this endpoint failed during a replay, so the UI can say so plainly
+    failedInReplay: r.origin === 'replay' && !r.ok ? true : undefined,
+    url: r.url, // what was actually called, so a bulk result can be audited
+    drift: r.drift ? { summary: r.drift.summary, count:
+      r.drift.added.length + r.drift.removed.length + r.drift.changed.length } : undefined,
+    status: r.status,
+    innerCode: r.innerCode,
+    ok: r.ok,
+    ms: r.ms,
+    error: r.error,
+    at: r.at,
+    env: session.env,
+    // was it passing before this run? lets the UI call out fresh breakage
+    wasOk: previous ? previous.ok : undefined,
+    lastOkAt: r.ok ? r.at : previous?.lastOkAt,
+  };
+};
+
+/** logging out mid-run would invalidate the token the rest of the run needs */
+const INVALIDATES_SESSION = /log_?out|sign_?out|revoke_token/i;
+
+/** a payload whose secret was stripped cannot be replayed as-is */
+const hasRedacted = (sample) => JSON.stringify(sample?.data ?? {}).includes('<redacted>');
+
+/**
+ * Decides what a bulk run may actually fire, and why anything was left out.
+ * The caller gets the reasons back so the UI never silently drops an endpoint.
+ */
+function planRun(ids, { allowMutating, includeDeletes, includeLogout, includeAccessToken }) {
+  const plan = {
+    queue: [],
+    skipped: { readOnly: 0, writes: [], deletes: [], logout: [], redacted: [], accessToken: [] },
+  };
+
+  for (const id of ids) {
+    const ep = findEndpoint(id);
+    if (!ep) continue;
+
+    // these mint or spend a signed JWT, and several of them are the sign-in chain itself
+    if (ep.customToken === 'ACCESS_TOKEN' && !includeAccessToken) {
+      plan.skipped.accessToken.push(ep.id);
+      continue;
+    }
+
+    if (!MUTATING.has(ep.method)) {
+      plan.queue.push(ep);
+      continue;
+    }
+    if (!allowMutating) {
+      plan.skipped.writes.push(ep.id);
+      continue;
+    }
+    if (ep.method === 'DELETE' && !includeDeletes) {
+      plan.skipped.deletes.push(ep.id);
+      continue;
+    }
+    if (INVALIDATES_SESSION.test(ep.subUrl) && !includeLogout) {
+      plan.skipped.logout.push(ep.id);
+      continue;
+    }
+    if (hasRedacted(session.samples[ep.id])) {
+      // sending the literal "<redacted>" would fail for a reason that is not the endpoint's fault
+      plan.skipped.redacted.push(ep.id);
+      continue;
+    }
+    plan.queue.push(ep);
+  }
+  return plan;
+}
+
+/**
+ * Runs a set of endpoints. Read-only runs go wide; a run that writes goes one at
+ * a time, because captured writes often depend on each other and a failure order
+ * you cannot reproduce is worse than a slow run.
+ */
+async function runBatch(ids, options = {}) {
+  const { allowMutating = false, includeDeletes = false, includeLogout = false } = options;
+  const sequential = options.sequential ?? allowMutating;
+
+  const { queue, skipped } = planRun(ids, { allowMutating, includeDeletes, includeLogout });
+
+  const out = [];
+  let unfilled = 0; // endpoints run with a blank path value, so their result means little
+  let cursor = 0;
+
+  // progress the UI can poll while this runs
+  session.run = {
+    active: true,
+    total: queue.length,
+    done: 0,
+    passed: 0,
+    failed: 0,
+    current: null,
+    finished: [],
+    cancelled: false,
+    startedAt: new Date().toISOString(),
+  };
+
+  const worker = async () => {
+    while (cursor < queue.length) {
+      if (session.run.cancelled) break;
+      const ep = queue[cursor++];
+      session.run.current = { id: ep.id, method: ep.method, module: ep.module };
+      // real traffic first, then a variable named after the hole, then blank
+      const sample = session.samples[ep.id];
+      const holes = {};
+      let missing = false;
+      for (const h of ep.holes) {
+        const value =
+          sample?.pathValues?.[h.expr] ?? session.vars[h.label] ?? session.vars[h.expr];
+        if (value === undefined) missing = true;
+        holes[h.expr] = value === undefined ? '' : String(value);
+      }
+      if (missing) unfilled++;
+      const result = summarize(
+        await callEndpoint({
+          id: ep.id,
+          holes,
+          params: sample?.params ?? {},
+          data: sample?.data ?? {},
+          bodyType: sample?.bodyType,
+          origin: allowMutating ? 'replay' : 'bulk',
+        }),
+      );
+      out.push(result);
+
+      session.run.done++;
+      session.run[result.ok ? 'passed' : 'failed']++;
+      session.run.finished.push({
+        id: ep.id,
+        method: ep.method,
+        ok: result.ok,
+        status: result.status,
+        innerCode: result.innerCode,
+        ms: result.ms,
+        error: result.error,
+      });
+    }
+  };
+
+  const workers = sequential ? 1 : BATCH_CONCURRENCY;
+  await Promise.all(Array.from({ length: workers }, worker));
+
+  const cancelled = session.run.cancelled;
+  session.run = { ...session.run, active: false, current: null };
+  saveLastRun();
+  recordRun();
+
+  return {
+    cancelled,
+    ran: out.length,
+    failed: out.filter((r) => !r.ok).length,
+    skipped:
+      skipped.writes.length +
+      skipped.deletes.length +
+      skipped.logout.length +
+      skipped.redacted.length +
+      skipped.accessToken.length,
+    skippedDetail: skipped,
+    sequential,
+    unfilled,
+    results: session.results,
+  };
+}
+
+/** what a write run would do, so the user can be told before it happens */
+function previewRun(ids, options) {
+  const { queue, skipped } = planRun(ids, options);
+  const byMethod = {};
+  for (const ep of queue) byMethod[ep.method] = (byMethod[ep.method] ?? 0) + 1;
+  return {
+    total: queue.length,
+    byMethod,
+    env: session.env,
+    baseUrl: baseUrl(),
+    skippedDetail: skipped,
+    deletes: ids.map(findEndpoint).filter((e) => e?.method === 'DELETE').map((e) => e.id),
+    accessToken: ids
+      .map(findEndpoint)
+      .filter((e) => e?.customToken === 'ACCESS_TOKEN')
+      .map((e) => e.id),
+    logout: ids
+      .map(findEndpoint)
+      .filter((e) => e && MUTATING.has(e.method) && INVALIDATES_SESSION.test(e.subUrl))
+      .map((e) => e.id),
+  };
+}
+
+/* -------------------------------------------------------------- live record */
+
+/**
+ * One call, streamed from the running app. We keep it as the endpoint's sample
+ * (so its payload and params are prefilled) and as a health result (so the app's
+ * own traffic counts as evidence the endpoint works).
+ */
+function recordLive(call) {
+  if (!session.live.on) return { ignored: 'recording is paused' };
+  if (!call?.url) return { ignored: 'no url' };
+
+  const path = toComparablePath(call.url, catalog.baseUrls);
+  if (path === null) return { ignored: 'not an API host' };
+
+  const method = (call.method ?? 'GET').toUpperCase();
+  const hit = matchEndpoint(method, path, catalog.endpoints);
+
+  // no service file explains this one: record it anyway, flagged as uncatalogued
+  const endpoint = hit?.endpoint ?? adoptEndpoint(method, path);
+  const pathValues = hit?.pathValues ?? {};
+  if (!hit) {
+    const miss = `${method} ${path}`;
+    if (!session.live.unmatched.includes(miss)) session.live.unmatched.push(miss);
+  }
+
+  const id = endpoint.id;
+  session.live.count++;
+  session.live.since ??= new Date().toISOString();
+
+  const query = call.url.includes('?') ? call.url.slice(call.url.indexOf('?')) : '';
+  const params = redact(call.params ?? {});
+  session.samples[id] = {
+    pathValues,
+    params: Object.keys(params).length ? params : parseQuery(query),
+    data: redact(call.data ?? {}),
+    seenAt: new Date().toISOString(),
+    from: `${method} ${path}`,
+    live: true,
+    // kept so an exported HAR carries real content
+    status: call.status,
+    ms: call.ms,
+    // how the app sent the body: json, formdata or urlencoded
+    bodyType: call.bodyType ?? 'json',
+    responseBody: typeof call.body === 'string' ? call.body.slice(0, 100_000) : undefined,
+  };
+  saveSamples();
+
+  // the app's own call is a real health signal, so score it the same way
+  let parsed;
+  try {
+    parsed = call.body ? JSON.parse(call.body) : undefined;
+  } catch {
+    /* not JSON */
+  }
+  const { ok, innerCode } = verdict(
+    typeof call.status === 'number' && call.status >= 200 && call.status < 300,
+    parsed,
+  );
+  session.results[id] = summarize({
+    id,
+    url: call.url,
+    status: call.status,
+    innerCode,
+    ok,
+    ms: call.ms ?? 0,
+    error: call.error,
+    drift: ok ? checkContract(id, call.body, 'live') : undefined,
+    at: new Date().toISOString(),
+  });
+  saveResults();
+
+  return { recorded: id, ok, count: session.live.count };
+}
+
+/* ------------------------------------------------------------------ export */
+
+/** the captured requests for a module, or all of them when module is empty */
+function capturedFor(module) {
+  return allEndpoints()
+    .filter((ep) => (!module || ep.module === module) && session.samples[ep.id])
+    .map((ep) => ({ ep, sample: session.samples[ep.id] }))
+    .sort((a, b) => (a.sample.seenAt < b.sample.seenAt ? -1 : 1));
+}
+
+/** a HAR the browser, Postman or anything else will accept */
+function toHar(entries) {
+  return {
+    log: {
+      version: '1.2',
+      creator: { name: 'api-tracer-kit', version: '1.0' },
+      entries: entries.map(({ ep, sample }) => {
+        const url = buildUrl(ep, sample.pathValues ?? {}, sample.params ?? {});
+        const body = sample.data && Object.keys(sample.data).length ? JSON.stringify(sample.data) : null;
+        const responseText = sample.responseBody ?? '';
+        return {
+          startedDateTime: sample.seenAt,
+          time: sample.ms ?? 0,
+          request: {
+            method: ep.method,
+            url,
+            httpVersion: 'HTTP/1.1',
+            cookies: [],
+            headers: [
+              { name: 'Content-Type', value: 'application/json' },
+              // deliberately a placeholder: real tokens are never exported
+              { name: catalog.auth.header, value: '<paste your token>' },
+            ],
+            queryString: Object.entries(sample.params ?? {}).map(([name, value]) => ({
+              name,
+              value: typeof value === 'object' ? JSON.stringify(value) : String(value),
+            })),
+            headersSize: -1,
+            bodySize: body ? Buffer.byteLength(body) : 0,
+            ...(body
+              ? { postData: { mimeType: 'application/json', text: body, params: [] } }
+              : {}),
+          },
+          response: {
+            status: sample.status ?? 0,
+            statusText: '',
+            httpVersion: 'HTTP/1.1',
+            cookies: [],
+            headers: [],
+            content: {
+              size: Buffer.byteLength(responseText),
+              mimeType: 'application/json',
+              text: responseText,
+            },
+            redirectURL: '',
+            headersSize: -1,
+            bodySize: Buffer.byteLength(responseText),
+          },
+          cache: {},
+          timings: { send: 0, wait: sample.ms ?? 0, receive: 0 },
+        };
+      }),
+    },
+  };
+}
+
+/**
+ * Postman Collection v2.1. Modules become folders, and the host plus token are
+ * left as {{baseUrl}} / {{token}} so the collection works against dev, stage or
+ * prod by switching a Postman environment rather than re-exporting.
+ */
+function toPostman(entries, title) {
+  const base = baseUrl();
+
+  const folders = new Map();
+  for (const { ep, sample } of entries) {
+    if (!folders.has(ep.module)) folders.set(ep.module, []);
+
+    const full = buildUrl(ep, sample.pathValues ?? {}, sample.params ?? {});
+    const rest = full.startsWith(base) ? full.slice(base.length) : full;
+    const [pathPart, queryPart = ''] = rest.split('?');
+
+    const body = bodyForPostman(sample);
+    folders.get(ep.module).push({
+      name: ep.name,
+      request: {
+        method: ep.method,
+        header: [
+          ...(sample.bodyType === 'formdata'
+            ? [] // Postman sets multipart's own content-type, boundary included
+            : [{ key: 'Content-Type', value: contentTypeFor(sample.bodyType) }]),
+          { key: catalog.auth.header, value: '{{token}}' },
+        ],
+        ...(body ? { body } : {}),
+        url: {
+          raw: `{{baseUrl}}${rest}`,
+          host: ['{{baseUrl}}'],
+          path: pathPart.split('/').filter(Boolean),
+          query: [...new URLSearchParams(queryPart)].map(([key, value]) => ({ key, value })),
+        },
+        description: `${ep.file}:${ep.line}\nCaptured ${sample.seenAt}${
+          sample.status ? `, answered ${sample.status}` : ''
+        }`,
+      },
+    });
+  }
+
+  return {
+    info: {
+      name: title,
+      _postman_id: randomUUID(),
+      schema: 'https://schema.getpostman.com/json/collection/v2.1.0/collection.json',
+      description:
+        `Generated by api-tracer-kit from calls the app actually made. ` +
+        `Set the token variable to your ${catalog.auth.header} before running.`,
+    },
+    item: [...folders.entries()]
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([name, item]) => ({ name, item })),
+    variable: [
+      { key: 'baseUrl', value: base },
+      { key: 'token', value: '', type: 'string' },
+    ],
+  };
+}
+
+const contentTypeFor = (bodyType) =>
+  bodyType === 'urlencoded' ? 'application/x-www-form-urlencoded' : 'application/json';
+
+/** the body in whichever mode Postman needs for how the app really sent it */
+function bodyForPostman(sample) {
+  const data = sample.data ?? {};
+  if (!Object.keys(data).length) return null;
+
+  const pairs = Object.entries(data).flatMap(([key, value]) =>
+    (Array.isArray(value) ? value : [value]).map((v) => ({
+      key,
+      value: typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v),
+      type: 'text',
+    })),
+  );
+
+  if (sample.bodyType === 'formdata') return { mode: 'formdata', formdata: pairs };
+  if (sample.bodyType === 'urlencoded') {
+    return { mode: 'urlencoded', urlencoded: pairs.map(({ key, value }) => ({ key, value })) };
+  }
+  return {
+    mode: 'raw',
+    raw: JSON.stringify(data, null, 2),
+    options: { raw: { language: 'json' } },
+  };
+}
+
+/** one runnable cURL command per captured request */
+function toCurl(entries) {
+  const q = (v) => `'${String(v).replaceAll("'", `'\\''`)}'`;
+  return entries
+    .map(({ ep, sample }) => {
+      const url = buildUrl(ep, sample.pathValues ?? {}, sample.params ?? {});
+      const lines = [
+        `# ${ep.id}  (${ep.file}:${ep.line})`,
+        `curl -X ${ep.method} ${q(url)}`,
+        `  -H 'Content-Type: application/json'`,
+        `  -H '${catalog.auth.header}: <paste your token>'`,
+      ];
+      if (sample.data && Object.keys(sample.data).length) {
+        lines.push(`  -d ${q(JSON.stringify(sample.data))}`);
+      }
+      return `${lines[0]}\n${lines.slice(1).join(' \\\n')}`;
+    })
+    .join('\n\n');
+}
+
+/* ------------------------------------------------------------------- login */
+
+/*
+ * Signing in, without knowing anything about the API doing it.
+ *
+ * Plenty of APIs need more than one call to hand out a usable token -- password,
+ * then a one-time code, then a choice of organisation. Rather than make everyone
+ * paste a token, the config file can describe that chain as a list of steps, and
+ * this drives it:
+ *
+ *   login: {
+ *     steps: [
+ *       { name: 'credentials',
+ *         fields: [{ name: 'email', type: 'email' }, { name: 'password', type: 'password' }],
+ *         endpointId: 'session.loginApi', path: '/users/login.json',
+ *         body: (input, state) => ({ user: input }),
+ *         then: (data, state) => ({ state: { apiToken: data.api_token }, next: 'otp' }) },
+ *     ],
+ *   }
+ *
+ * A project with no `login` config still gets `Paste a token`, which is all most
+ * APIs need. The password is forwarded once and is never stored, logged, or
+ * written to disk; only the resulting token is kept.
+ */
+const login = { state: {}, stage: null };
+
+const b64url = (buf) => Buffer.from(buf).toString('base64url');
+
+/**
+ * A short-lived HS256 JWT, for APIs that want every call signed. The signing key
+ * and the payload shape come from the config or from what the scan read out of
+ * the app, so a rotated key is picked up by rescanning rather than edited here.
+ */
+export function accessJwt() {
+  const cfg = config.login?.jwt ?? catalog.jwt;
+  if (!cfg) throw new Error('no JWT signing config; add login.jwt to the config file');
+
+  const secret = (session.env === 'prod' ? cfg.secretProd : cfg.secretDefault) ?? cfg.secret;
+  if (!secret) throw new Error('no signing secret in the JWT config');
+
+  const now = Math.floor(Date.now() / 1000);
+  const alphabet = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+  const secretCode = Array.from({ length: 10 }, () => alphabet[randomInt(alphabet.length)]).join('');
+
+  const payload = cfg.payload
+    ? cfg.payload({ now, secretCode, env: session.env })
+    : {
+        timestamp: `${cfg.timestampPrefix ?? ''}${new Date().toISOString().slice(0, 10)}`,
+        secret_code: secretCode,
+        exp: now + (cfg.ttlSeconds ?? 600),
+        code: randomUUID(),
+        iat: now,
+      };
+
+  const signingInput = `${b64url(JSON.stringify({ alg: 'HS256' }))}.${b64url(JSON.stringify(payload))}`;
+  const signature = createHmac('sha256', secret).update(signingInput).digest('base64url');
+  return `${signingInput}.${signature}`;
+}
+
+/** the scanned URL for a step, so a path change in the app is picked up here */
+const loginUrl = (id, fallback) => `${baseUrl()}${(id && findEndpoint(id)?.subUrl) || fallback}`;
+
+async function loginCall(url, body, headers) {
+  const upstream = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(30_000),
+  });
+
+  const text = await upstream.text();
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`login step returned non-JSON (${upstream.status})`);
+  }
+  // failure may be reported in the envelope rather than the status line
+  const { ok } = verdict(upstream.ok, parsed);
+  if (!ok) throw new Error(parsed.message || parsed.error || `login step failed (${upstream.status})`);
+  return parsed.data ?? parsed;
+}
+
+const loginSteps = () => config.login?.steps ?? [];
+const stepNamed = (name) => loginSteps().find((s) => s.name === name) ?? loginSteps()[0];
+
+/** what the UI should ask for next, without the UI knowing the flow */
+export function loginPlan() {
+  const steps = loginSteps();
+  if (!steps.length) return { supported: false };
+  const step = login.stage ? stepNamed(login.stage) : steps[0];
+  return {
+    supported: true,
+    stage: step?.name ?? null,
+    title: step?.title ?? step?.name ?? null,
+    fields: step?.fields ?? [],
+    choices: login.choices ?? null,
+    state: { ...login.state, password: undefined },
+  };
+}
+
+/** runs one step of the configured chain and says what comes next */
+export async function loginStep(input = {}) {
+  const steps = loginSteps();
+  if (!steps.length) throw new Error('this console has no sign-in flow configured; paste a token instead');
+
+  const step = stepNamed(input.stage ?? login.stage ?? steps[0].name);
+  if (!step) throw new Error(`unknown login step ${input.stage}`);
+
+  const headers = {};
+  if (config.login?.jwt) headers[config.login.jwt.headerName ?? 'ACCESS_TOKEN'] = accessJwt();
+  Object.assign(headers, step.headers ? step.headers(login.state) : {});
+
+  const body = step.body ? step.body(input, login.state) : input;
+  const data = await loginCall(loginUrl(step.endpointId, step.path), body, headers);
+
+  const outcome = step.then ? step.then(data, login.state, input) : {};
+  Object.assign(login.state, outcome.state ?? {});
+  login.choices = outcome.choices ?? null;
+
+  if (outcome.token) {
+    session.tokens[config.login?.header ?? catalog.auth.header] = outcome.token;
+    session.tokenOwner = outcome.owner
+      ? { ...outcome.owner, at: new Date().toISOString() }
+      : { at: new Date().toISOString() };
+    saveTokens();
+    // the intermediate tokens have done their job
+    login.state = {};
+    login.stage = null;
+    login.choices = null;
+    return { done: true, tokensHeld: Object.keys(session.tokens), user: session.tokenOwner };
+  }
+
+  login.stage = outcome.next ?? null;
+  return { done: false, ...loginPlan(), ...(outcome.info ?? {}) };
+}
+
+const currentReport = () =>
+  buildReport({
+    catalog,
+    endpoints: allEndpoints(),
+    samples: session.samples,
+    results: session.results,
+    contracts: session.contracts,
+    runs: loadRuns(),
+    env: session.env,
+  });
+
+/* ------------------------------------------------------------------ routes */
+
+/** constant-time compare, so the password cannot be guessed a byte at a time */
+function sameSecret(a, b) {
+  const x = Buffer.from(a);
+  const y = Buffer.from(b);
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+function authorised(req) {
+  if (!AUTH_USER && !AUTH_PASS) return true;
+  const header = req.headers.authorization ?? '';
+  if (!header.startsWith('Basic ')) return false;
+  const [user, ...rest] = Buffer.from(header.slice(6), 'base64').toString().split(':');
+  return sameSecret(user, AUTH_USER) && sameSecret(rest.join(':'), AUTH_PASS);
+}
+
+async function handle(req, res) {
+  const url = new URL(req.url ?? '/', `http://localhost:${PORT}`);
+  const method = req.method ?? 'GET';
+
+  // CloudFront forwards the mount path as-is, so strip it before routing
+  let { pathname } = url;
+  if (BASE_PATH && pathname.startsWith(BASE_PATH)) {
+    // /api-console must become /api-console/ or relative assets resolve one level up
+    if (pathname === BASE_PATH) {
+      res.writeHead(302, { location: `${BASE_PATH}/` });
+      return res.end();
+    }
+    pathname = pathname.slice(BASE_PATH.length) || '/';
+  }
+
+  // the app runs on another localhost port, so the recorder needs CORS
+  const origin = req.headers.origin;
+  const originAllowed =
+    origin && (/^https?:\/\/localhost(:\d+)?$/.test(origin) || ALLOWED_ORIGINS.includes(origin));
+  if (originAllowed) {
+    res.setHeader('access-control-allow-origin', origin);
+    res.setHeader('access-control-allow-headers', 'content-type');
+    res.setHeader('access-control-allow-methods', 'POST, GET, DELETE, OPTIONS');
+  }
+  if (method === 'OPTIONS') {
+    res.writeHead(204);
+    return res.end();
+  }
+
+  // the recorder posts from the app, which has no way to send basic auth
+  if (pathname !== '/api/record' && !authorised(req)) {
+    res.writeHead(401, {
+      'www-authenticate': 'Basic realm="API console", charset="UTF-8"',
+      'content-type': 'application/json',
+    });
+    return res.end(JSON.stringify({ error: 'authentication required' }));
+  }
+
+  if (!pathname.startsWith('/api/')) return serveStatic(res, pathname);
+
+  if (pathname === '/api/endpoints' && method === 'GET') {
+    return json(res, 200, {
+      scannedAt: catalog.scannedAt,
+      baseUrls: catalog.baseUrls,
+      auth: catalog.auth,
+      endpoints: allEndpoints(),
+      env: session.env,
+      // names of tokens held, never the values
+      tokensHeld: Object.keys(session.tokens),
+      // on a shared console it matters whose session the token belongs to
+      tokenOwner: session.tokenOwner ?? null,
+      locks: { recording: LOCK_RECORDING, env: LOCK_ENV || null },
+      name: config.name ?? 'API',
+      login: loginPlan(),
+      sourceLabel: catalog.sourceLabel ?? 'the source',
+      results: session.results,
+      vars: session.vars,
+      samples: session.samples,
+      live: session.live,
+      contracts: session.contracts,
+      lastRun: session.run,
+    });
+  }
+
+  if (pathname === '/api/login' && method === 'GET') {
+    return json(res, 200, loginPlan());
+  }
+
+  if (pathname === '/api/login' && method === 'POST') {
+    return json(res, 200, await loginStep(await readBody(req)));
+  }
+
+  if (pathname === '/api/token' && method === 'POST') {
+    const { key, token } = await readBody(req);
+    const name = key || catalog.auth.header;
+    if (token) session.tokens[name] = token;
+    else {
+      delete session.tokens[name];
+      session.tokenOwner = null;
+    }
+    saveTokens();
+    return json(res, 200, { tokensHeld: Object.keys(session.tokens) });
+  }
+
+  if (pathname === '/api/env' && method === 'POST') {
+    const { env } = await readBody(req);
+    if (LOCK_ENV) {
+      return json(res, 400, { error: `this console is pinned to ${LOCK_ENV}` });
+    }
+    if (!catalog.baseUrls[env]) return json(res, 400, { error: `unknown env ${env}` });
+    session.env = env;
+    // results from another environment would be misleading
+    session.results = {};
+    saveResults();
+    return json(res, 200, { env: session.env, baseUrl: baseUrl() });
+  }
+
+  if (pathname === '/api/export' && method === 'GET') {
+    const module = url.searchParams.get('module') ?? '';
+    const format = url.searchParams.get('format') ?? 'har';
+    const entries = capturedFor(module);
+    if (!entries.length) return json(res, 404, { error: 'nothing captured yet for that selection' });
+
+    const stamp = new Date().toISOString().slice(0, 10);
+    const name = `${module || 'all-modules'}-${stamp}`;
+
+    const shape = {
+      curl: { ext: 'sh', type: 'text/plain; charset=utf-8', build: () => toCurl(entries) },
+      postman: {
+        ext: 'postman_collection.json',
+        type: 'application/json',
+        build: () =>
+          `${JSON.stringify(toPostman(entries, `${module || config.name || 'API'} (captured ${stamp})`), null, 2)}\n`,
+      },
+      har: {
+        ext: 'har',
+        type: 'application/json',
+        build: () => `${JSON.stringify(toHar(entries), null, 2)}\n`,
+      },
+    }[format] ?? null;
+    if (!shape) return json(res, 400, { error: `unknown format ${format}` });
+
+    const body = shape.build();
+    res.writeHead(200, {
+      'content-type': shape.type,
+      'content-disposition': `attachment; filename="${name}.${shape.ext}"`,
+      'content-length': Buffer.byteLength(body),
+    });
+    return res.end(body);
+  }
+
+  if (pathname === '/api/record' && method === 'POST') {
+    return json(res, 200, recordLive(await readBody(req)));
+  }
+
+  if (pathname === '/api/live' && method === 'GET') {
+    return json(res, 200, { ...session.live, samples: session.samples, results: session.results });
+  }
+
+  if (pathname === '/api/live' && method === 'POST') {
+    const { on } = await readBody(req);
+    if (LOCK_RECORDING && !on) {
+      return json(res, 400, {
+        error: 'recording is locked on for this console, so one person cannot stop it for everyone',
+      });
+    }
+    session.live.on = Boolean(on);
+    if (session.live.on && !session.live.since) session.live.since = new Date().toISOString();
+    return json(res, 200, session.live);
+  }
+
+  if (pathname === '/api/live' && method === 'DELETE') {
+    session.live = { on: session.live.on, count: 0, since: new Date().toISOString(), unmatched: [] };
+    return json(res, 200, session.live);
+  }
+
+  if (pathname === '/api/import' && method === 'POST') {
+    const { kind, text } = await readBody(req);
+    if (!text?.trim()) return json(res, 400, { error: 'nothing to import' });
+    const ctx = { baseUrls: catalog.baseUrls, endpoints: catalog.endpoints };
+    const out = kind === 'curl' ? importCurl(text, ctx) : importHar(text, ctx);
+    Object.assign(session.samples, out.samples);
+
+    // the same rule as live capture: an unexplained call is still recorded
+    for (const miss of out.unmatchedCalls ?? []) {
+      const ep = adoptEndpoint(miss.method, miss.path);
+      session.samples[ep.id] = miss.sample;
+    }
+    saveSamples();
+    return json(res, 200, {
+      ...out,
+      adopted: (out.unmatchedCalls ?? []).length,
+      samples: session.samples,
+      endpoints: allEndpoints(),
+    });
+  }
+
+  if (pathname === '/api/contracts' && method === 'GET') {
+    return json(res, 200, { contracts: session.contracts });
+  }
+
+  if (pathname === '/api/contracts' && method === 'POST') {
+    // promote the last seen shape to the baseline: "this change is expected"
+    const { id } = await readBody(req);
+    const next = session.contracts[id]?.pending;
+    if (!id || !next) return json(res, 400, { error: 'no drifted shape waiting for that endpoint' });
+    session.contracts[id] = { shape: next, at: new Date().toISOString(), from: 'accepted' };
+    saveContracts();
+    if (session.results[id]) delete session.results[id].drift;
+    saveResults();
+    return json(res, 200, { contracts: session.contracts, results: session.results });
+  }
+
+  if (pathname === '/api/contracts' && method === 'DELETE') {
+    session.contracts = {};
+    saveContracts();
+    return json(res, 200, { contracts: session.contracts });
+  }
+
+  if (pathname === '/api/uncatalogued' && method === 'DELETE') {
+    for (const id of Object.keys(session.extras)) {
+      delete session.samples[id];
+      delete session.results[id];
+      delete session.contracts[id];
+    }
+    session.extras = {};
+    session.live.unmatched = [];
+    saveExtras();
+    saveSamples();
+    saveResults();
+    saveContracts();
+    return json(res, 200, { extras: session.extras });
+  }
+
+  if (pathname === '/api/samples' && method === 'DELETE') {
+    session.samples = {};
+    saveSamples();
+    return json(res, 200, { samples: session.samples });
+  }
+
+  if (pathname === '/api/variables' && method === 'GET') {
+    return json(res, 200, { vars: session.vars });
+  }
+
+  if (pathname === '/api/variables' && method === 'POST') {
+    const { name, value } = await readBody(req);
+    if (!name) return json(res, 400, { error: 'name required' });
+    if (value === '' || value === null) delete session.vars[name];
+    else session.vars[name] = value;
+    saveVars();
+    return json(res, 200, { vars: session.vars });
+  }
+
+  if (pathname === '/api/results' && method === 'DELETE') {
+    session.results = {};
+    session.run = null;
+    saveResults();
+    saveLastRun();
+    return json(res, 200, { results: session.results });
+  }
+
+  if (pathname === '/api/call' && method === 'POST') {
+    return json(res, 200, await callEndpoint(await readBody(req)));
+  }
+
+  if (pathname === '/api/report' && method === 'GET') {
+    return json(res, 200, currentReport());
+  }
+
+  if (pathname === '/api/report/export' && method === 'GET') {
+    const format = url.searchParams.get('format') ?? 'md';
+    const report = currentReport();
+    const stamp = new Date().toISOString().slice(0, 10);
+    const body = format === 'json' ? `${JSON.stringify(report, null, 2)}\n` : toMarkdown(report);
+    res.writeHead(200, {
+      'content-type': format === 'json' ? 'application/json' : 'text/markdown; charset=utf-8',
+      'content-disposition': `attachment; filename="api-report-${session.env}-${stamp}.${
+        format === 'json' ? 'json' : 'md'
+      }"`,
+      'content-length': Buffer.byteLength(body),
+    });
+    return res.end(body);
+  }
+
+  if (pathname === '/api/run/status' && method === 'GET') {
+    return json(res, 200, session.run ?? { active: false });
+  }
+
+  if (pathname === '/api/run/cancel' && method === 'POST') {
+    if (session.run?.active) session.run.cancelled = true;
+    return json(res, 200, { cancelling: Boolean(session.run?.active) });
+  }
+
+  if (pathname === '/api/run/preview' && method === 'POST') {
+    const { ids, ...opts } = await readBody(req);
+    return json(res, 200, previewRun(ids ?? [], opts));
+  }
+
+  if (pathname === '/api/run' && method === 'POST') {
+    const { ids, ...opts } = await readBody(req);
+    // replaying writes against production is never what someone meant to do
+    if (opts.allowMutating && session.env === 'prod') {
+      return json(res, 400, { error: 'refusing to replay writes against prod; switch environment first' });
+    }
+    return json(res, 200, await runBatch(ids ?? [], opts));
+  }
+
+  return json(res, 404, { error: 'not found' });
+}
+
+export { handle, session, catalog as currentCatalog };
+
+export function startServer({ port = PORT, host = HOST } = {}) {
+  return createServer((req, res) => {
+    handle(req, res).catch((e) => json(res, 500, { error: e.message }));
+  }).listen(port, host);
+}
+
+if (isMain)
+  createServer((req, res) => {
+    handle(req, res).catch((e) => json(res, 500, { error: e.message }));
+  }).listen(PORT, HOST, () => {
+    console.log(`api-tracer console  ->  http://${HOST}:${PORT}${BASE_PATH}/`);
+    console.log(
+      catalog.endpoints.length
+        ? `${catalog.endpoints.length} endpoints, env "${session.env}" (${baseUrl() ?? 'no base URL'})`
+        : `no catalog yet -- run \`api-tracer scan\`; live traffic is still recorded`,
+    );
+    if (BASE_PATH) console.log(`mounted under ${BASE_PATH}`);
+    if (ALLOWED_ORIGINS.length) console.log(`recording accepted from: ${ALLOWED_ORIGINS.join(', ')}`);
+    if (AUTH_USER) console.log('basic auth on; the recorder endpoint stays open');
+    if (LOCK_RECORDING) console.log('recording locked on');
+    if (LOCK_ENV) console.log(`environment pinned to ${LOCK_ENV}`);
+    console.log(
+      Object.keys(session.tokens).length
+        ? `${catalog.auth.header} restored from ${TOKENS}${
+            session.tokenOwner ? ` (${session.tokenOwner.email})` : ''
+          }`
+        : 'Sign in from the UI to get a token.',
+    );
+  });