@ait-co/devtools 0.1.131 → 0.1.133

package/dist/test-runner/relay-factory.js

@@ -23,12 +23,13 @@ function createRelayConnectionFactory(opts) {
 	let family;
 	let qrServer;
 	let phase = "active";
+	let manualPrompt = null;
 	return {
 		async open() {
 			const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import("../attach-orchestrator-Cjdhir2U.js");
-			const { injectDebugIndicator, injectGlobals } = await import("../cell-Cw4fVOl2.js");
+			const { injectDebugIndicator, injectGlobals } = await import("../cell-D1y4shoV.js");
 			const { loadRelaySecretReadOnly } = await import("../relay-secret-store-BcVrWwTq.js");
-			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-qRSRG7YZ.js");
+			const { bootRelayFamily, buildRelayVerifyAuth } = await import("../debug-server-CS1BS2BX.js");
 			await loadRelaySecretReadOnly({ projectRoot });
 			let resolveTunnelUp;
 			const tunnelReady = new Promise((resolve) => {
@@ -58,13 +59,14 @@ function createRelayConnectionFactory(opts) {
 				canOpenBrowser: () => !headless
 			};
 			try {
-				const { startQrHttpServer } = await import("../qr-http-server-cKbciY5k.js");
+				const { startQrHttpServer } = await import("../qr-http-server-DeRrKp_R.js");
 				const getDashboardState = () => ({
 					tunnel: attachDeps.getTunnelStatus(),
 					pages: null,
 					attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,
 					mode: "relay-dev",
-					phase
+					phase,
+					manualPrompt
 				});
 				qrServer = await startQrHttpServer(getDashboardState);
 				attachDeps.qrHttpServer = qrServer;
@@ -121,13 +123,17 @@ function createRelayConnectionFactory(opts) {
 			phase = next;
 			qrServer?.notifyStateChange();
 		},
+		onManualPrompt(next) {
+			manualPrompt = next;
+			qrServer?.notifyStateChange();
+		},
 		async close(connection) {
 			if (phase !== "complete") {
 				phase = "complete";
 				qrServer?.notifyStateChange();
 			}
 			try {
-				const { injectDebugIndicator } = await import("../cell-Cw4fVOl2.js");
+				const { injectDebugIndicator } = await import("../cell-D1y4shoV.js");
 				await injectDebugIndicator(connection, { state: "disconnected" });
 			} catch {}
 			family?.stop();

package/dist/test-runner/relay-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"relay-factory.js","names":[],"sources":["../../src/test-runner/relay-factory.ts"],"sourcesContent":["/**\n * Relay connection factory for the Vitest custom pool (devtools#696).\n *\n * The Vitest pool (`pool.ts`) takes a {@link RelayConnectionFactory} that knows\n * how to `open()` a live CDP relay connection (boot relay → QR → phone scan →\n * cell inject → enableDomains) and `close()` it. Before this module that exact\n * assembly lived only inside the `devtools-test` CLI's `main()`; the standalone\n * CLI and the Vitest pool would otherwise each hand-roll it and drift.\n *\n * This is the single source of that assembly. `cli.ts` is refactored to call\n * `createRelayConnectionFactory(...).open()`, and `definePhoneVitestConfig`\n * (config.ts) exposes it so a downstream `vitest.config.ts` can wire the pool:\n *\n *   import { createRelayConnectionFactory } from '@ait-co/devtools/test-runner';\n *   const connection = createRelayConnectionFactory({\n *     schemeUrl,\n *     cell,\n *     // REQUIRED — own the stdout decision (the chunks carry the relay wss +\n *     // TOTP code). Suppress on non-interactive stdout; print otherwise.\n *     onQrContent: (chunks) => {\n *       if (!process.stdout.isTTY) return;\n *       for (const c of chunks) process.stdout.write(`${c}\\n`);\n *     },\n *   });\n *   export default defineConfig({ test: definePhoneVitestConfig({ connection }) });\n *\n * The heavy boot graph (chii relay, cloudflared, ws, debug-server) is pulled via\n * DYNAMIC import inside `open()` — so merely importing this module (or the\n * `@ait-co/devtools/test-runner` barrel) does NOT statically drag that graph in.\n *\n * SECRET-HANDLING: relay wss URLs, scheme URLs, and the TOTP secret/code are\n * never logged. `open()` reads the project-local `.ait_relay` secret read-only\n * (never mints) and the minted TOTP code rides only inside the QR `at=` param.\n *\n * Node-only. react-free (CdpConnection + lazily-imported MCP boot helpers only).\n */\n\nimport type { AttachDeps, AttachUrlParts } from '../mcp/attach-orchestrator.js';\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\nimport type { DashboardState, QrHttpServer } from '../mcp/qr-http-server.js';\nimport type { RelayConnectionFactory } from './pool.js';\n\n// NOTE: every value import below is a DYNAMIC import inside `open()`. This module\n// keeps ONLY type-level static imports so that re-exporting it from the\n// `@ait-co/devtools/test-runner` barrel (config.ts) does NOT statically drag the\n// heavy MCP graph (cell.ts → attach-orchestrator.ts → tools.ts → server-lock,\n// plus chii/cloudflared via debug-server) onto that Node-config entry.\n\n/** Options for {@link createRelayConnectionFactory}. */\nexport interface RelayConnectionFactoryOptions {\n  /**\n   * intoss-private:// scheme URL from `ait deploy --scheme-only` (env3). The\n   * phone cold-loads the candidate bundle this URL points at. SECRET-HANDLING:\n   * never logged.\n   */\n  schemeUrl: string;\n  /**\n   * Project root for the `.ait_relay` secret lookup (read-only). Defaults to\n   * `process.cwd()`.\n   */\n  projectRoot?: string;\n  /**\n   * Attach wait timeout in ms — how long `open()` waits for the phone to scan\n   * the QR and attach. Omitted (the default) means **wait indefinitely** —\n   * the runner stays up until the user stops it (Ctrl-C/SIGTERM). QR-scan\n   * wait is a human-paced action; there is no sound default bound for it\n   * (devtools#735). Pass an explicit value to opt into a bounded wait (CI/\n   * headless callers — `--attach-timeout` on the CLI). (The per-file evaluate\n   * timeout is separate, passed via the pool's `run` options.)\n   */\n  timeoutMs?: number;\n  /** Disable browser auto-open of the QR dashboard (text QR only). */\n  headless?: boolean;\n  /**\n   * Cell axes injected as `__AIT_CELL__` before the first test bundle runs, so\n   * sdk-example's capture picks up the correct sdkLine/platform. Optional — when\n   * omitted no cell is injected. The values are not secrets.\n   */\n  cell?: { sdkLine: string; platform: string };\n  /**\n   * Receives the QR/attach render content (text chunks) from\n   * `renderAndMaybeWait`, so the caller decides whether to print them — e.g.\n   * suppress on non-interactive stdout.\n   *\n   * REQUIRED (not optional) on purpose: these chunks contain the QR payload\n   * (which encodes the relay wss + TOTP `at=` code) and the attach JSON block.\n   * Making the hook mandatory means the factory never falls back to printing\n   * them itself — a downstream `vitest.config.ts` consumer that wires this via\n   * the `@ait-co/devtools/test-runner` barrel is forced to make an explicit\n   * stdout decision rather than silently leaking the secret-bearing block.\n   *\n   * SECRET-HANDLING: when a non-interactive caller is detected the hook MUST\n   * suppress the WHOLE chunk (not just `attachUrl`), since `relayUrl` rides in\n   * the same block.\n   */\n  onQrContent: (textChunks: string[]) => void;\n}\n\n/**\n * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay\n * connection.\n *\n * `open()` performs the full attach lifecycle and BLOCKS while a human scans\n * the rendered QR with their phone — there is no way around the manual scan\n * for env3. By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the\n * runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is\n * a human-paced action with no sound default bound (devtools#735). Passing an\n * explicit `timeoutMs` opts into the old bounded behavior (CI/headless\n * callers). It resolves with the live `CdpConnection` once a matching page\n * attaches; `close()` tears the relay family down.\n *\n * The factory holds the booted relay family in a closure so `close()` can stop\n * it. A second `open()` on the same factory boots a fresh family (the previous\n * one should have been `close()`d first).\n */\nexport function createRelayConnectionFactory(\n  opts: RelayConnectionFactoryOptions,\n): RelayConnectionFactory {\n  const projectRoot = opts.projectRoot ?? process.cwd();\n  // Undefined/absent → Infinity (wait forever). An explicit finite value opts\n  // into the old bounded behavior. Number.isFinite guards downstream\n  // (renderAndMaybeWait / waitForFirstTarget) treat Infinity as \"no timer\".\n  const timeoutMs = opts.timeoutMs ?? Number.POSITIVE_INFINITY;\n  const headless = opts.headless === true;\n\n  // Captured so close() can stop the family that open() booted.\n  let family: { connection: CdpConnection; stop(): void } | undefined;\n  // QR HTTP server — started during open() when not headless, closed in close().\n  let qrServer: QrHttpServer | undefined;\n  // Session-phase state (#730) — drives the dashboard's `phase` field so the\n  // CLI's run start/complete and final teardown push an immediate SSE update\n  // instead of the dashboard just going dark when the process exits.\n  let phase: DashboardState['phase'] = 'active';\n\n  return {\n    async open(): Promise<CdpConnection> {\n      // Dynamic imports: keep the chii/cloudflared/debug-server graph OFF the\n      // static import graph of this module (and the test-runner config barrel).\n      const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import(\n        '../mcp/attach-orchestrator.js'\n      );\n      const { injectDebugIndicator, injectGlobals } = await import('./cell.js');\n      const { loadRelaySecretReadOnly } = await import('../mcp/relay-secret-store.js');\n      const { bootRelayFamily, buildRelayVerifyAuth } = await import('../mcp/debug-server.js');\n\n      // Load the project-local .ait_relay secret into AIT_DEBUG_TOTP_SECRET\n      // BEFORE booting the relay so assertRelayAuthConfigured()/buildRelayVerifyAuth()\n      // at the boot site see it. Read-only — never mints. SECRET-HANDLING: the\n      // value is never logged here.\n      await loadRelaySecretReadOnly({ projectRoot });\n\n      // PRIMARY FIX (devtools#714): bootRelayFamily starts the cloudflared tunnel\n      // as a background promise and returns immediately with tunnel.up === false.\n      // We must NOT call prepareAttach until the tunnel is up — it fails fast when\n      // tunnel.up is false (attach-orchestrator.ts tunnel-down guard).\n      //\n      // Wire onWssUrl (mirroring the MCP daemon path in debug-server.ts) to:\n      //   1. resolve a caller-held tunnel-ready promise so open() can await it, and\n      //   2. re-push dashboard SSE on late tunnel-up events (notifyStateChange).\n      //\n      // SECRET-HANDLING: onWssUrl receives the relay wss URL — never log it.\n      let resolveTunnelUp!: () => void;\n      const tunnelReady = new Promise<void>((resolve) => {\n        resolveTunnelUp = resolve;\n      });\n\n      const booted = await bootRelayFamily({\n        verifyAuth: buildRelayVerifyAuth(),\n        onWssUrl: () => {\n          // Resolve the tunnel-ready gate so the prepareAttach call below is\n          // unblocked. qrServer may not be set yet at call time (it's started\n          // after bootRelayFamily), so we use optional chaining — if the tunnel\n          // happens to come up after qrServer is started, notifyStateChange pushes\n          // the freshly minted attachUrl to any waiting dashboard SSE clients.\n          // SECRET-HANDLING: wssUrl is NOT forwarded here — the value travels only\n          // inside the closure via getTunnelStatus().wssUrl (used by mintAttachUrl).\n          resolveTunnelUp();\n          qrServer?.notifyStateChange();\n        },\n        // #730: parity with the MCP daemon path (debug-server.ts's onTunnelDown\n        // wiring) — without this, a permanent tunnel drop during a standalone\n        // CLI run left the dashboard showing a dead-but-scannable QR until the\n        // watchdog (up to ~210s) finally fired.\n        onTunnelDown: () => {\n          qrServer?.notifyStateChange();\n        },\n      });\n      family = booted;\n\n      // If the tunnel is already up (extremely fast boot or test double), resolve\n      // immediately so we don't stall on a promise that will never fire.\n      if (booted.getTunnelStatus?.().up) {\n        resolveTunnelUp();\n      }\n\n      // Track the last-captured attach parts so getDashboardState can mint a\n      // fresh attach URL on every dashboard request/SSE push (fresh TOTP at=).\n      // SECRET-HANDLING: parts contain the relay wss + scheme URL — never logged.\n      let lastAttachParts: AttachUrlParts | undefined;\n\n      // Assemble AttachDeps. We set qrHttpServer and onAttachUrlBuilt below\n      // (before prepareAttach) after optionally starting the web-QR server.\n      const attachDeps: AttachDeps = {\n        getTunnelStatus: booted.getTunnelStatus ?? (() => ({ up: false, wssUrl: null })),\n        getTotpSecret: () => process.env.AIT_DEBUG_TOTP_SECRET,\n        qrHttpServer: undefined, // filled in below if web-QR server started\n        onAttachUrlBuilt: undefined, // filled in below\n        canOpenBrowser: () => !headless,\n      };\n\n      // Web-QR server: reuse the same loopback HTTP dashboard that the MCP\n      // start_attach path uses (src/mcp/qr-http-server.ts). This makes the QR\n      // scannable even when stdout is non-interactive (Claude Code `!` / CI),\n      // because the browser is opened by URL — not via captured stdout.\n      //\n      // Headless decision: we start the server even in --headless mode so the\n      // printed stderr URL can be opened manually. The existing\n      // canOpenBrowser: () => !headless gate inside renderAndMaybeWait prevents\n      // the auto-open; headless users see only the stderr URL.\n      //\n      // On failure we fall back gracefully to the text-QR path — do NOT crash.\n      // SECRET-HANDLING: only http://127.0.0.1:<port>/ (no secrets) goes to stderr.\n      try {\n        const { startQrHttpServer } = await import('../mcp/qr-http-server.js');\n\n        const getDashboardState = (): DashboardState => ({\n          tunnel: attachDeps.getTunnelStatus(),\n          pages: null, // CLI/pool: no page-list introspection needed\n          attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,\n          mode: 'relay-dev' as const,\n          phase, // #730 — CLI-only 'running'/'complete' transitions via onSessionPhase\n        });\n\n        qrServer = await startQrHttpServer(getDashboardState);\n\n        // Wire the QR server into attachDeps BEFORE prepareAttach is called so\n        // renderAndMaybeWait sees it and takes Path 2/3 (web-QR) instead of Path 4.\n        attachDeps.qrHttpServer = qrServer;\n\n        // Capture attach parts via onAttachUrlBuilt so getDashboardState can\n        // mint a fresh URL (fresh TOTP at= code) on every dashboard render.\n        attachDeps.onAttachUrlBuilt = (parts: AttachUrlParts) => {\n          lastAttachParts = parts;\n          qrServer?.notifyStateChange();\n        };\n\n        // Print the loopback dashboard URL to stderr — it carries no secrets\n        // (TOTP codes and relay wss live only in the in-memory HTTP response).\n        process.stderr.write(`devtools-test: QR dashboard: http://127.0.0.1:${qrServer.port}/\\n`);\n      } catch {\n        // startQrHttpServer failed (e.g. port conflict, import error). Fall back\n        // to the existing text-QR path by leaving qrHttpServer: undefined.\n        // qrServer remains undefined; close() handles that with optional chaining.\n      }\n\n      // PRIMARY FIX (devtools#714): await tunnel readiness before calling\n      // prepareAttach. Race: a 15 s timeout is generous — cloudflared typically\n      // comes up in < 5 s. On timeout we still call prepareAttach; it will hit\n      // the tunnel-down guard and throw a secret-free error (same as before,\n      // but now with a clear diagnostic instead of a silent WAITING freeze).\n      //\n      // Implementation: Promise.race against a 15 000 ms timeout signal. We do\n      // NOT use a timer-based early-exit because the existing code already\n      // surface-fails on tunnel-down inside prepareAttach with a secret-free\n      // message. The timeout here is purely a \"give the tunnel a fair chance\"\n      // gate — not a correctness boundary.\n      const TUNNEL_BOOT_TIMEOUT_MS = 15_000;\n      await Promise.race([\n        tunnelReady,\n        new Promise<void>((resolve) => setTimeout(resolve, TUNNEL_BOOT_TIMEOUT_MS)),\n      ]);\n\n      const prep = await prepareAttach(\n        attachDeps,\n        'relay-dev',\n        { scheme_url: opts.schemeUrl },\n        booted.connection,\n      );\n      if (!prep.ok) {\n        booted.stop();\n        family = undefined;\n        // SECONDARY FIX (devtools#714): close the QR server on the failure path\n        // so the loopback port listener does not leak. The normal-exit path is\n        // handled by close(); this mirrors that cleanup for the error path.\n        await qrServer?.close();\n        qrServer = undefined;\n        // SECRET-HANDLING: do NOT surface `prep.error.content` in the thrown\n        // message. Some prep error paths build their text from attach\n        // components, and the CLI catch writes `e.message` to stderr — embedding\n        // that text risks leaking the scheme/relay wss URL. The detailed\n        // diagnostic is the daemon/dashboard's job; the factory throws a\n        // secret-free message only.\n        throw new Error(\n          'createRelayConnectionFactory: attach preparation failed — check the scheme_url and that the relay tunnel is up',\n        );\n      }\n\n      // Render the QR + wait for the phone to attach. SECRET-HANDLING: this\n      // function never logs scheme/wss/TOTP values.\n      const waitResult = await renderAndMaybeWait(\n        attachDeps,\n        prep,\n        true,\n        timeoutMs,\n        booted.connection,\n      );\n      if (waitResult.isError) {\n        booted.stop();\n        family = undefined;\n        // SECONDARY FIX (devtools#714): close the QR server on the timeout path\n        // (mirrors the prep.ok failure path above).\n        await qrServer?.close();\n        qrServer = undefined;\n        // SECRET-HANDLING (BLOCKER fix): `waitResult.content` is the timeout\n        // result built from `buildTimeoutError(baseText, ...)`, and `baseText`\n        // is `JSON.stringify({ attachUrl, relayUrl, ... })` — `attachUrl` carries\n        // the TOTP `at=` code and `relayUrl` is the relay `wss://` URL. The CLI\n        // catch writes `e.message` to stderr, so extracting that text here would\n        // leak the relay wss + TOTP code on every timeout. Throw a secret-free\n        // message with only the timeout duration.\n        const timeoutSec = Math.round(timeoutMs / 1000);\n        throw new Error(\n          `createRelayConnectionFactory: attach timed out after ${timeoutSec}s — phone did not scan the QR within the timeout`,\n        );\n      }\n\n      // Surface the QR/attach render content to the caller, which owns the\n      // stdout decision (suppress on non-interactive stdout). There is no\n      // fallback that prints here itself: `onQrContent` is a required option so\n      // the secret-bearing block (attachUrl TOTP + relayUrl wss) can never be\n      // emitted without an explicit caller decision. SECRET-HANDLING.\n      const qrChunks = waitResult.content\n        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n        .map((c) => c.text);\n      opts.onQrContent(qrChunks);\n\n      // PAGE-READY GATE (devtools#720, fix (a)+(b)):\n      //\n      // FIX (a) — ORDER: enableDomains() MUST run before injectDebugIndicator()\n      // and injectGlobals(). Both inject calls use Runtime.evaluate via\n      // sendCommand(), which guards with `if (!this.ws) reject(\"Call\n      // enableDomains() first\")`.  With the old ordering (inject → inject →\n      // enableDomains) injectDebugIndicator's throw was swallowed by cell.ts\n      // try/catch but injectGlobals (no try/catch) propagated fatally — when\n      // --cell was set open() hard-threw before enableDomains ever ran and the\n      // CLI exited with 0 files executed.\n      //\n      // FIX (b) — BOUNDED RETRY: the window between waitForFirstTarget (non-\n      // empty /targets) and enableDomains (page-level WS open) is where a\n      // Cloudflare edge idle-drop can disconnect the phone.  enableDomains()\n      // calls refreshTargets() internally; if the target list is empty at that\n      // point it throws \"No mini-app page attached\".  We absorb up to\n      // PAGE_READY_RETRIES transient failures by waiting briefly and retrying\n      // the refreshTargets+enableDomains sequence.  enableDomains() is\n      // idempotent (concurrent callers share the in-flight promise), so retries\n      // are safe.  Only after all retries fail do we surface a secret-free\n      // error.  This is the CLI equivalent of the MCP daemon's soft-fail\n      // cushion in relay-worker.ts.\n      //\n      // Neither fix touches chii-connection.ts or the MCP daemon path.\n      const PAGE_READY_RETRIES = 3;\n      const PAGE_READY_RETRY_DELAY_MS = 1_500;\n\n      let lastEnableError: Error | undefined;\n      for (let attempt = 1; attempt <= PAGE_READY_RETRIES; attempt++) {\n        try {\n          // FIX (a): enableDomains first — opens the page-level CDP websocket.\n          await booted.connection.enableDomains();\n          lastEnableError = undefined;\n          break;\n        } catch (err) {\n          lastEnableError = err instanceof Error ? err : new Error(String(err));\n          if (attempt < PAGE_READY_RETRIES) {\n            // FIX (b): brief pause then re-poll /targets before retrying\n            // enableDomains. Use a non-leaking approach: wait, then fall\n            // through to the next loop iteration.\n            await new Promise<void>((resolve) => setTimeout(resolve, PAGE_READY_RETRY_DELAY_MS));\n          }\n        }\n      }\n\n      if (lastEnableError !== undefined) {\n        booted.stop();\n        family = undefined;\n        await qrServer?.close();\n        qrServer = undefined;\n        // SECRET-HANDLING: message contains only a duration + attempt count.\n        // No relay wss URL, scheme URL, or TOTP code is included.\n        throw new Error(\n          `createRelayConnectionFactory: page did not become ready after ${PAGE_READY_RETRIES} attempts (${Math.round((PAGE_READY_RETRIES * PAGE_READY_RETRY_DELAY_MS) / 1000)}s) — the mini-app page may have disconnected before enableDomains() could open the CDP websocket`,\n        );\n      }\n\n      // FIX (a): inject AFTER enableDomains so the page-level CDP websocket is\n      // open and sendCommand() will not hit the ws===null guard.\n\n      // Show the on-phone \"Debugger Connected\" badge. injectDebugIndicator\n      // swallows its own errors (cell.ts try/catch), so a badge failure is\n      // non-fatal — test execution proceeds regardless.\n      await injectDebugIndicator(booted.connection);\n\n      // Inject the cell globals before any test bundle runs (session-global).\n      // injectGlobals() does NOT swallow errors — a genuine type/eval failure\n      // here surfaces clearly instead of silently skipping cell injection.\n      if (opts.cell !== undefined) {\n        await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });\n      }\n\n      return booted.connection;\n    },\n\n    // #730: drives the dashboard's `phase` field so the CLI's run start/end\n    // push an immediate SSE update instead of the dashboard just going dark.\n    onSessionPhase(next: 'running' | 'complete'): void {\n      phase = next;\n      qrServer?.notifyStateChange();\n    },\n\n    async close(connection: CdpConnection): Promise<void> {\n      // #730: flip the on-phone badge to disconnected AND push the terminal\n      // dashboard frame BEFORE tearing anything down, so neither surface goes\n      // dark without explanation when the CLI exits (dog-food gaps #1 + #2).\n      // Both are best-effort over the still-open channels — the ordering\n      // (before family.stop()/qrServer.close()) is load-bearing:\n      //   - qrServer.notifyStateChange() writes synchronously to the still-open\n      //     SSE sockets, so the 'complete' frame is on the wire before the HTTP\n      //     server is closed below.\n      //   - injectDebugIndicator runs over the still-open CDP channel, so the\n      //     phone actually receives the disconnected-state update before the\n      //     relay/tunnel are torn down.\n      if (phase !== 'complete') {\n        phase = 'complete';\n        qrServer?.notifyStateChange();\n      }\n      try {\n        const { injectDebugIndicator } = await import('./cell.js');\n        await injectDebugIndicator(connection, { state: 'disconnected' });\n      } catch {\n        // Channel may already be down (e.g. attach never completed) — non-fatal,\n        // the badge is informational UI only.\n      }\n      // family.stop() is synchronous best-effort: closes the CDP connection and\n      // shuts down the relay + cloudflared child.\n      family?.stop();\n      family = undefined;\n      // Close the web-QR HTTP server if one was started during open().\n      // close() is idempotent via optional chaining + reassignment to undefined.\n      await qrServer?.close();\n      qrServer = undefined;\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"relay-factory.js","names":[],"sources":["../../src/test-runner/relay-factory.ts"],"sourcesContent":["/**\n * Relay connection factory for the Vitest custom pool (devtools#696).\n *\n * The Vitest pool (`pool.ts`) takes a {@link RelayConnectionFactory} that knows\n * how to `open()` a live CDP relay connection (boot relay → QR → phone scan →\n * cell inject → enableDomains) and `close()` it. Before this module that exact\n * assembly lived only inside the `devtools-test` CLI's `main()`; the standalone\n * CLI and the Vitest pool would otherwise each hand-roll it and drift.\n *\n * This is the single source of that assembly. `cli.ts` is refactored to call\n * `createRelayConnectionFactory(...).open()`, and `definePhoneVitestConfig`\n * (config.ts) exposes it so a downstream `vitest.config.ts` can wire the pool:\n *\n *   import { createRelayConnectionFactory } from '@ait-co/devtools/test-runner';\n *   const connection = createRelayConnectionFactory({\n *     schemeUrl,\n *     cell,\n *     // REQUIRED — own the stdout decision (the chunks carry the relay wss +\n *     // TOTP code). Suppress on non-interactive stdout; print otherwise.\n *     onQrContent: (chunks) => {\n *       if (!process.stdout.isTTY) return;\n *       for (const c of chunks) process.stdout.write(`${c}\\n`);\n *     },\n *   });\n *   export default defineConfig({ test: definePhoneVitestConfig({ connection }) });\n *\n * The heavy boot graph (chii relay, cloudflared, ws, debug-server) is pulled via\n * DYNAMIC import inside `open()` — so merely importing this module (or the\n * `@ait-co/devtools/test-runner` barrel) does NOT statically drag that graph in.\n *\n * SECRET-HANDLING: relay wss URLs, scheme URLs, and the TOTP secret/code are\n * never logged. `open()` reads the project-local `.ait_relay` secret read-only\n * (never mints) and the minted TOTP code rides only inside the QR `at=` param.\n *\n * Node-only. react-free (CdpConnection + lazily-imported MCP boot helpers only).\n */\n\nimport type { AttachDeps, AttachUrlParts } from '../mcp/attach-orchestrator.js';\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\nimport type { DashboardState, QrHttpServer } from '../mcp/qr-http-server.js';\nimport type { RelayConnectionFactory } from './pool.js';\n\n// NOTE: every value import below is a DYNAMIC import inside `open()`. This module\n// keeps ONLY type-level static imports so that re-exporting it from the\n// `@ait-co/devtools/test-runner` barrel (config.ts) does NOT statically drag the\n// heavy MCP graph (cell.ts → attach-orchestrator.ts → tools.ts → server-lock,\n// plus chii/cloudflared via debug-server) onto that Node-config entry.\n\n/** Options for {@link createRelayConnectionFactory}. */\nexport interface RelayConnectionFactoryOptions {\n  /**\n   * intoss-private:// scheme URL from `ait deploy --scheme-only` (env3). The\n   * phone cold-loads the candidate bundle this URL points at. SECRET-HANDLING:\n   * never logged.\n   */\n  schemeUrl: string;\n  /**\n   * Project root for the `.ait_relay` secret lookup (read-only). Defaults to\n   * `process.cwd()`.\n   */\n  projectRoot?: string;\n  /**\n   * Attach wait timeout in ms — how long `open()` waits for the phone to scan\n   * the QR and attach. Omitted (the default) means **wait indefinitely** —\n   * the runner stays up until the user stops it (Ctrl-C/SIGTERM). QR-scan\n   * wait is a human-paced action; there is no sound default bound for it\n   * (devtools#735). Pass an explicit value to opt into a bounded wait (CI/\n   * headless callers — `--attach-timeout` on the CLI). (The per-file evaluate\n   * timeout is separate, passed via the pool's `run` options.)\n   */\n  timeoutMs?: number;\n  /** Disable browser auto-open of the QR dashboard (text QR only). */\n  headless?: boolean;\n  /**\n   * Cell axes injected as `__AIT_CELL__` before the first test bundle runs, so\n   * sdk-example's capture picks up the correct sdkLine/platform. Optional — when\n   * omitted no cell is injected. The values are not secrets.\n   */\n  cell?: { sdkLine: string; platform: string };\n  /**\n   * Receives the QR/attach render content (text chunks) from\n   * `renderAndMaybeWait`, so the caller decides whether to print them — e.g.\n   * suppress on non-interactive stdout.\n   *\n   * REQUIRED (not optional) on purpose: these chunks contain the QR payload\n   * (which encodes the relay wss + TOTP `at=` code) and the attach JSON block.\n   * Making the hook mandatory means the factory never falls back to printing\n   * them itself — a downstream `vitest.config.ts` consumer that wires this via\n   * the `@ait-co/devtools/test-runner` barrel is forced to make an explicit\n   * stdout decision rather than silently leaking the secret-bearing block.\n   *\n   * SECRET-HANDLING: when a non-interactive caller is detected the hook MUST\n   * suppress the WHOLE chunk (not just `attachUrl`), since `relayUrl` rides in\n   * the same block.\n   */\n  onQrContent: (textChunks: string[]) => void;\n}\n\n/**\n * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay\n * connection.\n *\n * `open()` performs the full attach lifecycle and BLOCKS while a human scans\n * the rendered QR with their phone — there is no way around the manual scan\n * for env3. By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the\n * runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is\n * a human-paced action with no sound default bound (devtools#735). Passing an\n * explicit `timeoutMs` opts into the old bounded behavior (CI/headless\n * callers). It resolves with the live `CdpConnection` once a matching page\n * attaches; `close()` tears the relay family down.\n *\n * The factory holds the booted relay family in a closure so `close()` can stop\n * it. A second `open()` on the same factory boots a fresh family (the previous\n * one should have been `close()`d first).\n */\nexport function createRelayConnectionFactory(\n  opts: RelayConnectionFactoryOptions,\n): RelayConnectionFactory {\n  const projectRoot = opts.projectRoot ?? process.cwd();\n  // Undefined/absent → Infinity (wait forever). An explicit finite value opts\n  // into the old bounded behavior. Number.isFinite guards downstream\n  // (renderAndMaybeWait / waitForFirstTarget) treat Infinity as \"no timer\".\n  const timeoutMs = opts.timeoutMs ?? Number.POSITIVE_INFINITY;\n  const headless = opts.headless === true;\n\n  // Captured so close() can stop the family that open() booted.\n  let family: { connection: CdpConnection; stop(): void } | undefined;\n  // QR HTTP server — started during open() when not headless, closed in close().\n  let qrServer: QrHttpServer | undefined;\n  // Session-phase state (#730) — drives the dashboard's `phase` field so the\n  // CLI's run start/complete and final teardown push an immediate SSE update\n  // instead of the dashboard just going dark when the process exits.\n  let phase: DashboardState['phase'] = 'active';\n  // Manual-blocking prompt state (devtools#741) — drives the dashboard's\n  // `manualPrompt` field. `null` outside a manual step.\n  let manualPrompt: DashboardState['manualPrompt'] = null;\n\n  return {\n    async open(): Promise<CdpConnection> {\n      // Dynamic imports: keep the chii/cloudflared/debug-server graph OFF the\n      // static import graph of this module (and the test-runner config barrel).\n      const { prepareAttach, renderAndMaybeWait, mintAttachUrl } = await import(\n        '../mcp/attach-orchestrator.js'\n      );\n      const { injectDebugIndicator, injectGlobals } = await import('./cell.js');\n      const { loadRelaySecretReadOnly } = await import('../mcp/relay-secret-store.js');\n      const { bootRelayFamily, buildRelayVerifyAuth } = await import('../mcp/debug-server.js');\n\n      // Load the project-local .ait_relay secret into AIT_DEBUG_TOTP_SECRET\n      // BEFORE booting the relay so assertRelayAuthConfigured()/buildRelayVerifyAuth()\n      // at the boot site see it. Read-only — never mints. SECRET-HANDLING: the\n      // value is never logged here.\n      await loadRelaySecretReadOnly({ projectRoot });\n\n      // PRIMARY FIX (devtools#714): bootRelayFamily starts the cloudflared tunnel\n      // as a background promise and returns immediately with tunnel.up === false.\n      // We must NOT call prepareAttach until the tunnel is up — it fails fast when\n      // tunnel.up is false (attach-orchestrator.ts tunnel-down guard).\n      //\n      // Wire onWssUrl (mirroring the MCP daemon path in debug-server.ts) to:\n      //   1. resolve a caller-held tunnel-ready promise so open() can await it, and\n      //   2. re-push dashboard SSE on late tunnel-up events (notifyStateChange).\n      //\n      // SECRET-HANDLING: onWssUrl receives the relay wss URL — never log it.\n      let resolveTunnelUp!: () => void;\n      const tunnelReady = new Promise<void>((resolve) => {\n        resolveTunnelUp = resolve;\n      });\n\n      const booted = await bootRelayFamily({\n        verifyAuth: buildRelayVerifyAuth(),\n        onWssUrl: () => {\n          // Resolve the tunnel-ready gate so the prepareAttach call below is\n          // unblocked. qrServer may not be set yet at call time (it's started\n          // after bootRelayFamily), so we use optional chaining — if the tunnel\n          // happens to come up after qrServer is started, notifyStateChange pushes\n          // the freshly minted attachUrl to any waiting dashboard SSE clients.\n          // SECRET-HANDLING: wssUrl is NOT forwarded here — the value travels only\n          // inside the closure via getTunnelStatus().wssUrl (used by mintAttachUrl).\n          resolveTunnelUp();\n          qrServer?.notifyStateChange();\n        },\n        // #730: parity with the MCP daemon path (debug-server.ts's onTunnelDown\n        // wiring) — without this, a permanent tunnel drop during a standalone\n        // CLI run left the dashboard showing a dead-but-scannable QR until the\n        // watchdog (up to ~210s) finally fired.\n        onTunnelDown: () => {\n          qrServer?.notifyStateChange();\n        },\n      });\n      family = booted;\n\n      // If the tunnel is already up (extremely fast boot or test double), resolve\n      // immediately so we don't stall on a promise that will never fire.\n      if (booted.getTunnelStatus?.().up) {\n        resolveTunnelUp();\n      }\n\n      // Track the last-captured attach parts so getDashboardState can mint a\n      // fresh attach URL on every dashboard request/SSE push (fresh TOTP at=).\n      // SECRET-HANDLING: parts contain the relay wss + scheme URL — never logged.\n      let lastAttachParts: AttachUrlParts | undefined;\n\n      // Assemble AttachDeps. We set qrHttpServer and onAttachUrlBuilt below\n      // (before prepareAttach) after optionally starting the web-QR server.\n      const attachDeps: AttachDeps = {\n        getTunnelStatus: booted.getTunnelStatus ?? (() => ({ up: false, wssUrl: null })),\n        getTotpSecret: () => process.env.AIT_DEBUG_TOTP_SECRET,\n        qrHttpServer: undefined, // filled in below if web-QR server started\n        onAttachUrlBuilt: undefined, // filled in below\n        canOpenBrowser: () => !headless,\n      };\n\n      // Web-QR server: reuse the same loopback HTTP dashboard that the MCP\n      // start_attach path uses (src/mcp/qr-http-server.ts). This makes the QR\n      // scannable even when stdout is non-interactive (Claude Code `!` / CI),\n      // because the browser is opened by URL — not via captured stdout.\n      //\n      // Headless decision: we start the server even in --headless mode so the\n      // printed stderr URL can be opened manually. The existing\n      // canOpenBrowser: () => !headless gate inside renderAndMaybeWait prevents\n      // the auto-open; headless users see only the stderr URL.\n      //\n      // On failure we fall back gracefully to the text-QR path — do NOT crash.\n      // SECRET-HANDLING: only http://127.0.0.1:<port>/ (no secrets) goes to stderr.\n      try {\n        const { startQrHttpServer } = await import('../mcp/qr-http-server.js');\n\n        const getDashboardState = (): DashboardState => ({\n          tunnel: attachDeps.getTunnelStatus(),\n          pages: null, // CLI/pool: no page-list introspection needed\n          attachUrl: lastAttachParts ? mintAttachUrl(attachDeps, lastAttachParts) : null,\n          mode: 'relay-dev' as const,\n          phase, // #730 — CLI-only 'running'/'complete' transitions via onSessionPhase\n          manualPrompt, // #741 — CLI-only --manual-blocking transitions via onManualPrompt\n        });\n\n        qrServer = await startQrHttpServer(getDashboardState);\n\n        // Wire the QR server into attachDeps BEFORE prepareAttach is called so\n        // renderAndMaybeWait sees it and takes Path 2/3 (web-QR) instead of Path 4.\n        attachDeps.qrHttpServer = qrServer;\n\n        // Capture attach parts via onAttachUrlBuilt so getDashboardState can\n        // mint a fresh URL (fresh TOTP at= code) on every dashboard render.\n        attachDeps.onAttachUrlBuilt = (parts: AttachUrlParts) => {\n          lastAttachParts = parts;\n          qrServer?.notifyStateChange();\n        };\n\n        // Print the loopback dashboard URL to stderr — it carries no secrets\n        // (TOTP codes and relay wss live only in the in-memory HTTP response).\n        process.stderr.write(`devtools-test: QR dashboard: http://127.0.0.1:${qrServer.port}/\\n`);\n      } catch {\n        // startQrHttpServer failed (e.g. port conflict, import error). Fall back\n        // to the existing text-QR path by leaving qrHttpServer: undefined.\n        // qrServer remains undefined; close() handles that with optional chaining.\n      }\n\n      // PRIMARY FIX (devtools#714): await tunnel readiness before calling\n      // prepareAttach. Race: a 15 s timeout is generous — cloudflared typically\n      // comes up in < 5 s. On timeout we still call prepareAttach; it will hit\n      // the tunnel-down guard and throw a secret-free error (same as before,\n      // but now with a clear diagnostic instead of a silent WAITING freeze).\n      //\n      // Implementation: Promise.race against a 15 000 ms timeout signal. We do\n      // NOT use a timer-based early-exit because the existing code already\n      // surface-fails on tunnel-down inside prepareAttach with a secret-free\n      // message. The timeout here is purely a \"give the tunnel a fair chance\"\n      // gate — not a correctness boundary.\n      const TUNNEL_BOOT_TIMEOUT_MS = 15_000;\n      await Promise.race([\n        tunnelReady,\n        new Promise<void>((resolve) => setTimeout(resolve, TUNNEL_BOOT_TIMEOUT_MS)),\n      ]);\n\n      const prep = await prepareAttach(\n        attachDeps,\n        'relay-dev',\n        { scheme_url: opts.schemeUrl },\n        booted.connection,\n      );\n      if (!prep.ok) {\n        booted.stop();\n        family = undefined;\n        // SECONDARY FIX (devtools#714): close the QR server on the failure path\n        // so the loopback port listener does not leak. The normal-exit path is\n        // handled by close(); this mirrors that cleanup for the error path.\n        await qrServer?.close();\n        qrServer = undefined;\n        // SECRET-HANDLING: do NOT surface `prep.error.content` in the thrown\n        // message. Some prep error paths build their text from attach\n        // components, and the CLI catch writes `e.message` to stderr — embedding\n        // that text risks leaking the scheme/relay wss URL. The detailed\n        // diagnostic is the daemon/dashboard's job; the factory throws a\n        // secret-free message only.\n        throw new Error(\n          'createRelayConnectionFactory: attach preparation failed — check the scheme_url and that the relay tunnel is up',\n        );\n      }\n\n      // Render the QR + wait for the phone to attach. SECRET-HANDLING: this\n      // function never logs scheme/wss/TOTP values.\n      const waitResult = await renderAndMaybeWait(\n        attachDeps,\n        prep,\n        true,\n        timeoutMs,\n        booted.connection,\n      );\n      if (waitResult.isError) {\n        booted.stop();\n        family = undefined;\n        // SECONDARY FIX (devtools#714): close the QR server on the timeout path\n        // (mirrors the prep.ok failure path above).\n        await qrServer?.close();\n        qrServer = undefined;\n        // SECRET-HANDLING (BLOCKER fix): `waitResult.content` is the timeout\n        // result built from `buildTimeoutError(baseText, ...)`, and `baseText`\n        // is `JSON.stringify({ attachUrl, relayUrl, ... })` — `attachUrl` carries\n        // the TOTP `at=` code and `relayUrl` is the relay `wss://` URL. The CLI\n        // catch writes `e.message` to stderr, so extracting that text here would\n        // leak the relay wss + TOTP code on every timeout. Throw a secret-free\n        // message with only the timeout duration.\n        const timeoutSec = Math.round(timeoutMs / 1000);\n        throw new Error(\n          `createRelayConnectionFactory: attach timed out after ${timeoutSec}s — phone did not scan the QR within the timeout`,\n        );\n      }\n\n      // Surface the QR/attach render content to the caller, which owns the\n      // stdout decision (suppress on non-interactive stdout). There is no\n      // fallback that prints here itself: `onQrContent` is a required option so\n      // the secret-bearing block (attachUrl TOTP + relayUrl wss) can never be\n      // emitted without an explicit caller decision. SECRET-HANDLING.\n      const qrChunks = waitResult.content\n        .filter((c): c is { type: 'text'; text: string } => c.type === 'text')\n        .map((c) => c.text);\n      opts.onQrContent(qrChunks);\n\n      // PAGE-READY GATE (devtools#720, fix (a)+(b)):\n      //\n      // FIX (a) — ORDER: enableDomains() MUST run before injectDebugIndicator()\n      // and injectGlobals(). Both inject calls use Runtime.evaluate via\n      // sendCommand(), which guards with `if (!this.ws) reject(\"Call\n      // enableDomains() first\")`.  With the old ordering (inject → inject →\n      // enableDomains) injectDebugIndicator's throw was swallowed by cell.ts\n      // try/catch but injectGlobals (no try/catch) propagated fatally — when\n      // --cell was set open() hard-threw before enableDomains ever ran and the\n      // CLI exited with 0 files executed.\n      //\n      // FIX (b) — BOUNDED RETRY: the window between waitForFirstTarget (non-\n      // empty /targets) and enableDomains (page-level WS open) is where a\n      // Cloudflare edge idle-drop can disconnect the phone.  enableDomains()\n      // calls refreshTargets() internally; if the target list is empty at that\n      // point it throws \"No mini-app page attached\".  We absorb up to\n      // PAGE_READY_RETRIES transient failures by waiting briefly and retrying\n      // the refreshTargets+enableDomains sequence.  enableDomains() is\n      // idempotent (concurrent callers share the in-flight promise), so retries\n      // are safe.  Only after all retries fail do we surface a secret-free\n      // error.  This is the CLI equivalent of the MCP daemon's soft-fail\n      // cushion in relay-worker.ts.\n      //\n      // Neither fix touches chii-connection.ts or the MCP daemon path.\n      const PAGE_READY_RETRIES = 3;\n      const PAGE_READY_RETRY_DELAY_MS = 1_500;\n\n      let lastEnableError: Error | undefined;\n      for (let attempt = 1; attempt <= PAGE_READY_RETRIES; attempt++) {\n        try {\n          // FIX (a): enableDomains first — opens the page-level CDP websocket.\n          await booted.connection.enableDomains();\n          lastEnableError = undefined;\n          break;\n        } catch (err) {\n          lastEnableError = err instanceof Error ? err : new Error(String(err));\n          if (attempt < PAGE_READY_RETRIES) {\n            // FIX (b): brief pause then re-poll /targets before retrying\n            // enableDomains. Use a non-leaking approach: wait, then fall\n            // through to the next loop iteration.\n            await new Promise<void>((resolve) => setTimeout(resolve, PAGE_READY_RETRY_DELAY_MS));\n          }\n        }\n      }\n\n      if (lastEnableError !== undefined) {\n        booted.stop();\n        family = undefined;\n        await qrServer?.close();\n        qrServer = undefined;\n        // SECRET-HANDLING: message contains only a duration + attempt count.\n        // No relay wss URL, scheme URL, or TOTP code is included.\n        throw new Error(\n          `createRelayConnectionFactory: page did not become ready after ${PAGE_READY_RETRIES} attempts (${Math.round((PAGE_READY_RETRIES * PAGE_READY_RETRY_DELAY_MS) / 1000)}s) — the mini-app page may have disconnected before enableDomains() could open the CDP websocket`,\n        );\n      }\n\n      // FIX (a): inject AFTER enableDomains so the page-level CDP websocket is\n      // open and sendCommand() will not hit the ws===null guard.\n\n      // Show the on-phone \"Debugger Connected\" badge. injectDebugIndicator\n      // swallows its own errors (cell.ts try/catch), so a badge failure is\n      // non-fatal — test execution proceeds regardless.\n      await injectDebugIndicator(booted.connection);\n\n      // Inject the cell globals before any test bundle runs (session-global).\n      // injectGlobals() does NOT swallow errors — a genuine type/eval failure\n      // here surfaces clearly instead of silently skipping cell injection.\n      if (opts.cell !== undefined) {\n        await injectGlobals(booted.connection, { __AIT_CELL__: opts.cell });\n      }\n\n      return booted.connection;\n    },\n\n    // #730: drives the dashboard's `phase` field so the CLI's run start/end\n    // push an immediate SSE update instead of the dashboard just going dark.\n    onSessionPhase(next: 'running' | 'complete'): void {\n      phase = next;\n      qrServer?.notifyStateChange();\n    },\n\n    // #741: drives the dashboard's `manualPrompt` field for --manual-blocking\n    // — the CLI calls this immediately before injecting each manual file\n    // (prompt set) and once more with `null` after the last one (prompt\n    // cleared). Push is immediate (not waited on for ack) — v1 does not block\n    // on dashboard acknowledgment, only on the file's own (long) evaluate.\n    onManualPrompt(next: { file: string; index: number; total: number } | null): void {\n      manualPrompt = next;\n      qrServer?.notifyStateChange();\n    },\n\n    async close(connection: CdpConnection): Promise<void> {\n      // #730: flip the on-phone badge to disconnected AND push the terminal\n      // dashboard frame BEFORE tearing anything down, so neither surface goes\n      // dark without explanation when the CLI exits (dog-food gaps #1 + #2).\n      // Both are best-effort over the still-open channels — the ordering\n      // (before family.stop()/qrServer.close()) is load-bearing:\n      //   - qrServer.notifyStateChange() writes synchronously to the still-open\n      //     SSE sockets, so the 'complete' frame is on the wire before the HTTP\n      //     server is closed below.\n      //   - injectDebugIndicator runs over the still-open CDP channel, so the\n      //     phone actually receives the disconnected-state update before the\n      //     relay/tunnel are torn down.\n      if (phase !== 'complete') {\n        phase = 'complete';\n        qrServer?.notifyStateChange();\n      }\n      try {\n        const { injectDebugIndicator } = await import('./cell.js');\n        await injectDebugIndicator(connection, { state: 'disconnected' });\n      } catch {\n        // Channel may already be down (e.g. attach never completed) — non-fatal,\n        // the badge is informational UI only.\n      }\n      // family.stop() is synchronous best-effort: closes the CDP connection and\n      // shuts down the relay + cloudflared child.\n      family?.stop();\n      family = undefined;\n      // Close the web-QR HTTP server if one was started during open().\n      // close() is idempotent via optional chaining + reassignment to undefined.\n      await qrServer?.close();\n      qrServer = undefined;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/test-runner/relay-worker.d.ts

@@ -1,2 +1,2 @@
-import { a as flattenResults, i as RelayRunReport, n as FileResult, o as runTestFilesOverRelay, r as RelayRunOptions, t as EVALUATE_TIMEOUT_MARKER } from "../relay-worker-o0M2ndyJ.js";
-export { EVALUATE_TIMEOUT_MARKER, FileResult, RelayRunOptions, RelayRunReport, flattenResults, runTestFilesOverRelay };
+import { a as RelayRunReport, i as RelayRunOptions, n as FileResult, o as flattenResults, r as MANUAL_FILE_TIMEOUT_MS, s as runTestFilesOverRelay, t as EVALUATE_TIMEOUT_MARKER } from "../relay-worker-DtX_eszH.js";
+export { EVALUATE_TIMEOUT_MARKER, FileResult, MANUAL_FILE_TIMEOUT_MS, RelayRunOptions, RelayRunReport, flattenResults, runTestFilesOverRelay };

package/dist/test-runner/relay-worker.js

@@ -1,2 +1,2 @@
-import { n as flattenResults, r as runTestFilesOverRelay, t as EVALUATE_TIMEOUT_MARKER } from "../relay-worker-CCAHLC4a.js";
-export { EVALUATE_TIMEOUT_MARKER, flattenResults, runTestFilesOverRelay };
+import { i as runTestFilesOverRelay, n as MANUAL_FILE_TIMEOUT_MS, r as flattenResults, t as EVALUATE_TIMEOUT_MARKER } from "../relay-worker-MZq4fLv8.js";
+export { EVALUATE_TIMEOUT_MARKER, MANUAL_FILE_TIMEOUT_MS, flattenResults, runTestFilesOverRelay };

package/dist/test-runner/report.d.ts

@@ -1,6 +1,6 @@
 import { t as AitCaptureLine } from "../capture-ltuV0gZa.js";
 import { n as TestResult } from "../runtime-9xhN9pr8.js";
-import { i as RelayRunReport } from "../relay-worker-o0M2ndyJ.js";
+import { a as RelayRunReport } from "../relay-worker-DtX_eszH.js";
 
 //#region src/test-runner/report.d.ts
 /** The cell axes a report is stamped with — the test-matrix coordinates. */
@@ -33,6 +33,14 @@ interface RunnerAgnosticFileReport {
   skipped?: number;
   /** Per-test results, when the file ran. Error strings are matcher messages only. */
   tests?: TestResult[];
+  /**
+   * Present + `'manual'` only when this file ran under `--manual-blocking`
+   * (devtools#741) — human-attended, real native envelopes. Absent (never
+   * `false`) for unattended files: absence-means-unattended is the contract,
+   * mirroring `FileResult.mode` in relay-worker.ts. A manual-stamped record
+   * must never be diffed against an unattended one as if equivalent.
+   */
+  mode?: 'manual';
 }
 /**
  * The runner-neutral, secret-free report written to disk. There are
@@ -53,6 +61,15 @@ interface RunnerAgnosticReport {
   totals: RelayRunReport['totals'];
   /** Per-file results with projectRoot-relative paths. */
   files: RunnerAgnosticFileReport[];
+  /**
+   * Permission-state preflight result (devtools#739), mirrored verbatim from
+   * `RelayRunReport.preflight` — see that field's docblock. Absent when the
+   * preflight did not complete (non-fatal; the run still succeeds). No
+   * secrets — permission-state strings only.
+   */
+  preflight?: {
+    permissions: Record<string, string>;
+  };
 }
 /**
  * Serialises a {@link RelayRunReport} into the runner-agnostic, secret-free
@@ -64,21 +81,35 @@ interface RunnerAgnosticReport {
 declare function serializeRelayReport(report: RelayRunReport, meta: ReportCellMeta): RunnerAgnosticReport;
 /**
  * Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating
- * `dir` if needed. Returns the absolute path written.
+ * `dir` if needed. Returns the absolute path(s) written.
  *
  * The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as
  * distinct artifacts in the same directory; the same cell metadata is also baked
  * into the body so a renamed/moved file still carries its provenance.
  *
+ * Manual-run provenance (devtools#741): when `report.files` contains ANY
+ * `mode: 'manual'` entry (i.e. this run included `--manual-blocking` files),
+ * the manual-tagged files are written to a SEPARATE
+ * `<dir>/<sdkLine>.<platform>.manual.json` artifact instead of the standard
+ * one — the standard `<sdkLine>.<platform>.json` filename is reserved for the
+ * regular (unattended) files only, so a manual run's presence never mutates
+ * what the unattended-baseline filename means. If ALL files in the run are
+ * regular, only the standard artifact is written (today's behavior,
+ * unchanged). If a run mixes both (regular files + `--manual-blocking`
+ * scheduled last), BOTH artifacts are written — the manual one ALONGSIDE, not
+ * replacing, the standard one.
+ *
  * SECRET-HANDLING: the written body contains no relay/secret fields (the schema
  * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
  *
  * @param report - The core relay run report.
  * @param dir    - Output directory (created recursively if missing).
  * @param meta   - Cell axes + projectRoot.
- * @returns The absolute path of the written file.
+ * @returns The absolute path(s) written, in order: standard first (if any
+ *   regular files ran), then manual (if any manual files ran). At least one
+ *   path is always returned when `report.files` is non-empty.
  */
-declare function writeReportArtifact(report: RelayRunReport, dir: string, meta: ReportCellMeta): Promise<string>;
+declare function writeReportArtifact(report: RelayRunReport, dir: string, meta: ReportCellMeta): Promise<string[]>;
 /**
  * Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,
  * named `<category>.<sdkLine>.<platform>.json` — the SAME convention

package/dist/test-runner/report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"report.d.ts","names":[],"sources":["../../src/test-runner/report.ts"],"mappings":";;;;;;UA+BiB,cAAA;EAqCA;EAnCf,OAAA;;EAEA,QAAA;EAmCA;;;;;EA7BA,WAAA;AAAA;;UAIe,wBAAA;EAiCgB;;AA4BjC;;;EAvDE,IAAA;EAyDM;EAvDN,KAAA;EAwDqB;EAtDrB,QAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EAkDA;EAhDA,KAAA,GAAQ,UAAA;AAAA;;AA0FV;;;;UAlFiB,oBAAA;EAsFd;EApFD,IAAA;IAAQ,OAAA;IAAiB,QAAA;EAAA;EAkFzB;EAhFA,SAAA;EAiFA;EA/EA,QAAA;EAgFQ;EA9ER,MAAA,EAAQ,cAAA;EAwGY;EAtGpB,KAAA,EAAO,wBAAA;AAAA;;;;;;;;iBA4BO,oBAAA,CACd,MAAA,EAAQ,cAAA,EACR,IAAA,EAAM,cAAA,GACL,oBAAA;;;;;;;;;;;;;;;;;iBAyCmB,mBAAA,CACpB,MAAA,EAAQ,cAAA,EACR,GAAA,UACA,IAAA,EAAM,cAAA,GACL,OAAA;;;;;;;;;;;;;;;;;;;iBA0BmB,qBAAA,CACpB,QAAA,EAAU,aAAA,CAAc,cAAA,GACxB,GAAA,UACA,IAAA;EAAQ,OAAA;EAAiB,QAAA;AAAA,IACxB,OAAA"}
+{"version":3,"file":"report.d.ts","names":[],"sources":["../../src/test-runner/report.ts"],"mappings":";;;;;;UA+BiB,cAAA;EAqCX;EAnCJ,OAAA;EA2CmC;EAzCnC,QAAA;EAiDQ;;;;;EA3CR,WAAA;AAAA;;UAIe,wBAAA;EAqCf;;;;;EA/BA,IAAA;EA0Cc;EAxCd,KAAA;EAwCiC;EAtCjC,QAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EAgEQ;EA9DR,KAAA,GAAQ,UAAA;EAgEP;;;;;;;EAxDD,IAAA;AAAA;;AAkHF;;;;UA1GiB,oBAAA;EA8Gd;EA5GD,IAAA;IAAQ,OAAA;IAAiB,QAAA;EAAA;EA0GzB;EAxGA,SAAA;EAyGA;EAvGA,QAAA;EAwGQ;EAtGR,MAAA,EAAQ,cAAA;EA2JY;EAzJpB,KAAA,EAAO,wBAAA;;;;;;;EAOP,SAAA;IAAc,WAAA,EAAa,MAAA;EAAA;AAAA;;;;;;;;iBA4Bb,oBAAA,CACd,MAAA,EAAQ,cAAA,EACR,IAAA,EAAM,cAAA,GACL,oBAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0DmB,mBAAA,CACpB,MAAA,EAAQ,cAAA,EACR,GAAA,UACA,IAAA,EAAM,cAAA,GACL,OAAA;;;;;;;;;;;;;;;;;;;iBAqDmB,qBAAA,CACpB,QAAA,EAAU,aAAA,CAAc,cAAA,GACxB,GAAA,UACA,IAAA;EAAQ,OAAA;EAAiB,QAAA;AAAA,IACxB,OAAA"}

package/dist/test-runner/report.js

@@ -53,11 +53,14 @@ function serializeRelayReport(report, meta) {
 		startedAt: report.startedAt,
 		duration: report.duration,
 		totals: report.totals,
+		...report.preflight ? { preflight: report.preflight } : {},
 		files: report.files.map((f) => {
 			const file = relativise(meta.projectRoot, f.file);
+			const modeField = f.mode === "manual" ? { mode: "manual" } : {};
 			if ("error" in f.result) return {
 				file,
-				error: f.result.error
+				error: f.result.error,
+				...modeField
 			};
 			return {
 				file,
@@ -65,33 +68,65 @@ function serializeRelayReport(report, meta) {
 				passed: f.result.passed,
 				failed: f.result.failed,
 				skipped: f.result.skipped,
-				tests: f.result.tests
+				tests: f.result.tests,
+				...modeField
 			};
 		})
 	};
 }
 /**
 * Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating
-* `dir` if needed. Returns the absolute path written.
+* `dir` if needed. Returns the absolute path(s) written.
 *
 * The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as
 * distinct artifacts in the same directory; the same cell metadata is also baked
 * into the body so a renamed/moved file still carries its provenance.
 *
+* Manual-run provenance (devtools#741): when `report.files` contains ANY
+* `mode: 'manual'` entry (i.e. this run included `--manual-blocking` files),
+* the manual-tagged files are written to a SEPARATE
+* `<dir>/<sdkLine>.<platform>.manual.json` artifact instead of the standard
+* one — the standard `<sdkLine>.<platform>.json` filename is reserved for the
+* regular (unattended) files only, so a manual run's presence never mutates
+* what the unattended-baseline filename means. If ALL files in the run are
+* regular, only the standard artifact is written (today's behavior,
+* unchanged). If a run mixes both (regular files + `--manual-blocking`
+* scheduled last), BOTH artifacts are written — the manual one ALONGSIDE, not
+* replacing, the standard one.
+*
 * SECRET-HANDLING: the written body contains no relay/secret fields (the schema
 * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.
 *
 * @param report - The core relay run report.
 * @param dir    - Output directory (created recursively if missing).
 * @param meta   - Cell axes + projectRoot.
-* @returns The absolute path of the written file.
+* @returns The absolute path(s) written, in order: standard first (if any
+*   regular files ran), then manual (if any manual files ran). At least one
+*   path is always returned when `report.files` is non-empty.
 */
 async function writeReportArtifact(report, dir, meta) {
 	const serialised = serializeRelayReport(report, meta);
 	await mkdir(dir, { recursive: true });
-	const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
-	await writeFile(outFile, `${JSON.stringify(serialised, null, 2)}\n`, "utf8");
-	return outFile;
+	const regularFiles = serialised.files.filter((f) => f.mode !== "manual");
+	const manualFiles = serialised.files.filter((f) => f.mode === "manual");
+	const written = [];
+	if (regularFiles.length > 0 || serialised.files.length === 0) {
+		const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);
+		await writeFile(outFile, `${JSON.stringify({
+			...serialised,
+			files: regularFiles
+		}, null, 2)}\n`, "utf8");
+		written.push(outFile);
+	}
+	if (manualFiles.length > 0) {
+		const manualOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.manual.json`);
+		await writeFile(manualOutFile, `${JSON.stringify({
+			...serialised,
+			files: manualFiles
+		}, null, 2)}\n`, "utf8");
+		written.push(manualOutFile);
+	}
+	return written;
 }
 /**
 * Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,

package/dist/test-runner/report.js.map

@@ -1 +1 @@
-{"version":3,"file":"report.js","names":[],"sources":["../../src/test-runner/report.ts"],"sourcesContent":["/**\n * Runner-agnostic report serialisation for env3 test runs (devtools#696).\n *\n * Both env3 execution paths — the Vitest custom pool (`pool.ts`) and the\n * standalone `devtools-test` CLI (`cli.ts`) — call the same core\n * `runTestFilesOverRelay` and so produce the same {@link RelayRunReport}. This\n * module is the single, runner-neutral place that turns that in-memory report\n * into a stable on-disk artifact so a 2.x run and a 3.0 run can be diffed\n * cell-by-cell after the fact.\n *\n * The serialised schema is deliberately MINIMAL and secret-free:\n *\n *   - file paths are stored RELATIVE to `projectRoot` (no absolute `/Users/...`\n *     leakage — see {@link RunnerAgnosticReport.files});\n *   - the cell metadata (sdkLine/platform) is baked INTO the body, not only the\n *     filename, so a moved artifact never loses its provenance;\n *   - NO relay wss / scheme / TOTP / relayUrl fields exist in the schema at all\n *     (enforced by the type + this comment) — error strings are the matcher\n *     message only, inherited from rpc.ts which already strips expression/value.\n *\n * react-free — depends only on the type-level `RelayRunReport` and `node:fs` /\n * `node:path`. Safe to bundle without pulling the chii/cloudflared graph.\n */\n\nimport { mkdir, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport type { AitCaptureLine } from './capture.js';\nimport type { RelayRunReport } from './relay-worker.js';\nimport type { TestResult } from './runtime.js';\n\n/** The cell axes a report is stamped with — the test-matrix coordinates. */\nexport interface ReportCellMeta {\n  /** SDK line under test (e.g. `'2.x'` / `'3.x'`). */\n  sdkLine: string;\n  /** Platform under test (e.g. `'ios'` / `'android'` / `'mock'`). */\n  platform: string;\n  /**\n   * Project root the run was launched from. Used ONLY to relativise file paths\n   * out of the serialised report — never stored in the output. SECRET-HANDLING:\n   * absolute project paths must not leak into artifacts.\n   */\n  projectRoot: string;\n}\n\n/** Per-file slice of a {@link RunnerAgnosticReport}. */\nexport interface RunnerAgnosticFileReport {\n  /**\n   * Test file path, RELATIVE to `projectRoot`. Never absolute — `path.relative`\n   * strips the machine-specific prefix so the artifact is portable and leaks no\n   * local filesystem layout.\n   */\n  file: string;\n  /** Whole-file bundle/inject error (matcher message only), when the file failed. */\n  error?: string;\n  /** In-page run duration (ms) for this file, when it ran. */\n  duration?: number;\n  passed?: number;\n  failed?: number;\n  skipped?: number;\n  /** Per-test results, when the file ran. Error strings are matcher messages only. */\n  tests?: TestResult[];\n}\n\n/**\n * The runner-neutral, secret-free report written to disk. There are\n * intentionally NO wss/scheme/TOTP/relayUrl fields on this type — the absence is\n * load-bearing (SECRET-HANDLING) and must not be \"completed\" by a future edit.\n */\nexport interface RunnerAgnosticReport {\n  /** Cell axes this run belongs to — baked into the body for portability. */\n  cell: { sdkLine: string; platform: string };\n  /** ISO timestamp of when the run started (from the core report). */\n  startedAt: string;\n  /** Total wall-clock ms (bundling + sequential injection). */\n  duration: number;\n  /** Flattened totals across all files. */\n  totals: RelayRunReport['totals'];\n  /** Per-file results with projectRoot-relative paths. */\n  files: RunnerAgnosticFileReport[];\n}\n\n/**\n * Converts an absolute (or already-relative) file path to a projectRoot-relative\n * one. `path.relative` returns `''` when the paths are equal — guard that to the\n * basename so the field is never empty.\n *\n * SECRET-HANDLING: this is the single choke point that strips absolute project\n * paths from the artifact.\n */\nfunction relativise(projectRoot: string, file: string): string {\n  const rel = path.relative(projectRoot, file);\n  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {\n    // Outside the project root (or equal) — fall back to the basename rather\n    // than emitting an absolute or `../../..` traversal path.\n    return path.basename(file);\n  }\n  return rel;\n}\n\n/**\n * Serialises a {@link RelayRunReport} into the runner-agnostic, secret-free\n * on-disk shape. Pure — no IO; testable with a plain report + meta.\n *\n * @param report - The core relay run report.\n * @param meta   - Cell axes + projectRoot (projectRoot is consumed, not stored).\n */\nexport function serializeRelayReport(\n  report: RelayRunReport,\n  meta: ReportCellMeta,\n): RunnerAgnosticReport {\n  return {\n    cell: { sdkLine: meta.sdkLine, platform: meta.platform },\n    startedAt: report.startedAt,\n    duration: report.duration,\n    totals: report.totals,\n    files: report.files.map((f): RunnerAgnosticFileReport => {\n      const file = relativise(meta.projectRoot, f.file);\n      if ('error' in f.result) {\n        // Matcher/inject error message only — rpc.ts already stripped the\n        // expression/value upstream.\n        return { file, error: f.result.error };\n      }\n      return {\n        file,\n        duration: f.result.duration,\n        passed: f.result.passed,\n        failed: f.result.failed,\n        skipped: f.result.skipped,\n        tests: f.result.tests,\n      };\n    }),\n  };\n}\n\n/**\n * Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating\n * `dir` if needed. Returns the absolute path written.\n *\n * The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as\n * distinct artifacts in the same directory; the same cell metadata is also baked\n * into the body so a renamed/moved file still carries its provenance.\n *\n * SECRET-HANDLING: the written body contains no relay/secret fields (the schema\n * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.\n *\n * @param report - The core relay run report.\n * @param dir    - Output directory (created recursively if missing).\n * @param meta   - Cell axes + projectRoot.\n * @returns The absolute path of the written file.\n */\nexport async function writeReportArtifact(\n  report: RelayRunReport,\n  dir: string,\n  meta: ReportCellMeta,\n): Promise<string> {\n  const serialised = serializeRelayReport(report, meta);\n  await mkdir(dir, { recursive: true });\n  const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);\n  await writeFile(outFile, `${JSON.stringify(serialised, null, 2)}\\n`, 'utf8');\n  return outFile;\n}\n\n/**\n * Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,\n * named `<category>.<sdkLine>.<platform>.json` — the SAME convention\n * sdk-example's env1 `flushCapture` uses on the filesystem, so env1 and env3\n * capture artifacts line up for diffing.\n *\n * Each line's `json` payload is an opaque JSON array of capture records. Lines\n * sharing a category are concatenated into one array, in harvest order.\n *\n * SECRET-HANDLING: only allowlist-prefixed capture lines reach here (the parser\n * dropped wss/scheme noise); the `json` payload is written verbatim but is a\n * capture record array, not a relay/secret.\n *\n * @param captures - Parsed capture lines (from `RelayRunReport.captures`).\n * @param dir      - Output directory (created recursively if missing).\n * @param cell     - Cell axes for the filename suffix.\n * @returns The absolute paths written (one per category), in category order.\n */\nexport async function writeCaptureArtifacts(\n  captures: ReadonlyArray<AitCaptureLine>,\n  dir: string,\n  cell: { sdkLine: string; platform: string },\n): Promise<string[]> {\n  if (captures.length === 0) return [];\n\n  // Group payloads by category, preserving harvest order. Each payload is an\n  // opaque JSON array string; concatenate parsed arrays under the same category.\n  const byCategory = new Map<string, unknown[]>();\n  for (const { category, json } of captures) {\n    let merged = byCategory.get(category);\n    if (!merged) {\n      merged = [];\n      byCategory.set(category, merged);\n    }\n    // The parser already validated `json` parses; an array payload is expected.\n    const parsed = JSON.parse(json) as unknown;\n    if (Array.isArray(parsed)) {\n      merged.push(...parsed);\n    } else {\n      merged.push(parsed);\n    }\n  }\n\n  await mkdir(dir, { recursive: true });\n  const written: string[] = [];\n  for (const [category, records] of byCategory) {\n    const outFile = path.join(dir, `${category}.${cell.sdkLine}.${cell.platform}.json`);\n    await writeFile(outFile, `${JSON.stringify(records, null, 2)}\\n`, 'utf8');\n    written.push(outFile);\n  }\n  return written;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyFA,SAAS,WAAW,aAAqB,MAAsB;CAC7D,MAAM,MAAM,KAAK,SAAS,aAAa,KAAK;AAC5C,KAAI,QAAQ,MAAM,IAAI,WAAW,KAAK,IAAI,KAAK,WAAW,IAAI,CAG5D,QAAO,KAAK,SAAS,KAAK;AAE5B,QAAO;;;;;;;;;AAUT,SAAgB,qBACd,QACA,MACsB;AACtB,QAAO;EACL,MAAM;GAAE,SAAS,KAAK;GAAS,UAAU,KAAK;GAAU;EACxD,WAAW,OAAO;EAClB,UAAU,OAAO;EACjB,QAAQ,OAAO;EACf,OAAO,OAAO,MAAM,KAAK,MAAgC;GACvD,MAAM,OAAO,WAAW,KAAK,aAAa,EAAE,KAAK;AACjD,OAAI,WAAW,EAAE,OAGf,QAAO;IAAE;IAAM,OAAO,EAAE,OAAO;IAAO;AAExC,UAAO;IACL;IACA,UAAU,EAAE,OAAO;IACnB,QAAQ,EAAE,OAAO;IACjB,QAAQ,EAAE,OAAO;IACjB,SAAS,EAAE,OAAO;IAClB,OAAO,EAAE,OAAO;IACjB;IACD;EACH;;;;;;;;;;;;;;;;;;AAmBH,eAAsB,oBACpB,QACA,KACA,MACiB;CACjB,MAAM,aAAa,qBAAqB,QAAQ,KAAK;AACrD,OAAM,MAAM,KAAK,EAAE,WAAW,MAAM,CAAC;CACrC,MAAM,UAAU,KAAK,KAAK,KAAK,GAAG,KAAK,QAAQ,GAAG,KAAK,SAAS,OAAO;AACvE,OAAM,UAAU,SAAS,GAAG,KAAK,UAAU,YAAY,MAAM,EAAE,CAAC,KAAK,OAAO;AAC5E,QAAO;;;;;;;;;;;;;;;;;;;;AAqBT,eAAsB,sBACpB,UACA,KACA,MACmB;AACnB,KAAI,SAAS,WAAW,EAAG,QAAO,EAAE;CAIpC,MAAM,6BAAa,IAAI,KAAwB;AAC/C,MAAK,MAAM,EAAE,UAAU,UAAU,UAAU;EACzC,IAAI,SAAS,WAAW,IAAI,SAAS;AACrC,MAAI,CAAC,QAAQ;AACX,YAAS,EAAE;AACX,cAAW,IAAI,UAAU,OAAO;;EAGlC,MAAM,SAAS,KAAK,MAAM,KAAK;AAC/B,MAAI,MAAM,QAAQ,OAAO,CACvB,QAAO,KAAK,GAAG,OAAO;MAEtB,QAAO,KAAK,OAAO;;AAIvB,OAAM,MAAM,KAAK,EAAE,WAAW,MAAM,CAAC;CACrC,MAAM,UAAoB,EAAE;AAC5B,MAAK,MAAM,CAAC,UAAU,YAAY,YAAY;EAC5C,MAAM,UAAU,KAAK,KAAK,KAAK,GAAG,SAAS,GAAG,KAAK,QAAQ,GAAG,KAAK,SAAS,OAAO;AACnF,QAAM,UAAU,SAAS,GAAG,KAAK,UAAU,SAAS,MAAM,EAAE,CAAC,KAAK,OAAO;AACzE,UAAQ,KAAK,QAAQ;;AAEvB,QAAO"}
+{"version":3,"file":"report.js","names":[],"sources":["../../src/test-runner/report.ts"],"sourcesContent":["/**\n * Runner-agnostic report serialisation for env3 test runs (devtools#696).\n *\n * Both env3 execution paths — the Vitest custom pool (`pool.ts`) and the\n * standalone `devtools-test` CLI (`cli.ts`) — call the same core\n * `runTestFilesOverRelay` and so produce the same {@link RelayRunReport}. This\n * module is the single, runner-neutral place that turns that in-memory report\n * into a stable on-disk artifact so a 2.x run and a 3.0 run can be diffed\n * cell-by-cell after the fact.\n *\n * The serialised schema is deliberately MINIMAL and secret-free:\n *\n *   - file paths are stored RELATIVE to `projectRoot` (no absolute `/Users/...`\n *     leakage — see {@link RunnerAgnosticReport.files});\n *   - the cell metadata (sdkLine/platform) is baked INTO the body, not only the\n *     filename, so a moved artifact never loses its provenance;\n *   - NO relay wss / scheme / TOTP / relayUrl fields exist in the schema at all\n *     (enforced by the type + this comment) — error strings are the matcher\n *     message only, inherited from rpc.ts which already strips expression/value.\n *\n * react-free — depends only on the type-level `RelayRunReport` and `node:fs` /\n * `node:path`. Safe to bundle without pulling the chii/cloudflared graph.\n */\n\nimport { mkdir, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\nimport type { AitCaptureLine } from './capture.js';\nimport type { RelayRunReport } from './relay-worker.js';\nimport type { TestResult } from './runtime.js';\n\n/** The cell axes a report is stamped with — the test-matrix coordinates. */\nexport interface ReportCellMeta {\n  /** SDK line under test (e.g. `'2.x'` / `'3.x'`). */\n  sdkLine: string;\n  /** Platform under test (e.g. `'ios'` / `'android'` / `'mock'`). */\n  platform: string;\n  /**\n   * Project root the run was launched from. Used ONLY to relativise file paths\n   * out of the serialised report — never stored in the output. SECRET-HANDLING:\n   * absolute project paths must not leak into artifacts.\n   */\n  projectRoot: string;\n}\n\n/** Per-file slice of a {@link RunnerAgnosticReport}. */\nexport interface RunnerAgnosticFileReport {\n  /**\n   * Test file path, RELATIVE to `projectRoot`. Never absolute — `path.relative`\n   * strips the machine-specific prefix so the artifact is portable and leaks no\n   * local filesystem layout.\n   */\n  file: string;\n  /** Whole-file bundle/inject error (matcher message only), when the file failed. */\n  error?: string;\n  /** In-page run duration (ms) for this file, when it ran. */\n  duration?: number;\n  passed?: number;\n  failed?: number;\n  skipped?: number;\n  /** Per-test results, when the file ran. Error strings are matcher messages only. */\n  tests?: TestResult[];\n  /**\n   * Present + `'manual'` only when this file ran under `--manual-blocking`\n   * (devtools#741) — human-attended, real native envelopes. Absent (never\n   * `false`) for unattended files: absence-means-unattended is the contract,\n   * mirroring `FileResult.mode` in relay-worker.ts. A manual-stamped record\n   * must never be diffed against an unattended one as if equivalent.\n   */\n  mode?: 'manual';\n}\n\n/**\n * The runner-neutral, secret-free report written to disk. There are\n * intentionally NO wss/scheme/TOTP/relayUrl fields on this type — the absence is\n * load-bearing (SECRET-HANDLING) and must not be \"completed\" by a future edit.\n */\nexport interface RunnerAgnosticReport {\n  /** Cell axes this run belongs to — baked into the body for portability. */\n  cell: { sdkLine: string; platform: string };\n  /** ISO timestamp of when the run started (from the core report). */\n  startedAt: string;\n  /** Total wall-clock ms (bundling + sequential injection). */\n  duration: number;\n  /** Flattened totals across all files. */\n  totals: RelayRunReport['totals'];\n  /** Per-file results with projectRoot-relative paths. */\n  files: RunnerAgnosticFileReport[];\n  /**\n   * Permission-state preflight result (devtools#739), mirrored verbatim from\n   * `RelayRunReport.preflight` — see that field's docblock. Absent when the\n   * preflight did not complete (non-fatal; the run still succeeds). No\n   * secrets — permission-state strings only.\n   */\n  preflight?: { permissions: Record<string, string> };\n}\n\n/**\n * Converts an absolute (or already-relative) file path to a projectRoot-relative\n * one. `path.relative` returns `''` when the paths are equal — guard that to the\n * basename so the field is never empty.\n *\n * SECRET-HANDLING: this is the single choke point that strips absolute project\n * paths from the artifact.\n */\nfunction relativise(projectRoot: string, file: string): string {\n  const rel = path.relative(projectRoot, file);\n  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {\n    // Outside the project root (or equal) — fall back to the basename rather\n    // than emitting an absolute or `../../..` traversal path.\n    return path.basename(file);\n  }\n  return rel;\n}\n\n/**\n * Serialises a {@link RelayRunReport} into the runner-agnostic, secret-free\n * on-disk shape. Pure — no IO; testable with a plain report + meta.\n *\n * @param report - The core relay run report.\n * @param meta   - Cell axes + projectRoot (projectRoot is consumed, not stored).\n */\nexport function serializeRelayReport(\n  report: RelayRunReport,\n  meta: ReportCellMeta,\n): RunnerAgnosticReport {\n  return {\n    cell: { sdkLine: meta.sdkLine, platform: meta.platform },\n    startedAt: report.startedAt,\n    duration: report.duration,\n    totals: report.totals,\n    ...(report.preflight ? { preflight: report.preflight } : {}),\n    files: report.files.map((f): RunnerAgnosticFileReport => {\n      const file = relativise(meta.projectRoot, f.file);\n      const modeField = f.mode === 'manual' ? ({ mode: 'manual' } as const) : {};\n      if ('error' in f.result) {\n        // Matcher/inject error message only — rpc.ts already stripped the\n        // expression/value upstream.\n        return { file, error: f.result.error, ...modeField };\n      }\n      return {\n        file,\n        duration: f.result.duration,\n        passed: f.result.passed,\n        failed: f.result.failed,\n        skipped: f.result.skipped,\n        tests: f.result.tests,\n        ...modeField,\n      };\n    }),\n  };\n}\n\n/**\n * Writes the serialised report to `<dir>/<sdkLine>.<platform>.json`, creating\n * `dir` if needed. Returns the absolute path(s) written.\n *\n * The cell-suffixed filename keeps 2.x and 3.0 (and per-platform) runs as\n * distinct artifacts in the same directory; the same cell metadata is also baked\n * into the body so a renamed/moved file still carries its provenance.\n *\n * Manual-run provenance (devtools#741): when `report.files` contains ANY\n * `mode: 'manual'` entry (i.e. this run included `--manual-blocking` files),\n * the manual-tagged files are written to a SEPARATE\n * `<dir>/<sdkLine>.<platform>.manual.json` artifact instead of the standard\n * one — the standard `<sdkLine>.<platform>.json` filename is reserved for the\n * regular (unattended) files only, so a manual run's presence never mutates\n * what the unattended-baseline filename means. If ALL files in the run are\n * regular, only the standard artifact is written (today's behavior,\n * unchanged). If a run mixes both (regular files + `--manual-blocking`\n * scheduled last), BOTH artifacts are written — the manual one ALONGSIDE, not\n * replacing, the standard one.\n *\n * SECRET-HANDLING: the written body contains no relay/secret fields (the schema\n * has none). `dir`/`projectRoot` are local filesystem paths, never logged here.\n *\n * @param report - The core relay run report.\n * @param dir    - Output directory (created recursively if missing).\n * @param meta   - Cell axes + projectRoot.\n * @returns The absolute path(s) written, in order: standard first (if any\n *   regular files ran), then manual (if any manual files ran). At least one\n *   path is always returned when `report.files` is non-empty.\n */\nexport async function writeReportArtifact(\n  report: RelayRunReport,\n  dir: string,\n  meta: ReportCellMeta,\n): Promise<string[]> {\n  const serialised = serializeRelayReport(report, meta);\n  await mkdir(dir, { recursive: true });\n\n  const regularFiles = serialised.files.filter((f) => f.mode !== 'manual');\n  const manualFiles = serialised.files.filter((f) => f.mode === 'manual');\n\n  const written: string[] = [];\n\n  // Standard artifact: written whenever there are regular files, OR when the\n  // whole run is empty (preserves the pre-#741 \"always write one file\"\n  // behavior for a run with zero files, e.g. an empty glob match).\n  if (regularFiles.length > 0 || serialised.files.length === 0) {\n    const outFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.json`);\n    await writeFile(\n      outFile,\n      `${JSON.stringify({ ...serialised, files: regularFiles }, null, 2)}\\n`,\n      'utf8',\n    );\n    written.push(outFile);\n  }\n\n  if (manualFiles.length > 0) {\n    const manualOutFile = path.join(dir, `${meta.sdkLine}.${meta.platform}.manual.json`);\n    await writeFile(\n      manualOutFile,\n      `${JSON.stringify({ ...serialised, files: manualFiles }, null, 2)}\\n`,\n      'utf8',\n    );\n    written.push(manualOutFile);\n  }\n\n  return written;\n}\n\n/**\n * Writes harvested `__AIT_CAPTURE__` lines to per-category files under `dir`,\n * named `<category>.<sdkLine>.<platform>.json` — the SAME convention\n * sdk-example's env1 `flushCapture` uses on the filesystem, so env1 and env3\n * capture artifacts line up for diffing.\n *\n * Each line's `json` payload is an opaque JSON array of capture records. Lines\n * sharing a category are concatenated into one array, in harvest order.\n *\n * SECRET-HANDLING: only allowlist-prefixed capture lines reach here (the parser\n * dropped wss/scheme noise); the `json` payload is written verbatim but is a\n * capture record array, not a relay/secret.\n *\n * @param captures - Parsed capture lines (from `RelayRunReport.captures`).\n * @param dir      - Output directory (created recursively if missing).\n * @param cell     - Cell axes for the filename suffix.\n * @returns The absolute paths written (one per category), in category order.\n */\nexport async function writeCaptureArtifacts(\n  captures: ReadonlyArray<AitCaptureLine>,\n  dir: string,\n  cell: { sdkLine: string; platform: string },\n): Promise<string[]> {\n  if (captures.length === 0) return [];\n\n  // Group payloads by category, preserving harvest order. Each payload is an\n  // opaque JSON array string; concatenate parsed arrays under the same category.\n  const byCategory = new Map<string, unknown[]>();\n  for (const { category, json } of captures) {\n    let merged = byCategory.get(category);\n    if (!merged) {\n      merged = [];\n      byCategory.set(category, merged);\n    }\n    // The parser already validated `json` parses; an array payload is expected.\n    const parsed = JSON.parse(json) as unknown;\n    if (Array.isArray(parsed)) {\n      merged.push(...parsed);\n    } else {\n      merged.push(parsed);\n    }\n  }\n\n  await mkdir(dir, { recursive: true });\n  const written: string[] = [];\n  for (const [category, records] of byCategory) {\n    const outFile = path.join(dir, `${category}.${cell.sdkLine}.${cell.platform}.json`);\n    await writeFile(outFile, `${JSON.stringify(records, null, 2)}\\n`, 'utf8');\n    written.push(outFile);\n  }\n  return written;\n}\n"],"mappings":"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"}

package/dist/{totp-DvOYkYim.js → totp-CZLLKfOC.js}

@@ -1,18 +1,6 @@
 #!/usr/bin/env node
-import "node:module";
+import { t as __exportAll } from "./rolldown-runtime-DGkTqVfb.js";
 import { createHmac, timingSafeEqual } from "node:crypto";
-//#region \0rolldown/runtime.js
-var __defProp = Object.defineProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-//#endregion
 //#region src/mcp/totp.ts
 /**
 * RFC 6238 TOTP implementation (Node.js, node:crypto only).
@@ -209,4 +197,4 @@ function buildRelayVerifyAuth(env = process.env) {
 //#endregion
 export { totp_exports as i, buildRelayVerifyAuth as n, generateTotp as r, assertRelayAuthConfigured as t };
 
-//# sourceMappingURL=totp-DvOYkYim.js.map
+//# sourceMappingURL=totp-CZLLKfOC.js.map

package/dist/{totp-DvOYkYim.js.map → totp-CZLLKfOC.js.map}

@@ -1 +1 @@
-{"version":3,"file":"totp-DvOYkYim.js","names":[],"sources":["../src/mcp/totp.ts"],"sourcesContent":["/**\n * RFC 6238 TOTP implementation (Node.js, node:crypto only).\n *\n * External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used\n * to keep the dependency surface minimal. This hand-roll is ~30 lines and\n * covers exactly what relay-side auth needs.\n *\n * Algorithm summary (RFC 6238 + RFC 4226):\n *   T  = floor(now / 30)          — 30-second time step counter\n *   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)\n *   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)\n *   offset = MAC[19] & 0x0f\n *   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits\n *\n * Security note (keep this comment accurate):\n *   The baked-in secret in a dog-food build is extractable from the bundle by a\n *   determined reverse engineer. This mechanism raises the bar from\n *   \"anyone with the URL\" to \"URL + bundle extraction + live TOTP calculation\".\n *   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are\n *   blocked; deliberate reverse engineering is not. See threat model in\n *   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.\n *\n * SECRET-HANDLING: secret values and computed codes MUST NOT appear in any\n * log, error message, or string visible outside this module. Only boolean\n * pass/fail and reason enum values are safe to surface.\n */\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** Time step window in seconds (RFC 6238 default). */\nconst TIME_STEP = 30;\n\n/** Number of digits in the generated code. */\nconst DIGITS = 6;\n\n/**\n * Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-\n * clock time.\n *\n * @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32\n *   bytes). Must be the output of `generateAttachToken()` or compatible.\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @returns A zero-padded 6-digit decimal string, e.g. `\"042193\"`.\n */\nexport function generateTotp(secret: string, when: number = Date.now()): string {\n  const key = Buffer.from(secret, 'hex');\n  // Clamp to 0 so negative timestamps (e.g. in ±skew checks near epoch) do not\n  // produce a negative counter, which would cause writeUInt32BE to throw.\n  const counter = Math.max(0, Math.floor(when / 1000 / TIME_STEP));\n\n  // Encode counter as 8-byte big-endian unsigned integer.\n  const counterBuf = Buffer.alloc(8);\n  // JavaScript numbers are safe integers up to 2^53; counter is ~7.5×10^10 at\n  // year 9999 — well within safe range so standard bitwise ops are fine.\n  const hi = Math.floor(counter / 0x100000000);\n  const lo = counter >>> 0;\n  counterBuf.writeUInt32BE(hi, 0);\n  counterBuf.writeUInt32BE(lo, 4);\n\n  const mac = createHmac('sha1', key).update(counterBuf).digest();\n\n  // Dynamic truncation (RFC 4226 §5.4).\n  const offset = mac[19] & 0x0f;\n  const binCode =\n    ((mac[offset] & 0x7f) << 24) |\n    ((mac[offset + 1] & 0xff) << 16) |\n    ((mac[offset + 2] & 0xff) << 8) |\n    (mac[offset + 3] & 0xff);\n\n  const otp = binCode % 10 ** DIGITS;\n  return otp.toString().padStart(DIGITS, '0');\n}\n\n/**\n * Verifies a TOTP code against the secret, accepting ±`skew` time steps to\n * tolerate clock drift between the relay host and the client device.\n *\n * Uses `timingSafeEqual` for constant-time comparison to prevent timing\n * side-channel attacks.\n *\n * @param secret - Hex-encoded shared secret.\n * @param code - The 6-digit code to verify (string or numeric).\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @param skew - Number of adjacent steps to accept on either side. Default 1\n *   (accepts T-1, T, T+1 — a 90-second acceptance window).\n * @returns `true` if the code matches any accepted step, `false` otherwise.\n */\nexport function verifyTotp(\n  secret: string,\n  code: string,\n  when: number = Date.now(),\n  skew: number = 1,\n): boolean {\n  const normalised = String(code).padStart(DIGITS, '0');\n  if (normalised.length !== DIGITS || !/^\\d{6}$/.test(normalised)) {\n    return false;\n  }\n\n  const candidateBuf = Buffer.from(normalised, 'utf8');\n\n  for (let delta = -skew; delta <= skew; delta++) {\n    const stepWhen = when + delta * TIME_STEP * 1000;\n    const expected = generateTotp(secret, stepWhen);\n    const expectedBuf = Buffer.from(expected, 'utf8');\n    if (timingSafeEqual(expectedBuf, candidateBuf)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.\n *\n * The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,\n * 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key\n * we are willing to gate a public relay behind. `generateAttachToken()` emits\n * 64 hex chars (32 bytes), comfortably above this bar.\n */\nconst MIN_SECRET_HEX_CHARS = 32;\n\n/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */\nconst HEX_RE = /^[0-9a-fA-F]+$/;\n\n/**\n * Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.\n *\n * SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and\n * how to mint one. It NEVER echoes the configured value, its length, or any\n * fragment derived from it — see {@link assertRelayAuthConfigured}.\n *\n * Note on encoding: the secret is hex (base16), not base32 — `generateTotp`\n * decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be\n * silently mis-decoded and every TOTP code would fail to match, so the minting\n * command emits hex.\n */\nexport const RELAY_AUTH_SECRET_MISSING_MESSAGE = [\n  '[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.',\n  '발급: openssl rand -hex 32',\n  '데몬은 start_debug의 projectRoot 인자로 받은 디렉토리에서 .ait_relay 파일을 읽어 이 시크릿을 채웁니다.',\n  '프로젝트에서 pnpm dev:phone:cdp를 한 번 띄우면 unplugin이 .ait_relay를 자동 생성하니(tunnel.cdp 옵션 필요), projectRoot를 전달하세요.',\n  '자세히: https://docs.aitc.dev/guides/relay-auth-totp',\n].join('\\n');\n\n/**\n * Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at\n * least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd\n * length would have its trailing nibble silently dropped by `Buffer.from(...,\n * 'hex')`, weakening the key without warning).\n *\n * Pure predicate so callers can test the validation independently of the\n * fail-fast side effect in {@link assertRelayAuthConfigured}.\n *\n * SECRET-HANDLING: returns only a boolean — the input value is never returned,\n * logged, or echoed.\n */\nexport function isValidRelayAuthSecret(secret: string | undefined): secret is string {\n  if (secret === undefined || secret === '') return false;\n  if (secret.length < MIN_SECRET_HEX_CHARS) return false;\n  if (secret.length % 2 !== 0) return false;\n  return HEX_RE.test(secret);\n}\n\n/**\n * Fail-fast guard enforcing that a relay-auth TOTP secret is configured before\n * a public-internet-exposed relay is booted (issue #250).\n *\n * Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes\n * the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third\n * party attach a debugger to a dog-food/live mini-app. Without a secret the relay\n * comes up unauthenticated, so this guard is called at every relay-boot site —\n * `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),\n * both eager and lazy. Local-only sessions never boot a relay and so never reach\n * this guard, matching the issue's exemption for non-relay debugging.\n *\n * Throws when the secret is unset, empty, too short, or not a valid hex string.\n * The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)\n * — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.\n *\n * SECRET-HANDLING: the env value is read once, passed ONLY to the boolean\n * predicate, and never logged. The thrown message names the requirement, never\n * the value, its length, or any derived fragment.\n *\n * @param env - Environment to read from. Defaults to `process.env`; injectable\n *   for tests so they never mutate the real process environment.\n */\nexport function assertRelayAuthConfigured(env: NodeJS.ProcessEnv = process.env): void {\n  if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) {\n    throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);\n  }\n}\n\n/**\n * Gate-specific skew for the relay WebSocket upgrade TOTP check.\n *\n * Rationale (why 6, not the RFC default of 1):\n *   - Each step is 30 s, so ±6 steps = past 6 steps accepted = 180–210 s of\n *     backwards acceptance. This means a code generated at issuance time is\n *     guaranteed valid for at least 3 minutes (180 s) after it was minted.\n *   - The real-world attach flow (QR issued on desktop → developer picks up\n *     phone → camera scan → launcher PWA loads → attach) routinely exceeds\n *     the 90 s window of the RFC default (skew=1), especially when the launcher\n *     PWA needs to reinstall or when the phone is not immediately at hand.\n *   - Expanding to ~3.5 min reachability is acceptable under the §4 threat\n *     model: the adversary we guard against is \"someone who got the URL but\n *     does NOT have the secret\". Without the secret they cannot compute a TOTP\n *     code regardless of the window size — security theater is explicitly\n *     forbidden by the project principle. An attacker WITH the secret (bundle\n *     extractor) is out of scope per CLAUDE.md §4.\n *\n * `verifyTotp`'s own default (skew=1) is deliberately left unchanged — it is\n * the RFC primitive. Only this relay-gate call site is widened.\n */\nexport const RELAY_VERIFY_SKEW_STEPS = 6;\n\n/**\n * Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a\n * `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.\n *\n * The predicate checks the `at` query parameter against the current and\n * adjacent TOTP time steps (±{@link RELAY_VERIFY_SKEW_STEPS} skew) using\n * {@link verifyTotp}. This gives the issued code a minimum validity of ~3\n * minutes, which is enough to cover the QR-scan → launcher-attach flow even\n * when the launcher PWA needs to load or reinstall (#490).\n *\n * Returns `undefined` when the env var is not set — callers treat that as\n * \"auth disabled\" (no predicate registered on the relay). Note that since\n * issue #250 the secret is MANDATORY at every relay-boot site (enforced by\n * {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production\n * this never returns `undefined` for a relay that actually boots; the\n * `undefined` branch only matters for the no-relay local path and tests.\n *\n * Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the\n * same gate without importing the heavy MCP server module graph. Re-exported\n * from `debug-server.ts` for back-compat.\n *\n * SECRET-HANDLING: The secret value read from env is captured in a closure and\n * is NEVER written to any log, error message, or process output.\n */\nexport function buildRelayVerifyAuth(\n  env: NodeJS.ProcessEnv = process.env,\n): ((req: import('node:http').IncomingMessage) => boolean) | undefined {\n  const secret = env.AIT_DEBUG_TOTP_SECRET;\n  if (!secret) return undefined;\n\n  return (req) => {\n    // Parse the `at` query param from the upgrade request URL.\n    // req.url is the raw request path + query, e.g. `/client/id?target=…&at=123456`\n    const rawUrl = req.url ?? '';\n    const qIndex = rawUrl.indexOf('?');\n    const queryStr = qIndex === -1 ? '' : rawUrl.slice(qIndex + 1);\n    const params = new URLSearchParams(queryStr);\n    const code = params.get('at') ?? '';\n\n    // Do NOT log `code`, `secret`, or any derived value here.\n    // Use RELAY_VERIFY_SKEW_STEPS (±6) for a ~3-minute acceptance window (#490).\n    // verifyTotp's own default (skew=1) is unchanged — only this call site is widened.\n    return verifyTotp(secret, code, undefined, RELAY_VERIFY_SKEW_STEPS);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAM,YAAY;;AAGlB,MAAM,SAAS;;;;;;;;;;AAWf,SAAgB,aAAa,QAAgB,OAAe,KAAK,KAAK,EAAU;CAC9E,MAAM,MAAM,OAAO,KAAK,QAAQ,MAAM;CAGtC,MAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,MAAO,UAAU,CAAC;CAGhE,MAAM,aAAa,OAAO,MAAM,EAAE;CAGlC,MAAM,KAAK,KAAK,MAAM,UAAU,WAAY;CAC5C,MAAM,KAAK,YAAY;AACvB,YAAW,cAAc,IAAI,EAAE;AAC/B,YAAW,cAAc,IAAI,EAAE;CAE/B,MAAM,MAAM,WAAW,QAAQ,IAAI,CAAC,OAAO,WAAW,CAAC,QAAQ;CAG/D,MAAM,SAAS,IAAI,MAAM;AAQzB,WANI,IAAI,UAAU,QAAS,MACvB,IAAI,SAAS,KAAK,QAAS,MAC3B,IAAI,SAAS,KAAK,QAAS,IAC5B,IAAI,SAAS,KAAK,OAEC,MAAM,QACjB,UAAU,CAAC,SAAS,QAAQ,IAAI;;;;;;;;;;;;;;;;AAiB7C,SAAgB,WACd,QACA,MACA,OAAe,KAAK,KAAK,EACzB,OAAe,GACN;CACT,MAAM,aAAa,OAAO,KAAK,CAAC,SAAS,QAAQ,IAAI;AACrD,KAAI,WAAW,WAAW,UAAU,CAAC,UAAU,KAAK,WAAW,CAC7D,QAAO;CAGT,MAAM,eAAe,OAAO,KAAK,YAAY,OAAO;AAEpD,MAAK,IAAI,QAAQ,CAAC,MAAM,SAAS,MAAM,SAAS;EAE9C,MAAM,WAAW,aAAa,QADb,OAAO,QAAQ,YAAY,IACG;AAE/C,MAAI,gBADgB,OAAO,KAAK,UAAU,OAAO,EAChB,aAAa,CAC5C,QAAO;;AAIX,QAAO;;;;;;;;;;AAWT,MAAM,uBAAuB;;AAG7B,MAAM,SAAS;;;;;;;;;;;;;AAcf,MAAa,oCAAoC;CAC/C;CACA;CACA;CACA;CACA;CACD,CAAC,KAAK,KAAK;;;;;;;;;;;;;AAcZ,SAAgB,uBAAuB,QAA8C;AACnF,KAAI,WAAW,KAAA,KAAa,WAAW,GAAI,QAAO;AAClD,KAAI,OAAO,SAAS,qBAAsB,QAAO;AACjD,KAAI,OAAO,SAAS,MAAM,EAAG,QAAO;AACpC,QAAO,OAAO,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5B,SAAgB,0BAA0B,MAAyB,QAAQ,KAAW;AACpF,KAAI,CAAC,uBAAuB,IAAI,sBAAsB,CACpD,OAAM,IAAI,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDtD,SAAgB,qBACd,MAAyB,QAAQ,KACoC;CACrE,MAAM,SAAS,IAAI;AACnB,KAAI,CAAC,OAAQ,QAAO,KAAA;AAEpB,SAAQ,QAAQ;EAGd,MAAM,SAAS,IAAI,OAAO;EAC1B,MAAM,SAAS,OAAO,QAAQ,IAAI;EAClC,MAAM,WAAW,WAAW,KAAK,KAAK,OAAO,MAAM,SAAS,EAAE;AAO9D,SAAO,WAAW,QANH,IAAI,gBAAgB,SAAS,CACxB,IAAI,KAAK,IAAI,IAKD,KAAA,GAAA,EAAmC"}
+{"version":3,"file":"totp-CZLLKfOC.js","names":[],"sources":["../src/mcp/totp.ts"],"sourcesContent":["/**\n * RFC 6238 TOTP implementation (Node.js, node:crypto only).\n *\n * External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used\n * to keep the dependency surface minimal. This hand-roll is ~30 lines and\n * covers exactly what relay-side auth needs.\n *\n * Algorithm summary (RFC 6238 + RFC 4226):\n *   T  = floor(now / 30)          — 30-second time step counter\n *   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)\n *   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)\n *   offset = MAC[19] & 0x0f\n *   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits\n *\n * Security note (keep this comment accurate):\n *   The baked-in secret in a dog-food build is extractable from the bundle by a\n *   determined reverse engineer. This mechanism raises the bar from\n *   \"anyone with the URL\" to \"URL + bundle extraction + live TOTP calculation\".\n *   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are\n *   blocked; deliberate reverse engineering is not. See threat model in\n *   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.\n *\n * SECRET-HANDLING: secret values and computed codes MUST NOT appear in any\n * log, error message, or string visible outside this module. Only boolean\n * pass/fail and reason enum values are safe to surface.\n */\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** Time step window in seconds (RFC 6238 default). */\nconst TIME_STEP = 30;\n\n/** Number of digits in the generated code. */\nconst DIGITS = 6;\n\n/**\n * Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-\n * clock time.\n *\n * @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32\n *   bytes). Must be the output of `generateAttachToken()` or compatible.\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @returns A zero-padded 6-digit decimal string, e.g. `\"042193\"`.\n */\nexport function generateTotp(secret: string, when: number = Date.now()): string {\n  const key = Buffer.from(secret, 'hex');\n  // Clamp to 0 so negative timestamps (e.g. in ±skew checks near epoch) do not\n  // produce a negative counter, which would cause writeUInt32BE to throw.\n  const counter = Math.max(0, Math.floor(when / 1000 / TIME_STEP));\n\n  // Encode counter as 8-byte big-endian unsigned integer.\n  const counterBuf = Buffer.alloc(8);\n  // JavaScript numbers are safe integers up to 2^53; counter is ~7.5×10^10 at\n  // year 9999 — well within safe range so standard bitwise ops are fine.\n  const hi = Math.floor(counter / 0x100000000);\n  const lo = counter >>> 0;\n  counterBuf.writeUInt32BE(hi, 0);\n  counterBuf.writeUInt32BE(lo, 4);\n\n  const mac = createHmac('sha1', key).update(counterBuf).digest();\n\n  // Dynamic truncation (RFC 4226 §5.4).\n  const offset = mac[19] & 0x0f;\n  const binCode =\n    ((mac[offset] & 0x7f) << 24) |\n    ((mac[offset + 1] & 0xff) << 16) |\n    ((mac[offset + 2] & 0xff) << 8) |\n    (mac[offset + 3] & 0xff);\n\n  const otp = binCode % 10 ** DIGITS;\n  return otp.toString().padStart(DIGITS, '0');\n}\n\n/**\n * Verifies a TOTP code against the secret, accepting ±`skew` time steps to\n * tolerate clock drift between the relay host and the client device.\n *\n * Uses `timingSafeEqual` for constant-time comparison to prevent timing\n * side-channel attacks.\n *\n * @param secret - Hex-encoded shared secret.\n * @param code - The 6-digit code to verify (string or numeric).\n * @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.\n * @param skew - Number of adjacent steps to accept on either side. Default 1\n *   (accepts T-1, T, T+1 — a 90-second acceptance window).\n * @returns `true` if the code matches any accepted step, `false` otherwise.\n */\nexport function verifyTotp(\n  secret: string,\n  code: string,\n  when: number = Date.now(),\n  skew: number = 1,\n): boolean {\n  const normalised = String(code).padStart(DIGITS, '0');\n  if (normalised.length !== DIGITS || !/^\\d{6}$/.test(normalised)) {\n    return false;\n  }\n\n  const candidateBuf = Buffer.from(normalised, 'utf8');\n\n  for (let delta = -skew; delta <= skew; delta++) {\n    const stepWhen = when + delta * TIME_STEP * 1000;\n    const expected = generateTotp(secret, stepWhen);\n    const expectedBuf = Buffer.from(expected, 'utf8');\n    if (timingSafeEqual(expectedBuf, candidateBuf)) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Minimum length (in hex characters) accepted for `AIT_DEBUG_TOTP_SECRET`.\n *\n * The secret is hex-encoded (see {@link generateTotp} — `Buffer.from(secret,\n * 'hex')`). 32 hex chars = 16 bytes = 128 bits, the floor for an HMAC-SHA1 key\n * we are willing to gate a public relay behind. `generateAttachToken()` emits\n * 64 hex chars (32 bytes), comfortably above this bar.\n */\nconst MIN_SECRET_HEX_CHARS = 32;\n\n/** Hex string: one or more hex digits, case-insensitive (RFC 4648 base16). */\nconst HEX_RE = /^[0-9a-fA-F]+$/;\n\n/**\n * Human-facing guidance printed when {@link assertRelayAuthConfigured} fails.\n *\n * SECRET-HANDLING: this message states only the REQUIREMENT (≥32 hex chars) and\n * how to mint one. It NEVER echoes the configured value, its length, or any\n * fragment derived from it — see {@link assertRelayAuthConfigured}.\n *\n * Note on encoding: the secret is hex (base16), not base32 — `generateTotp`\n * decodes it with `Buffer.from(secret, 'hex')`. A base32 string would be\n * silently mis-decoded and every TOTP code would fail to match, so the minting\n * command emits hex.\n */\nexport const RELAY_AUTH_SECRET_MISSING_MESSAGE = [\n  '[ait-debug] AIT_DEBUG_TOTP_SECRET이 필수입니다. 32자 이상 16진수(hex) 문자열을 설정하세요.',\n  '발급: openssl rand -hex 32',\n  '데몬은 start_debug의 projectRoot 인자로 받은 디렉토리에서 .ait_relay 파일을 읽어 이 시크릿을 채웁니다.',\n  '프로젝트에서 pnpm dev:phone:cdp를 한 번 띄우면 unplugin이 .ait_relay를 자동 생성하니(tunnel.cdp 옵션 필요), projectRoot를 전달하세요.',\n  '자세히: https://docs.aitc.dev/guides/relay-auth-totp',\n].join('\\n');\n\n/**\n * Whether `secret` is a well-formed relay-auth TOTP secret: a hex string of at\n * least {@link MIN_SECRET_HEX_CHARS} characters with an even length (an odd\n * length would have its trailing nibble silently dropped by `Buffer.from(...,\n * 'hex')`, weakening the key without warning).\n *\n * Pure predicate so callers can test the validation independently of the\n * fail-fast side effect in {@link assertRelayAuthConfigured}.\n *\n * SECRET-HANDLING: returns only a boolean — the input value is never returned,\n * logged, or echoed.\n */\nexport function isValidRelayAuthSecret(secret: string | undefined): secret is string {\n  if (secret === undefined || secret === '') return false;\n  if (secret.length < MIN_SECRET_HEX_CHARS) return false;\n  if (secret.length % 2 !== 0) return false;\n  return HEX_RE.test(secret);\n}\n\n/**\n * Fail-fast guard enforcing that a relay-auth TOTP secret is configured before\n * a public-internet-exposed relay is booted (issue #250).\n *\n * Relay-auth (the §4 Layer C TOTP gate) is the only fail-fast layer that closes\n * the real gap: a leaked `wss://…trycloudflare.com` URL otherwise lets a third\n * party attach a debugger to a dog-food/live mini-app. Without a secret the relay\n * comes up unauthenticated, so this guard is called at every relay-boot site —\n * `bootRelayFamily` (intoss env 3/4) and `bootExternalRelayFamily` (env-2 PWA),\n * both eager and lazy. Local-only sessions never boot a relay and so never reach\n * this guard, matching the issue's exemption for non-relay debugging.\n *\n * Throws when the secret is unset, empty, too short, or not a valid hex string.\n * The thrown message is the bin entry's fatal stderr (see `cli.ts` `main().catch`)\n * — the same fatal model as the missing-`AIT_RELAY_BASE_URL` path.\n *\n * SECRET-HANDLING: the env value is read once, passed ONLY to the boolean\n * predicate, and never logged. The thrown message names the requirement, never\n * the value, its length, or any derived fragment.\n *\n * @param env - Environment to read from. Defaults to `process.env`; injectable\n *   for tests so they never mutate the real process environment.\n */\nexport function assertRelayAuthConfigured(env: NodeJS.ProcessEnv = process.env): void {\n  if (!isValidRelayAuthSecret(env.AIT_DEBUG_TOTP_SECRET)) {\n    throw new Error(RELAY_AUTH_SECRET_MISSING_MESSAGE);\n  }\n}\n\n/**\n * Gate-specific skew for the relay WebSocket upgrade TOTP check.\n *\n * Rationale (why 6, not the RFC default of 1):\n *   - Each step is 30 s, so ±6 steps = past 6 steps accepted = 180–210 s of\n *     backwards acceptance. This means a code generated at issuance time is\n *     guaranteed valid for at least 3 minutes (180 s) after it was minted.\n *   - The real-world attach flow (QR issued on desktop → developer picks up\n *     phone → camera scan → launcher PWA loads → attach) routinely exceeds\n *     the 90 s window of the RFC default (skew=1), especially when the launcher\n *     PWA needs to reinstall or when the phone is not immediately at hand.\n *   - Expanding to ~3.5 min reachability is acceptable under the §4 threat\n *     model: the adversary we guard against is \"someone who got the URL but\n *     does NOT have the secret\". Without the secret they cannot compute a TOTP\n *     code regardless of the window size — security theater is explicitly\n *     forbidden by the project principle. An attacker WITH the secret (bundle\n *     extractor) is out of scope per CLAUDE.md §4.\n *\n * `verifyTotp`'s own default (skew=1) is deliberately left unchanged — it is\n * the RFC primitive. Only this relay-gate call site is widened.\n */\nexport const RELAY_VERIFY_SKEW_STEPS = 6;\n\n/**\n * Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a\n * `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.\n *\n * The predicate checks the `at` query parameter against the current and\n * adjacent TOTP time steps (±{@link RELAY_VERIFY_SKEW_STEPS} skew) using\n * {@link verifyTotp}. This gives the issued code a minimum validity of ~3\n * minutes, which is enough to cover the QR-scan → launcher-attach flow even\n * when the launcher PWA needs to load or reinstall (#490).\n *\n * Returns `undefined` when the env var is not set — callers treat that as\n * \"auth disabled\" (no predicate registered on the relay). Note that since\n * issue #250 the secret is MANDATORY at every relay-boot site (enforced by\n * {@link assertRelayAuthConfigured} BEFORE the relay starts), so in production\n * this never returns `undefined` for a relay that actually boots; the\n * `undefined` branch only matters for the no-relay local path and tests.\n *\n * Lives here (not in the MCP server) so the unplugin's env-2 relay can wire the\n * same gate without importing the heavy MCP server module graph. Re-exported\n * from `debug-server.ts` for back-compat.\n *\n * SECRET-HANDLING: The secret value read from env is captured in a closure and\n * is NEVER written to any log, error message, or process output.\n */\nexport function buildRelayVerifyAuth(\n  env: NodeJS.ProcessEnv = process.env,\n): ((req: import('node:http').IncomingMessage) => boolean) | undefined {\n  const secret = env.AIT_DEBUG_TOTP_SECRET;\n  if (!secret) return undefined;\n\n  return (req) => {\n    // Parse the `at` query param from the upgrade request URL.\n    // req.url is the raw request path + query, e.g. `/client/id?target=…&at=123456`\n    const rawUrl = req.url ?? '';\n    const qIndex = rawUrl.indexOf('?');\n    const queryStr = qIndex === -1 ? '' : rawUrl.slice(qIndex + 1);\n    const params = new URLSearchParams(queryStr);\n    const code = params.get('at') ?? '';\n\n    // Do NOT log `code`, `secret`, or any derived value here.\n    // Use RELAY_VERIFY_SKEW_STEPS (±6) for a ~3-minute acceptance window (#490).\n    // verifyTotp's own default (skew=1) is unchanged — only this call site is widened.\n    return verifyTotp(secret, code, undefined, RELAY_VERIFY_SKEW_STEPS);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8BA,MAAM,YAAY;;AAGlB,MAAM,SAAS;;;;;;;;;;AAWf,SAAgB,aAAa,QAAgB,OAAe,KAAK,KAAK,EAAU;CAC9E,MAAM,MAAM,OAAO,KAAK,QAAQ,MAAM;CAGtC,MAAM,UAAU,KAAK,IAAI,GAAG,KAAK,MAAM,OAAO,MAAO,UAAU,CAAC;CAGhE,MAAM,aAAa,OAAO,MAAM,EAAE;CAGlC,MAAM,KAAK,KAAK,MAAM,UAAU,WAAY;CAC5C,MAAM,KAAK,YAAY;AACvB,YAAW,cAAc,IAAI,EAAE;AAC/B,YAAW,cAAc,IAAI,EAAE;CAE/B,MAAM,MAAM,WAAW,QAAQ,IAAI,CAAC,OAAO,WAAW,CAAC,QAAQ;CAG/D,MAAM,SAAS,IAAI,MAAM;AAQzB,WANI,IAAI,UAAU,QAAS,MACvB,IAAI,SAAS,KAAK,QAAS,MAC3B,IAAI,SAAS,KAAK,QAAS,IAC5B,IAAI,SAAS,KAAK,OAEC,MAAM,QACjB,UAAU,CAAC,SAAS,QAAQ,IAAI;;;;;;;;;;;;;;;;AAiB7C,SAAgB,WACd,QACA,MACA,OAAe,KAAK,KAAK,EACzB,OAAe,GACN;CACT,MAAM,aAAa,OAAO,KAAK,CAAC,SAAS,QAAQ,IAAI;AACrD,KAAI,WAAW,WAAW,UAAU,CAAC,UAAU,KAAK,WAAW,CAC7D,QAAO;CAGT,MAAM,eAAe,OAAO,KAAK,YAAY,OAAO;AAEpD,MAAK,IAAI,QAAQ,CAAC,MAAM,SAAS,MAAM,SAAS;EAE9C,MAAM,WAAW,aAAa,QADb,OAAO,QAAQ,YAAY,IACG;AAE/C,MAAI,gBADgB,OAAO,KAAK,UAAU,OAAO,EAChB,aAAa,CAC5C,QAAO;;AAIX,QAAO;;;;;;;;;;AAWT,MAAM,uBAAuB;;AAG7B,MAAM,SAAS;;;;;;;;;;;;;AAcf,MAAa,oCAAoC;CAC/C;CACA;CACA;CACA;CACA;CACD,CAAC,KAAK,KAAK;;;;;;;;;;;;;AAcZ,SAAgB,uBAAuB,QAA8C;AACnF,KAAI,WAAW,KAAA,KAAa,WAAW,GAAI,QAAO;AAClD,KAAI,OAAO,SAAS,qBAAsB,QAAO;AACjD,KAAI,OAAO,SAAS,MAAM,EAAG,QAAO;AACpC,QAAO,OAAO,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5B,SAAgB,0BAA0B,MAAyB,QAAQ,KAAW;AACpF,KAAI,CAAC,uBAAuB,IAAI,sBAAsB,CACpD,OAAM,IAAI,MAAM,kCAAkC;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDtD,SAAgB,qBACd,MAAyB,QAAQ,KACoC;CACrE,MAAM,SAAS,IAAI;AACnB,KAAI,CAAC,OAAQ,QAAO,KAAA;AAEpB,SAAQ,QAAQ;EAGd,MAAM,SAAS,IAAI,OAAO;EAC1B,MAAM,SAAS,OAAO,QAAQ,IAAI;EAClC,MAAM,WAAW,WAAW,KAAK,KAAK,OAAO,MAAM,SAAS,EAAE;AAO9D,SAAO,WAAW,QANH,IAAI,gBAAgB,SAAS,CACxB,IAAI,KAAK,IAAI,IAKD,KAAA,GAAA,EAAmC"}