@avivbenhamo/polly-kit 0.1.0 → 0.3.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.js

@@ -1,4 +1,4 @@
-import { pollyUi } from '@avivbenhamo/polly-studio';
+import { pollyUi } from './studio/index.js';
 import { recordingStore, STORE_NAMESPACE } from './store.js';
 const STUDIO_PATH = '/__polly';
 export default function pollyKit(options = {}) {

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "@avivbenhamo/polly-kit",
-  "version": "0.1.0",
+  "version": "0.3.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"
@@ -13,9 +17,24 @@
   "//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 +53,41 @@
     "./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\""
   },
   "dependencies": {
-    "@avivbenhamo/polly-studio": "^0.1.0",
+    "@pollyjs/adapter": "^6.0.6",
+    "@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 +101,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"
   }