@ait-co/devtools 0.1.107 → 0.1.109

package/dist/mcp/cli.js

@@ -2,12 +2,17 @@
 import { i as generateTotp, n as assertRelayAuthConfigured, r as buildRelayVerifyAuth } from "../totp-WY6l0ysP.js";
 import { t as loadRelaySecretReadOnly } from "../relay-secret-store-DhzAnnj-.js";
 import { createRequire } from "node:module";
-import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { accessSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { argv } from "node:process";
 import { fileURLToPath } from "node:url";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { parseArgs } from "node:util";
+import * as fs from "node:fs/promises";
+import { glob } from "node:fs/promises";
+import * as path from "node:path";
+import { isAbsolute, join, resolve } from "node:path";
 import { EventEmitter } from "node:events";
 import { WebSocket, WebSocketServer } from "ws";
 import { randomBytes } from "node:crypto";
@@ -15,7 +20,6 @@ import { createServer } from "node:http";
 import { spawn } from "node:child_process";
 import net from "node:net";
 import { homedir, platform } from "node:os";
-import { join } from "node:path";
 import { Tunnel, bin, install } from "cloudflared";
 //#region \0rolldown/runtime.js
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
@@ -119,6 +123,511 @@ function startMaxAgeWatchdog(onExpired, opts = {}) {
 	} };
 }
 //#endregion
