@loopingai/core 0.1.2 → 0.3.0

package/dist/testing/node.js

@@ -2,46 +2,56 @@
  * `@loopingai/core/testing/node` — the **Node-realm** half of the VCR harness.
  *
  * Separate from `@loopingai/core/testing` because the two halves cannot share a
- * module graph. This side imports `undici` and `node:fs`; the other side runs
- * inside workerd, which has neither. `vcr-shared.ts` is the only thing both may
- * touch, and it is deliberately dependency-free so it can load in either realm.
+ * module graph. This side reaches `node:fs`; the other side runs inside workerd,
+ * which has no filesystem. `vcr-shared.ts` is the only thing both may touch, and
+ * it is deliberately dependency-free so it can load in either realm.
  *
  * Import this from a Vitest **config** (or anything else running in Node), never
  * from a spec:
  *
  * ```ts
  * // vitest.config.ts
- * import { createVcrAgent } from "@loopingai/core/testing/node";
+ * import { defineConfig } from "vitest/config";
+ * import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+ * import path from "node:path";
+ * import { createVcr, recordFromEnv } from "@loopingai/core/testing/node";
+ *
+ * const vcr = createVcr({
+ *   snapshotsDir: path.resolve(import.meta.dirname, "test/snapshots"),
+ *   record: recordFromEnv(),
+ *   // Why a committed cassette is safe, and why playback needs no credentials.
+ *   excludeHeaders: ["x-api-key", "authorization", "cookie", "set-cookie"]
+ * });
  *
  * export default defineConfig({
- *   plugins: [cloudflareTest({ miniflare: { fetchMock: createVcrAgent({ … }) } })],
+ *   plugins: [
+ *     cloudflareTest({
+ *       wrangler: { configPath: "./wrangler.jsonc" },
+ *       miniflare: { outboundService: vcr.outboundService }
+ *     })
+ *   ],
  *   test: { globalSetup: ["@loopingai/core/testing/vcr-global-setup"] }
  * });
  * ```
  *
- * ## Two version constraints, both of which fail unreadably
- *
- * **1. `@cloudflare/vitest-pool-workers` must be `^0.18`.** The recorder is
- * installed as Miniflare's `fetchMock`, and that option **does not exist in
- * Miniflare 5**, which pool `0.19`+ depends on — only `outboundService` remains.
- * On a newer pool the option is silently ignored rather than rejected, so
- * `disableNetConnect()` never takes effect, every request goes to the real
- * network, and each one fails as `internal error; reference = …` naming nothing.
- * That is why the peer range is pinned rather than open.
- *
- * **2. Your `undici` must be the copy Miniflare uses.** `fetchMock` is an undici
- * `MockAgent` and Miniflare validates it against *its own* undici, so two copies
- * in one `node_modules` fail with `Input not instance of MockAgent`. Miniflare
- * pins an exact version (7.28.0 at the time of writing) and this package's
- * `undici` peer range tracks it. Check with
- * `ls node_modules/miniflare/node_modules/undici` — anything there means a
- * second copy, and the fix is to align yours rather than to debug the message.
- *
- * For the common case — wiring cassette flush/teardown — you do not need this
- * subpath at all. Point `globalSetup` at
- * `@loopingai/core/testing/vcr-global-setup`, which is this module's `setup`/
- * `teardown` pair already packaged for Vitest.
+ * `RECORD=1` captures live traffic into every cassette a run activates; anything
+ * else replays. A host with no active cassette is **blocked**, so a test that
+ * was never wired for recording cannot reach the network by accident.
+ *
+ * ## Version constraints: there are none
+ *
+ * This used to carry two, both of which failed unreadably, and both of which
+ * were consequences of installing the recorder as Miniflare's `fetchMock`:
+ * the pool had to be `^0.18` (Miniflare 5 dropped the option, and pool 0.20
+ * removed it from its overrides), and your `undici` had to be byte-identical to
+ * Miniflare's (`fetchMock` was validated with `instanceof MockAgent`).
+ *
+ * The recorder is now a plain `outboundService` function — the hook `fetchMock`
+ * was sugar over in the first place. It is present and identical in Miniflare 4
+ * and 5, it type-checks against both, and it involves no `undici` at all. Core
+ * declares no `undici` peer and the pool peer is open.
  */
