diff --git a/AGENTS.md b/AGENTS.md index 25c4795b..48fc5f61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1003,7 +1003,7 @@ Everything about the selection lives in **`scripts/lib/headless-browser.mjs`** - **An unrecognized `SMOKE_BROWSER` is an error, never a fallback.** Falling back to Chromium would report a green Chromium run under a job labelled `webkit` — coverage claimed but not run, which is worse than none. - **A launch failure names the engine that failed** and a remedy that works **from where the caller actually is**: `npm run smoke:web:`, or `npx playwright install --with-deps ` run *from `clients/web`*. Naming `chromium` while WebKit was missing would send the reader to install a browser they already have — and naming a bare root-level `npx playwright` would send them to a version that is not the pinned one, which can install a browser revision the pinned Playwright still cannot launch. - **Firefox is gated locally, not in CI, and that asymmetry is deliberate.** A GitHub Actions job was trialled and removed. It was cheap — ~2 minutes, parallel with the 15-minute `build` job, so zero added wall-clock — but across a dozen runs Firefox never once disagreed with Chromium, so it spent runner minutes on every push, from every branch, carrying a real flake surface (`playwright install --with-deps` runs `apt-get update`, which fails whenever a third-party repo in the runner image breaks) to re-confirm a result already in hand. Moving it into `npm run local:gate` keeps the check where a human is about to push a change they can still reason about, and pays for it once rather than on every push. **Don't re-add the CI job on the argument that cross-engine coverage is good in principle** — that argument was accepted, and the pre-push gate is what serves it. Re-add it on evidence: a cross-engine regression that reached `v2/main` because someone skipped the gate. -- **A guard enforces the split, so it cannot be undone by accident (#2146).** `scripts/lib/workflow-gate.mjs` is run by `npm run test:scripts` over every file under `.github/workflows/`, and fails the suite on: an invocation of a `local:*` script (the prefix *means* local-only, so a future sibling is covered without editing the guard); an invocation of a non-Chromium engine pass, derived from `SUPPORTED_BROWSERS` so a fourth engine extends the guard rather than opening a hole in it; an invocation of `smoke:web:engine`, whose engine comes from the environment and so cannot be read off the workflow at all; or `SMOKE_BROWSER` set to anything but a literal `chromium` — the back door that would redirect an otherwise innocent `npm run smoke`, and one that includes setting it to *nothing*, since present-and-empty is rejected rather than defaulted, and `container.env` as much as a job's own `env`. That rule is kind-aware — an `env:` key, or an assignment in a `run:` — so a script printing the variable's name is not read as setting it; and the `run:` half covers POSIX, cmd, the `>> $GITHUB_ENV` append and PowerShell (the default shell on a Windows runner), not just `NAME=value`. A name built from a workflow **expression** counts as forbidden too (`smoke:web:${{ matrix.browser }}`, `local:${{ matrix.task }}`): a matrix the guard cannot read may well contain `firefox`, so an unreadable name is not waved through. Its limit is worth knowing — a fully opaque `npm run ${{ matrix.script }}` names no family at all and is not detectable. It deliberately does **not** forbid `npm run smoke`, `smoke:web:chromium`, or `smoke:tui`: those belong in CI and are there today, and `smoke:tui` self-skips under `process.env.CI` on its own. It **parses** the workflow (via the root-declared `yaml` package) and descends the schema's executable paths — workflow `env`, job `env`/`container.env`/`with`, step `run`/`env`/`with`, with YAML aliases resolved — rather than matching pairs by key name anywhere in the tree, which would scan a workflow input legitimately named `env` and fail the gate on documentation of the gate. So it reads only what executes — so ordinary metadata such as a step `name:` explaining the rule is not reported as an invocation of it (Copilot); comments are skipped for the same reason, and because a guard that made the workflow undocumentable would be traded for the wrong thing. That scoping is a stated limit rather than a hidden one: an execution vector outside those three positions is not seen. +- **A guard enforces the split, so it cannot be undone by accident (#2146).** `scripts/lib/workflow-gate.mjs` is run by `npm run test:scripts` over every file under `.github/workflows/`, and fails the suite on: an invocation of a `local:*` script (the prefix *means* local-only, so a future sibling is covered without editing the guard); an invocation of a non-Chromium engine pass, derived from `SUPPORTED_BROWSERS` so a fourth engine extends the guard rather than opening a hole in it; an invocation of `smoke:web:engine`, whose engine comes from the environment and so cannot be read off the workflow at all; or `SMOKE_BROWSER` set to anything but a literal `chromium` — the back door that would redirect an otherwise innocent `npm run smoke`, and one that includes setting it to *nothing*, since present-and-empty is rejected rather than defaulted, and `container.env` as much as a job's own `env`. That rule is kind-aware — an `env:` key (matched case-insensitively, since Windows environment variables are), or an assignment in a `run:` — so a script printing the variable's name is not read as setting it; and the `run:` half covers POSIX, cmd, the `>> $GITHUB_ENV` append and PowerShell (the default shell on a Windows runner), not just `NAME=value`. A name the guard cannot **read** counts as forbidden too — a workflow expression (`smoke:web:${{ matrix.browser }}`) or a shell variable the script expands itself (`smoke:web:$ENGINE`, `%ENGINE%`, `local:$TASK`): a matrix the guard cannot read may well contain `firefox`, so an unreadable name is not waved through. Its limit is worth knowing — a fully opaque `npm run ${{ matrix.script }}` names no family at all and is not detectable. It deliberately does **not** forbid `npm run smoke`, `smoke:web:chromium`, or `smoke:tui`: those belong in CI and are there today, and `smoke:tui` self-skips under `process.env.CI` on its own. It **parses** the workflow (via the root-declared `yaml` package) and descends the schema's executable paths — workflow `env`, job `env`/`container.env`/`with`, step `run`/`env`/`with`, with YAML aliases resolved — rather than matching pairs by key name anywhere in the tree, which would scan a workflow input legitimately named `env` and fail the gate on documentation of the gate. So it reads only what executes — so ordinary metadata such as a step `name:` explaining the rule is not reported as an invocation of it (Copilot); comments are skipped for the same reason, and because a guard that made the workflow undocumentable would be traded for the wrong thing. That scoping is a stated limit rather than a hidden one: an execution vector outside those three positions is not seen. - **This makes `npm run local:gate` a strict superset of GitHub CI rather than a mirror of it.** That was already the direction (`smoke:tui` self-skips on CI and runs only locally); Firefox is the second such step. The invariant that still holds, and the one that matters, is the useful direction: **passing `npm run local:gate` locally means CI's gates will pass.** - **`pack:verify` stays pinned to Chromium**, passing it explicitly rather than reading `SMOKE_BROWSER`. It is a _packaging_ check; the engine question belongs where the sandbox is under test, and pinning it also means it can't be pointed at an engine its npm script never installed. - **WebKit fails the two App smokes**, for reasons nobody has identified — the failure stage even varies between runs. The investigation was dropped as not worth the effort once it became clear it does not reproduce in real Safari, and that an isolated repro of the suspected mechanism did not reproduce it under Playwright's WebKit either. Treat a WebKit failure as unexplained rather than as a defect until someone has actually looked. diff --git a/README.md b/README.md index 034f63af..9b6cf1dd 100644 --- a/README.md +++ b/README.md @@ -502,7 +502,7 @@ So the direction that matters holds: **passing `npm run local:gate` means CI's g **The gate is deliberately not named `ci`** ([#2146](https://github.com/modelcontextprotocol/inspector/issues/2146)). That name collided with `npm ci` — a built-in that clean-installs from the lockfile, does **not** run this script, and is one keystroke away — and it invited the cross-engine passes into GitHub CI by looking like the thing a workflow ought to call. There is **no back-compat alias**: `npm run ci` now fails with npm's missing-script error, which prints the available scripts. -That is the readable half, and prose rots. The enforced half is `scripts/lib/workflow-gate.mjs`, run by `npm run test:scripts` over every file under `.github/workflows/`. It fails the suite if a workflow invokes a `local:*` script, a non-Chromium engine pass (`smoke:web:firefox`, `smoke:web:webkit`), or `smoke:web:engine` (whose engine comes from the environment and so cannot be read off the workflow at all), or sets `SMOKE_BROWSER` to anything but a literal `chromium` (including setting it to *nothing*, which is present-and-empty rather than unset, and is rejected rather than defaulted). That last rule respects **where** it is written — an `env:` entry whose key is literally `SMOKE_BROWSER`, or an assignment in a `run:` script (POSIX, cmd, a `>> $GITHUB_ENV` append, or PowerShell — the default shell on a Windows runner) — so a script that merely *prints* the variable's name is not read as setting it. It treats a name built from a workflow **expression** the same way — `smoke:web:${{ matrix.browser }}`, `local:${{ matrix.task }}` — since a matrix the guard cannot read may well contain `firefox`. It deliberately does **not** forbid `npm run smoke`, `smoke:web:chromium`, or `smoke:tui` — those belong in CI and are there today. It **parses** the workflow and descends the schema's executable paths — workflow `env`, job `env`/`container.env`/`with`, step `run`/`env`/`with`, with aliases resolved — rather than matching text or key names, so it reads only what actually executes — so a step *name* explaining the rule is not mistaken for an invocation of it, and the workflow can still document itself. +That is the readable half, and prose rots. The enforced half is `scripts/lib/workflow-gate.mjs`, run by `npm run test:scripts` over every file under `.github/workflows/`. It fails the suite if a workflow invokes a `local:*` script, a non-Chromium engine pass (`smoke:web:firefox`, `smoke:web:webkit`), or `smoke:web:engine` (whose engine comes from the environment and so cannot be read off the workflow at all), or sets `SMOKE_BROWSER` to anything but a literal `chromium` (including setting it to *nothing*, which is present-and-empty rather than unset, and is rejected rather than defaulted). That last rule respects **where** it is written — an `env:` entry whose key is `SMOKE_BROWSER` (case-insensitively, since Windows environment variables are), or an assignment in a `run:` script (POSIX, cmd, a `>> $GITHUB_ENV` append, or PowerShell — the default shell on a Windows runner) — so a script that merely *prints* the variable's name is not read as setting it. It treats any name it cannot **read** the same way — a workflow expression (`smoke:web:${{ matrix.browser }}`) or a shell variable the script expands itself (`smoke:web:$ENGINE`, `%ENGINE%`) — since a value the workflow can vary may well be `firefox`. It deliberately does **not** forbid `npm run smoke`, `smoke:web:chromium`, or `smoke:tui` — those belong in CI and are there today. It **parses** the workflow and descends the schema's executable paths — workflow `env`, job `env`/`container.env`/`with`, step `run`/`env`/`with`, with aliases resolved — rather than matching text or key names, so it reads only what actually executes — so a step *name* explaining the rule is not mistaken for an invocation of it, and the workflow can still document itself. | Script | What it does | | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/scripts/lib/workflow-gate.mjs b/scripts/lib/workflow-gate.mjs index adb2143e..66d18c0d 100644 --- a/scripts/lib/workflow-gate.mjs +++ b/scripts/lib/workflow-gate.mjs @@ -112,21 +112,27 @@ export const VIOLATION = { // (`local:${{ matrix.task }}`) — both are `local:` scripts, and neither may be // invoked from a workflow. // -// The expression arm keys off the `${{` PREFIX and then runs to the end of the -// line, rather than trying to find the matching `}}`. An expression body can -// itself contain braces — `${{ format('{0}', matrix.browser) }}` — so a -// `[^}]*\}\}` body stops at the first `}` and misses exactly the case worth -// catching (Copilot). Matching the prefix cannot be defeated by nesting, and -// since these are display strings the greedy tail costs nothing. -const EXPRESSION = String.raw`\$\{\{[^\n]*`; +// A name the guard cannot read: a GitHub expression (`${{ … }}`) or a shell +// variable the script expands itself — `$ENGINE`, `${ENGINE}`, `$env:ENGINE`, +// or cmd's `%ENGINE%` (Copilot). All of them resolve to *some* engine at run +// time, and the guard has no way to know which, so all of them are read as a +// forbidden one for the same reason `smoke:web:engine` is. +// +// It keys off the leading `$`/`%` and then runs to the end of the line, rather +// than trying to find a matching `}}`. An expression body can itself contain +// braces — `${{ format('{0}', matrix.browser) }}` — so a `[^}]*\}\}` body stops +// at the first `}` and misses exactly the case worth catching (Copilot). A +// prefix cannot be defeated by nesting, and since these are display strings the +// greedy tail costs nothing. +const UNREADABLE = String.raw`[$%][^\n]*`; const LOCAL_SCRIPT_RE = new RegExp( - String.raw`\blocal:(?:[a-z0-9][a-z0-9:-]*|${EXPRESSION})`, + String.raw`\blocal:(?:[a-z0-9][a-z0-9:-]*|${UNREADABLE})`, "gi", ); // Same reasoning one level down: `smoke:web:` followed by an expression could // resolve to any engine, so it is read as a forbidden one. const DYNAMIC_ENGINE_RE = new RegExp( - String.raw`\bsmoke:web:${EXPRESSION}`, + String.raw`\bsmoke:web:${UNREADABLE}`, "gi", ); /** @@ -147,7 +153,8 @@ const BROWSER_ASSIGNMENTS = [ // POSIX `SMOKE_BROWSER=firefox`. Also covers cmd's `set SMOKE_BROWSER=…` and // the GitHub-native `echo "SMOKE_BROWSER=…" >> $GITHUB_ENV`, since both carry // the same `NAME=value` substring. - { re: new RegExp(String.raw`\b${BROWSER_ENV_VAR}=(\S*)`, "g"), value: 1 }, + // Case-insensitive for the same Windows reason as the `env:` key above. + { re: new RegExp(String.raw`\b${BROWSER_ENV_VAR}=(\S*)`, "gi"), value: 1 }, // PowerShell `$env:SMOKE_BROWSER = "firefox"`, and its `${env:NAME}` form. { re: new RegExp( @@ -364,16 +371,24 @@ export function findWorkflowViolations(text, file = "") { rule: VIOLATION.ENGINE_SCRIPT, match: match[0], message: - `\`${match[0]}\` builds an engine-pass name from an expression, so the guard cannot ` + - `tell which engine it runs — and a matrix that a workflow can vary may well contain ` + - `\`firefox\`. Name \`smoke:web:${DEFAULT_BROWSER}\` outright, or just run \`npm run smoke\`.`, + `\`${match[0]}\` builds an engine-pass name from an expression or a shell variable, ` + + `so the guard cannot tell which engine it runs — and a value a workflow can vary may ` + + `well be \`firefox\`. Name \`smoke:web:${DEFAULT_BROWSER}\` outright, or just run ` + + `\`npm run smoke\`.`, }); } // The browser rule is the one that must respect WHICH position it is in. const overrides = kind === "env" - ? region.name === BROWSER_ENV_VAR + ? // Compared case-INSENSITIVELY: Windows environment variables are, so + // `smoke_browser: firefox` on a windows-latest job sets the very + // variable Node then reads as SMOKE_BROWSER (Copilot). On a POSIX + // runner that spelling would be a different variable and harmless, so + // this is stricter there than it strictly needs to be — the right + // direction for a guard, and the alternative is a rule whose verdict + // depends on a `runs-on` that may itself be an expression. + region.name.toUpperCase() === BROWSER_ENV_VAR.toUpperCase() ? [{ value: region.value, match: region.text.trim() }] : [] : kind === "run" diff --git a/scripts/lib/workflow-gate.test.mjs b/scripts/lib/workflow-gate.test.mjs index 0bb19025..6b1e655f 100644 --- a/scripts/lib/workflow-gate.test.mjs +++ b/scripts/lib/workflow-gate.test.mjs @@ -175,6 +175,44 @@ describe("findWorkflowViolations", () => { text: workflow(" - run: SMOKE_BROWSER= npm run smoke"), rules: [VIOLATION.BROWSER_ENV], }, + { + // Copilot, seventh review: a shell resolves the name itself, so the + // engine is just as unreadable as it is behind a `${{ }}` expression. + name: "flags an engine pass named through a shell variable", + text: workflow( + " - env:\n ENGINE: firefox\n run: npm run smoke:web:$ENGINE", + ), + rules: [VIOLATION.ENGINE_SCRIPT], + }, + { + name: "flags the braced and cmd spellings of that too", + text: workflow( + " - run: npm run smoke:web:${ENGINE}\n - run: npm run smoke:web:%ENGINE%", + ), + rules: [VIOLATION.ENGINE_SCRIPT, VIOLATION.ENGINE_SCRIPT], + }, + { + name: "flags a local: script named through a shell variable", + text: workflow(" - run: npm run local:$TASK"), + rules: [VIOLATION.LOCAL_SCRIPT], + }, + { + // Copilot, seventh review: Windows environment variables are + // case-insensitive, so this sets the very variable Node reads as + // SMOKE_BROWSER. + name: "flags a lower-cased env key, which Windows treats as the same var", + text: workflow( + " - env: { smoke_browser: firefox }\n run: npm run smoke", + ), + rules: [VIOLATION.BROWSER_ENV], + }, + { + name: "allows a lower-cased key set to chromium", + text: workflow( + " - env: { smoke_browser: chromium }\n run: npm run smoke", + ), + rules: [], + }, { // Copilot, sixth review: PowerShell is the DEFAULT shell on a Windows // runner, so a POSIX-only pattern is silent on exactly the workflow least