+//#region src/test-runner/discover.ts
+/**
+* Test-file discovery shared by the `devtools-test` CLI and the `run_tests`
+* MCP tool, so both expand glob patterns with identical semantics.
+*
+* Uses Node's built-in `fs/promises` `glob` (Node 22+) — no extra dependency,
+* which keeps the MCP daemon install graph lean (a plain glob lib would land in
+* the `npx … devtools-mcp` path for no benefit).
+*
+* Pure Node IO only (`node:fs/promises` + `node:path`) — react-free, so it is
+* safe to import from the MCP daemon graph.
+*/
+/**
+* Expands `patterns` (globs or plain paths) into a sorted, de-duplicated list of
+* ABSOLUTE test file paths, resolved relative to `cwd`.
+*
+* A plain (non-glob) path passes through when it matches a real file; a glob
+* expands against `cwd`. Absolute matches are kept as-is; relative matches are
+* resolved against `cwd`. `bundleTestFile` requires an absolute path, so the
+* absolute output feeds it directly.
+*
+* @param patterns Glob patterns or file paths (e.g. `['src/**\/*.phone.test.ts']`).
+* @param cwd      Base directory for relative patterns/results.
+* @returns Sorted, de-duplicated absolute file paths. Empty when nothing matches.
+*/
+async function discoverTestFiles(patterns, cwd) {
+	const out = /* @__PURE__ */ new Set();
+	for await (const match of glob(patterns, { cwd })) out.add(isAbsolute(match) ? match : resolve(cwd, match));
+	return [...out].sort();
+}
+//#endregion
+//#region src/test-runner/bundle.ts
+/**
+* esbuild-based bundler for user test files.
+*
+* Bundles a single test file into a self-contained IIFE string that can be
+* injected into a WebView via `Runtime.evaluate`. The bundle includes the
+* test runtime (`runtime.ts`), which provides `describe/it/test/expect` and
+* the `runTestModule(factory)` entry point.
+*
+* ## How the wiring works
+*
+* The bundle exposes two exports on `globalThis.__testBundle`:
+*   - `runTestModule` — the runtime's entry function.
+*   - `__userFactory`  — an async function whose body is the user's top-level
+*     test registration code (describe/it/test calls).
+*
+* The Node-side RPC (`rpc.ts`) calls:
+*   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
+*
+* `runTestModule` then installs `describe/it/test/expect` as globals, invokes
+* the factory (which registers all tests), runs them, and returns a `RunReport`.
+*
+* ## Why a factory wrapper is needed
+*
+* Naively adding the runtime to `entryPoints` and bundling the user file would
+* fail for two reasons:
+*   1. `describe/it/test/expect` from the runtime are module-local in the IIFE
+*      scope. The user's top-level `describe(...)` calls expect them as globals —
+*      they are not globals until `runTestModule` installs them.
+*   2. Even with globals pre-installed, the user file runs at IIFE-evaluation
+*      time, before the RPC layer calls `runTestModule` to reset state and start
+*      the test clock.
+*
+* The factory approach solves both: the user's registration code is deferred
+* into a function that `runTestModule` calls AFTER installing the globals.
+*
+* ## Factory extraction algorithm
+*
+* The `userFactoryPlugin` reads the user file and splits lines into:
+*   - **top-level**: `import …` and re-export lines — kept at module scope
+*     (the only valid position for static `import` in ESM).
+*   - **body**: all other statements — moved into the body of the exported
+*     `__userFactory` async function.
+*
+* esbuild processes the re-generated module, following each static import
+* through the normal dependency graph (including the SDK-redirect plugin).
+*
+* ## SDK redirect
+*
+* Imports of `@apps-in-toss/web-framework` (and sub-paths) are intercepted via
+* the `sdkRedirectPlugin` and replaced with a virtual `window.__sdk` proxy that
+* `src/in-app/auto.ts` installs at runtime. This works for both 2.x and 3.x SDK.
+*
+* SECRET-HANDLING: the returned bundle code is caller-managed; never log it.
+*/
+/**
+* Matches the bare SDK package and any sub-path import
+* (`@apps-in-toss/web-framework`, `@apps-in-toss/web-framework/foo`).
+* Built from {@link SDK_PACKAGE} so the package name has a single source.
+*/
+const SDK_IMPORT_FILTER = new RegExp(`^${"@apps-in-toss/web-framework".replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`);
+/**
+* esbuild plugin that intercepts SDK imports and redirects them to the
+* `window.__sdk` proxy that `src/in-app/auto.ts` installs at runtime.
+*
+* Strategy: for every import of `@apps-in-toss/web-framework` (or sub-paths),
+* esbuild resolves it to a virtual module that re-exports all named exports
+* via `window.__sdk[name]`. This avoids bundling the real SDK (which may not
+* be available in the test environment) while still making named imports work.
+*
+* If `window.__sdk` is absent (non-dog-food build), every access throws a
+* descriptive error rather than returning `undefined` silently.
+*/
+function sdkRedirectPlugin() {
+	return {
+		name: "sdk-redirect",
+		setup(build) {
+			build.onResolve({ filter: SDK_IMPORT_FILTER }, (args) => ({
+				path: args.path,
+				namespace: "sdk-redirect"
+			}));
+			build.onLoad({
+				filter: /.*/,
+				namespace: "sdk-redirect"
+			}, () => ({
+				contents: `
+var __proxy = (typeof window !== 'undefined' && window.__sdk)
+  ? window.__sdk
+  : new Proxy({}, {
+      get: function(_t, p) {
+        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));
+      }
+    });
+module.exports = __proxy;
+`,
+				loader: "js"
+			}));
+		}
+	};
+}
+/**
+* esbuild plugin that transforms the user test file into a module that exports
+* an async `__userFactory` function. The factory defers the user's top-level
+* test registration code (describe/it/test calls) so it only runs when
+* `runTestModule(__userFactory)` explicitly invokes it — AFTER the runtime has
+* installed describe/it/test/expect as globals.
+*
+* Algorithm:
+*   - Lines matching import declarations or re-export statements are kept at
+*     module top-level (the only valid ESM position for static `import`).
+*   - All other lines (describe/it/test calls, local declarations, etc.) are
+*     moved into the body of the exported async factory function.
+*
+* This preserves SDK import resolution (the sdk-redirect plugin processes
+* top-level imports normally) while deferring test registration to the factory.
+*/
+function userFactoryPlugin(absPath) {
+	const NAMESPACE = "user-test-factory";
+	return {
+		name: "user-test-factory",
+		setup(build) {
+			build.onResolve({ filter: /^user-test-factory$/ }, () => ({
+				path: absPath,
+				namespace: NAMESPACE
+			}));
+			build.onLoad({
+				filter: /.*/,
+				namespace: NAMESPACE
+			}, async (args) => {
+				const lines = (await fs.readFile(args.path, "utf8")).split("\n");
+				const topLevelLines = [];
+				const bodyLines = [];
+				const EXPORT_DECLARATION_RE = /^(export\s+)(default\s+|async\s+function\s+|function\s+|class\s+|const\s+|let\s+|var\s+)/;
+				for (const line of lines) {
+					const trimmed = line.trimStart();
+					const indent = line.slice(0, line.length - trimmed.length);
+					if (trimmed.startsWith("import ") || trimmed.startsWith("import{") || trimmed.startsWith("import'") || trimmed.startsWith("import\"")) topLevelLines.push(line);
+					else if (trimmed.startsWith("export ")) if (trimmed.match(EXPORT_DECLARATION_RE)) bodyLines.push(indent + trimmed.slice(7));
+					else topLevelLines.push(line);
+					else bodyLines.push(line);
+				}
+				return {
+					contents: [
+						...topLevelLines,
+						"",
+						"// biome-ignore lint: generated factory wrapper",
+						"export default async function __userFactory(): Promise<void> {",
+						...bodyLines.map((l) => `  ${l}`),
+						"}"
+					].join("\n"),
+					loader: "ts",
+					resolveDir: path.dirname(absPath)
+				};
+			});
+		}
+	};
+}
+/**
+* Returns the absolute path to the co-located runtime module.
+*
+* In the source tree (running via tsx / ts-node) the file is `runtime.ts`.
+* After `tsdown` compiles to `dist/test-runner/`, it becomes `runtime.js`.
+* We try both extensions to support both environments.
+*/
+function getRuntimePath() {
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	for (const ext of [".ts", ".js"]) {
+		const candidate = path.join(dir, `runtime${ext}`);
+		try {
+			accessSync(candidate);
+			return candidate;
+		} catch {}
+	}
+	return path.join(dir, "runtime.js");
+}
+/**
+* Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
+*
+* The IIFE installs `window.__testBundle` (or the custom `globalName`) with:
+*   - `runTestModule` — the runtime entry (from `runtime.ts`).
+*   - `__userFactory` — an async function wrapping the user's test registration
+*     code so it runs AFTER `runTestModule` installs the globals.
+*
+* Callers (rpc.ts) invoke:
+*   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
+*
+* @param absPath - Absolute path to the user test file.
+* @param opts    - Optional bundling overrides.
+*/
+async function bundleTestFile(absPath, opts) {
+	const globalName = opts?.globalName ?? "__testBundle";
+	const extraExternals = opts?.extraExternals ?? [];
+	const esbuild = await import("esbuild");
+	const runtimePath = getRuntimePath();
+	const wrapperContent = [
+		`import { runTestModule } from ${JSON.stringify(runtimePath)};`,
+		`import __userFactory from "user-test-factory";`,
+		`export { runTestModule, __userFactory };`
+	].join("\n");
+	const result = await esbuild.build({
+		stdin: {
+			contents: wrapperContent,
+			loader: "ts",
+			resolveDir: path.dirname(absPath)
+		},
+		bundle: true,
+		format: "iife",
+		globalName,
+		platform: "browser",
+		target: "es2022",
+		write: false,
+		plugins: [userFactoryPlugin(absPath), sdkRedirectPlugin()],
+		external: extraExternals,
+		treeShaking: true,
+		footer: { js: `globalThis[${JSON.stringify(globalName)}] = ${globalName};` }
+	});
+	const warnings = result.warnings.map((w) => `${path.relative(process.cwd(), w.location?.file ?? "")}:${w.location?.line ?? "?"}: ${w.text}`);
+	const outputFile = result.outputFiles?.[0];
+	if (!outputFile) throw new Error("bundleTestFile: esbuild produced no output — check entryPoints");
+	return {
+		code: outputFile.text,
+		warnings
+	};
+}
+//#endregion
+//#region src/test-runner/rpc.ts
+/** Maximum milliseconds to wait for a single evaluate round-trip. */
+const DEFAULT_TIMEOUT_MS = 3e4;
+/**
+* Wraps bundle code in a self-executing IIFE that:
+*   1. Evaluates the bundle (registering describe/it/test).
+*   2. Calls `__testBundle.runTestModule(...)` — the entry the runtime exports.
+*   3. Returns a JSON-serialised `RunReport` string.
+*
+* The double-serialisation (RunReport → JSON string → returnByValue string)
+* is intentional: CDP `returnByValue` reliably transports strings; deeply
+* nested objects can lose fidelity across the Chii relay.
+*
+* SECRET-HANDLING: `bundleCode` MUST NOT be logged by callers.
+*/
+function buildRunTestsExpression(bundleCode) {
+	return `(async () => {  try { ${bundleCode} } catch(e) {    return JSON.stringify({ok:false,error:'bundle-eval: ' + String(e && e.message || e)});  }  if (typeof globalThis.__testBundle !== 'object' || typeof globalThis.__testBundle.runTestModule !== 'function' || typeof globalThis.__testBundle.__userFactory !== 'function') {    return JSON.stringify({ok:false,error:'bundle-missing-export: __testBundle.runTestModule or __userFactory is not a function'});  }  try {    const report = await globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory);    return JSON.stringify({ok:true,value:report});  } catch(e) {    return JSON.stringify({ok:false,error:'test-run: ' + String(e && e.message || e)});  }})()`;
+}
+/**
+* Parses the raw CDP `returnByValue` result from a `buildRunTestsExpression`
+* evaluate call into a typed `RpcRunResult`.
+*
+* Throws only on parse failure — an `ok:false` envelope is a normal result.
+*
+* SECRET-HANDLING: `rawValue` is not included in error messages.
+*/
+function parseRunTestsResult(rawValue) {
+	if (typeof rawValue !== "string") throw new Error(`rpc.parseRunTestsResult: unexpected return type "${typeof rawValue}" — expected JSON string`);
+	let parsed;
+	try {
+		parsed = JSON.parse(rawValue);
+	} catch {
+		throw new Error("rpc.parseRunTestsResult: bridge returned non-JSON string");
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("rpc.parseRunTestsResult: parsed result is not an object");
+	const obj = parsed;
+	if (obj.ok === true) return {
+		ok: true,
+		report: obj.value
+	};
+	if (obj.ok === false) return {
+		ok: false,
+		error: typeof obj.error === "string" ? obj.error : String(obj.error)
+	};
+	throw new Error("rpc.parseRunTestsResult: result missing \"ok\" field");
+}
+/**
+* Injects `bundleCode` into the attached page and awaits test execution.
+*
+* Uses `Runtime.evaluate` with `awaitPromise: true` to wait for the
+* async IIFE to settle.  The 30-second CDP command timeout covers even
+* long-running test suites; split into smaller files if you hit it.
+*
+* @param connection   - Active CDP connection (relay or local).
+* @param bundleCode   - IIFE bundle string from `bundleTestFile`.
+* @param timeoutMs    - Override the default 30 s timeout.
+*
+* SECRET-HANDLING: `bundleCode` and the raw CDP result value are never logged.
+*/
+async function injectAndRunBundle(connection, bundleCode, timeoutMs = DEFAULT_TIMEOUT_MS) {
+	const expression = buildRunTestsExpression(bundleCode);
+	const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`rpc: evaluate timed out after ${timeoutMs}ms`)), timeoutMs));
+	const evalPromise = connection.send("Runtime.evaluate", {
+		expression,
+		returnByValue: true,
+		awaitPromise: true
+	});
+	const cdpResult = await Promise.race([evalPromise, timeoutPromise]);
+	if (cdpResult.exceptionDetails) {
+		const msg = cdpResult.exceptionDetails.exception?.description ?? cdpResult.exceptionDetails.text ?? "Runtime.evaluate threw an exception";
+		throw new Error(`rpc.injectAndRunBundle: ${msg}`);
+	}
+	return parseRunTestsResult(cdpResult.result.value);
+}
+//#endregion
+//#region src/test-runner/relay-worker.ts
+/**
+* Runs all `files` sequentially over the given CDP `connection`.
+*
+* For each file:
+*   1. Bundle with esbuild (includes SDK shim + runtime).
+*   2. Inject into the attached page via `Runtime.evaluate`.
+*   3. Await the `RunReport` JSON response.
+*   4. Accumulate results.
+*
+* Returns a `RelayRunReport` with per-file results and flattened totals.
+*
+* This function does NOT open or manage the relay connection — the caller
+* is responsible for attaching and closing it.
+*
+* TODO (#645): implement the Vitest `PoolRunnerInitializer` interface here
+* so that `runTestFilesOverRelay` can be used as a Vitest pool entry.
+*
+* @param connection - Active CDP connection (relay or local kind).
+* @param files      - Absolute paths to test files, run in order.
+* @param opts       - Optional per-run overrides.
+*/
+async function runTestFilesOverRelay(connection, files, opts) {
+	const wallStart = Date.now();
+	const startedAt = new Date(wallStart).toISOString();
+	const fileResults = [];
+	for (const file of files) {
+		let fileEntry;
+		try {
+			const { code } = await bundleTestFile(file, opts?.bundleOptions);
+			const rpcResult = await injectAndRunBundle(connection, code, opts?.timeoutMs);
+			if (rpcResult.ok) fileEntry = {
+				file,
+				result: rpcResult.report
+			};
+			else fileEntry = {
+				file,
+				result: { error: rpcResult.error }
+			};
+		} catch (e) {
+			fileEntry = {
+				file,
+				result: { error: e instanceof Error ? e.message : String(e) }
+			};
+		}
+		fileResults.push(fileEntry);
+	}
+	const totals = fileResults.reduce((acc, { result }) => {
+		if ("error" in result) {
+			acc.failed += 1;
+			acc.total += 1;
+		} else {
+			acc.passed += result.passed;
+			acc.failed += result.failed;
+			acc.skipped += result.skipped;
+			acc.total += result.passed + result.failed + result.skipped;
+		}
+		return acc;
+	}, {
+		passed: 0,
+		failed: 0,
+		skipped: 0,
+		total: 0
+	});
+	return {
+		startedAt,
+		duration: Date.now() - wallStart,
+		files: fileResults,
+		totals
+	};
+}
+//#endregion
+//#region src/test-runner/cli.ts
+/**
+* `devtools-test` CLI.
+*
+* Shares test-file discovery with the `run_tests` MCP tool (`discoverTestFiles`)
+* and exposes `runWithConnection` — the pure run core that bundles, injects, and
+* collects each file over a CDP connection. Today the run path that has a live
+* connection is the `run_tests` MCP tool (it runs these files against the
+* daemon's attached page); the CLI's own standalone relay attach (resolve CDP
+* URL → attach → run → close) is not wired yet, so `main()` resolves the matched
+* files and points the operator at the MCP tool.
+*
+* NOTE: no shebang in this source file — the tsdown entry's `banner` option
+* injects `#!/usr/bin/env node` into the compiled output (same pattern as
+* `src/mcp/cli.ts`).
+*/
+const USAGE = `
+devtools-test — run mini-app tests on a real device WebView over the CDP relay
+
+USAGE
+  devtools-test <glob> [<glob> ...] [options]
+
+OPTIONS
+  --timeout <ms>    Per-file evaluate timeout in ms (default: 30000)
+  --help, -h        Show this help message
+
+DESCRIPTION
+  Bundles each matched test file with esbuild (SDK imports redirected to
+  window.__sdk), injects the bundle into the attached WebView via
+  Runtime.evaluate, and returns a RunReport.
+
+  A live CDP relay connection must be active before running tests. Use the
+  \`run_tests\` MCP tool (via \`devtools-mcp\` / \`/ait debug\`) to run these files
+  against an attached page — the CLI's own standalone relay attach is not wired
+  yet (it currently resolves the matched files and defers to that tool).
+
+EXAMPLE
+  devtools-test 'src/**/*.phone.test.ts' --timeout 60000
+
+`.trimStart();
+/**
+* Runs `files` over `connection` and returns the aggregate report.
+* This pure function is the testable core of the CLI (and is what the
+* `run_tests` MCP tool calls against the daemon's attached connection); it is
+* separate from `main()` so tests can call it without spawning a subprocess.
+*
+* A standalone CLI relay attach/detach lifecycle (connect via Chii relay URL,
+* `enableDomains`, run, then close) is not wired into `main()` yet.
+*/
+async function runWithConnection(connection, files, opts) {
+	const report = await runTestFilesOverRelay(connection, files, opts);
+	if (opts?.printSummary) {
+		const { totals } = report;
+		process.stdout.write(`\ndevtools-test: ${totals.passed} passed, ${totals.failed} failed, ${totals.skipped} skipped (${report.duration}ms)\n`);
+	}
+	return report;
+}
+/**
+* CLI entry point.
+*
+* Resolves the matched test files and prints a "relay attach required" notice:
+* the CLI's own standalone relay attach (resolve CDP URL, attach, run, close) is
+* not wired yet, so today these files run via the `run_tests` MCP tool against
+* the daemon's attached page.
+*/
+async function main$1(argv = process.argv.slice(2)) {
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			options: {
+				help: {
+					type: "boolean",
+					short: "h"
+				},
+				timeout: { type: "string" }
+			},
+			allowPositionals: true
+		});
+	} catch (e) {
+		process.stderr.write(`devtools-test: ${e instanceof Error ? e.message : String(e)}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	if (parsed.values.help || argv.length === 0) {
+		process.stdout.write(USAGE);
+		return;
+	}
+	const files = await discoverTestFiles(parsed.positionals, process.cwd());
+	if (files.length === 0) {
+		process.stderr.write(`devtools-test: no test files matched ${parsed.positionals.join(", ")}\n`);
+		process.exitCode = 1;
+		return;
+	}
+	process.stderr.write(`devtools-test: matched ${files.length} test file(s), but direct CLI relay attach is not yet wired.\n  Use the devtools-mcp server (\`devtools-mcp\`) to start a debug session,\n  then the \`run_tests\` MCP tool to run these files against the attached page.\n`);
+	process.exitCode = 1;
+}
+if (import.meta.url === new URL(process.argv[1], "file://").href) main$1().catch((e) => {
+	process.stderr.write(`devtools-test: unexpected error: ${e instanceof Error ? e.message : String(e)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
 //#region src/mcp/ait-chii-source.ts
 function isObject$4(value) {
 	return typeof value === "object" && value !== null;
@@ -213,7 +722,11 @@ const ALLOWED_KEYS = new Set([
 	"errorKind",
 	"reason",
 	"prevTargetId",
-	"mode"
+	"mode",
+	"fileCount",
+	"passed",
+	"failed",
+	"skipped"
 ]);
 /**
 * Patterns that match secret values.
@@ -4033,6 +4546,34 @@ const DEBUG_TOOL_DEFINITIONS = [
 			required: []
 		},
 		availableIn: "both"
+	},
+	{
+		name: "run_tests",
+		description: "Runs mini-app test files on the attached page over CDP (Runtime.evaluate). Each matched file is bundled with esbuild (SDK imports redirected to the live mock/SDK), injected into the attached WebView, and executed; returns per-file results plus flattened totals (passed/failed/skipped/total). Requires an attached page — call list_pages first to confirm one is attached. Files run SEQUENTIALLY (single-attach model: the relay/local target serves one page), and one run_tests call runs at a time (a concurrent call is rejected). Test verification (assert/snapshot) is delegated to the in-page Vitest runtime; this tool is the transport + report. The per-file results array is the progress record — on partial failure you see exactly which files passed/failed/timed-out. In a relay-live session this is a state-mutating injection and is blocked unless confirm=true (confirm is ignored in every non-live session: mock/local, relay-dev, relay-mobile). debug-mode only — dev-mode (--mode=dev) has no CDP. Tier C (both mock/local and relay). The devtools-test CLI shares this run core and file discovery, but its standalone relay attach is not wired yet — run via this tool for now.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				files: {
+					type: "array",
+					items: { type: "string" },
+					description: "Glob patterns or file paths to run (e.g. [\"src/**/*.phone.test.ts\"]). Resolved relative to projectRoot when given, else the daemon cwd. Required, non-empty."
+				},
+				projectRoot: {
+					type: "string",
+					description: "Absolute path to the mini-app project root used as the glob base. Pass this because the daemon's cwd is fixed at launch. Optional."
+				},
+				timeout_ms: {
+					type: "number",
+					description: "Per-file evaluate timeout in ms (default 30000, range 1000–600000). Out-of-range/invalid values fall back to the default."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required (true) to run in a relay-live session — test injection mutates page state. Ignored in every non-live session (mock/local, relay-dev, relay-mobile)."
+				}
+			},
+			required: ["files"]
+		},
+		availableIn: "both"
 	}
 ];
 const DEBUG_TOOL_NAMES = new Set(DEBUG_TOOL_DEFINITIONS.map((t) => t.name));
@@ -4855,7 +5396,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.107";
+	return "0.1.109";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -5103,9 +5644,11 @@ async function renderQr(text) {
 	return `${lines.join("\n")}\n`;
 }
 /**
-* Renders the attach banner (relay URL + ASCII QR) as a string.
+* Renders the attach banner (relay URL + unicode half-block QR) as a string.
 *
-* The QR encodes the base `wssUrl` only. When `totpEnabled` is true, a note
+* The QR is produced by `renderQr` (a half-block matrix, not the
+* `qrcode-terminal` ASCII art used by the unplugin banner) and encodes the
+* base `wssUrl` only. When `totpEnabled` is true, a note
 * is added that attach URLs generated by `build_attach_url` will include a
 * live TOTP code (`at=`) appended at call time.
 *
@@ -5385,6 +5928,16 @@ function isRelayMode(mode) {
 	return mode === "relay-sandbox" || mode === "relay-staging" || mode === "relay-live";
 }
 /**
+* Single-attach guard for `run_tests` (#646). Two concurrent runs injecting
+* into the same single-attach page would interleave `Runtime.evaluate` and
+* corrupt each other's `globalThis.__testBundle`. The model is "reject the
+* second", not "queue" — a module-level flag is process-wide, which matches the
+* single physical attached page (only one target is live at a time). The
+* entry-time `conn` snapshot ensures a run finishes on the connection it started
+* on even if `router.active` flips mid-run.
+*/
+let runTestsInFlight = false;
+/**
 * Waits for the first target matching `filterFn` to attach, using the
 * event-driven `waitForFirstTarget()` when the connection supports it
 * (interface-optional member, present on `ChiiCdpConnection`), or falling
@@ -5395,6 +5948,12 @@ function isRelayMode(mode) {
 * to resolve before the relay had observed the first inbound CDP message from
 * the phone.
 *
+* Timeout note: callers (e.g. the `build_attach_url` path) always pass an
+* explicit `timeoutMs`, sourced from the factory's `waitForAttachTimeoutMs`
+* (default 60 000). That value is forwarded to `waitForFirstTarget`, so it
+* overrides that method's own 90 000 signature default — the effective
+* wait on the tool path is 60 s, not 90 s.
+*
 * @param connection - The CDP connection (production or fake).
 * @param filterFn   - Resolves when this predicate is satisfied.
 * @param timeoutMs  - Maximum wait time in ms.
@@ -5447,7 +6006,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.107"
+		version: "0.1.109"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -5950,6 +6509,35 @@ ${browserResult.httpUrl}\n또는 PNG로 받기: ${browserResult.pngUrl}` + stder
 					if (!sdkResult.ok && typeof sdkResult.error === "string" && sdkResult.error.startsWith("sdk-absent:")) return sdkAbsentError("call_sdk", conn.kind === "local");
 					return envelopeResult$1(sdkResult, name, env, conn.listTargets().length > 0);
 				}
+				case "run_tests": {
+					const rawFiles = request.params.arguments?.files;
+					if (!Array.isArray(rawFiles) || rawFiles.length === 0) return mcpError("run_tests: files 인자가 비어 있습니다. 실행할 테스트 파일 glob을 배열로 전달하세요.");
+					const patterns = rawFiles.filter((p) => typeof p === "string" && p !== "");
+					if (patterns.length === 0) return mcpError("run_tests: files 인자에 유효한 문자열 glob이 없습니다.");
+					const rawRoot = request.params.arguments?.projectRoot;
+					const projectRoot = typeof rawRoot === "string" ? rawRoot : process.cwd();
+					const rawTimeout = request.params.arguments?.timeout_ms;
+					const timeoutMs = typeof rawTimeout === "number" && rawTimeout >= 1e3 && rawTimeout <= 6e5 ? rawTimeout : void 0;
+					if (conn.kind === "relay" && getLiveIntent() && request.params.arguments?.confirm !== true) return liveGuardError("run_tests");
+					if (runTestsInFlight) return mcpError("run_tests: 이미 다른 테스트 실행이 진행 중입니다 (single-attach 모델: 페이지는 한 번에 하나의 실행만 처리). 완료 후 다시 시도하세요.");
+					runTestsInFlight = true;
+					try {
+						const files = await discoverTestFiles(patterns, projectRoot);
+						if (files.length === 0) return mcpError(`run_tests: 매칭된 테스트 파일이 없습니다 (patterns: ${patterns.join(", ")}).`);
+						if (conn.listTargets().length === 0) return pageMissingError("run_tests");
+						logInfo("run_tests.start", { fileCount: files.length });
+						const report = await runWithConnection(conn, files, { timeoutMs });
+						logInfo("run_tests.done", {
+							passed: report.totals.passed,
+							failed: report.totals.failed,
+							skipped: report.totals.skipped
+						});
+						const runAttached = conn.listTargets().length > 0;
+						return envelopeResult$1(toRunTestsResult(report), name, env, runAttached);
+					} finally {
+						runTestsInFlight = false;
+					}
+				}
 				default: return unknownTool(name);
 			}
 		} catch (err) {
@@ -6035,6 +6623,31 @@ function envelopeResult$1(value, tool, env, attached) {
 		text: JSON.stringify(wrapped, null, 2)
 	}] };
 }
