@ait-co/devtools 0.1.127 → 0.1.129

package/dist/debug-server-Bu3pCG9c.js

@@ -0,0 +1,436 @@
+import { n as buildRelayVerifyAuth, t as assertRelayAuthConfigured } from "./totp-DfekTBk3.js";
+import { a as RELAY_AUTH_REJECT_CLOSE_CODE, i as ChiiCdpConnection, o as RELAY_AUTH_REJECT_REASON } from "./relay-worker-Bt0QYKQH.js";
+import { n as logInfo, t as logError } from "./log-CUik_tHp.js";
+import "./relay-factory-Ck3vBonr.js";
+import { a as startTunnelHealthProbe, i as startQuickTunnel, n as makeTunnelStatus, r as printAttachBanner, t as generateAttachToken } from "./attach-orchestrator-DvrgUIx7.js";
+import "./cell-DA_lcpDI.js";
+import "./qr-http-server-HANhOFwI.js";
+import "./relay-secret-store-DzxDsK6S.js";
+import { createRequire } from "node:module";
+import "node:events";
+import { WebSocketServer } from "ws";
+import "@modelcontextprotocol/sdk/server/index.js";
+import "@modelcontextprotocol/sdk/server/stdio.js";
+import "@modelcontextprotocol/sdk/types.js";
+import { createServer } from "node:http";
+`
+devtools-test — run mini-app tests on a real device WebView over the CDP relay
+
+USAGE
+  devtools-test <glob> [<glob> ...] [options]
+
+OPTIONS
+  --scheme-url <url>      intoss-private:// URL from \`ait deploy --scheme-only\`
+                          (required for standalone relay attach / env3)
+  --timeout <ms>          Per-file evaluate timeout in ms (default: 60000).
+                          Controls how long a single test file is allowed to run
+                          before it is considered hung. Does NOT affect how long
+                          the CLI waits for a human to scan the QR code — use
+                          --attach-timeout for that.
+  --attach-timeout <ms>   How long to wait for a human to scan the QR code with
+                          their phone (default: 600000 — 10 minutes). Omit to
+                          use the relay factory's generous default. Decrease for
+                          CI environments where a scan should arrive quickly.
+  --cell-sdk-line <line>  SDK line to inject as __AIT_CELL__.sdkLine (2.x|3.x)
+  --cell-platform <plat>  Platform to inject as __AIT_CELL__.platform
+                          (mock|ios|android, default: AIT_CELL_PLATFORM env)
+  --report-dir <dir>      Persist a runner-agnostic report + captures to <dir>
+                          (report: <sdkLine>.<platform>.json; captures:
+                          <dir>/.ait-capture/<category>.<sdkLine>.<platform>.json).
+                          Omitted = nothing saved. Enables console capture.
+  --no-qr-stdout          Suppress the QR/attach block on stdout (auto-on for
+                          non-interactive stdout / CI / AIT_NO_QR_STDOUT)
+  --headless              Disable browser auto-open (text QR only)
+  --project-root <dir>    Project root for .ait_relay secret lookup
+                          (default: current working directory)
+  --help, -h              Show this help message
+
+DESCRIPTION
+  Boots a Chii relay + cloudflared tunnel, renders a QR code, waits for a real
+  device to scan and attach, injects the cell globals (__AIT_CELL__), bundles
+  each matched test file with esbuild (SDK imports redirected to window.__sdk),
+  injects the bundle into the attached WebView via Runtime.evaluate, and prints
+  a summary.
+
+  With --report-dir, also harvests __AIT_CAPTURE__ console lines and writes a
+  runner-agnostic report + per-category capture files so 2.x↔3.0 runs can be
+  compared offline.
+
+  The test files run against the live relay connection started by this process;
+  no separate MCP daemon is required.
+
+EXAMPLE
+  devtools-test 'src/**/*.ait.test.ts' \\
+    --scheme-url "intoss-private://..." \\
+    --cell-sdk-line 3.x \\
+    --cell-platform ios \\
+    --report-dir .ait-report \\
+    --timeout 60000
+
+`.trimStart();
+//#endregion
+//#region src/mcp/chii-relay.ts
+/**
+* Boots the local Chii relay server.
+*
+* Chii (liriliri/chii) is a chobitsu-based CDP relay that lets non-Chrome
+* WebViews (iOS WKWebView / Android WebView — i.e. the Toss app) expose CDP.
+* The relay accepts a `target` websocket from the phone's injected `target.js`
+* and `client` websockets from CDP frontends (our MCP connection).
+*
+* Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app
+* entries.
+*
+* TOTP auth (relay-side, authoritative gate):
+*   When `verifyAuth` is provided, this module gates both inbound surfaces:
+*
+*   - HTTP 'request': a listener registered BEFORE `chii.start({server})`.
+*     Node's `http.Server` calls listeners in registration order; the first
+*     to call `res.end()` wins. Invalid auth → 401 + CORS header + a tiny
+*     JSON body (`{"error":"totp-rejected"}`) so a cross-origin script
+*     `fetch()` probe can READ the status (issue #478). Valid auth → return
+*     without side-effect (chii's Koa handler serves it).
+*
+*   - WS 'upgrade': after `chii.start()` has registered chii's own upgrade
+*     listener, we take over the upgrade chain (remove chii's listeners,
+*     re-dispatch manually). Invalid auth → accept-then-close: complete the
+*     handshake via a `noServer` WebSocketServer, then immediately close
+*     with code 4401 reason 'totp-rejected' (issue #478). A raw 401 +
+*     `socket.destroy()` only ever surfaced as close code 1006 in the
+*     browser — indistinguishable from a tunnel failure, which left the
+*     env-2 phone UI silent. The explicit dispatch (not listener ordering)
+*     is what keeps chii away from rejected sockets: accept-then-close
+*     leaves the socket alive, so an order-based early-return would let
+*     chii's later listener complete a SECOND handshake on the same socket
+*     — an auth bypass. Valid auth → forward to chii's captured listeners.
+*
+* TOTP code transports (issue #466) — two equivalent ways to carry the code:
+*   1. Query param `at=<code>` — used by the daemon-side `/client` connection
+*      (`chii-connection.ts` appends it; it holds the secret).
+*   2. Path prefix `/at/<code>/…` — used by the phone-side target. Chii's
+*      stock `target.js` derives its WS endpoint from the script `src`
+*      (`scriptEl.src.replace('target.js','')`), so the only way for the
+*      phone to carry a code is to embed it in the script URL path. The
+*      in-app attach injects `https://<host>/at/<code>/target.js`; both the
+*      script fetch and the derived `wss://<host>/at/<code>/target/<id>` WS
+*      dial then carry the prefix. The listeners below rewrite the prefix
+*      into the query form (`rewriteAtPathPrefix`) and MUTATE `req.url`
+*      before chii's own handlers (registered later) parse it — chii only
+*      ever sees the stripped URL.
+*
+* Threat model: "URL leak" — someone obtains the tunnel URL (Slack paste, QR
+*   screenshot, shoulder-surfing) but does not have the shared TOTP secret.
+*   Rotating 6-digit code makes the URL stale after 30 s.
+*   A determined attacker who extracts the secret from the dogfood bundle can
+*   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).
+*
+* SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear
+*   in any log, error message, or process output. `verifyAuth` is a black-box
+*   predicate from the caller's perspective; this module only forwards pass/fail.
+*/
+const require = createRequire(import.meta.url);
+/**
+* WS keepalive ping interval (ms).
+*
+* Cloudflare proxied connections are dropped after ~100 s of no traffic.
+* 45 s comfortably fits inside that window and lets both the phone-target leg
+* and the daemon-client leg survive idle CDP sessions.
+*/
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 45e3;
+/**
+* Loads chii's internal WebSocketServer class and returns it together with a
+* flag indicating whether the real class was found.
+*
+* Returns `null` if the internal path is not resolvable (future chii release
+* changes the layout) — callers skip keepalive gracefully.
+*/
+function tryLoadChiiWssClass() {
+	try {
+		const mod = require("chii/server/lib/WebSocketServer");
+		if (typeof mod === "function") return mod;
+	} catch {}
+	return null;
+}
+/**
+* Calls `chii.start()` and returns the chii `WebSocketServer` instance that
+* was constructed during the call.
+*
+* How: `chii/server/index.js`'s `start()` creates `new WebSocketServer()`
+* where `WebSocketServer` is captured from `require('./lib/WebSocketServer')`
+* at module load time. The class reference is stable, so we can temporarily
+* patch `ChiiWssClass.prototype.start` — which runs *on the instance* —
+* to record `this` before the original `start` runs.
+*
+* The patch is installed before `chii.start()` and removed (via `finally`)
+* immediately after, so concurrent `startChiiRelay` calls nest correctly: each
+* call's patch overrides the previous in the prototype chain for the duration
+* of its own `chii.start()` call, restoring the prior descriptor on exit.
+*
+* If `ChiiWssClass` is null (internal path changed in a future chii release),
+* `chii.start()` runs unpatched and the function returns null — callers skip
+* keepalive gracefully without affecting relay correctness.
+*/
+async function startChiiWithCapture(chii, startOptions, ChiiWssClass) {
+	if (ChiiWssClass === null) {
+		await chii.start(startOptions);
+		return null;
+	}
+	let captured = null;
+	const proto = ChiiWssClass.prototype;
+	const originalStart = proto.start;
+	proto.start = function(server) {
+		captured = this;
+		return originalStart.call(this, server);
+	};
+	try {
+		await chii.start(startOptions);
+	} finally {
+		proto.start = originalStart;
+	}
+	return captured;
+}
+function loadChiiServer() {
+	const mod = require("chii");
+	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
+	throw new Error("chii server module did not expose start()");
+}
+/**
+* Rewrites a `/at/<code>/…` path-prefixed request URL into the equivalent
+* query-based form, e.g.:
+*
+*   `/at/123456/target.js`        → `/target.js?at=123456`
+*   `/at/123456/target/x?url=u`   → `/target/x?url=u&at=123456`
+*   `/at/123456/`                 → `/?at=123456`
+*
+* Returns `null` when the URL does not carry the prefix (including an empty
+* code segment) — callers fall back to the unmodified URL and the existing
+* query-based auth path.
+*
+* Pure string surgery — this function knows nothing about secrets or code
+* validity; verification stays inside the caller-provided `verifyAuth`
+* predicate (which parses the query). The raw path segment is appended
+* verbatim to the query: both path segments and query values are
+* percent-decoded exactly once by their consumers, so no re-encoding is
+* needed (TOTP codes are 6 digits and never percent-encoded in practice).
+*/
+function rewriteAtPathPrefix(rawUrl) {
+	const match = /^\/at\/([^/?]+)(\/[^?]*)?(\?.*)?$/.exec(rawUrl);
+	if (match === null) return null;
+	const code = match[1];
+	const path = match[2] === void 0 || match[2] === "" ? "/" : match[2];
+	const query = match[3] ?? "";
+	return `${path}${query}${query === "" ? "?" : "&"}at=${code}`;
+}
+/**
+* Starts the Chii relay and resolves once listening.
+*
+* Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral
+* port on every start, so a stale cloudflared orphan holding any particular
+* port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`
+* always reflect the actual bound port.
+*
+* chii.start() is called with `server` (our pre-created httpServer) BEFORE
+* httpServer.listen(). This is intentional: chii attaches its Koa handler and
+* WS upgrade listener to the server object, but the actual TCP bind is
+* performed by our httpServer.listen() call below. The `port`/`domain` values
+* passed to chii.start() are used for display/banner purposes inside chii and
+* do not affect which port the server binds. The connection path (clients
+* connecting to `relay.baseUrl`) always uses the post-listen confirmed port.
+*/
+async function startChiiRelay(options = {}) {
+	const requestedPort = options.port ?? 0;
+	const host = options.host ?? "127.0.0.1";
+	const { verifyAuth, onAuthReject } = options;
+	const keepaliveIntervalMs = options.keepaliveIntervalMs !== void 0 ? options.keepaliveIntervalMs : DEFAULT_KEEPALIVE_INTERVAL_MS;
+	const httpServer = createServer();
+	const notifyAuthReject = (kind) => {
+		if (onAuthReject === void 0) return;
+		try {
+			onAuthReject({ kind });
+		} catch {}
+	};
+	if (verifyAuth) httpServer.on("request", (req, res) => {
+		const rewritten = rewriteAtPathPrefix(req.url ?? "");
+		if (rewritten !== null) {
+			req.url = rewritten;
+			if (!verifyAuth(req)) {
+				res.statusCode = 401;
+				res.setHeader("Access-Control-Allow-Origin", "*");
+				res.setHeader("Content-Type", "application/json");
+				res.end(JSON.stringify({ error: RELAY_AUTH_REJECT_REASON }));
+				notifyAuthReject("http-request");
+			}
+			return;
+		}
+		const pathname = (req.url ?? "").split("?")[0];
+		if (pathname === "/targets" || pathname === "/targets/") {
+			if (!verifyAuth(req)) {
+				res.statusCode = 401;
+				res.setHeader("Access-Control-Allow-Origin", "*");
+				res.setHeader("Content-Type", "application/json");
+				res.end(JSON.stringify({ error: RELAY_AUTH_REJECT_REASON }));
+				notifyAuthReject("http-request");
+				return;
+			}
+			return;
+		}
+	});
+	const chiiWssClass = keepaliveIntervalMs > 0 ? tryLoadChiiWssClass() : null;
+	const capturedChiiWss = await startChiiWithCapture(loadChiiServer(), {
+		server: httpServer,
+		domain: `${host}:${requestedPort}`,
+		port: requestedPort
+	}, chiiWssClass);
+	if (verifyAuth) {
+		const chiiUpgradeListeners = httpServer.listeners("upgrade");
+		httpServer.removeAllListeners("upgrade");
+		const rejectWss = new WebSocketServer({ noServer: true });
+		httpServer.on("upgrade", (req, socket, head) => {
+			const rewritten = rewriteAtPathPrefix(req.url ?? "");
+			if (rewritten !== null) req.url = rewritten;
+			if (!verifyAuth(req)) {
+				rejectWss.handleUpgrade(req, socket, head, (ws) => {
+					ws.close(RELAY_AUTH_REJECT_CLOSE_CODE, RELAY_AUTH_REJECT_REASON);
+				});
+				notifyAuthReject("ws-upgrade");
+				return;
+			}
+			for (const listener of chiiUpgradeListeners) listener(req, socket, head);
+		});
+	}
+	const actualPort = await new Promise((resolve, reject) => {
+		httpServer.once("error", reject);
+		httpServer.listen(requestedPort, host, () => {
+			httpServer.off("error", reject);
+			resolve(httpServer.address().port);
+		});
+	});
+	let keepaliveHandle = null;
+	if (keepaliveIntervalMs > 0 && capturedChiiWss !== null) {
+		const chiiWss = capturedChiiWss;
+		keepaliveHandle = setInterval(() => {
+			for (const client of chiiWss._wss.clients) if (client.readyState === 1) client.ping();
+		}, keepaliveIntervalMs);
+	}
+	return {
+		port: actualPort,
+		baseUrl: `http://${host}:${actualPort}`,
+		close: () => new Promise((resolve) => {
+			if (keepaliveHandle !== null) {
+				clearInterval(keepaliveHandle);
+				keepaliveHandle = null;
+			}
+			httpServer.close(() => resolve());
+		})
+	};
+}
+//#endregion
+//#region src/mcp/debug-server.ts
+/**
+* Factory that constructs a `ChiiCdpConnection` for the given relay base URL.
+*
+* Introduced as a named seam so PR-2 (dual-connection, #348) can defer
+* construction to first-activation time by moving or replacing this call. Since
+* #396 every family (relay included) is constructed lazily on its first
+* `start_debug`, so this is always called from the lazy boot path.
+*
+* The relay base URL is only available after `startChiiRelay()` resolves, so
+* the factory is called right after that point (same as before this refactor).
+*/
+function createRelayConnection(relayBaseUrl) {
+	return new ChiiCdpConnection({
+		relayBaseUrl,
+		totpSecret: process.env.AIT_DEBUG_TOTP_SECRET
+	});
+}
+/**
+* Boots the relay family (issues #348, #356): starts the Chii relay on an
+* OS-assigned port (with optional TOTP gate), opens a cloudflared quick tunnel
+* to the relay's confirmed port in the background, prints the attach banner,
+* and arms the tunnel health probe. Returns a {@link BootedFamily} whose
+* `getTunnelStatus()` reflects the live tunnel (it flips up once the background
+* tunnel resolves and follows reissues).
+*
+* Booted lazily via the dual router's `bootLazyFor('relay-intoss')` callback
+* (symmetry with {@link bootLocalFamily}), at most once on the first
+* `start_debug({ mode: 'relay-staging' })` (all-lazy, #396 — every relay boot now
+* flows through `switchMode` after the project-local secret load). `relay-live`
+* removed (#665).
+*
+* The relay base URL is only known after `startChiiRelay()` resolves, so the
+* `ChiiCdpConnection` (via {@link createRelayConnection}) is constructed inside
+* this function, after the relay port is confirmed.
+*
+* SECRET-HANDLING: the TOTP secret rides only inside `verifyAuth`; the wssUrl
+* (relay host) is never logged here directly.
+*/
+async function bootRelayFamily(options = {}) {
+	assertRelayAuthConfigured();
+	const relayPort = options.relayPort ?? 0;
+	const totpEnabled = options.verifyAuth !== void 0;
+	const relay = await startChiiRelay({
+		port: relayPort,
+		verifyAuth: options.verifyAuth,
+		onAuthReject: options.onAuthReject
+	});
+	logInfo("server.start", {
+		port: relay.port,
+		totpEnabled
+	});
+	let tunnel = null;
+	let tunnelStatus = makeTunnelStatus(false, null);
+	let tunnelProbe = null;
+	generateAttachToken();
+	startQuickTunnel(relay.port).then((t) => {
+		tunnel = t;
+		tunnelStatus = makeTunnelStatus(true, t.wssUrl);
+		options.onWssUrl?.(t.wssUrl);
+		if (t.childPid !== void 0) options.onTunnelChildPid?.(t.childPid);
+		logInfo("tunnel.up", { totpEnabled });
+		tunnelProbe = startTunnelHealthProbe(t, relay.port, {
+			onReissue: (newTunnel) => {
+				tunnel = newTunnel;
+				tunnelStatus = makeTunnelStatus(true, newTunnel.wssUrl, null, 0);
+				options.onWssUrl?.(newTunnel.wssUrl);
+				if (newTunnel.childPid !== void 0) options.onTunnelChildPid?.(newTunnel.childPid);
+				printAttachBanner({
+					wssUrl: newTunnel.wssUrl,
+					totpEnabled
+				}).then(() => {
+					logInfo("tunnel.up", {
+						totpEnabled,
+						reissued: true
+					});
+				});
+			},
+			onPermanentDrop: (droppedAt) => {
+				tunnelStatus = makeTunnelStatus(false, null, droppedAt, 3);
+				logError("tunnel.down", { msg: `tunnel permanently dropped (${droppedAt}). Restart: npx @ait-co/devtools devtools-mcp` });
+				options.onTunnelDown?.();
+			}
+		});
+		return printAttachBanner({
+			wssUrl: t.wssUrl,
+			totpEnabled
+		});
+	}, (err) => {
+		logError("tunnel.down", { msg: `Failed to open cloudflared quick tunnel: ${err instanceof Error ? err.message : String(err)}. The relay is up locally; attach over the public URL is unavailable until the tunnel starts.` });
+	});
+	const connection = createRelayConnection(relay.baseUrl);
+	return {
+		connection,
+		relayOrigin: "intoss-webview",
+		relayHttpUrl: relay.baseUrl,
+		getTunnelStatus: () => tunnelStatus,
+		stop() {
+			tunnelProbe?.stop();
+			tunnel?.stop();
+			connection.close();
+			relay.close();
+		}
+	};
+}
+//#endregion
+export { bootRelayFamily, buildRelayVerifyAuth };
+
+//# sourceMappingURL=debug-server-Bu3pCG9c.js.map