@pugi/cli 0.1.0-beta.9 → 0.1.0-beta.91

package/dist/testing/vcr.js

@@ -0,0 +1,486 @@
+/**
+ * VCR — Pugi CLI test helper that records `fetch` interactions to a JSON
+ * cassette and replays them deterministically. independent implementation re-implementation
+ * of the external `vcr.ts` pattern; Node built-ins only (`node:fs`,
+ * `node:crypto`, `node:path`), no new dependencies.
+ *
+ * # Why this exists
+ *
+ * Hand-stubbed `globalThis.fetch =` blocks are spread across the CLI
+ * test corpus (`anvil-client-e2-contract.spec.ts`, `submit-delegate.spec.ts`,
+ * `cost-quota-slash.spec.ts`, `repl-render-transport.spec.ts`). They
+ * work but the response bodies are inlined as JSON literals — drifts
+ * between the real admin-api wire shape and the test fixture are
+ * caught only when production breaks.
+ *
+ * VCR shifts the source-of-truth: a real run records once to a cassette,
+ * subsequent runs replay deterministically. Operators can re-record by
+ * deleting the cassette file (auto-mode flips back to record).
+ *
+ * # Lifecycle
+ *
+ *  const tape = vcr({ path: '...', mode: 'auto' });
+ *  const restore = tape.install();
+ *  try {
+ *    await codeUnderTestThatCallsFetch();
+ *    await tape.flush(); // no-op in replay mode
+ *  } finally {
+ *    restore();
+ *  }
+ *
+ * # Matching strategy
+ *
+ * `method + url + sha256(canonical-body)`. Bodies are normalised when
+ * the request advertises `content-type: application/json` so timestamp
+ * / uuid wobble inside a JSON envelope does NOT cause a cassette miss.
+ *
+ * # Security
+ *
+ * Sensitive headers (`authorization`, `x-pugi-bearer`, `x-api-key`,
+ * `cookie`) are redacted at write time so a cassette accidentally
+ * committed never leaks a real bearer token. Redaction is one-way —
+ * the cassette retains `[REDACTED]` and replay matches on the original
+ * scrubbed value (replay does not re-hash the headers; only the body
+ * participates in the match key, which keeps record/replay symmetric).
+ *
+ * # Atomicity
+ *
+ * Cassette writes go `tmp + rename` so a concurrent reader never sees
+ * a half-written JSON document (mirrors the agent-progress writer
+ * pattern in `src/core/agent-progress/writer.ts`).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+/** Cassette schema version. Bump on breaking changes to the JSON shape. */
+export const VCR_CASSETTE_VERSION = 1;
+/** Headers that are scrubbed to `[REDACTED]` at cassette-write time. */
+export const VCR_SENSITIVE_HEADERS = Object.freeze([
+    'authorization',
+    'x-pugi-bearer',
+    'x-api-key',
+    'cookie',
+]);
+/** Placeholder written in place of a sensitive header value. */
+export const VCR_REDACTED = '[REDACTED]';
+/**
+ * Error thrown when replay mode looks up a request that is NOT in the
+ * cassette. The message lists the cassette's recorded URLs so the
+ * operator immediately sees whether the test drifted or the cassette
+ * is stale.
+ */
+export class VcrCassetteMiss extends Error {
+    request;
+    recordedUrls;
+    constructor(request, recordedUrls) {
+        const recordedList = recordedUrls.length
+            ? recordedUrls.map((u) => ` - ${u}`).join('\n')
+            : ' (empty cassette)';
+        super(`VCR cassette miss: ${request.method} ${request.url}\n` +
+            `Recorded URLs:\n${recordedList}\n` +
+            'Re-record by deleting the cassette and running the test, ' +
+            'or check whether the request shape drifted.');
+        this.name = 'VcrCassetteMiss';
+        this.request = request;
+        this.recordedUrls = recordedUrls;
+    }
+}
+/**
+ * Error thrown when a cassette file on disk advertises a `version`
+ * that this VCR build does not understand. Loud failure is the right
+ * call — silent best-effort would replay against a shape the test
+ * expects to be a different one.
+ */
+export class VcrCassetteVersionMismatch extends Error {
+    cassettePath;
+    foundVersion;
+    expectedVersion;
+    constructor(cassettePath, foundVersion) {
+        super(`VCR cassette ${cassettePath} advertises version ${foundVersion}; ` +
+            `this build expects version ${VCR_CASSETTE_VERSION}. ` +
+            'Delete the cassette and re-record, or upgrade the helper.');
+        this.name = 'VcrCassetteVersionMismatch';
+        this.cassettePath = cassettePath;
+        this.foundVersion = foundVersion;
+        this.expectedVersion = VCR_CASSETTE_VERSION;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Internal helpers                                                   */
+/* ------------------------------------------------------------------ */
+/**
+ * Canonicalise a JSON body string so two semantically-equal payloads
+ * with different key order hash identically. Non-JSON bodies pass
+ * through unchanged.
+ *
+ * The contract intentionally does NOT walk arrays or recursively
+ * normalise nested objects beyond their key order — that is a future
+ * refinement if cassettes start to miss on collection re-orderings.
+ */
+function canonicaliseBodyForHash(body, contentType) {
+    if (body === undefined || body === '')
+        return '';
+    const isJson = typeof contentType === 'string' && contentType.toLowerCase().includes('application/json');
+    if (!isJson)
+        return body;
+    try {
+        const parsed = JSON.parse(body);
+        return canonicalStringify(parsed);
+    }
+    catch {
+        // Body advertised JSON but was not parseable — fall back to the raw
+        // string so the test still produces a stable hash and the operator
+        // sees the broken body during diagnostics.
+        return body;
+    }
+}
+/**
+ * Stable JSON.stringify with sorted object keys. Arrays preserve order
+ * (order is semantically meaningful in the wire shape).
+ */
+function canonicalStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => canonicalStringify(v)).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const body = entries
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonicalStringify(v)}`)
+        .join(',');
+    return `{${body}}`;
+}
+/**
+ * Normalise a Headers / plain-object header bag into a lowercased
+ * record. The cassette stores lowercase keys exclusively so a runtime
+ * fetch that sends `Authorization` matches a recorded `authorization`
+ * fixture without ambiguity.
+ */
+function normaliseHeaders(input) {
+    const out = {};
+    if (!input)
+        return out;
+    if (input instanceof Headers) {
+        input.forEach((value, key) => {
+            out[key.toLowerCase()] = value;
+        });
+        return out;
+    }
+    if (Array.isArray(input)) {
+        for (const entry of input) {
+            if (Array.isArray(entry) && entry.length === 2) {
+                const [k, v] = entry;
+                if (typeof k === 'string' && typeof v === 'string') {
+                    out[k.toLowerCase()] = v;
+                }
+            }
+        }
+        return out;
+    }
+    if (typeof input === 'object') {
+        for (const [k, v] of Object.entries(input)) {
+            if (typeof v === 'string') {
+                out[k.toLowerCase()] = v;
+            }
+            else if (typeof v === 'number' || typeof v === 'boolean') {
+                out[k.toLowerCase()] = String(v);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Redact sensitive headers in-place by replacing their values with
+ * `[REDACTED]`. The exported list is canonical lowercase; the headers
+ * argument is also normalised to lowercase keys before this is called.
+ */
+function redactHeaders(headers) {
+    const out = { ...headers };
+    for (const key of VCR_SENSITIVE_HEADERS) {
+        if (key in out) {
+            out[key] = VCR_REDACTED;
+        }
+    }
+    return out;
+}
+/**
+ * Resolve `fetch` arguments into the canonical request shape used by
+ * the matcher and cassette writer.
+ */
+function buildRequest(input, init) {
+    let method = 'GET';
+    let url;
+    let headers = {};
+    let body;
+    if (typeof input === 'string') {
+        url = input;
+    }
+    else if (input instanceof URL) {
+        url = input.toString();
+    }
+    else if (typeof input === 'object' && input !== null && 'url' in input) {
+        // Request object
+        const req = input;
+        url = req.url;
+        method = req.method;
+        headers = normaliseHeaders(req.headers);
+    }
+    else {
+        url = String(input);
+    }
+    if (init) {
+        if (typeof init.method === 'string')
+            method = init.method;
+        if (init.headers !== undefined) {
+            headers = { ...headers, ...normaliseHeaders(init.headers) };
+        }
+        if (typeof init.body === 'string') {
+            body = init.body;
+        }
+        else if (init.body instanceof URLSearchParams) {
+            body = init.body.toString();
+        }
+        else if (init.body !== undefined && init.body !== null) {
+            // ArrayBuffer / Blob / ReadableStream are not supported in VCR
+            // record mode — fall back to JSON.stringify so the matcher key
+            // is at least stable. The recorded body still surfaces in the
+            // cassette so the operator can see what landed.
+            try {
+                body = JSON.stringify(init.body);
+            }
+            catch {
+                body = String(init.body);
+            }
+        }
+    }
+    return {
+        method: method.toUpperCase(),
+        url,
+        headers,
+        body,
+    };
+}
+/**
+ * Compute the match key for an interaction. The cassette key uses
+ * sha256 because collision probability across a test suite is
+ * astronomically low, and the hex is short enough to log.
+ */
+function matchKey(request) {
+    const contentType = request.headers['content-type'];
+    const canonicalBody = canonicaliseBodyForHash(request.body, contentType);
+    const hash = createHash('sha256')
+        .update(`${request.method}\n${request.url}\n${canonicalBody}`)
+        .digest('hex');
+    return hash;
+}
+function loadCassette(path) {
+    if (!existsSync(path))
+        return [];
+    const raw = readFileSync(path, 'utf8');
+    if (raw.trim() === '')
+        return [];
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        !('version' in parsed) ||
+        !('interactions' in parsed)) {
+        throw new Error(`VCR cassette ${path} has invalid shape (missing version / interactions)`);
+    }
+    const cast = parsed;
+    if (typeof cast.version !== 'number' || cast.version !== VCR_CASSETTE_VERSION) {
+        throw new VcrCassetteVersionMismatch(path, typeof cast.version === 'number' ? cast.version : -1);
+    }
+    if (!Array.isArray(cast.interactions)) {
+        throw new Error(`VCR cassette ${path}: interactions must be an array`);
+    }
+    return cast.interactions;
+}
+function writeCassetteAtomic(path, interactions) {
+    const parent = dirname(path);
+    if (!existsSync(parent)) {
+        mkdirSync(parent, { recursive: true });
+    }
+    const file = {
+        version: VCR_CASSETTE_VERSION,
+        interactions: [...interactions],
+    };
+    const tmpPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    const body = `${JSON.stringify(file, null, 2)}\n`;
+    try {
+        writeFileSync(tmpPath, body, 'utf8');
+        renameSync(tmpPath, path);
+    }
+    catch (err) {
+        try {
+            rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort
+        }
+        throw err;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* Public factory                                                     */
+/* ------------------------------------------------------------------ */
+/** Internal guard — only one VCR can be installed on globalThis at a time. */
+let installed = false;
+export function vcr(cassette) {
+    // Snapshot the recorded interactions at construction time so the
+    // matcher does not re-read the cassette on every fetch call.
+    //
+    // In explicit `mode: 'record'` we swallow VcrCassetteVersionMismatch
+    // and treat the cassette as empty — the whole point of explicit
+    // record mode is to nuke and rewrite, so refusing to construct on a
+    // stale on-disk version would brick the re-record workflow.
+    // Triple-review Claude P1,.
+    let recordedFromDisk;
+    try {
+        recordedFromDisk = loadCassette(cassette.path);
+    }
+    catch (err) {
+        if (cassette.mode === 'record' && err instanceof VcrCassetteVersionMismatch) {
+            recordedFromDisk = [];
+        }
+        else {
+            throw err;
+        }
+    }
+    const newlyRecorded = [];
+    const effectiveMode = cassette.mode === 'auto'
+        ? recordedFromDisk.length > 0 || existsSync(cassette.path)
+            ? 'replay'
+            : 'record'
+        : cassette.mode;
+    // Precompute the match index for replay mode so lookup is O(1).
+    const replayIndex = new Map();
+    if (effectiveMode === 'replay') {
+        for (const interaction of recordedFromDisk) {
+            replayIndex.set(matchKey(interaction.request), interaction);
+        }
+    }
+    let originalFetch;
+    function buildResponse(interaction) {
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(interaction.response.headers)) {
+            headers.set(k, v);
+        }
+        return new Response(interaction.response.body, {
+            status: interaction.response.status,
+            headers,
+        });
+    }
+    async function interceptor(input, init) {
+        const request = buildRequest(input, init);
+        const key = matchKey(request);
+        if (effectiveMode === 'replay') {
+            const hit = replayIndex.get(key);
+            if (!hit) {
+                const recordedUrls = recordedFromDisk.map((r) => `${r.request.method} ${r.request.url}`);
+                throw new VcrCassetteMiss(request, recordedUrls);
+            }
+            return buildResponse(hit);
+        }
+        // Record mode: pass through to the real network, then store.
+        if (!originalFetch) {
+            // Defensive — should not happen because install() captures it.
+            throw new Error('VCR record mode requires a captured original fetch but found none');
+        }
+        const liveResponse = await originalFetch(input, init);
+        // Clone before draining the body so the caller still gets a
+        // readable Response with its own untouched stream.
+        const cloned = liveResponse.clone();
+        const responseBody = await cloned.text();
+        const responseHeaders = {};
+        liveResponse.headers.forEach((value, key) => {
+            responseHeaders[key.toLowerCase()] = value;
+        });
+        const recordedRequestHeaders = redactHeaders(request.headers);
+        const interaction = {
+            request: {
+                method: request.method,
+                url: request.url,
+                headers: recordedRequestHeaders,
+                body: request.body,
+            },
+            response: {
+                status: liveResponse.status,
+                headers: responseHeaders,
+                body: responseBody,
+            },
+            recordedAt: new Date().toISOString(),
+        };
+        newlyRecorded.push(interaction);
+        return liveResponse;
+    }
+    return {
+        install() {
+            if (installed) {
+                throw new Error('VCR is already installed on globalThis.fetch. ' +
+                    'Restore the previous tape before installing a new one.');
+            }
+            originalFetch = globalThis.fetch;
+            installed = true;
+            globalThis.fetch = interceptor;
+            return () => {
+                // Idempotent restore — calling twice is safe.
+                if (!installed)
+                    return;
+                if (originalFetch) {
+                    globalThis.fetch = originalFetch;
+                }
+                installed = false;
+            };
+        },
+        recordedCount() {
+            return newlyRecorded.length;
+        },
+        async flush() {
+            if (effectiveMode === 'replay')
+                return;
+            if (newlyRecorded.length === 0)
+                return;
+            // Merge any pre-existing on-disk interactions (e.g. auto-mode
+            // started fresh but a parallel process raced us) with the newly
+            // recorded ones. On-disk wins for duplicate keys so a manual
+            // edit to the cassette is not stomped.
+            const merged = [];
+            const seen = new Set();
+            const existing = loadCassette(cassette.path);
+            for (const interaction of existing) {
+                const k = matchKey(interaction.request);
+                seen.add(k);
+                merged.push(interaction);
+            }
+            for (const interaction of newlyRecorded) {
+                const k = matchKey(interaction.request);
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                merged.push(interaction);
+            }
+            writeCassetteAtomic(cassette.path, merged);
+        },
+    };
+}
+/**
+ * Test-only escape hatch: forcibly clear the install latch. Use from
+ * an `afterEach` if a test crashed mid-install before its restore
+ * handle could run. NEVER call from production code.
+ */
+export function __resetVcrInstallLatchForTests() {
+    installed = false;
+}
+/**
+ * Build a synthetic cassette file on disk. Useful in tests that want
+ * to exercise replay-mode against an inline fixture (cassettes are
+ * gitignored so a checked-in fixture is not the right pattern). Writes
+ * atomically using the same tmp+rename path as the record-mode flush.
+ */
+export function writeCassetteFixtureForTests(path, interactions) {
+    writeCassetteAtomic(path, interactions);
+}
+//# sourceMappingURL=vcr.js.map