feat(web): build dist on demand for prod --web + end-to-end CI smoke (#1486) (#1497)

* feat(web): build dist on demand for prod --web + end-to-end CI smoke (#1486)

Prod `mcp-inspector --web` serves static assets from clients/web/dist,
which only exists after a build. In a fresh checkout it was absent and the
prod path served a broken page (ENOENT on index.html); the launcher smoke
test only covered --help, so this path was unverified in CI.

- ensure-web-build.ts: build dist on demand (vite build via build:client)
  when missing, or exit with an actionable error if the build can't run.
- run-web.ts: invoke ensureWebBuild before startHonoServer in the prod path
  (--dev runs Vite directly and skips it).
- scripts/smoke-web.mjs + smoke:web: start --web against built dist and
  assert GET / returns 200 with the injected __INSPECTOR_API_TOKEN__.
  Wired into validate:launcher and a new CI step.
- Docs: launcher README + AGENTS.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(web): surface spawn error in build-on-demand; clarify smoke comment

Address PR #1497 review:
- runViteBuild now logs result.error.message (e.g. ENOENT when npm isn't on
  PATH) before returning a null status, so the spawn-failure cause surfaces
  instead of only the generic actionable error. The build seam gains a `log`
  param; added a test covering the ENOENT path.
- Reword scripts/smoke-web.mjs header so it no longer implies the readiness
  wait covers a cold build-on-demand vite build (it's sized for a pre-built
  dist, which validate/CI guarantee).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

clients/web/server/run-web.ts

@@ -21,6 +21,7 @@ import {
 import { buildWebServerConfig } from "./web-server-config.js";
 import { startViteDevServer } from "./start-vite-dev-server.js";
 import { startHonoServer } from "./server.js";
+import { ensureWebBuild } from "./ensure-web-build.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -237,8 +238,10 @@ export async function runWeb(argv: string[]): Promise<number> {
     writable,
     initialServers,
   });
+  const webRoot = join(__dirname, "..");
+  const distRoot = join(webRoot, "dist");
   if (!isDev) {
-    webConfig.staticRoot = join(__dirname, "..", "dist");
+    webConfig.staticRoot = distRoot;
   }
 
   console.log(
@@ -253,6 +256,9 @@ export async function runWeb(argv: string[]): Promise<number> {
     if (isDev) {
       handle = await startViteDevServer(webConfig);
     } else {
+      // Build clients/web/dist on demand if it's missing so prod `--web` never
+      // serves a broken page (#1486); throws an actionable error if it can't.
+      ensureWebBuild(webRoot, distRoot);
       handle = await startHonoServer(webConfig);
     }
   } catch (err) {