+/**
+* Maps a {@link RelayRunReport} to a flat, agent-friendly object for the
+* `run_tests` tool result. SECRET-HANDLING: a RelayRunReport carries only
+* startedAt/duration/totals and per-file `{file, result}` — file paths are
+* surfaced (allowed), relay wss/TOTP URLs never appear in it. No stripping
+* needed; this only reshapes for readability.
+*/
+function toRunTestsResult(report) {
+	return {
+		startedAt: report.startedAt,
+		duration: report.duration,
+		totals: report.totals,
+		files: report.files.map((f) => "error" in f.result ? {
+			file: f.file,
+			error: f.result.error
+		} : {
+			file: f.file,
+			duration: f.result.duration,
+			passed: f.result.passed,
+			failed: f.result.failed,
+			skipped: f.result.skipped,
+			tests: f.result.tests
+		})
+	};
+}
 function unknownTool(name) {
 	return mcpError(`알 수 없는 tool: ${name}`);
 }
@@ -7456,6 +8069,34 @@ const DEV_TOOL_DEFINITIONS = [
 			required: []
 		},
 		availableIn: "both"
+	},
+	{
+		name: "run_tests",
+		description: "Runs mini-app test files on the attached page over CDP (Runtime.evaluate). NOT available in dev-mode (no CDP connection). Switch to `--mode=local` or `--mode=debug`.",
+		inputSchema: {
+			type: "object",
+			properties: {
+				files: {
+					type: "array",
+					items: { type: "string" },
+					description: "Glob patterns or file paths to run."
+				},
+				projectRoot: {
+					type: "string",
+					description: "Glob base directory."
+				},
+				timeout_ms: {
+					type: "number",
+					description: "Per-file evaluate timeout in ms."
+				},
+				confirm: {
+					type: "boolean",
+					description: "Required in relay-live sessions."
+				}
+			},
+			required: ["files"]
+		},
+		availableIn: "both"
 	}
 ];
 /** All tool names served in dev-mode (including tier-filter stubs). */
@@ -7468,7 +8109,8 @@ const CDP_ONLY_TOOL_NAMES = new Set([
 	"take_snapshot",
 	"list_console_messages",
 	"list_network_requests",
-	"list_exceptions"
+	"list_exceptions",
+	"run_tests"
 ]);
 /**
 * Tier B tools — relay-only per RFC #277.
@@ -7585,7 +8227,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.107"
+		version: "0.1.109"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {