@avivbenhamo/polly-kit 0.1.0 → 0.5.0

package/dist/studio/ui/render.js

@@ -0,0 +1,171 @@
+import { decodeContent } from '../body.js';
+import { getHeader } from '../headers.js';
+/**
+ * Rendering is string-in, string-out and lives apart from the DOM so it can be tested
+ * without a browser. Recorded bodies are attacker-shaped by nature — they came off the
+ * network — so everything interpolated goes through `escapeHtml`.
+ *
+ * The parameter is not `string`, and the body opens with `String(value)`. `parseHar`'s
+ * `isHarShaped` (`src/har.ts`) is a shape check, not a schema validator: it confirms
+ * `log.entries` is an array and casts the rest of the parsed JSON to `Har`, so a field
+ * this module's types call `string` can be a number, `null` or `undefined` on disk — and
+ * `.replaceAll` does not exist on any of those. Design spec §7 requires the UI to open
+ * exactly the recordings Polly would reject, so that is an expected input.
+ *
+ * It is a union of the JSON primitives rather than `unknown`, which is the narrowest
+ * type that accepts everything a malformed HAR can put in a text field while still
+ * failing the build on `escapeHtml(someObject)` — a call that is always a mistake, and
+ * that `unknown` would have accepted silently as `[object Object]`. Callers holding an
+ * `unknown` say `String(value)` themselves, which makes the coercion visible at the site
+ * that chose it.
+ */
+export function escapeHtml(value) {
+    return String(value)
+        .replaceAll('&', '&')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+/**
+ * A render-boundary guard for fields the *type* declares `number` but that actually
+ * came off disk. `isHarShaped` (`src/har.ts`) is a shape check, not a schema
+ * validator — it confirms `log.entries` is an array and casts the rest of the parsed
+ * JSON to `Har` unchecked, so `_order`, `response.status` and `content.size` are
+ * whatever the file says they are. Design spec §7 requires this UI to list and open
+ * recordings Polly itself would reject, so a hand-edited or foreign HAR is an expected
+ * input, not an edge case. Reasoning per-field about which numbers are "safe" is what
+ * produced the gap this closes — a value with the shape `'0" onmouseover=alert(1) x="'`
+ * sails straight through a template literal typed as `number`. Stringifying and escaping
+ * uniformly, at every site that interpolates one of these fields, closes it without
+ * having to trust the type checker over the file.
+ */
+function renderNumeric(value) {
+    return escapeHtml(String(value));
+}
+export function renderRecordingList(recordings) {
+    if (recordings.length === 0) {
+        return '<p class="empty">No recordings here yet. Run your app in Polly\'s record mode first.</p>';
+    }
+    const rows = recordings
+        .map((recording) => {
+        // The note sits outside the button: it describes the recording rather than offering
+        // an action, and a warning nested inside a control reads as part of the label.
+        const note = recording.problem
+            ? `<p class="ps-rec-note problem">${escapeHtml(recording.problem)}</p>`
+            : recording.pollyWillReject
+                ? `<p class="ps-rec-note warn">Polly will reject this: ${escapeHtml(recording.pollyWillReject)}</p>`
+                : '';
+        // The count moved inside the button so the row is one target with the id and its
+        // size on one line. `app.ts` finds the button with `closest('button')` and reads
+        // `dataset.id` off it, so nesting spans inside changes nothing for the click.
+        return (`<li><button class="recording" data-id="${escapeHtml(recording.id)}">` +
+            `<span class="ps-rec-name">${escapeHtml(recording.id)}</span>` +
+            `<span class="count">${renderNumeric(recording.entryCount)}</span></button>${note}</li>`);
+    })
+        .join('');
+    return `<ul class="recordings">${rows}</ul>`;
+}
+/**
+ * The other half of the same problem `escapeHtml`'s `String(value)` closes, and the half
+ * stringifying a leaf cannot reach. `isHarShaped` checks only that `log.entries` is an
+ * array — so `entries: [{}]` is a shape-valid HAR whose entries have no `request` and no
+ * `response` at all, and `entry.request.method` or `response.headers.map(...)` dies on a
+ * property access before any value reaches `escapeHtml`.
+ *
+ * Spec §7 wants such a recording listed and opened rather than hidden, so each entry is
+ * rendered inside its own boundary: an unreadable entry becomes a row or panel saying so,
+ * the readable entries beside it still render, and nothing escapes to the caller. The
+ * alternative — validating every field in `parseHar` — is a far larger change and would
+ * turn "shows you what is wrong with your file" back into "refuses to open it".
+ *
+ * The message is escaped like any other interpolated value: it can quote data from the
+ * file that produced it.
+ */
+function unrenderable(err) {
+    return escapeHtml(err instanceof Error ? err.message : String(err));
+}
+export function renderEntryRow(entry) {
+    try {
+        // _order is the only thing distinguishing two entries with the same _id, so it is
+        // shown rather than hidden — a list with two identical-looking rows is unusable.
+        const order = entry._order > 0 ? ` <span class="order">#${renderNumeric(entry._order)}</span>` : '';
+        return (`<li><button class="entry" data-id="${escapeHtml(entry._id)}" data-order="${renderNumeric(entry._order)}">` +
+            `<span class="method">${escapeHtml(entry.request.method)}</span> ` +
+            `<span class="status s${Math.floor(entry.response.status / 100)}">${renderNumeric(entry.response.status)}</span> ` +
+            `<span class="url">${escapeHtml(entry.request.url)}</span>${order}</button></li>`);
+    }
+    catch (err) {
+        // The catch wraps the whole entry body, so it swallows a genuine bug in this file
+        // just as readily as a malformed recording. The message reaches the page, but a
+        // stack does not — log it, or a defect on an uncommon path leaves no trace anywhere.
+        console.error('polly-studio: could not render entry row', err);
+        return `<li class="problem">this entry could not be rendered: ${unrenderable(err)}</li>`;
+    }
+}
+export function renderEntryDetail(entry) {
+    try {
+        return entryDetail(entry);
+    }
+    catch (err) {
+        // Logged for the same reason as the row guard above: the message reaches the page,
+        // the stack would otherwise reach nothing.
+        console.error('polly-studio: could not render entry detail', err);
+        // Deliberately not `class="detail"`: `app.ts`'s click handler finds the entry a Save
+        // or Delete button belongs to with `closest('.detail')` and reads `_id`/`_order` off
+        // its dataset. This panel has neither button and no trustworthy id, so it must not
+        // look like one to that handler.
+        return `<section class="problem"><p>this entry could not be rendered: ${unrenderable(err)}</p></section>`;
+    }
+}
+function entryDetail(entry) {
+    const response = entry.response;
+    const decoded = decodeContent(response.content);
+    // Deliberately not a `readonly` textarea for the binary case, however much tidier two
+    // identical-looking fields would be: `readPatch` (`src/ui/app.ts`) reads `bodyText`
+    // by name and cannot tell a disabled field from an edited one, so the only safe way to
+    // say "this body is not editable" is for the field not to exist.
+    const body = decoded.kind === 'binary'
+        ? `<p class="ps-notice warn">This body is binary (${escapeHtml(getHeader(response.headers, 'content-type') ?? 'unknown type')}, ${renderNumeric(response.content.size)} bytes). Editing it as text would replace the recorded bytes with a UTF-8 rendering of them, so it is shown read-only.</p>`
+        : `<textarea name="bodyText" rows="16" spellcheck="false" aria-label="Response body">${escapeHtml(decoded.text)}</textarea>`;
+    // `name` immediately followed by `value`, with one space and nothing between: the
+    // fixed attribute order the DOM-free test harness in `test/http-store.test.ts` reads
+    // a field's current value back with. Anything else goes after `value`.
+    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>
+</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 @@
-import { pollyUi } from '@avivbenhamo/polly-studio';
+/**
+ * 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,21 +1,44 @@
 {
   "name": "@avivbenhamo/polly-kit",
-  "version": "0.1.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",
+  "//engines": "The README states this; without the field npm never enforces it. >=22.6 is what the undici adapter's handler protocol and the studio's server both assume.",
+  "engines": {
+    "node": ">=22.6"
+  },
   "files": [
     "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'.",
   "typesVersions": {
     "*": {
-      "vite": ["./dist/vite.d.ts"],
-      "store": ["./dist/store.d.ts"],
-      "global-shim": ["./dist/global-shim.d.ts"]
+      "vite": [
+        "./dist/vite.d.ts"
+      ],
+      "store": [
+        "./dist/store.d.ts"
+      ],
+      "global-shim": [
+        "./dist/global-shim.d.ts"
+      ],
+      "node": [
+        "./dist/node.d.ts"
+      ],
+      "studio": [
+        "./dist/studio/index.d.ts"
+      ],
+      "studio/browser": [
+        "./dist/studio/browser.d.ts"
+      ]
     }
   },
   "exports": {
@@ -34,21 +57,43 @@
     "./global-shim": {
       "types": "./dist/global-shim.d.ts",
       "default": "./dist/global-shim.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./studio": {
+      "types": "./dist/studio/index.d.ts",
+      "default": "./dist/studio/index.js"
+    },
+    "./studio/browser": {
+      "types": "./dist/studio/browser.d.ts",
+      "default": "./dist/studio/browser.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "//scripts": "dist/ is gitignored, so `prepack` builds it — npm runs prepack before both `npm pack` and `npm publish`. Deliberately not `prepare`: that would also fire in a consumer's tree, where there is no src/ or tsconfig to compile.",
+  "//test": "Against dist/, not src/: src imports with `.js` specifiers that Node cannot resolve to the `.ts` files on disk. The build is also what gets published, so every test exercises the artifact.",
   "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "prepack": "tsc -p tsconfig.json"
+    "build": "tsc -p tsconfig.json && npm run bundle",
+    "prepack": "tsc -p tsconfig.json && npm run bundle",
+    "//bundle": "From dist/, not src/: the client imports `./app.js`, which exists only once tsc has emitted it. server.ts resolves the bundle as `new URL('./client.bundle.js', import.meta.url)` relative to the compiled dist/studio/server.js, so this outfile is the path it looks for.",
+    "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\"",
+    "studio": "node --experimental-strip-types --disable-warning=ExperimentalWarning src/cli.ts studio"
   },
   "dependencies": {
-    "@avivbenhamo/polly-studio": "^0.1.0",
+    "@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",
     "@pollyjs/node-server": "^6.0.6",
+    "@pollyjs/persister-fs": "^6.0.6",
     "@pollyjs/persister-rest": "^6.0.6",
     "buffer": "^6.0.3"
   },
@@ -62,6 +107,9 @@
   },
   "//devDependencies": "vite is here only so `./vite` typechecks standalone; it stays an optional peer at runtime.",
   "devDependencies": {
+    "@types/node": "^22.20.4",
+    "axios": "^1.20.0",
+    "esbuild": "^0.24.2",
     "typescript": "^5.3.3",
     "vite": "^5.0.0"
   }