Skip to content

Commit b97b407

Browse files
cliffhallclaude
andcommitted
ci: reframe browser smoke around uncaught pageerror; fix stop() edge
Third-review findings. 1. The `Module "…" has been externalized` string can't fire against a Vite 8 *prod* bundle — verified end-to-end against the installed [email protected]: a node: import reaching the browser graph is a BUILD-time warning, and the shipped stub is a silent `module.exports = {}`. The real #1612 manifestation is the first *call* into that empty stub throwing a TypeError at module init (confirmed: injecting a used `node:fs` import fails the smoke with "readFileSync is not a function"; an unused one ships {} and is harmless). So the signature machinery was dead against the bundle it runs on — dropped it. The smoke now asserts exactly what it verifies: the prod bundle boots and paints with no uncaught page error. Reworded the script header, the AGENTS.md bullet, and the README row to match. Console errors stay diagnostic-only. 2. The helper's child 'error' handler set `exited = true`, but Node emits 'error' for a failed kill/send too (child still alive) — so `stop()` (guarded on `exited`) would skip the SIGTERM and orphan the launcher on the port. Track the error separately (`childError`); `bootFailed()` = exited || childError, while `stop()` still SIGTERMs a live child. Docs: fixed the stale AGENTS.md claim that `cd clients/web` makes `import("playwright")` resolve (createRequire does, cwd-independently; the cd is only for `npx playwright install`), and noted the shared scripts/lib/prod-web-server.mjs helper on both smoke bullets. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5
1 parent 45e828e commit b97b407

4 files changed

