docs(smoke): document the throwaway-catalog invariant and fix the label JSDoc

Addresses the two review comments that still applied to HEAD (the third, the
stop() race, was already fixed in a8022138).

- AGENTS.md still described the prod-web-server helper as shared by only
  smoke:web and smoke:web:browser, and said nothing about catalog isolation.
  It is the source of truth for these smoke mechanics, so record the invariant
  there: the temp catalog per run and why, that only the catalog (not HOME) is
  redirected, that teardown needs both halves of child-cleanup.mjs and is
  therefore async for every caller, and where the contract is unit-tested.

- The `label` JSDoc claimed the option prefixes the temp dir. It does not —
  that prefix is fixed at `smoke-web-catalog-` (deliberately, so every run's
  dir is greppable); `label` only prefixes teardown warnings.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HDdo1rNRVQnVRRdsqSrvG3
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-08-11 14:32:20 -04:00
commit 4a993fc45a

View file

@ -103,7 +103,8 @@ export function buildWebServerEnv({
* @param {string} opts.host
* @param {string} opts.port
* @param {string} opts.token value injected as MCP_INSPECTOR_API_TOKEN
* @param {string} [opts.label] prefix for the temp dir + cleanup warnings
* @param {string} [opts.label] prefix for teardown warnings (the temp dir's own
* prefix is fixed, so every run's dir is greppable as `smoke-web-catalog-*`)
*/
export function startProdWebServer({ host, port, token, label = "smoke:web" }) {
const baseUrl = `http://${host}:${port}`;