@avivbenhamo/polly-kit 0.3.0 → 0.5.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 avivbenhamo
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 avivbenhamo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,276 +1,298 @@
-# @avivbenhamo/polly-kit
-
-Record an app's real HTTP traffic to HAR files, then replay it so the app runs with no
-backends. Polly.JS, the recording store and the HAR editor in one package — one install, no
-companion to keep in step.
-
-Entry points:
-
-| | |
-|---|---|
-| `@avivbenhamo/polly-kit` | a Vite app, in the browser |
-| [`@avivbenhamo/polly-kit/node`](#non-browser-apps) | a Node process — NestJS, a service, a CLI. `http(s)` **and** the built-in `fetch` |
-| [`@avivbenhamo/polly-kit/studio`](#the-editor) | the editor's handler and HAR API, to mount anywhere |
-| `@avivbenhamo/polly-kit/studio/browser` | the editor for a browser app with no server at all |
-| `@avivbenhamo/polly-kit/vite` | the Vite plugin |
-| `@avivbenhamo/polly-kit/store` | the recording store as bare connect middleware |
-
-Nothing in here knows a hostname. You supply a policy; the package is the machinery.
-
-## Install
-
-```sh
-npm i -D @avivbenhamo/polly-kit
-```
-
-## Three steps
-
-**1. `vite.config.ts`** — one plugin, dev-server only (it registers in `configureServer`, so a
-production build never sees it):
-
-```ts
-import pollyKit from '@avivbenhamo/polly-kit/vite';
-
-export default defineConfig({
-    plugins: [react(), pollyKit({recordingsDir: 'recordings'})],
-});
-```
-
-**2. A config file** — the only file you write:
-
-```ts
-// src/polly/config.ts
-import type {PollyPolicyConfig} from '@avivbenhamo/polly-kit';
-
-export const pollyConfig: PollyPolicyConfig = {
-    recordingName: 'my-app',
-    policy: {kind: 'except', hosts: [import.meta.env.VITE_AUTH_URL]},
-};
-```
-
-**3. A bootstrap module, imported FIRST in your entry point:**
-
-```ts
-// src/polly/bootstrap.ts
-import {resolveMode, startPolly} from '@avivbenhamo/polly-kit';
-import {pollyConfig} from './config';
-
-const mode = import.meta.env.PROD ? 'off' : resolveMode(import.meta.env.VITE_POLLY_MODE);
-
-startPolly({...pollyConfig, mode});
-```
-
-```ts
-// src/index.tsx — FIRST import, above everything
-import './polly/bootstrap';
-```
-
-`bootstrap.ts` exists so that `startPolly()` runs before your component tree is evaluated. ES
-module imports are hoisted and fully evaluated before any statement in the importing module's
-body, so a bare `startPolly()` call in `index.tsx` runs *after* `./App` and everything it
-imports — and any module that fires a request at import time would escape interception,
-silently and only sometimes.
-
-Add `/recordings` to `.gitignore`. A HAR holds complete response bodies.
-
-## Running it
-
-Off unless `VITE_POLLY_MODE` is set, so the default behaviour of your app is unchanged.
-
-```powershell
-$env:VITE_POLLY_MODE='record'; npm run dev     # capture real traffic
-$env:VITE_POLLY_MODE='replay'; npm run dev     # serve from recordings
-```
-
-```sh
-VITE_POLLY_MODE=record npm run dev             # bash
-```
-
-Record once against reachable backends, then replay forever. Recordings land in
-`recordings/<recordingName>_<hash>/recording.har`, editable at **http://localhost:<port>/__polly**
-— the URL is printed on startup.
-
-## Non-browser apps
-
-`@avivbenhamo/polly-kit/node` is the same thing for a Node process — NestJS, a plain
-service, a CLI. It intercepts **both** transports: `http(s).request`/`get` (axios, got,
-Nest's `HttpModule`) and Node's built-in `fetch`.
-
-```ts
-// src/polly/mock.ts
-import {startPolly, resolveMode} from '@avivbenhamo/polly-kit/node';
-
-export const polly = startPolly({
-    mode: resolveMode(process.env.POLLY_MODE),
-    recordingName: 'my-api',
-    recordingsDir: './recordings',
-    policy: {kind: 'only', hosts: [process.env.PARTNER_API_URL]},
-});
-```
-
-```ts
-// main.ts
-import {polly} from './polly/mock';               // FIRST import
-import {pollyUi} from '@avivbenhamo/polly-kit/node';
-
-// startPolly() runs above NestFactory.create: providers can fire requests during
-// module init, and anything that goes out ahead of it is not recorded.
-const app = await NestFactory.create(AppModule);
-
-if (polly) {
-    app.use('/__polly', pollyUi({recordingsDir: './recordings'}));
-}
-
-// Polly persists on stop. A SIGKILL still loses whatever the debounce had not flushed.
-for (const signal of ['SIGINT', 'SIGTERM']) {
-    process.on(signal, async () => {
-        await polly?.stop();
-        process.exit(0);
-    });
-}
-```
-
-```powershell
-$env:POLLY_MODE='record'; npm run start:dev
-```
-
-No Vite plugin and no recording store: `persister-fs` writes the HAR straight to disk.
-Add `/recordings` to `.gitignore`.
-
-**Use `{kind: 'only'}`, not `{kind: 'all'}`.** In a browser Polly sees the page's own
-requests. In Node the adapters are process-wide: they also see your service talking to
-Postgres, Redis, the broker, its health checks and its telemetry collector. `{kind: 'all'}`
-on a server mocks the database. `startPolly` logs the policy it resolved on startup — read
-that line once.
-
-**Call `http.get(...)` off the namespace, never `import {get} from 'node:http'`.** A named
-ESM import of a builtin is bound before the adapter patches the module object, and the
-already-bound name never sees the patch. Measured on Node v22.14.0: every request completes
-against the real upstream and Polly records none of them. axios is unaffected — it resolves
-`request` off the module object at call time.
-
-**Streaming is buffered.** Polly hands an adapter a complete response, so a
-server-sent-events or long-poll endpoint will not stream in record mode. Put such hosts in
-`alwaysPassthrough`.
-
-**Compressed responses are decompressed before they are stored**, and their
-`content-encoding` and `content-length` go with the compression. The undici dispatcher sees
-bodies still gzipped — `fetch` decompresses in a layer above it — so storing them raw would
-put base64 of compressed bytes in the HAR and leave nothing editable in the editor.
-
-**Quieter than Polly's default.** `logLevel` defaults to `'error'` here, not Polly's
-`'warn'`: `@pollyjs/adapter` warns on every recorded request when
-`'navigator' in global && !navigator.onLine`, and Node has a global `navigator` with no
-`onLine` — so the claim is always false, and each one drags a full stringified request and
-config into the log. Pass `logLevel: 'warn'` to get Polly's default back.
-
-Requires Node >= 22.6. Node 24 ships undici 7, whose handler protocol differs; `fetch`
-interception then fails with a message naming your Node version rather than silently
-recording nothing.
-
-## Policies
-
-```ts
-policy: {kind: 'all'}                    // mock every host
-policy: {kind: 'except', hosts: [...]}   // mock everything EXCEPT these
-policy: {kind: 'only',   hosts: [...]}   // mock ONLY these
-```
-
-Hosts match by origin, so a trailing slash or a path on the value is fine — they are `baseURL`s
-in practice, and `toOrigin` reduces them. An entry that resolves to `undefined` (an env var
-that was never set) is skipped rather than throwing at startup.
-
-**What is never mocked differs by entry point.** In the browser, the app's own origin is
-always passed through: it serves the HMR socket, the recording store and every static asset,
-so mocking it breaks the dev server. On `./node` there is no such origin, so
-`alwaysPassthrough` starts **empty** — nothing is exempt until you name it. That is deliberate:
-the adapters are process-wide, and a default that guessed which of your hosts were
-infrastructure would guess wrong quietly.
-
-**Passed-through hosts still hit the real network in `replay` mode.** That is what passthrough
-means, but it has a sharp edge: the hosts you exclude are usually auth and analytics, which are
-also the least likely to be reachable from an isolated environment. Replaying off-network then
-gives you hanging calls to exactly those while everything else replays fine — which reads as
-"Polly is broken" and isn't. For true isolation use `{kind: 'all'}` and record them too.
-
-## The editor
-
-The editor ships inside this package — there is nothing else to install. On the Vite path the
-plugin mounts it for you at `/__polly`. Anywhere else, `pollyUi()` is a bare `(req, res)`
-handler:
-
-```ts
-import {pollyUi} from '@avivbenhamo/polly-kit/studio';
-
-app.use('/__polly', pollyUi({recordingsDir: './recordings'}));
-```
-
-On a raw `http.createServer` also pass `basePath: '/__polly'`, since nothing stripped the
-prefix for you. Options: `recordingsDir` (required), `basePath`, `cwd`, and `enabled`, which
-defaults to `process.env.NODE_ENV !== 'production'`.
-
-**It answers 404, not 403, when disabled** — the same answer an unmounted path gives, rather
-than confirming something is there. Recordings hold real request and response bodies, so
-"someone mounted this and shipped it" must not become a data leak.
-
-For a browser app with no server at all, recording through Polly's
-`persister-local-storage`, `@avivbenhamo/polly-kit/studio/browser` mounts the same UI against
-that one localStorage key:
-
-```ts
-import {mountPollyStudio} from '@avivbenhamo/polly-kit/studio/browser';
-
-mountPollyStudio(document.getElementById('polly')!);
-```
-
-## API
-
-| Export | From | What |
-|---|---|---|
-| `startPolly(options)` | `.` | Starts Polly. Returns `null` when `mode` is `'off'`, having constructed nothing. |
-| `resolveMode(raw)` | `.` | Narrows an env value to `'off' \| 'record' \| 'replay'`. Anything unrecognised is `off`. |
-| `toOrigin` / `toOrigins` | `.` | The origin reduction the policy matcher uses. |
-| `pollyKit(options)` | `./vite` | The Vite plugin: recording store + studio. |
-| `recordingStore(options)` | `./store` | The store as a bare connect middleware, for mounting on something that isn't Vite. |
-| `startPolly` / `resolveMode` | `./node` | The Node entry: `http(s)` and `fetch`, HAR straight to disk. |
-| `pollyUi(options)` | `./node`, `./studio` | The editor as a bare `(req, res)` handler. Mounts on Express, Fastify, Koa, Vite or raw `http`. |
-| `FsStore` / `serializeHar` | `./studio` | The HAR file store the editor reads and writes through. |
-| `parseHar` / `findEntry` | `./studio` | Reading a HAR, with the Polly-specific quirks handled. |
-| `applyResponsePatch` / `deleteEntry` | `./studio` | Editing an entry, returning a typed `EditError` rather than throwing. |
-| `mountPollyStudio(root)` | `./studio/browser` | The editor with no server at all, against Polly's `persister-local-storage`. |
-
-`startPolly` options beyond the policy config: `mode` (required), `alwaysPassthrough`,
-`apiNamespace`, `saveDebounceMs`; on `./node`, `recordingsDir` and `logLevel` instead of
-`apiNamespace`. `pollyKit` options: `recordingsDir`, `studioPath`,
-`apiNamespace`, `studio`. Change `apiNamespace` in one place and you must change it in both.
-
-## Notes on why it is built this way
-
-**In the browser: the XHR adapter, not fetch.** axios resolves its adapter as
-`['xhr', 'http', 'fetch']`, so in a browser it uses `XMLHttpRequest`. `@pollyjs/adapter-fetch`
-would attach cleanly and then see no traffic at all. `adapter-xhr` patches
-`window.XMLHttpRequest`, which axios picks up with no awareness — so no axios instance in your
-app needs to change.
-
-**On Node: two adapters, one of them ours.** `@pollyjs/adapter-node-http` patches
-`http.request`/`http.get`, which covers axios, got and Nest's `HttpModule`. It sees nothing of
-the built-in `fetch`: that is undici, which reads its dispatcher off a global symbol and opens
-a socket without going through `http.request`. Polly ships no adapter for that layer, so this
-package contains one. An `http`-only wrapper would attach cleanly and record none of your
-`fetch` traffic — silently, which is the failure this package exists to prevent.
-
-**The `global` shim.** `@pollyjs/persister-rest` reads a bare, unbound `global` at module top
-level, which throws in a browser. `startPolly`'s module imports the shim as its own first
-import, so you cannot get the order wrong.
-
-**Recordings flush while you browse.** Polly only persists on `stop()`, which suits a test that
-ends; a dev server page stays open and would write nothing. The kit debounces a `persist()` per
-response instead.
-
-**Defaults that differ from Polly's.** `recordIfMissing: false` (a replay miss must fail loudly
-— the default quietly hits the network and records it, which looks identical to replay working),
-`recordFailedRequests: true`, `matchRequestsBy.order: false` (screens refetch) and
-`.headers: false` (bearer tokens would pin a recording to one session).
-
-**If you also run MSW, Polly wins.** It patches `XMLHttpRequest` in-page, so the request is
-answered before the service worker sees it. Run one or the other.
+# @avivbenhamo/polly-kit
+
+Record an app's real HTTP traffic to HAR files, then replay it so the app runs with no
+backends. Polly.JS, the recording store and the HAR editor in one package — one install, no
+companion to keep in step.
+
+Entry points:
+
+| | |
+|---|---|
+| `@avivbenhamo/polly-kit` | a Vite app, in the browser |
+| [`@avivbenhamo/polly-kit/node`](#non-browser-apps) | a Node process — NestJS, a service, a CLI. `http(s)` **and** the built-in `fetch` |
+| [`@avivbenhamo/polly-kit/studio`](#the-editor) | the editor's handler and HAR API, to mount anywhere |
+| `@avivbenhamo/polly-kit/studio/browser` | the editor for a browser app with no server at all |
+| `@avivbenhamo/polly-kit/vite` | the Vite plugin |
+| `@avivbenhamo/polly-kit/store` | the recording store as bare connect middleware |
+
+Nothing in here knows a hostname. You supply a policy; the package is the machinery.
+
+## Install
+
+```sh
+npm i -D @avivbenhamo/polly-kit
+```
+
+## Three steps
+
+**1. `vite.config.ts`** — one plugin, dev-server only (it registers in `configureServer`, so a
+production build never sees it):
+
+```ts
+import pollyKit from '@avivbenhamo/polly-kit/vite';
+
+export default defineConfig({
+    plugins: [react(), pollyKit({recordingsDir: 'recordings'})],
+});
+```
+
+**2. A config file** — the only file you write:
+
+```ts
+// src/polly/config.ts
+import type {PollyPolicyConfig} from '@avivbenhamo/polly-kit';
+
+export const pollyConfig: PollyPolicyConfig = {
+    recordingName: 'my-app',
+    policy: {kind: 'except', hosts: [import.meta.env.VITE_AUTH_URL]},
+};
+```
+
+**3. A bootstrap module, imported FIRST in your entry point:**
+
+```ts
+// src/polly/bootstrap.ts
+import {resolveMode, startPolly} from '@avivbenhamo/polly-kit';
+import {pollyConfig} from './config';
+
+const mode = import.meta.env.PROD ? 'off' : resolveMode(import.meta.env.VITE_POLLY_MODE);
+
+startPolly({...pollyConfig, mode});
+```
+
+```ts
+// src/index.tsx — FIRST import, above everything
+import './polly/bootstrap';
+```
+
+`bootstrap.ts` exists so that `startPolly()` runs before your component tree is evaluated. ES
+module imports are hoisted and fully evaluated before any statement in the importing module's
+body, so a bare `startPolly()` call in `index.tsx` runs *after* `./App` and everything it
+imports — and any module that fires a request at import time would escape interception,
+silently and only sometimes.
+
+Add `/recordings` to `.gitignore`. A HAR holds complete response bodies.
+
+## Running it
+
+Off unless `VITE_POLLY_MODE` is set, so the default behaviour of your app is unchanged.
+
+```powershell
+$env:VITE_POLLY_MODE='record'; npm run dev     # capture real traffic
+$env:VITE_POLLY_MODE='replay'; npm run dev     # serve from recordings
+```
+
+```sh
+VITE_POLLY_MODE=record npm run dev             # bash
+```
+
+Record once against reachable backends, then replay forever. Recordings land in
+`recordings/<recordingName>_<hash>/recording.har`, editable at **http://localhost:<port>/__polly**
+— the URL is printed on startup.
+
+## Non-browser apps
+
+`@avivbenhamo/polly-kit/node` is the same thing for a Node process — NestJS, a plain
+service, a CLI. It intercepts **both** transports: `http(s).request`/`get` (axios, got,
+Nest's `HttpModule`) and Node's built-in `fetch`.
+
+```ts
+// src/polly/mock.ts
+import {startPolly, resolveMode} from '@avivbenhamo/polly-kit/node';
+
+export const polly = startPolly({
+    mode: resolveMode(process.env.POLLY_MODE),
+    recordingName: 'my-api',
+    recordingsDir: './recordings',
+    policy: {kind: 'only', hosts: [process.env.PARTNER_API_URL]},
+});
+```
+
+```ts
+// main.ts
+import {polly} from './polly/mock';               // FIRST import
+import {pollyUi} from '@avivbenhamo/polly-kit/node';
+
+// startPolly() runs above NestFactory.create: providers can fire requests during
+// module init, and anything that goes out ahead of it is not recorded.
+const app = await NestFactory.create(AppModule);
+
+if (polly) {
+    app.use('/__polly', pollyUi({recordingsDir: './recordings'}));
+}
+
+// Polly persists on stop. A SIGKILL still loses whatever the debounce had not flushed.
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, async () => {
+        await polly?.stop();
+        process.exit(0);
+    });
+}
+```
+
+```powershell
+$env:POLLY_MODE='record'; npm run start:dev
+```
+
+No Vite plugin and no recording store: `persister-fs` writes the HAR straight to disk.
+Add `/recordings` to `.gitignore`.
+
+**Use `{kind: 'only'}`, not `{kind: 'all'}`.** In a browser Polly sees the page's own
+requests. In Node the adapters are process-wide: they also see your service talking to
+Postgres, Redis, the broker, its health checks and its telemetry collector. `{kind: 'all'}`
+on a server mocks the database. `startPolly` logs the policy it resolved on startup — read
+that line once.
+
+**Call `http.get(...)` off the namespace, never `import {get} from 'node:http'`.** A named
+ESM import of a builtin is bound before the adapter patches the module object, and the
+already-bound name never sees the patch. Measured on Node v22.14.0: every request completes
+against the real upstream and Polly records none of them. axios is unaffected — it resolves
+`request` off the module object at call time.
+
+**Streaming is buffered.** Polly hands an adapter a complete response, so a
+server-sent-events or long-poll endpoint will not stream in record mode. Put such hosts in
+`alwaysPassthrough`.
+
+**Compressed responses are decompressed before they are stored**, and their
+`content-encoding` and `content-length` go with the compression. The undici dispatcher sees
+bodies still gzipped — `fetch` decompresses in a layer above it — so storing them raw would
+put base64 of compressed bytes in the HAR and leave nothing editable in the editor.
+
+**Quieter than Polly's default.** `logLevel` defaults to `'error'` here, not Polly's
+`'warn'`: `@pollyjs/adapter` warns on every recorded request when
+`'navigator' in global && !navigator.onLine`, and Node has a global `navigator` with no
+`onLine` — so the claim is always false, and each one drags a full stringified request and
+config into the log. Pass `logLevel: 'warn'` to get Polly's default back.
+
+Requires Node >= 22.6. Node 24 ships undici 7, whose handler protocol differs; `fetch`
+interception then fails with a message naming your Node version rather than silently
+recording nothing.
+
+## Policies
+
+```ts
+policy: {kind: 'all'}                    // mock every host
+policy: {kind: 'except', hosts: [...]}   // mock everything EXCEPT these
+policy: {kind: 'only',   hosts: [...]}   // mock ONLY these
+```
+
+Hosts match by origin, so a trailing slash or a path on the value is fine — they are `baseURL`s
+in practice, and `toOrigin` reduces them. An entry that resolves to `undefined` (an env var
+that was never set) is skipped rather than throwing at startup.
+
+**What is never mocked differs by entry point.** In the browser, the app's own origin is
+always passed through: it serves the HMR socket, the recording store and every static asset,
+so mocking it breaks the dev server. On `./node` there is no such origin, so
+`alwaysPassthrough` starts **empty** — nothing is exempt until you name it. That is deliberate:
+the adapters are process-wide, and a default that guessed which of your hosts were
+infrastructure would guess wrong quietly.
+
+**Passed-through hosts still hit the real network in `replay` mode.** That is what passthrough
+means, but it has a sharp edge: the hosts you exclude are usually auth and analytics, which are
+also the least likely to be reachable from an isolated environment. Replaying off-network then
+gives you hanging calls to exactly those while everything else replays fine — which reads as
+"Polly is broken" and isn't. For true isolation use `{kind: 'all'}` and record them too.
+
+## The editor
+
+The editor ships inside this package — there is nothing else to install. On the Vite path the
+plugin mounts it for you at `/__polly`. Anywhere else, `pollyUi()` is a bare `(req, res)`
+handler:
+
+```ts
+import {pollyUi} from '@avivbenhamo/polly-kit/studio';
+
+app.use('/__polly', pollyUi({recordingsDir: './recordings'}));
+```
+
+On a raw `http.createServer` also pass `basePath: '/__polly'`, since nothing stripped the
+prefix for you. Options: `recordingsDir` (required), `basePath`, `cwd`, and `enabled`, which
+defaults to `process.env.NODE_ENV !== 'production'`.
+
+### Without an app
+
+```sh
+npx polly-kit studio --dir recordings      # http://127.0.0.1:7788
+```
+
+For a checkout with no dev server to mount on: reviewing the recordings in a pull request,
+pruning a stale one, opening somebody else's `recordings/` without installing their app. Same
+editor, same files — the recordings directory is the only state, so an app recording into it
+from another process shows up without restarting anything. If the port is taken it walks up to
+the next free one and says so.
+
+**The mounted form is still the default**, and the better one when there is a dev server: no
+second process, no second port, no CORS, and it stops when the server does. Recordings kept in
+a browser's `localStorage` cannot be served this way at all — no separate process can see them,
+which is what `mountPollyStudio` is for.
+
+Unlike the mounted handler this ignores `NODE_ENV`. Something mounted into an app can be
+deployed by accident; an `npx` invocation cannot, and a shell that happens to export
+`NODE_ENV=production` would otherwise get 404s with no explanation.
+
+**It answers 404, not 403, when disabled** — the same answer an unmounted path gives, rather
+than confirming something is there. Recordings hold real request and response bodies, so
+"someone mounted this and shipped it" must not become a data leak.
+
+For a browser app with no server at all, recording through Polly's
+`persister-local-storage`, `@avivbenhamo/polly-kit/studio/browser` mounts the same UI against
+that one localStorage key:
+
+```ts
+import {mountPollyStudio} from '@avivbenhamo/polly-kit/studio/browser';
+
+mountPollyStudio(document.getElementById('polly')!);
+```
+
+## API
+
+| Export | From | What |
+|---|---|---|
+| `startPolly(options)` | `.` | Starts Polly. Returns `null` when `mode` is `'off'`, having constructed nothing. |
+| `resolveMode(raw)` | `.` | Narrows an env value to `'off' \| 'record' \| 'replay'`. Anything unrecognised is `off`. |
+| `toOrigin` / `toOrigins` | `.` | The origin reduction the policy matcher uses. |
+| `pollyKit(options)` | `./vite` | The Vite plugin: recording store + studio. |
+| `recordingStore(options)` | `./store` | The store as a bare connect middleware, for mounting on something that isn't Vite. |
+| `startPolly` / `resolveMode` | `./node` | The Node entry: `http(s)` and `fetch`, HAR straight to disk. |
+| `pollyUi(options)` | `./node`, `./studio` | The editor as a bare `(req, res)` handler. Mounts on Express, Fastify, Koa, Vite or raw `http`. |
+| `FsStore` / `serializeHar` | `./studio` | The HAR file store the editor reads and writes through. |
+| `parseHar` / `findEntry` | `./studio` | Reading a HAR, with the Polly-specific quirks handled. |
+| `applyResponsePatch` / `deleteEntry` | `./studio` | Editing an entry, returning a typed `EditError` rather than throwing. |
+| `mountPollyStudio(root)` | `./studio/browser` | The editor with no server at all, against Polly's `persister-local-storage`. |
+
+`startPolly` options beyond the policy config: `mode` (required), `alwaysPassthrough`,
+`apiNamespace`, `saveDebounceMs`; on `./node`, `recordingsDir` and `logLevel` instead of
+`apiNamespace`. `pollyKit` options: `recordingsDir`, `studioPath`,
+`apiNamespace`, `studio`. Change `apiNamespace` in one place and you must change it in both.
+
+## Notes on why it is built this way
+
+**In the browser: both adapters.** A browser has two request transports and an app can use
+either, so covering one covers half the app — silently, because an adapter attaches cleanly
+whether or not any traffic reaches it. `adapter-xhr` patches `window.XMLHttpRequest`, which is
+what axios uses (it resolves its adapter as `['xhr', 'http', 'fetch']`), so no axios instance
+in your app needs to change. `adapter-fetch` patches `window.fetch`, which is what code
+written against the platform calls directly. They patch different globals and do not interact.
+
+**On Node: two adapters, one of them ours.** `@pollyjs/adapter-node-http` patches
+`http.request`/`http.get`, which covers axios, got and Nest's `HttpModule`. It sees nothing of
+the built-in `fetch`: that is undici, which reads its dispatcher off a global symbol and opens
+a socket without going through `http.request`. Polly ships no adapter for that layer, so this
+package contains one. An `http`-only wrapper would attach cleanly and record none of your
+`fetch` traffic — silently, which is the failure this package exists to prevent.
+
+**The `global` shim.** `@pollyjs/persister-rest` reads a bare, unbound `global` at module top
+level, which throws in a browser. `startPolly`'s module imports the shim as its own first
+import, so you cannot get the order wrong.
+
+**Recordings flush while you browse.** Polly only persists on `stop()`, which suits a test that
+ends; a dev server page stays open and would write nothing. The kit debounces a `persist()` per
+response instead.
+
+**Defaults that differ from Polly's.** `recordIfMissing: false` (a replay miss must fail loudly
+— the default quietly hits the network and records it, which looks identical to replay working),
+`recordFailedRequests: true`, `matchRequestsBy.order: false` (screens refetch) and
+`.headers: false` (bearer tokens would pin a recording to one session).
+
+**If you also run MSW, Polly wins.** It patches `XMLHttpRequest` and `fetch` in-page, so the
+request is answered before the service worker sees it. Run one or the other.

package/dist/browser.d.ts

@@ -5,11 +5,19 @@
  * first request goes out. Import the module that calls it FIRST in your entry
  * point — see the README.
  *
- * WHY THE XHR ADAPTER. axios resolves its adapter in the order
- * `['xhr', 'http', 'fetch']`, so in a browser it uses XMLHttpRequest. The fetch
- * adapter would attach cleanly and then see no traffic at all. `adapter-xhr`
- * patches `window.XMLHttpRequest`, which axios picks up with no awareness — so no
- * axios instance in the host app needs to change.
+ * WHY BOTH ADAPTERS. A browser has two request transports and an app can use
+ * either, so covering one is covering half the app — silently, because an
+ * adapter attaches cleanly whether or not any traffic reaches it.
+ *
+ *   - `adapter-xhr` patches `window.XMLHttpRequest`. axios resolves its adapter
+ *     in the order `['xhr', 'http', 'fetch']`, so in a browser it uses XHR —
+ *     which means no axios instance in the host app needs to change.
+ *   - `adapter-fetch` patches `window.fetch`, which is what application code
+ *     written against the platform uses directly.
+ *
+ * They patch different globals and do not interact. This mirrors `./node`, which
+ * has always intercepted both of its transports (`http(s)` and `fetch`) for the
+ * same reason.
  *
  * Nothing here reads the environment. The caller resolves the mode and passes it
  * in, which is what keeps this file free of any bundler's env API.

package/dist/browser.js

@@ -5,11 +5,19 @@
  * first request goes out. Import the module that calls it FIRST in your entry
  * point — see the README.
  *
- * WHY THE XHR ADAPTER. axios resolves its adapter in the order
- * `['xhr', 'http', 'fetch']`, so in a browser it uses XMLHttpRequest. The fetch
- * adapter would attach cleanly and then see no traffic at all. `adapter-xhr`
- * patches `window.XMLHttpRequest`, which axios picks up with no awareness — so no
- * axios instance in the host app needs to change.
+ * WHY BOTH ADAPTERS. A browser has two request transports and an app can use
+ * either, so covering one is covering half the app — silently, because an
+ * adapter attaches cleanly whether or not any traffic reaches it.
+ *
+ *   - `adapter-xhr` patches `window.XMLHttpRequest`. axios resolves its adapter
+ *     in the order `['xhr', 'http', 'fetch']`, so in a browser it uses XHR —
+ *     which means no axios instance in the host app needs to change.
+ *   - `adapter-fetch` patches `window.fetch`, which is what application code
+ *     written against the platform uses directly.
+ *
+ * They patch different globals and do not interact. This mirrors `./node`, which
+ * has always intercepted both of its transports (`http(s)` and `fetch`) for the
+ * same reason.
  *
  * Nothing here reads the environment. The caller resolves the mode and passes it
  * in, which is what keeps this file free of any bundler's env API.
@@ -20,6 +28,7 @@
 // rather than in the host app so the host app cannot get the order wrong.
 import './global-shim.js';
 import { Polly } from '@pollyjs/core';
+import FetchAdapter from '@pollyjs/adapter-fetch';
 import XHRAdapter from '@pollyjs/adapter-xhr';
 import RestPersister from '@pollyjs/persister-rest';
 import { KEEP_UNUSED_REQUESTS, POLLY_DEFAULTS } from './defaults.js';
@@ -65,12 +74,13 @@ export function startPolly(options) {
     }
     if (!registered) {
         Polly.register(XHRAdapter);
+        Polly.register(FetchAdapter);
         Polly.register(RestPersister);
         registered = true;
     }
     const polly = new Polly(recordingName, {
         mode,
-        adapters: ['xhr'],
+        adapters: ['xhr', 'fetch'],
         persister: 'rest',
         persisterOptions: {
             keepUnusedRequests: KEEP_UNUSED_REQUESTS,

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;
+export interface StudioOptions {
+    recordingsDir: string;
+    port?: number;
+}
+export interface Studio {
+    /** The port it actually got, which is not always the one asked for. */
+    port: number;
+    close(): Promise<void>;
+}
+/**
+ * The server, without the process around it.
+ *
+ * Separate from `main` because stopping it has to be something a caller does,
+ * not something a signal does: `process.once('SIGINT')` listeners are global,
+ * so a second studio started in the same process would be stopped by the first
+ * one's Ctrl-C. That is only ever a test, but it is also the shape anything
+ * embedding this would want.
+ */
+export declare function startStudio(options: StudioOptions): Promise<Studio>;

package/dist/cli.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * The studio, served on its own, for a checkout with no app running.
+ *
+ * The mounted form stays the default and is the better one when there *is* a dev
+ * server: `app.use('/__polly', pollyUi(...))` — or the Vite plugin, which does
+ * it for you — costs no second process, no second port and no CORS, and it goes
+ * away when the dev server does.
+ *
+ * This exists for the times there is no dev server to mount on. Reviewing the
+ * recordings in a pull request, pruning a stale one on a CI box, opening a
+ * colleague's `recordings/` without installing their app's dependencies: all of
+ * them are file-editing, and the editor is already a plain handler over a
+ * directory, so they do not need the app at all.
+ *
+ * What this *cannot* serve is the browser case. `mountPollyStudio` edits
+ * recordings held in the page's own localStorage, and no separate process can
+ * see those.
+ */
+import { createServer } from 'node:http';
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { pollyUi } from './studio/server.js';
+const DEFAULT_PORT = 7788;
+const DEFAULT_DIR = 'recordings';
+/**
+ * How far to walk up from the asked-for port before giving up. A studio left
+ * open in another window is the normal case, and `EADDRINUSE` with a stack
+ * trace is a poor answer to it.
+ */
+const PORT_TRIES = 20;
+const USAGE = `polly-kit — Polly recordings, in a browser
+
+  npx polly-kit studio [--dir DIR] [--port PORT]
+
+  studio    Serve the recording editor on 127.0.0.1. Reads and writes the HAR
+            files under DIR (default ${DEFAULT_DIR}), the same ones the mounted
+            editor edits.
+
+Mounted in a dev server instead — no second port, and it stops when the server
+does — this is the Vite plugin, or app.use('/__polly', pollyUi({recordingsDir})).
+Recordings held in a browser's localStorage are reachable only from the page
+that owns them, through mountPollyStudio.
+`;
+export async function main(argv) {
+    const command = argv[0] ?? 'help';
+    if (command === 'help' || command === '--help' || command === '-h') {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (command !== 'studio') {
+        process.stderr.write(`unknown command: ${command}\n\n${USAGE}`);
+        return 2;
+    }
+    const dir = flag(argv, 'dir') ?? DEFAULT_DIR;
+    const root = isAbsolute(dir) ? dir : join(process.cwd(), dir);
+    const port = Number(flag(argv, 'port') ?? DEFAULT_PORT);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        process.stderr.write(`--port must be a port number, not "${flag(argv, 'port')}"\n`);
+        return 2;
+    }
+    // Said, not refused. An empty or missing directory is what you get before the
+    // first recording, and the editor explains that better than an exit code —
+    // but the path is printed either way, because "no recordings" almost always
+    // means the studio is looking somewhere else than the app records to.
+    if (!existsSync(root)) {
+        process.stdout.write(`no ${resolve(root)} yet — the editor will be empty until something records\n`);
+    }
+    const studio = await startStudio({ recordingsDir: root, port });
+    if (studio.port !== port)
+        process.stdout.write(`port ${port} was busy — using ${studio.port}\n`);
+    process.stdout.write(`polly studio on http://127.0.0.1:${studio.port}\n`);
+    process.stdout.write(`recordings: ${resolve(root)}\n`);
+    await new Promise((done) => {
+        process.once('SIGINT', () => done());
+        process.once('SIGTERM', () => done());
+    });
+    await studio.close();
+    return 0;
+}
+/**
+ * The server, without the process around it.
+ *
+ * Separate from `main` because stopping it has to be something a caller does,
+ * not something a signal does: `process.once('SIGINT')` listeners are global,
+ * so a second studio started in the same process would be stopped by the first
+ * one's Ctrl-C. That is only ever a test, but it is also the shape anything
+ * embedding this would want.
+ */
+export async function startStudio(options) {
+    // `enabled` is forced on. The mounted handler defaults it to NODE_ENV not
+    // being production, because something mounted into an app can be deployed by
+    // accident and recordings hold recorded request and response bodies. Nobody
+    // deploys an npx invocation by accident, and a shell that happens to export
+    // NODE_ENV=production would otherwise serve 404s with no explanation.
+    const server = createServer(pollyUi({ recordingsDir: options.recordingsDir, enabled: true }));
+    const port = await listenNearby(server, options.port ?? DEFAULT_PORT);
+    return {
+        port,
+        close: () => new Promise((done) => server.close(() => done())),
+    };
+}
+/** Loopback only: this serves recorded bodies, and it is a tool for one person. */
+async function listenNearby(server, port) {
+    for (let offset = 0; offset < PORT_TRIES; offset++) {
+        try {
+            await new Promise((done, fail) => {
+                server.once('error', fail);
+                server.listen(port + offset, '127.0.0.1', () => {
+                    server.removeListener('error', fail);
+                    done();
+                });
+            });
+            return port + offset;
+        }
+        catch (err) {
+            if (err.code !== 'EADDRINUSE')
+                throw err;
+        }
+    }
+    throw new Error(`ports ${port}-${port + PORT_TRIES - 1} are all in use. Pass --port to pick another.`);
+}
+/** `--dir recordings` and `--dir=recordings`, both. */
+function flag(argv, name) {
+    const index = argv.indexOf(`--${name}`);
+    if (index !== -1)
+        return argv[index + 1];
+    const inline = argv.find((arg) => arg.startsWith(`--${name}=`));
+    return inline === undefined ? undefined : inline.slice(name.length + 3);
+}
+// Only when run as a program. Importing this from a test must not start a
+// server — and the comparison is through fileURLToPath rather than string
+// matching on the URL, because on Windows argv[1] is `C:\...\cli.js` and
+// import.meta.url is `file:///C:/.../cli.js`.
+if (process.argv[1] !== undefined && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/studio/ui/render.js

@@ -134,38 +134,38 @@ function entryDetail(entry) {
     const headers = response.headers
         .map((header, index) => `<div class="header-row"><input name="headerName${index}" value="${escapeHtml(header.name)}" class="ps-header-name" spellcheck="false" aria-label="Header name"><input name="headerValue${index}" value="${escapeHtml(header.value)}" class="ps-header-value" spellcheck="false" aria-label="Header value"></div>`)
         .join('');
-    return `
-<section class="detail" data-id="${escapeHtml(entry._id)}" data-order="${renderNumeric(entry._order)}">
-  <div class="ps-block ps-block--request">
-    <h2>Request <small>read-only</small></h2>
-    <p class="note">Polly matches a replayed request on <code>_id</code>, an md5 of the request built
-    from your <code>matchRequestsBy</code> config — and that config is not stored in the recording.
-    Editing any of this would leave an entry that looks right and never matches again.</p>
-    <dl>
-      <dt>Method</dt><dd>${escapeHtml(entry.request.method)}</dd>
-      <dt>URL</dt><dd>${escapeHtml(entry.request.url)}</dd>
-      <dt>Recorded</dt><dd>${escapeHtml(entry.startedDateTime)}</dd>
-      <dt>_id / _order</dt><dd><code>${escapeHtml(entry._id)}</code> / ${renderNumeric(entry._order)}</dd>
-    </dl>
-  </div>
-
-  <div class="ps-block ps-block--response">
-    <h2>Response</h2>
-    <div class="ps-fields">
-      <label class="ps-field"><span class="ps-field-label">Status</span><input name="status" type="number" value="${renderNumeric(response.status)}" class="ps-input" min="100" max="599"></label>
-      <label class="ps-field"><span class="ps-field-label">Status text</span><input name="statusText" value="${escapeHtml(response.statusText)}" class="ps-input" spellcheck="false"></label>
-    </div>
-
-    <h3 class="ps-group-title">Headers</h3>
-    ${headers === '' ? '<p class="empty">This response was recorded without headers.</p>' : `<div class="headers">${headers}</div>`}
-
-    <h3 class="ps-group-title">Body</h3>
-    ${body}
-
-    <div class="actions">
-      <button name="save">Save response</button>
-      <button name="delete" class="danger">Delete entry</button>
-    </div>
-  </div>
+    return `
+<section class="detail" data-id="${escapeHtml(entry._id)}" data-order="${renderNumeric(entry._order)}">
+  <div class="ps-block ps-block--request">
+    <h2>Request <small>read-only</small></h2>
+    <p class="note">Polly matches a replayed request on <code>_id</code>, an md5 of the request built
+    from your <code>matchRequestsBy</code> config — and that config is not stored in the recording.
+    Editing any of this would leave an entry that looks right and never matches again.</p>
+    <dl>
+      <dt>Method</dt><dd>${escapeHtml(entry.request.method)}</dd>
+      <dt>URL</dt><dd>${escapeHtml(entry.request.url)}</dd>
+      <dt>Recorded</dt><dd>${escapeHtml(entry.startedDateTime)}</dd>
+      <dt>_id / _order</dt><dd><code>${escapeHtml(entry._id)}</code> / ${renderNumeric(entry._order)}</dd>
+    </dl>
+  </div>
+
+  <div class="ps-block ps-block--response">
+    <h2>Response</h2>
+    <div class="ps-fields">
+      <label class="ps-field"><span class="ps-field-label">Status</span><input name="status" type="number" value="${renderNumeric(response.status)}" class="ps-input" min="100" max="599"></label>
+      <label class="ps-field"><span class="ps-field-label">Status text</span><input name="statusText" value="${escapeHtml(response.statusText)}" class="ps-input" spellcheck="false"></label>
+    </div>
+
+    <h3 class="ps-group-title">Headers</h3>
+    ${headers === '' ? '<p class="empty">This response was recorded without headers.</p>' : `<div class="headers">${headers}</div>`}
+
+    <h3 class="ps-group-title">Body</h3>
+    ${body}
+
+    <div class="actions">
+      <button name="save">Save response</button>
+      <button name="delete" class="danger">Delete entry</button>
+    </div>
+  </div>
 </section>`;
 }

package/dist/vite.d.ts

@@ -1,20 +1,3 @@
-/**
- * One Vite plugin: the recording store plus the polly-studio editor.
- *
- * Two plugins would be honest about the two concerns, but they always go
- * together and each needed the same `recordingsDir` — so the host app's
- * vite.config gains one import and one line.
- *
- * WHY THE STUDIO'S `basePath` IS NOT SET. Connect strips the mount path before
- * the handler runs — `GET /__polly/api/recordings` arrives as
- * `/api/recordings` — so the handler must not strip it a second time. The
- * browser side does not need to be told either: the page derives its API base
- * from `location.pathname`. Set `basePath` here and every API call 404s.
- *
- * Dev only, deliberately. This hooks `configureServer`, which a production build
- * never calls, and `pollyUi()` disables itself when `NODE_ENV === 'production'`
- * anyway — recordings hold real recorded request and response bodies.
- */
 import type { Plugin } from 'vite';
 export interface PollyKitOptions {
     /** Where HARs are read from and written to. Gitignore it. */

package/dist/vite.js

@@ -1,6 +1,40 @@
+/**
+ * One Vite plugin: the recording store plus the polly-studio editor.
+ *
+ * Two plugins would be honest about the two concerns, but they always go
+ * together and each needed the same `recordingsDir` — so the host app's
+ * vite.config gains one import and one line.
+ *
+ * WHY THE STUDIO'S `basePath` IS NOT SET. Connect strips the mount path before
+ * the handler runs — `GET /__polly/api/recordings` arrives as
+ * `/api/recordings` — so the handler must not strip it a second time. The
+ * browser side does not need to be told either: the page derives its API base
+ * from `location.pathname`. Set `basePath` here and every API call 404s.
+ *
+ * Dev only, deliberately. This hooks `configureServer`, which a production build
+ * never calls, and `pollyUi()` disables itself when `NODE_ENV === 'production'`
+ * anyway — recordings hold real recorded request and response bodies.
+ */
+import { createRequire } from 'node:module';
 import { pollyUi } from './studio/index.js';
 import { recordingStore, STORE_NAMESPACE } from './store.js';
 const STUDIO_PATH = '/__polly';
+/**
+ * The npm `buffer` package, resolved to an absolute path from THIS file.
+ *
+ * Resolving it from here rather than aliasing to the bare specifier `buffer/`
+ * matters twice. Vite warns on a non-absolute alias replacement because it
+ * cannot dedupe the result ("will lead to duplicated modules"). And the bare
+ * form is resolved from the consuming app's root, so it only works when the
+ * installer has hoisted `buffer` out of this package and into theirs. Measured
+ * with a `file:` link, where npm does not: the dep optimizer fails with "Cannot
+ * optimize dependency: buffer" and every response then errors on `Buffer.from`.
+ * A strict node_modules layout (pnpm's default, Yarn PnP) should hit the same
+ * thing for the same reason — not measured.
+ *
+ * `buffer` is a dependency of this package, so this resolution always succeeds.
+ */
+const BUFFER_PATH = createRequire(import.meta.url).resolve('buffer/');
 export default function pollyKit(options = {}) {
     const { recordingsDir = 'recordings', studioPath = STUDIO_PATH, apiNamespace = STORE_NAMESPACE, studio = true, } = options;
     return {
@@ -39,18 +73,21 @@ export default function pollyKit(options = {}) {
                             // resolves to a stub and every response errors with
                             // "Cannot read properties of undefined (reading 'from')".
                             //
-                            // The trailing slash is what makes this resolve to the npm
-                            // `buffer` package rather than back to the Node builtin. The
-                            // anchored regex keeps it from also rewriting `buffer/...`.
+                            // The anchored regex keeps it from also rewriting
+                            // `buffer/...`; see BUFFER_PATH for why the replacement is
+                            // an absolute path from this package rather than `buffer/`.
                             find: /^buffer$/,
-                            replacement: 'buffer/',
+                            replacement: BUFFER_PATH,
                         },
                     ],
                 },
                 optimizeDeps: {
                     // `buffer`: pre-bundled alongside the Polly packages that import
                     // it, so the dep optimizer does not treat it as an unresolved
-                    // external on a cold start.
+                    // external on a cold start. By absolute path for the same reason
+                    // the alias is — a bare `'buffer'` here is resolved from the
+                    // consuming app's root, which has no `buffer` unless npm hoisted
+                    // ours into it.
                     //
                     // This package itself: without it, Vite discovers the dependency
                     // when the entry module first requests it, optimizes, and triggers
@@ -60,7 +97,7 @@ export default function pollyKit(options = {}) {
                     // `.vite` cache missed every request, the reload after it recorded
                     // fine. Naming it here makes the optimizer run before the server
                     // accepts requests, so the first load is the optimized one.
-                    include: ['buffer', '@avivbenhamo/polly-kit'],
+                    include: [BUFFER_PATH, '@avivbenhamo/polly-kit'],
                     // The `define` above does not reach pre-bundled dependencies, and
                     // persister-rest is one. This is the half that actually fixes it.
                     esbuildOptions: { define: { global: 'globalThis' } },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avivbenhamo/polly-kit",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Drop-in record/replay of an app's HTTP traffic with Polly.JS, plus the polly-studio editor. Bring your own host policy.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,10 @@
     "dist",
     "README.md"
   ],
+  "//bin": "The studio on its own, for a checkout with no dev server to mount it in. The mounted form stays the default.",
+  "bin": {
+    "polly-kit": "./dist/cli.js"
+  },
   "main": "./dist/browser.js",
   "types": "./dist/browser.d.ts",
   "//typesVersions": "For consumers still on moduleResolution 'node', which ignores `exports`. Drop once everything is on 'bundler'.",
@@ -79,10 +83,12 @@
     "bundle": "esbuild dist/studio/ui/client.js --bundle --format=esm --target=es2022 --outfile=dist/studio/client.bundle.js",
     "fixture": "node --experimental-strip-types --disable-warning=ExperimentalWarning test/studio/fixtures/record.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --experimental-strip-types --disable-warning=ExperimentalWarning --test \"test/**/*.test.ts\""
+    "test": "npm run build && node --experimental-strip-types --disable-warning=ExperimentalWarning --test \"test/**/*.test.ts\"",
+    "studio": "node --experimental-strip-types --disable-warning=ExperimentalWarning src/cli.ts studio"
   },
   "dependencies": {
     "@pollyjs/adapter": "^6.0.6",
+    "@pollyjs/adapter-fetch": "^6.0.7",
     "@pollyjs/adapter-node-http": "^6.0.6",
     "@pollyjs/adapter-xhr": "^6.0.6",
     "@pollyjs/core": "^6.0.6",