@pugi/cli 0.1.0-beta.99 → 1.0.0-alpha.10

package/dist/testing/vcr.js

@@ -1,486 +0,0 @@
-/**
- * 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