Lines changed: 53 additions & 66 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -218,8 +218,8 @@ gh project item-edit --project-id PVT_kwDOCt2Azc4BJVxt --id "$ITEM_ID" --field-i
218218
- **`npm run coverage`** is the per-file ≥90 gate and is now part of `npm run ci` — never treat it as optional before a push. It supersedes the old standalone `test:integration` step: web's `test:coverage` runs the `unit` **and** `integration` projects under v8 instrumentation, so `coverage` both enforces the ≥90 gate and exercises the same web integration paths CI covers.
219219
- **`smoke` is NOT part of `validate`** — it is included in `npm run ci`. It runs `smoke:launcher` (`--help` dispatch) plus the prod `smoke:cli` / `smoke:tui` / `smoke:web` / `smoke:web:browser`, and contains **no build commands** — it assumes the cli/tui/launcher bundles already exist (a full `validate` builds them; `smoke:web` builds `clients/web/dist` on demand). CI runs `validate`, then the `coverage` gate (which also covers the web integration project), then `smoke` (with Playwright chromium installed just before it, since `smoke:web:browser` needs it). Storybook is the only CI step left out (see below).
220220
- `smoke:launcher` (`scripts/smoke-launcher.mjs`) runs the built launcher with `--help`, `--cli --help`, and `--tui --help`, asserting each exits 0 and prints that mode's usage banner (which also proves the launcher resolved and loaded the right client build). It's the cheap dispatch check before the heavier prod smokes below.
221-
- `smoke:web` (`scripts/smoke-web.mjs`) starts `mcp-inspector --web` (prod, no `--dev`) against the built `clients/web/dist` and asserts `GET /` serves the SPA (HTTP 200) with the injected `__INSPECTOR_API_TOKEN__`. Prod `--web` serves from `clients/web/dist`, which ships in the published package but is absent in a fresh checkout — the runner builds it on demand (`build:client` = `vite build`) on first launch, or exits with an actionable error if that build can't run (see `clients/web/server/ensure-web-build.ts` and the launcher README). `--dev` runs Vite directly and never needs `dist`.
222-
- `smoke:web:browser` (`scripts/smoke-web-browser.mjs`, #1615) goes a step further than `smoke:web`: it boots the same prod `--web` server and then actually **runs** the bundle in headless Chromium (Playwright — already a `clients/web` devDependency for the Storybook tests), asserting the app renders its first meaningful frame (the "Add Servers" control) with **no uncaught page errors** — in particular no `Module "node:*" has been externalized for browser compatibility`. `smoke:web` only checks the served HTML, so a Node built-in reaching the browser bundle (which crashes the app to a blank page at runtime, e.g. #1612) slipped through it; this smoke catches that regression as a *class*. The npm script runs `cd clients/web && npx playwright install chromium` first so `import("playwright")` resolves and chromium is present (a no-op when already installed); repo-root paths inside the script come from `import.meta.url`, so the cwd change doesn't affect which build tree is exercised.
221+
- `smoke:web` (`scripts/smoke-web.mjs`) starts `mcp-inspector --web` (prod, no `--dev`) against the built `clients/web/dist` and asserts `GET /` serves the SPA (HTTP 200) with the injected `__INSPECTOR_API_TOKEN__`. Prod `--web` serves from `clients/web/dist`, which ships in the published package but is absent in a fresh checkout — the runner builds it on demand (`build:client` = `vite build`) on first launch, or exits with an actionable error if that build can't run (see `clients/web/server/ensure-web-build.ts` and the launcher README). `--dev` runs Vite directly and never needs `dist`. It shares the spawn/readiness/teardown helper (`scripts/lib/prod-web-server.mjs`) with `smoke:web:browser`, so the two can't drift.
222+
- `smoke:web:browser` (`scripts/smoke-web-browser.mjs`, #1615) goes a step further than `smoke:web`: it boots the same prod `--web` server and then actually **runs** the bundle in headless Chromium (Playwright — already a `clients/web` devDependency for the Storybook tests), asserting the app renders its first meaningful frame (the "Add Servers" control) with **no uncaught page error**. `smoke:web` only checks the served HTML, so a Node built-in reaching the browser bundle slipped through it; this smoke catches that regression as a *class* (e.g. #1612). The mechanism is the uncaught error, not a magic string: under Vite the excluded module becomes an empty stub and the first *call* into it (e.g. `fs.readFileSync(...)` during a transitive module's init) throws a `TypeError` that aborts app mount — a `pageerror` the smoke fails on. The literal `Module "…" has been externalized` text is a **build-time** warning (`vite build` / `npm run build`), not a runtime message, so the browser never sees it; and an externalized import that is never *called* ships a harmless `{}` and is invisible here by design. Console errors are printed as diagnostics, not failures (so a benign font-CDN or React-warning `console.error` doesn't flake CI). Playwright is resolved via `createRequire` based at `clients/web/package.json` — a bare `import("playwright")` would resolve relative to `scripts/`, not the cwd, so it can't be reached that way (it only appears to work when an ancestor `node_modules` carries playwright, and fails in CI, which has none). The npm script's `cd clients/web` exists only so `npx playwright install chromium` finds the local playwright bin (a no-op when already installed).
223223
- `smoke:cli` (`scripts/smoke-cli.mjs`) drives `mcp-inspector --cli` through the built launcher against the bundled stdio test server via a temp `--catalog`: it asserts `tools/list` returns the server's tools (real connect over stdio), the default writable catalog is seeded empty on first run, a missing read-only `--config` errors without seeding, and `--catalog` + `--config` is rejected. `smoke:tui` (`scripts/smoke-tui.mjs`) launches `mcp-inspector --tui --catalog <temp>` and asserts the Ink app renders its first frame (the "MCP Servers" panel) within a timeout, then SIGTERMs it — a shallow boot/render check, not full interaction. **`smoke:tui` is local-only: it self-skips when `process.env.CI` is set**, because the Ink TUI needs a real TTY (raw mode) that headless CI lacks — so run it (via `npm run smoke`) on your own machine before pushing. Both build `test-servers/build` on demand if it's missing.
224224
- Storybook play-function tests (`clients/web` `test:storybook`) run in headless Chromium via `@vitest/browser-playwright` (~10s). They are part of `npm run ci` (which installs Playwright chromium first); kept out of `validate` because they need the browser binary and are slower than the unit suite.
225225

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ Each client self-validates from its own folder; the root scripts chain them. The
142142
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
143143
| `npm run validate` | Runs `validate:core` (the shared `core/` `format:check` + `lint` gate) first, then per client: `format:check` + `lint` + **`typecheck`** (cli/tui only) + `build` + fast unit tests. The quick inner-loop check. |
144144
| `npm run coverage` | The **per-file ≥90% gate** (lines/statements/functions/branches) under v8 instrumentation, per client. CI-enforced. For web this also runs the integration project and covers the shared `core/` runtime (including `core/json` and `core/client`). |
145-
| `npm run smoke` | End-to-end smokes through the built launcher (`--help` dispatch + prod cli/tui/web), plus a headless-Chromium boot smoke that runs the prod web bundle and asserts a clean first render (no `node:*` in the browser bundle). |
145+
| `npm run smoke` | End-to-end smokes through the built launcher (`--help` dispatch + prod cli/tui/web), plus a headless-Chromium boot smoke that runs the prod web bundle and asserts a clean first render (no uncaught page error — how a Node built-in reaching the browser bundle manifests). |
146146
| `npm run ci` | **Mandatory pre-push command.** `validate` → `coverage` → `smoke` → Storybook. A true superset of GitHub CI. |
147147
| `npm run pack:verify` | Publish smoke — see [Publishing](#publishing). |
148148

‎scripts/lib/prod-web-server.mjs‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -46,23 +46,28 @@ export function startProdWebServer({ host, port, token }) {
4646

4747
let exited = false;
4848
let exitCode = null;
49-
let spawnError = null;
49+
let childError = null;
5050
child.on("exit", (code) => {
5151
exited = true;
5252
exitCode = code;
5353
});
54-
// A spawn-level failure (e.g. a missing launcher entry) emits 'error', not
55-
// 'exit'; without a listener Node throws it uncaught with a raw stack instead
56-
// of the smoke's `… FAILED —` line. Capture it so readiness surfaces it.
54+
// A child 'error' event covers a spawn failure (e.g. a missing launcher
55+
// entry) but ALSO a failed kill / failed send where the process is still
56+
// alive. Without a listener Node throws it uncaught with a raw stack instead
57+
// of the smoke's `… FAILED —` line. Record it, but deliberately do NOT set
58+
// `exited` — otherwise `stop()` (which guards on `exited`) would skip the
59+
// SIGTERM and orphan a still-running launcher on the port.
5760
child.on("error", (err) => {
58-
exited = true;
59-
spawnError = err;
61+
childError = err;
6062
});
6163

64+
// Boot has failed if the process exited or emitted an error.
65+
const bootFailed = () => exited || childError !== null;
66+
6267
function bootFailure(phase) {
6368
return new Error(
64-
spawnError
65-
? `launcher failed to spawn: ${spawnError.message}`
69+
childError
70+
? `launcher process error: ${childError.message}`
6671
: `launcher exited (code ${exitCode}) ${phase} — see output above`,
6772
);
6873
}
@@ -78,7 +83,7 @@ export function startProdWebServer({ host, port, token }) {
7883
async function waitForReady({ attempts = 120, intervalMs = 500 } = {}) {
7984
let lastStatus = null;
8085
for (let attempt = 0; attempt < attempts; attempt++) {
81-
if (exited) throw bootFailure("before serving");
86+
if (bootFailed()) throw bootFailure("before serving");
8287
try {
8388
const res = await fetch(`${baseUrl}/`);
8489
if (res.ok) return res;
@@ -104,7 +109,7 @@ export function startProdWebServer({ host, port, token }) {
104109
function whenChildExits() {
105110
return new Promise((_resolve, reject) => {
106111
const onDeath = () => reject(bootFailure("mid-run"));
107-
if (exited) onDeath();
112+
if (bootFailed()) onDeath();
108113
else {
109114
child.once("exit", onDeath);
110115
child.once("error", onDeath);

‎scripts/smoke-web-browser.mjs‎

Lines changed: 35 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -6,35 +6,38 @@
66
* HTML with the injected auth token — it never executes the React app, so a
77
* regression that only manifests when the bundle *runs* slips through. The
88
* canonical example (#1612): the browser bundle transitively value-imported a
9-
* Node-only module, pulling `node:*` built-ins into the browser build and
10-
* crashing the app to a blank page with
11-
* `Module "node:*" has been externalized for browser compatibility`.
12-
* Unit/integration tests run in node / happy-dom, never a real browser bundle,
13-
* so none of them caught it.
9+
* Node-only module (`store-io` → `atomically` → `stubborn-fs` → `node:process`),
10+
* pulling a Node built-in into the browser graph and crashing the app to a blank
11+
* page at runtime. Unit/integration tests run in node / happy-dom, never a real
12+
* browser bundle, so none of them caught it.
1413
*
15-
* This script closes that gap as a *class* of bug rather than one import at a
16-
* time: it launches `mcp-inspector --web` (prod, no `--dev`) against the built
17-
* `clients/web/dist`, opens the served page in headless Chromium (Playwright,
18-
* already a clients/web devDependency for the Storybook tests), and asserts the
19-
* app renders its first meaningful frame (the "Add Servers" control).
14+
* The assertion: the prod bundle **boots and paints its first meaningful frame
15+
* (the "Add Servers" control) with no uncaught page error.** That is how a
16+
* Node-only module reaching the browser bundle actually manifests under Vite:
17+
* the excluded module is replaced by an empty stub, and the first call into it
18+
* (e.g. `fs.readFileSync(...)` during a transitive module's init) throws a
19+
* `TypeError` that aborts app mount — an uncaught `pageerror` here.
2020
*
21-
* Failure signal: an **uncaught `pageerror`** — that's how the #1612 class
22-
* arrives (Vite's `__vite-browser-external` proxy *throws* on property access).
23-
* A `console.error` is NOT treated as a hard failure by itself, because the
24-
* console is also where Chromium reports benign things a boot smoke shouldn't
25-
* fail on: a failed subresource load (e.g. the Google-Fonts `<link>` in
26-
* index.html on a network-restricted box) or a React key/prop warning. Console
27-
* errors are collected and printed as diagnostics, and only fail the run when
28-
* they carry the externalized-module signature.
21+
* What this does NOT rely on: the literal `Module "…" has been externalized`
22+
* string. Under Vite 8 that is a **build-time** warning (surfaced by
23+
* `vite build`, i.e. `npm run build`), not a runtime message — the shipped stub
24+
* is a silent `module.exports = {}`. So the browser never sees that string; the
25+
* load-bearing signal is the uncaught `TypeError`. (Corollary: an externalized
26+
* import that is never *called* ships a harmless empty object and is invisible
27+
* to this smoke by design — an unused Node import doesn't crash the app.)
28+
*
29+
* `console.error` is NOT a hard failure: the console is where Chromium also
30+
* reports benign things a boot smoke shouldn't fail on — a failed subresource
31+
* load (e.g. the Google-Fonts `<link>` in index.html on a network-restricted
32+
* box) or a React key/prop warning. Console errors are printed as diagnostics.
2933
*
3034
* Playwright lives in clients/web's node_modules, so it's resolved with a
3135
* `createRequire` based at clients/web/package.json rather than a bare
3236
* `import("playwright")`. A bare ESM specifier resolves relative to *this
3337
* script's* directory (scripts/), not the cwd — so `cd clients/web` in the npm
34-
* script would NOT make it resolvable, and it only appeared to work locally
35-
* when an ancestor node_modules happened to carry playwright (it fails in CI,
36-
* which has none). createRequire pins resolution to clients/web regardless of
37-
* cwd or ancestor dirs.
38+
* script would NOT make it resolvable (it only appeared to work locally when an
39+
* ancestor node_modules happened to carry playwright; it fails in CI, which has
40+
* none). createRequire pins resolution to clients/web regardless of cwd.
3841
*
3942
* Expects `clients/web/dist` and `clients/launcher/build` to be built first —
4043
* the validate / CI ordering guarantees this.
@@ -58,17 +61,6 @@ const HOST = "127.0.0.1";
5861
const PORT = process.env.SMOKE_WEB_BROWSER_PORT ?? "6298";
5962
const TOKEN = "smoke-web-browser-token";
6063

61-
// Vite emits `Module "${id}" has been externalized for browser compatibility…`
62-
// where `id` is whatever was imported — `node:fs` OR a bare `fs` (both common
63-
// in transitive deps). Match either so the diagnostic label always attaches.
64-
const EXTERNALIZED = /Module "[^"]+" has been externalized/;
65-
66-
function labelExternalized(message) {
67-
return EXTERNALIZED.test(message)
68-
? `Node built-in reached the browser bundle: ${message}`
69-
: message;
70-
}
71-
7264
const server = startProdWebServer({ host: HOST, port: PORT, token: TOKEN });
7365
let browser = null;
7466

@@ -113,10 +105,11 @@ try {
113105
browser = await loadChromium();
114106
const page = await browser.newPage();
115107

116-
// Uncaught page errors are the hard failure (the #1612 signature lands here).
108+
// Uncaught page errors are the hard failure — a Node-only module reaching the
109+
// browser bundle surfaces here as a TypeError when its empty stub is called.
117110
const pageErrors = [];
118-
// Console errors are diagnostic unless they carry the externalization
119-
// signature (see the header comment for why they're not a blanket failure).
111+
// Console errors are diagnostic only (see the header comment for why they're
112+
// not a blanket failure).
120113
const consoleErrors = [];
121114
page.on("pageerror", (err) =>
122115
pageErrors.push(err instanceof Error ? err.message : String(err)),
@@ -156,8 +149,8 @@ try {
156149
await Promise.race([server.whenChildExits(), render()]);
157150
} catch (err) {
158151
const diagnostics = [
159-
...pageErrors.map(labelExternalized),
160-
...consoleErrors.map((m) => `console: ${labelExternalized(m)}`),
152+
...pageErrors,
153+
...consoleErrors.map((m) => `console: ${m}`),
161154
];
162155
await fail(
163156
`${err instanceof Error ? err.message : String(err)}${
@@ -168,26 +161,15 @@ try {
168161
);
169162
}
170163

171-
// Hard failures: any uncaught page error, plus console errors that carry the
172-
// externalization signature.
173-
const hardErrors = [
174-
...pageErrors.map(labelExternalized),
175-
...consoleErrors
176-
.filter((m) => EXTERNALIZED.test(m))
177-
.map((m) => `console: ${labelExternalized(m)}`),
178-
];
179-
if (hardErrors.length > 0) {
180-
await fail(
181-
`app logged uncaught / externalization errors: ${hardErrors.join("; ")}`,
182-
);
164+
if (pageErrors.length > 0) {
165+
await fail(`app logged uncaught page error(s): ${pageErrors.join("; ")}`);
183166
}
184167

185168
// Non-fatal console errors: surface them so a real problem isn't invisible,
186169
// without failing the smoke on benign subresource/warning noise.
187-
const benignConsole = consoleErrors.filter((m) => !EXTERNALIZED.test(m));
188-
if (benignConsole.length > 0) {
170+
if (consoleErrors.length > 0) {
189171
console.log(
190-
`smoke:web:browser note — ${benignConsole.length} non-fatal console error(s): ${benignConsole.join("; ")}`,
172+
`smoke:web:browser note — ${consoleErrors.length} non-fatal console error(s): ${consoleErrors.join("; ")}`,
191173
);
192174
}
193175

0 commit comments

Comments
 (0)