-export { createVcrAgent, closeVcr, VcrAgent } from "./vcr.js";
-export { VCR_CONTROL_ORIGIN, CASSETTE_NAME_RE } from "./vcr-shared.js";
+export { createVcr, recordFromEnv, closeVcr } from "./vcr.js";
+export { Cassette, requestKey, replayable } from "./vcr-store.js";
+export { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER, CASSETTE_NAME_RE } from "./vcr-shared.js";
 //# sourceMappingURL=node.js.map

package/dist/testing/node.js.map

@@ -1 +1 @@
-{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/testing/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,EACL,cAAc,EACd,QAAQ,EACR,QAAQ,EAET,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../../src/testing/node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,EACL,SAAS,EACT,aAAa,EACb,QAAQ,EAMT,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,UAAU,EAMX,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,iBAAiB,CAAC"}

package/dist/testing/vcr-global-setup.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Vitest `globalSetup`: the exported teardown runs after all tests but before
+ * Vite tears down its server, so it is the last point at which a cassette can
+ * still be written.
+ *
+ * Belt and braces rather than load-bearing — each cassette is already flushed
+ * when its test releases it, so a run that ends normally has nothing left to do
+ * here, and a run that dies mid-test keeps everything recorded up to that point.
+ * (Under the old undici recorder this step was mandatory: it held real sockets
+ * and a self-refreshing auto-flush timer open, and a `RECORD=1` run hung on
+ * "close timed out" without it. Neither exists now.)
+ */
 export declare function setup(): void;
 export declare function teardown(): Promise<void>;
 //# sourceMappingURL=vcr-global-setup.d.ts.map

package/dist/testing/vcr-global-setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-global-setup.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-global-setup.ts"],"names":[],"mappings":"AAKA,wBAAgB,KAAK,IAAI,IAAI,CAAG;AAEhC,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9C"}
+{"version":3,"file":"vcr-global-setup.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-global-setup.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAAG;AAEhC,wBAAsB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAE9C"}

package/dist/testing/vcr-global-setup.js

@@ -1,7 +1,16 @@
 import { closeVcr } from "./vcr.js";
-// Vitest globalSetup: the exported teardown runs after all tests but before Vite
-// tears down its server, so closing the VCR agent here (flush cassette, stop the
-// recorder timer, close real sockets) prevents the record-run hang.
+/**
+ * Vitest `globalSetup`: the exported teardown runs after all tests but before
+ * Vite tears down its server, so it is the last point at which a cassette can
+ * still be written.
+ *
+ * Belt and braces rather than load-bearing — each cassette is already flushed
+ * when its test releases it, so a run that ends normally has nothing left to do
+ * here, and a run that dies mid-test keeps everything recorded up to that point.
+ * (Under the old undici recorder this step was mandatory: it held real sockets
+ * and a self-refreshing auto-flush timer open, and a `RECORD=1` run hung on
+ * "close timed out" without it. Neither exists now.)
+ */
 export function setup() { }
 export async function teardown() {
     await closeVcr();

package/dist/testing/vcr-global-setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-global-setup.js","sourceRoot":"","sources":["../../src/testing/vcr-global-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC,iFAAiF;AACjF,iFAAiF;AACjF,oEAAoE;AACpE,MAAM,UAAU,KAAK,KAAU,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,MAAM,QAAQ,EAAE,CAAC;AACnB,CAAC"}
+{"version":3,"file":"vcr-global-setup.js","sourceRoot":"","sources":["../../src/testing/vcr-global-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,KAAK,KAAU,CAAC;AAEhC,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,MAAM,QAAQ,EAAE,CAAC;AACnB,CAAC"}

package/dist/testing/vcr-shared.d.ts

@@ -1,16 +1,34 @@
 /**
  * Constants shared between the two sides of the VCR harness that must NOT import
- * each other: the Node-side agent (`vcr.ts`, imports `undici`) and the
- * worker-side spec helper (`vcr-spec.ts`, runs in workerd). Keep this file
- * dependency-free so both realms can load it.
+ * each other: the Node-side recorder (`vcr.ts` / `vcr-store.ts`, which reach
+ * `node:fs`) and the worker-side spec helper (`vcr-spec.ts`, which runs in
+ * workerd). Keep this file dependency-free so both realms can load it.
  */
 /**
  * Reserved origin for the in-band control channel. A recorded spec `fetch`es
- * here (via the single Miniflare `fetchMock`) to tell the Node-side agent which
- * cassette is active for the current test — see `setupRecording` (vcr-spec.ts)
- * and `VcrAgent` (vcr.ts). Never a real network host.
+ * here — through the same Miniflare `outboundService` every worker fetch already
+ * flows through — to tell the Node-side recorder which cassette is active for
+ * the current test. See `setupRecording` (vcr-spec.ts) and `createVcr` (vcr.ts).
+ * Never a real network host.
  */
 export declare const VCR_CONTROL_ORIGIN = "https://vcr.internal";
+/**
+ * Stamped on every response the recorder produces.
+ *
+ * The point is to prove the recorder is *installed*. A Miniflare option that no
+ * longer exists is silently ignored rather than rejected — which is exactly how
+ * a harness still wired to `fetchMock` on pool 0.20 failed: nothing intercepted
+ * anything, every request escaped to the real network, and each one died as
+ * `internal error; reference = …` naming nothing. Checking for this header on
+ * the control response turns that whole class of failure into one named error
+ * before any test runs.
+ */
+export declare const VCR_MARKER_HEADER = "x-vcr";
+/** Body of a successful `POST /release`: what the recorder could not serve. */
+export interface VcrReleaseResult {
+    /** `"<METHOD> <url>"` for each blocked or unmatched request in the test. */
+    misses: string[];
+}
 /**
  * Cassette filenames are derived from kebab-cased file + describe + test names
  * (see `cassetteNameFor`), so they are always lowercase `a-z0-9-` plus the

package/dist/testing/vcr-shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-shared.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAiC,CAAC"}
+{"version":3,"file":"vcr-shared.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,QAAiC,CAAC"}

package/dist/testing/vcr-shared.js

@@ -1,16 +1,29 @@
 /**
  * Constants shared between the two sides of the VCR harness that must NOT import
- * each other: the Node-side agent (`vcr.ts`, imports `undici`) and the
- * worker-side spec helper (`vcr-spec.ts`, runs in workerd). Keep this file
- * dependency-free so both realms can load it.
+ * each other: the Node-side recorder (`vcr.ts` / `vcr-store.ts`, which reach
+ * `node:fs`) and the worker-side spec helper (`vcr-spec.ts`, which runs in
+ * workerd). Keep this file dependency-free so both realms can load it.
  */
 /**
  * Reserved origin for the in-band control channel. A recorded spec `fetch`es
- * here (via the single Miniflare `fetchMock`) to tell the Node-side agent which
- * cassette is active for the current test — see `setupRecording` (vcr-spec.ts)
- * and `VcrAgent` (vcr.ts). Never a real network host.
+ * here — through the same Miniflare `outboundService` every worker fetch already
+ * flows through — to tell the Node-side recorder which cassette is active for
+ * the current test. See `setupRecording` (vcr-spec.ts) and `createVcr` (vcr.ts).
+ * Never a real network host.
  */
 export const VCR_CONTROL_ORIGIN = "https://vcr.internal";
+/**
+ * Stamped on every response the recorder produces.
+ *
+ * The point is to prove the recorder is *installed*. A Miniflare option that no
+ * longer exists is silently ignored rather than rejected — which is exactly how
+ * a harness still wired to `fetchMock` on pool 0.20 failed: nothing intercepted
+ * anything, every request escaped to the real network, and each one died as
+ * `internal error; reference = …` naming nothing. Checking for this header on
+ * the control response turns that whole class of failure into one named error
+ * before any test runs.
+ */
+export const VCR_MARKER_HEADER = "x-vcr";
 /**
  * Cassette filenames are derived from kebab-cased file + describe + test names
  * (see `cassetteNameFor`), so they are always lowercase `a-z0-9-` plus the

package/dist/testing/vcr-shared.js.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-shared.js","sourceRoot":"","sources":["../../src/testing/vcr-shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAC"}
+{"version":3,"file":"vcr-shared.js","sourceRoot":"","sources":["../../src/testing/vcr-shared.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,OAAO,CAAC;AAQzC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,8BAA8B,CAAC"}

package/dist/testing/vcr-spec.d.ts

@@ -7,11 +7,20 @@ import type { RunnerTestCase } from "vitest";
  * Exported for debugging / the cassette-rename step.
  */
 export declare function cassetteNameFor(task: RunnerTestCase): string;
+export interface SetupRecordingOptions {
+    /**
+     * Let a test finish even though the recorder could not serve one of its
+     * requests. Only for a spec that deliberately exercises a failing `fetch`;
+     * the default is to fail, because a silent miss reads as a broken assertion
+     * several frames from its cause.
+     */
+    allowMisses?: boolean;
+}
 /**
  * Call once at the top of a recorded spec file (outside any `describe`). Adds
  * per-test hooks that activate the test's cassette before it runs and release
  * it after. A missing cassette **fails** the test with instructions to record
  * (never skips — CI must go red so the gap is visible).
  */
-export declare function setupRecording(): void;
+export declare function setupRecording(options?: SetupRecordingOptions): void;
 //# sourceMappingURL=vcr-spec.d.ts.map

package/dist/testing/vcr-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-spec.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-spec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,QAAQ,CAAC;AAkD9D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAW5D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,IAAI,CA8BrC"}
+{"version":3,"file":"vcr-spec.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-spec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAmB,MAAM,QAAQ,CAAC;AAsD9D;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAW5D;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAgBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAkDxE"}

package/dist/testing/vcr-spec.js

@@ -1,15 +1,15 @@
 import { beforeEach, afterEach } from "vitest";
-import { VCR_CONTROL_ORIGIN } from "./vcr-shared.js";
+import { VCR_CONTROL_ORIGIN, VCR_MARKER_HEADER } from "./vcr-shared.js";
 /**
  * Worker-side half of the VCR harness. `setupRecording()` is the *only* thing a
  * recorded spec wires up: one call at the top of the file gives every `it` its
  * own cassette, auto-named from the file + describe + test names, recorded under
  * `RECORD=1` and replayed otherwise. No per-recipe config, no registry.
  *
- * How it reaches the Node-side agent: specs run in workerd (no filesystem), so
- * the active cassette is announced over an in-band control channel — a `fetch`
- * to {@link VCR_CONTROL_ORIGIN} that `VcrAgent` (test/helpers/vcr.ts) answers
- * from the same Miniflare `fetchMock` every worker fetch already flows through.
+ * How it reaches the Node-side recorder: specs run in workerd (no filesystem),
+ * so the active cassette is announced over an in-band control channel — a
+ * `fetch` to {@link VCR_CONTROL_ORIGIN} that `createVcr` (vcr.ts) answers from
+ * the same Miniflare `outboundService` every worker fetch already flows through.
  */
 const kebab = (s) => s
     .toLowerCase()
@@ -60,18 +60,35 @@ export function cassetteNameFor(task) {
     }
     return [rel, ...suites, task.name].map(kebab).join("--") + ".snapshot.json";
 }
+/**
+ * The recorder answers every control request with {@link VCR_MARKER_HEADER}, so
+ * its absence — or a `fetch` that rejects outright, which is what a request to
+ * a host that does not resolve does — means nothing is intercepting outbound
+ * traffic at all.
+ */
+const NOT_INSTALLED = `The VCR recorder is not installed, so ${VCR_CONTROL_ORIGIN} went to the ` +
+    `real network. Wire it into your vitest config:\n\n` +
+    `  const vcr = createVcr({ snapshotsDir, record: recordFromEnv() });\n` +
+    `  cloudflareTest({ miniflare: { outboundService: vcr.outboundService } })\n\n` +
+    `(\`fetchMock\` is not it: pool 0.20 removed the option, and an unknown key ` +
+    `in \`miniflare\` is ignored rather than rejected.)`;
 /**
  * Call once at the top of a recorded spec file (outside any `describe`). Adds
  * per-test hooks that activate the test's cassette before it runs and release
  * it after. A missing cassette **fails** the test with instructions to record
  * (never skips — CI must go red so the gap is visible).
  */
-export function setupRecording() {
+export function setupRecording(options = {}) {
     beforeEach(async (ctx) => {
         const cassette = cassetteNameFor(ctx.task);
         const res = await fetch(`${VCR_CONTROL_ORIGIN}/use?cassette=${cassette}`, {
             method: "POST"
+        }).catch(() => {
+            throw new Error(NOT_INSTALLED);
         });
+        if (res.headers.get(VCR_MARKER_HEADER) === null) {
+            throw new Error(NOT_INSTALLED);
+        }
         if (res.status === 404) {
             throw new Error(`No VCR cassette "${cassette}". Record it with \`RECORD=1\` ` +
                 `(add \`-t "${ctx.task.name}"\` to record only this test), which needs ` +
@@ -79,7 +96,7 @@ export function setupRecording() {
         }
         if (res.status === 409) {
             throw new Error(`VCR cassette "${cassette}" could not activate: another recorded test is ` +
-                `already using the shared agent. Recorded specs must not run in ` +
+                `already using the shared recorder. Recorded specs must not run in ` +
                 `parallel — keep them sequential.`);
         }
         if (!res.ok) {
@@ -87,7 +104,22 @@ export function setupRecording() {
         }
     });
     afterEach(async () => {
-        await fetch(`${VCR_CONTROL_ORIGIN}/release`, { method: "POST" });
+        const res = await fetch(`${VCR_CONTROL_ORIGIN}/release`, {
+            method: "POST"
+        });
+        if (options.allowMisses === true || !res.ok)
+            return;
+        const { misses } = (await res.json());
+        if (misses.length === 0)
+            return;
+        // A miss cannot reject the Worker's own `fetch()` — Miniflare turns anything
+        // an outbound service throws into a 500 — so the request under test sees a
+        // 500 body and fails somewhere downstream, if at all. Reporting it here is
+        // what makes the *cause* the failure.
+        throw new Error(`VCR could not serve ${misses.length} request(s) in this test:\n` +
+            misses.map((m) => `  • ${m}`).join("\n") +
+            `\nRe-record with \`RECORD=1\`, or pass ` +
+            `\`setupRecording({ allowMisses: true })\` if the failure is the point.`);
     });
 }
 //# sourceMappingURL=vcr-spec.js.map

package/dist/testing/vcr-spec.js.map

@@ -1 +1 @@
-{"version":3,"file":"vcr-spec.js","sourceRoot":"","sources":["../../src/testing/vcr-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErD;;;;;;;;;;GAUG;AAEH,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAClC,CAAC;KACE,WAAW,EAAE;KACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;KAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAE7B,kFAAkF;AAClF,SAAS,UAAU,CAAC,KAAsB;IACxC,OAAO,OAAQ,KAA+B,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,gBAAgB,CAAC,IAA4B;IACpD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACxE,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB;IAClD,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAEnE,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAgC,IAAI,CAAC,KAAK,CAAC;IACpD,OAAO,KAAK,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc;IAC5B,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,kBAAkB,iBAAiB,QAAQ,EAAE,EAAE;YACxE,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,oBAAoB,QAAQ,iCAAiC;gBAC3D,cAAc,GAAG,CAAC,IAAI,CAAC,IAAI,6CAA6C;gBACxE,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,iBAAiB,QAAQ,iDAAiD;gBACxE,iEAAiE;gBACjE,kCAAkC,CACrC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mCAAmC,GAAG,CAAC,MAAM,iBAAiB,QAAQ,IAAI,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACnB,MAAM,KAAK,CAAC,GAAG,kBAAkB,UAAU,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACnE,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"vcr-spec.js","sourceRoot":"","sources":["../../src/testing/vcr-spec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAE/C,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;GAUG;AAEH,MAAM,KAAK,GAAG,CAAC,CAAS,EAAU,EAAE,CAClC,CAAC;KACE,WAAW,EAAE;KACb,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;KAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;AAE7B,kFAAkF;AAClF,SAAS,UAAU,CAAC,KAAsB;IACxC,OAAO,OAAQ,KAA+B,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,gBAAgB,CAAC,IAA4B;IACpD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACxE,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAG,CAAC;AAC7D,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,IAAoB;IAClD,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IAEnE,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAgC,IAAI,CAAC,KAAK,CAAC;IACpD,OAAO,KAAK,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QACnC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,OAAO,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,gBAAgB,CAAC;AAC9E,CAAC;AAYD;;;;;GAKG;AACH,MAAM,aAAa,GACjB,yCAAyC,kBAAkB,eAAe;IAC1E,oDAAoD;IACpD,uEAAuE;IACvE,+EAA+E;IAC/E,6EAA6E;IAC7E,oDAAoD,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,UAAiC,EAAE;IAChE,UAAU,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,kBAAkB,iBAAiB,QAAQ,EAAE,EAAE;YACxE,MAAM,EAAE,MAAM;SACf,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACZ,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,IAAI,EAAE,CAAC;YAChD,MAAM,IAAI,KAAK,CAAC,aAAa,CAAC,CAAC;QACjC,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,oBAAoB,QAAQ,iCAAiC;gBAC3D,cAAc,GAAG,CAAC,IAAI,CAAC,IAAI,6CAA6C;gBACxE,2DAA2D,CAC9D,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CACb,iBAAiB,QAAQ,iDAAiD;gBACxE,oEAAoE;gBACpE,kCAAkC,CACrC,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CACb,mCAAmC,GAAG,CAAC,MAAM,iBAAiB,QAAQ,IAAI,CAC3E,CAAC;QACJ,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,KAAK,IAAI,EAAE;QACnB,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,kBAAkB,UAAU,EAAE;YACvD,MAAM,EAAE,MAAM;SACf,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,WAAW,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,OAAO;QACpD,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAqB,CAAC;QAC1D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAChC,6EAA6E;QAC7E,2EAA2E;QAC3E,2EAA2E;QAC3E,sCAAsC;QACtC,MAAM,IAAI,KAAK,CACb,uBAAuB,MAAM,CAAC,MAAM,6BAA6B;YAC/D,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YACxC,yCAAyC;YACzC,wEAAwE,CAC3E,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/testing/vcr-store.d.ts

@@ -0,0 +1,91 @@
+/** A stored request. `body` is utf-8 text; binary request bodies are not supported. */
+export interface RecordedRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[]>;
+    body: string;
+}
+/** A stored response. `body` is base64, as `SnapshotAgent` wrote it. */
+export interface RecordedResponse {
+    statusCode: number;
+    headers: Record<string, string | string[]>;
+    body: string;
+    trailers?: Record<string, string>;
+}
+/**
+ * One cassette entry: a request and every response recorded for it, in order.
+ *
+ * The array is what makes a replayed sequence work — two identical requests
+ * that returned different things (an ARC frame after a move, say) are one entry
+ * with two responses, walked in order. See {@link Cassette.match}.
+ */
+export interface CassetteEntry {
+    request: RecordedRequest;
+    responses: RecordedResponse[];
+}
+/** What {@link Cassette.match} hands back: everything needed to build a Response. */
+export interface ReplayableResponse {
+    status: number;
+    headers: [string, string][];
+    body: Uint8Array;
+}
+export interface CassetteOptions {
+    /** Request *and* response headers never written to the file (API keys, auth). */
+    excludeHeaders?: string[];
+}
+/** `${METHOD}\n${url}\n${sha256(body)}` — the whole matching rule. */
+export declare function requestKey(method: string, url: string, body: string): string;
+/**
+ * Turn a stored response into the pieces a `Response` is built from: body
+ * decoded from base64, headers flattened (a repeated header such as
+ * `set-cookie` becomes one entry per value) and {@link HOP_BY_HOP} dropped.
+ *
+ * Used on both paths, so a response served straight after recording is framed
+ * exactly as the same response will be on replay.
+ */
+export declare function replayable(response: RecordedResponse): ReplayableResponse;
+/**
+ * One cassette file, loaded lazily and written only when it has changed.
+ *
+ * Playback is **read-only**: nothing here mutates on a replay, which is what
+ * stops a plain `npm test` from dirtying committed cassettes. `SnapshotAgent`
+ * persisted its `callCount` and re-saved on close, so every run left the files
+ * modified; the equivalent counter here ({@link #calls}) is in memory and dies
+ * with the process.
+ */
+export declare class Cassette {
+    #private;
+    constructor(file: string, options?: CassetteOptions);
+    get file(): string;
+    /** Every request in the file, as `METHOD url`, for error messages. */
+    get recorded(): string[];
+    /**
+     * Read the file into memory. Tolerates both shapes: `SnapshotAgent` wrapped
+     * each entry in `{ hash, snapshot: { request, responses } }`, this writes the
+     * same wrapper (so a re-record diffs cleanly against an old cassette) but
+     * ignores `hash`, `callCount` and `timestamp` — all three were volatile
+     * bookkeeping and none is needed to replay.
+     *
+     * Entries are re-keyed on load rather than trusted, which is the point of the
+     * rewrite. Two legacy entries that differed *only* by a request header now
+     * collapse onto one key; their responses are concatenated in file order,
+     * which is exactly the sequential-response semantics {@link match} walks.
+     */
+    load(): void;
+    /**
+     * The next recorded response for this request, or `null` if it was never
+     * recorded.
+     *
+     * Repeated identical requests walk `responses` in order and then **hold on
+     * the last one**, matching what `SnapshotAgent` did
+     * (`responses[min(callCount, length - 1)]`). A recording that captured one
+     * response therefore replays it for every call, which is what a poll loop
+     * needs.
+     */
+    match(method: string, url: string, body: string): ReplayableResponse | null;
+    /** Append a live response. Repeats of a request extend its `responses`. */
+    record(request: RecordedRequest, response: RecordedResponse): void;
+    /** Write if anything was recorded since the last flush. A no-op in playback. */
+    flush(): void;
+}
+//# sourceMappingURL=vcr-store.d.ts.map

package/dist/testing/vcr-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr-store.d.ts","sourceRoot":"","sources":["../../src/testing/vcr-store.ts"],"names":[],"mappings":"AAyBA,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,gBAAgB,EAAE,CAAC;CAC/B;AAsBD,qFAAqF;AACrF,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5E;AAaD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,gBAAgB,GAAG,kBAAkB,CAazE;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;;gBASP,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB;IAOvD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,sEAAsE;IACtE,IAAI,QAAQ,IAAI,MAAM,EAAE,CAIvB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,IAAI;IAiBZ;;;;;;;;;OASG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IAW3E,2EAA2E;IAC3E,MAAM,CAAC,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAqBlE,gFAAgF;IAChF,KAAK,IAAI,IAAI;CASd"}