@ait-co/devtools 0.1.106 → 0.1.108

package/dist/test-runner/cli.js

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { glob } from "node:fs/promises";
+import * as path from "node:path";
+import { isAbsolute, resolve } from "node:path";
+//#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 user's SDK imports
+* (`@apps-in-toss/web-framework` and sub-paths) are intercepted via an
+* esbuild plugin that redirects them to `window.__sdk`, which the in-app
+* debug gate (`src/in-app/auto.ts`) installs as a namespace mirror of the
+* SDK exports (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"
+			}));
+		}
+	};
+}
+/**
+* Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
+*
+* The IIFE installs `window.__testBundle` (or the custom `globalName`) with
+* `runTestModule` as the callable entry point.
+*
+* @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 result = await (await import("esbuild")).build({
+		entryPoints: [absPath],
+		bundle: true,
+		format: "iife",
+		globalName,
+		platform: "browser",
+		target: "es2022",
+		write: false,
+		plugins: [sdkRedirectPlugin()],
+		external: extraExternals,
+		treeShaking: true
+	});
+	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') {    return JSON.stringify({ok:false,error:'bundle-missing-export: __testBundle.runTestModule is not a function'});  }  try {    const report = await globalThis.__testBundle.runTestModule();    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 — MVP skeleton.
+*
+* Parses argv, prints usage, and delegates to `runTestFilesOverRelay` when
+* a live CDP connection is provided. The relay connection wiring
+* (attach → run → detach) is tracked in issue #645 / #646.
+*
+* MVP contract: `--help` works, `runWithConnection` is a testable pure
+* function, and the binary entry exists in package.json.
+*
+* 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 \`/ait debug\` (devtools-mcp) to attach and then call this CLI from
+  the same process context.
+
+  Full Vitest pool integration and the \`run_tests\` MCP tool are tracked in
+  issues #645 and #646 respectively. This MVP provides the transport layer.
+
+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; it is separate from
+* `main()` so tests can call it without spawning a subprocess.
+*
+* TODO (#645): add real relay attach/detach lifecycle here (connect via
+* Chii relay URL, call enableDomains, run, then close).
+*/
+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.
+*
+* MVP: prints usage and a "relay attach required" notice. Real relay wiring
+* (resolve CDP URL, attach, run, close) is tracked in issues #645 / #646.
+*/
+async function main(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  Direct CLI relay wiring is tracked in issue #645.\n`);
+	process.exitCode = 1;
+}
+if (import.meta.url === new URL(process.argv[1], "file://").href) main().catch((e) => {
+	process.stderr.write(`devtools-test: unexpected error: ${e instanceof Error ? e.message : String(e)}\n`);
+	process.exitCode = 1;
+});
+//#endregion
+export { main, runWithConnection };
+
+//# sourceMappingURL=cli.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","names":[],"sources":["../../src/test-runner/discover.ts","../../src/test-runner/bundle.ts","../../src/test-runner/rpc.ts","../../src/test-runner/relay-worker.ts","../../src/test-runner/cli.ts"],"sourcesContent":["/**\n * Test-file discovery shared by the `devtools-test` CLI and the `run_tests`\n * MCP tool, so both expand glob patterns with identical semantics.\n *\n * Uses Node's built-in `fs/promises` `glob` (Node 22+) — no extra dependency,\n * which keeps the MCP daemon install graph lean (a plain glob lib would land in\n * the `npx … devtools-mcp` path for no benefit).\n *\n * Pure Node IO only (`node:fs/promises` + `node:path`) — react-free, so it is\n * safe to import from the MCP daemon graph.\n */\n\nimport { glob } from 'node:fs/promises';\nimport { isAbsolute, resolve } from 'node:path';\n\n/**\n * Expands `patterns` (globs or plain paths) into a sorted, de-duplicated list of\n * ABSOLUTE test file paths, resolved relative to `cwd`.\n *\n * A plain (non-glob) path passes through when it matches a real file; a glob\n * expands against `cwd`. Absolute matches are kept as-is; relative matches are\n * resolved against `cwd`. `bundleTestFile` requires an absolute path, so the\n * absolute output feeds it directly.\n *\n * @param patterns Glob patterns or file paths (e.g. `['src/**\\/*.phone.test.ts']`).\n * @param cwd      Base directory for relative patterns/results.\n * @returns Sorted, de-duplicated absolute file paths. Empty when nothing matches.\n */\nexport async function discoverTestFiles(patterns: string[], cwd: string): Promise<string[]> {\n  const out = new Set<string>();\n  for await (const match of glob(patterns, { cwd })) {\n    out.add(isAbsolute(match) ? match : resolve(cwd, match));\n  }\n  return [...out].sort();\n}\n","/**\n * esbuild-based bundler for user test files.\n *\n * Bundles a single test file into a self-contained IIFE string that can be\n * injected into a WebView via `Runtime.evaluate`. The user's SDK imports\n * (`@apps-in-toss/web-framework` and sub-paths) are intercepted via an\n * esbuild plugin that redirects them to `window.__sdk`, which the in-app\n * debug gate (`src/in-app/auto.ts`) installs as a namespace mirror of the\n * SDK exports (works for both 2.x and 3.x SDK).\n *\n * SECRET-HANDLING: the returned bundle code is caller-managed; never log it.\n */\n\nimport * as path from 'node:path';\n// esbuild is imported for TYPES only at module scope; the runtime module is\n// loaded lazily inside `bundleTestFile` via dynamic import. esbuild runs a\n// startup invariant check (`TextEncoder().encode('') instanceof Uint8Array`)\n// that fails in a jsdom realm — a static import would break every MCP/test\n// module that merely *imports* this file's transitive graph (e.g. debug-server →\n// run_tests). Lazy load keeps esbuild off the import graph until a bundle is\n// actually built, and mirrors the cloudflared/chii dynamic-import precedent.\nimport type * as esbuild from 'esbuild';\n\n/** Options accepted by `bundleTestFile`. */\nexport interface BundleOptions {\n  /**\n   * Additional esbuild `external` patterns. The SDK package\n   * (`@apps-in-toss/web-framework` and `@apps-in-toss/web-framework/*`) is\n   * always handled by the SDK redirect plugin — callers may add more patterns\n   * to be left as globals.\n   */\n  extraExternals?: string[];\n  /**\n   * Global name for the IIFE output object. Defaults to `__testBundle`.\n   * The runtime entry uses this to call `__testBundle.runTestModule()`.\n   */\n  globalName?: string;\n}\n\n/**\n * The result of bundling a test file.\n * `code` is a self-contained IIFE string ready for `Runtime.evaluate`.\n */\nexport interface BundleResult {\n  code: string;\n  warnings: string[];\n}\n\n/** The SDK package name that mini-app test code imports from. */\nconst SDK_PACKAGE = '@apps-in-toss/web-framework';\n\n/**\n * Matches the bare SDK package and any sub-path import\n * (`@apps-in-toss/web-framework`, `@apps-in-toss/web-framework/foo`).\n * Built from {@link SDK_PACKAGE} so the package name has a single source.\n */\nconst SDK_IMPORT_FILTER = new RegExp(`^${SDK_PACKAGE.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&')}`);\n\n/**\n * esbuild plugin that intercepts SDK imports and redirects them to the\n * `window.__sdk` proxy that `src/in-app/auto.ts` installs at runtime.\n *\n * Strategy: for every import of `@apps-in-toss/web-framework` (or sub-paths),\n * esbuild resolves it to a virtual module that re-exports all named exports\n * via `window.__sdk[name]`. This avoids bundling the real SDK (which may not\n * be available in the test environment) while still making named imports work.\n *\n * If `window.__sdk` is absent (non-dog-food build), every access throws a\n * descriptive error rather than returning `undefined` silently.\n */\nfunction sdkRedirectPlugin(): esbuild.Plugin {\n  return {\n    name: 'sdk-redirect',\n    setup(build) {\n      // Match the bare package and any sub-path imports\n      build.onResolve({ filter: SDK_IMPORT_FILTER }, (args) => ({\n        path: args.path,\n        namespace: 'sdk-redirect',\n      }));\n\n      build.onLoad({ filter: /.*/, namespace: 'sdk-redirect' }, () => ({\n        // Generate a virtual CommonJS-style module so that esbuild does NOT perform\n        // strict named-export matching. When `format:'iife'` bundles a CJS module,\n        // it wraps it with its own __toCommonJS helper and satisfies named imports\n        // via property access on the module.exports object — which is our Proxy.\n        // This means `import { getPlatformOS } from '...'` becomes\n        // `__proxy.getPlatformOS` at runtime, which correctly reads from window.__sdk.\n        contents: `\nvar __proxy = (typeof window !== 'undefined' && window.__sdk)\n  ? window.__sdk\n  : new Proxy({}, {\n      get: function(_t, p) {\n        throw new Error('window.__sdk is not installed — run in a dog-food build. Missing: ' + String(p));\n      }\n    });\nmodule.exports = __proxy;\n`,\n        loader: 'js',\n      }));\n    },\n  };\n}\n\n/**\n * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.\n *\n * The IIFE installs `window.__testBundle` (or the custom `globalName`) with\n * `runTestModule` as the callable entry point.\n *\n * @param absPath - Absolute path to the user test file.\n * @param opts    - Optional bundling overrides.\n */\nexport async function bundleTestFile(absPath: string, opts?: BundleOptions): Promise<BundleResult> {\n  const globalName = opts?.globalName ?? '__testBundle';\n  const extraExternals = opts?.extraExternals ?? [];\n\n  // Lazy load esbuild at call time (see the module-scope import note).\n  const esbuild = await import('esbuild');\n\n  const result = await esbuild.build({\n    entryPoints: [absPath],\n    bundle: true,\n    format: 'iife',\n    globalName,\n    platform: 'browser',\n    target: 'es2022',\n    write: false,\n    plugins: [sdkRedirectPlugin()],\n    // Extra externals are left as global references (caller's responsibility\n    // to ensure they exist in the WebView context).\n    external: extraExternals,\n    // Keep bundle self-contained; no dynamic require/import at runtime.\n    treeShaking: true,\n  });\n\n  const warnings = result.warnings.map(\n    (w) =>\n      `${path.relative(process.cwd(), w.location?.file ?? '')}:${w.location?.line ?? '?'}: ${w.text}`,\n  );\n\n  const outputFile = result.outputFiles?.[0];\n  if (!outputFile) {\n    throw new Error('bundleTestFile: esbuild produced no output — check entryPoints');\n  }\n\n  return { code: outputFile.text, warnings };\n}\n","/**\n * Node-side RPC helpers for injecting and collecting test execution over CDP.\n *\n * Uses the same IIFE + JSON.stringify envelope pattern as `buildCallSdkExpression`\n * in `src/mcp/tools.ts` to reliably shuttle structured results through\n * `Runtime.evaluate`'s `returnByValue: true` boundary.\n *\n * SECRET-HANDLING: bundle code, relay URLs, and result values are NOT logged.\n */\n\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\nimport type { RunReport } from './runtime.js';\n\n/** Maximum milliseconds to wait for a single evaluate round-trip. */\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/**\n * Wraps bundle code in a self-executing IIFE that:\n *   1. Evaluates the bundle (registering describe/it/test).\n *   2. Calls `__testBundle.runTestModule(...)` — the entry the runtime exports.\n *   3. Returns a JSON-serialised `RunReport` string.\n *\n * The double-serialisation (RunReport → JSON string → returnByValue string)\n * is intentional: CDP `returnByValue` reliably transports strings; deeply\n * nested objects can lose fidelity across the Chii relay.\n *\n * SECRET-HANDLING: `bundleCode` MUST NOT be logged by callers.\n */\nexport function buildRunTestsExpression(bundleCode: string): string {\n  // We trust bundleCode is already a self-contained IIFE that installs\n  // `window.__testBundle` (or `globalThis.__testBundle`).\n  // We then call `__testBundle.runTestModule()` and return a JSON string.\n  return (\n    `(async () => {` +\n    // Step 1: evaluate the bundle to register tests\n    `  try { ${bundleCode} } catch(e) {` +\n    `    return JSON.stringify({ok:false,error:'bundle-eval: ' + String(e && e.message || e)});` +\n    `  }` +\n    // Step 2: check that the expected export is present\n    `  if (typeof globalThis.__testBundle !== 'object' || typeof globalThis.__testBundle.runTestModule !== 'function') {` +\n    `    return JSON.stringify({ok:false,error:'bundle-missing-export: __testBundle.runTestModule is not a function'});` +\n    `  }` +\n    // Step 3: run tests\n    `  try {` +\n    `    const report = await globalThis.__testBundle.runTestModule();` +\n    `    return JSON.stringify({ok:true,value:report});` +\n    `  } catch(e) {` +\n    `    return JSON.stringify({ok:false,error:'test-run: ' + String(e && e.message || e)});` +\n    `  }` +\n    `})()`\n  );\n}\n\n/**\n * Result of `injectAndRunBundle`.\n */\nexport type RpcRunResult = { ok: true; report: RunReport } | { ok: false; error: string };\n\n/**\n * Parses the raw CDP `returnByValue` result from a `buildRunTestsExpression`\n * evaluate call into a typed `RpcRunResult`.\n *\n * Throws only on parse failure — an `ok:false` envelope is a normal result.\n *\n * SECRET-HANDLING: `rawValue` is not included in error messages.\n */\nexport function parseRunTestsResult(rawValue: unknown): RpcRunResult {\n  if (typeof rawValue !== 'string') {\n    throw new Error(\n      `rpc.parseRunTestsResult: unexpected return type \"${typeof rawValue}\" — expected JSON string`,\n    );\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(rawValue);\n  } catch {\n    // Do NOT include rawValue — could contain secrets.\n    throw new Error('rpc.parseRunTestsResult: bridge returned non-JSON string');\n  }\n  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {\n    throw new Error('rpc.parseRunTestsResult: parsed result is not an object');\n  }\n  const obj = parsed as Record<string, unknown>;\n  if (obj.ok === true) {\n    return { ok: true, report: obj.value as RunReport };\n  }\n  if (obj.ok === false) {\n    return {\n      ok: false,\n      error: typeof obj.error === 'string' ? obj.error : String(obj.error),\n    };\n  }\n  throw new Error('rpc.parseRunTestsResult: result missing \"ok\" field');\n}\n\n/**\n * Injects `bundleCode` into the attached page and awaits test execution.\n *\n * Uses `Runtime.evaluate` with `awaitPromise: true` to wait for the\n * async IIFE to settle.  The 30-second CDP command timeout covers even\n * long-running test suites; split into smaller files if you hit it.\n *\n * @param connection   - Active CDP connection (relay or local).\n * @param bundleCode   - IIFE bundle string from `bundleTestFile`.\n * @param timeoutMs    - Override the default 30 s timeout.\n *\n * SECRET-HANDLING: `bundleCode` and the raw CDP result value are never logged.\n */\nexport async function injectAndRunBundle(\n  connection: CdpConnection,\n  bundleCode: string,\n  timeoutMs = DEFAULT_TIMEOUT_MS,\n): Promise<RpcRunResult> {\n  const expression = buildRunTestsExpression(bundleCode);\n\n  // Use AbortSignal-style timeout via Promise.race so we surface a clear\n  // message rather than hanging indefinitely.\n  const timeoutPromise = new Promise<never>((_, reject) =>\n    setTimeout(() => reject(new Error(`rpc: evaluate timed out after ${timeoutMs}ms`)), timeoutMs),\n  );\n\n  const evalPromise = connection.send('Runtime.evaluate', {\n    expression,\n    returnByValue: true,\n    awaitPromise: true,\n  });\n\n  const cdpResult = await Promise.race([evalPromise, timeoutPromise]);\n\n  if (cdpResult.exceptionDetails) {\n    // Surface only the engine error string — not the expression or value.\n    const msg =\n      cdpResult.exceptionDetails.exception?.description ??\n      cdpResult.exceptionDetails.text ??\n      'Runtime.evaluate threw an exception';\n    throw new Error(`rpc.injectAndRunBundle: ${msg}`);\n  }\n\n  return parseRunTestsResult(cdpResult.result.value);\n}\n","/**\n * Orchestrator: runs a list of test files sequentially over a CDP relay.\n *\n * Each file goes through: bundle → inject → run → collect.\n * This is the MVP transport layer. Full Vitest pool integration (issue #645)\n * and `run_tests` MCP tool (issue #646) are NOT implemented here.\n *\n * Single-attach constraint: only one page is active at a time. Files run\n * sequentially; parallel execution across targets is a post-MVP concern.\n *\n * The 30-second per-file timeout is inherited from `injectAndRunBundle`.\n * For suites that exceed it, split the file into smaller pieces.\n *\n * SECRET-HANDLING: file paths are surfaced in reports; relay URLs are not.\n */\n\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\nimport { type BundleOptions, bundleTestFile } from './bundle.js';\nimport { injectAndRunBundle } from './rpc.js';\nimport type { RunReport, TestResult } from './runtime.js';\n\n/** Per-file result in the aggregate `RunReport`. */\nexport interface FileResult {\n  /** Absolute or relative path to the test file. */\n  file: string;\n  /** Full run report for this file, or an error if bundling/injection failed. */\n  result: RunReport | { error: string };\n}\n\n/** Aggregate report returned by `runTestFilesOverRelay`. */\nexport interface RelayRunReport {\n  /** ISO timestamp of when the run started. */\n  startedAt: string;\n  /** Total elapsed wall-clock milliseconds. */\n  duration: number;\n  /** Per-file results in execution order. */\n  files: FileResult[];\n  /** Flattened totals across all files. */\n  totals: {\n    passed: number;\n    failed: number;\n    skipped: number;\n    total: number;\n  };\n}\n\n/** Options for `runTestFilesOverRelay`. */\nexport interface RelayRunOptions {\n  /**\n   * Options forwarded to `bundleTestFile` for each file.\n   */\n  bundleOptions?: BundleOptions;\n  /**\n   * Per-file evaluate timeout in milliseconds. Defaults to 30 000.\n   * Increase for long-running suites or split the file.\n   */\n  timeoutMs?: number;\n}\n\n/**\n * Runs all `files` sequentially over the given CDP `connection`.\n *\n * For each file:\n *   1. Bundle with esbuild (includes SDK shim + runtime).\n *   2. Inject into the attached page via `Runtime.evaluate`.\n *   3. Await the `RunReport` JSON response.\n *   4. Accumulate results.\n *\n * Returns a `RelayRunReport` with per-file results and flattened totals.\n *\n * This function does NOT open or manage the relay connection — the caller\n * is responsible for attaching and closing it.\n *\n * TODO (#645): implement the Vitest `PoolRunnerInitializer` interface here\n * so that `runTestFilesOverRelay` can be used as a Vitest pool entry.\n *\n * @param connection - Active CDP connection (relay or local kind).\n * @param files      - Absolute paths to test files, run in order.\n * @param opts       - Optional per-run overrides.\n */\nexport async function runTestFilesOverRelay(\n  connection: CdpConnection,\n  files: string[],\n  opts?: RelayRunOptions,\n): Promise<RelayRunReport> {\n  const wallStart = Date.now();\n  const startedAt = new Date(wallStart).toISOString();\n  const fileResults: FileResult[] = [];\n\n  for (const file of files) {\n    let fileEntry: FileResult;\n    try {\n      const { code } = await bundleTestFile(file, opts?.bundleOptions);\n      const rpcResult = await injectAndRunBundle(connection, code, opts?.timeoutMs);\n      if (rpcResult.ok) {\n        fileEntry = { file, result: rpcResult.report };\n      } else {\n        fileEntry = { file, result: { error: rpcResult.error } };\n      }\n    } catch (e) {\n      // Capture bundle/inject errors per-file so subsequent files still run.\n      fileEntry = {\n        file,\n        result: {\n          error: e instanceof Error ? e.message : String(e),\n        },\n      };\n    }\n    fileResults.push(fileEntry);\n  }\n\n  const totals = fileResults.reduce(\n    (acc, { result }) => {\n      if ('error' in result) {\n        // Treat whole-file errors as a single failure.\n        acc.failed += 1;\n        acc.total += 1;\n      } else {\n        acc.passed += result.passed;\n        acc.failed += result.failed;\n        acc.skipped += result.skipped;\n        acc.total += result.passed + result.failed + result.skipped;\n      }\n      return acc;\n    },\n    { passed: 0, failed: 0, skipped: 0, total: 0 },\n  );\n\n  return {\n    startedAt,\n    duration: Date.now() - wallStart,\n    files: fileResults,\n    totals,\n  };\n}\n\n/**\n * Flattens all test results from a `RelayRunReport` into a single array.\n * Files that errored during bundle/inject produce a synthetic failed entry.\n */\nexport function flattenResults(report: RelayRunReport): Array<TestResult & { file: string }> {\n  const out: Array<TestResult & { file: string }> = [];\n  for (const { file, result } of report.files) {\n    if ('error' in result) {\n      out.push({\n        file,\n        name: `<bundle/inject error>`,\n        status: 'fail',\n        duration: 0,\n        error: result.error,\n      });\n    } else {\n      for (const t of result.tests) {\n        out.push({ ...t, file });\n      }\n    }\n  }\n  return out;\n}\n","/**\n * `devtools-test` CLI — MVP skeleton.\n *\n * Parses argv, prints usage, and delegates to `runTestFilesOverRelay` when\n * a live CDP connection is provided. The relay connection wiring\n * (attach → run → detach) is tracked in issue #645 / #646.\n *\n * MVP contract: `--help` works, `runWithConnection` is a testable pure\n * function, and the binary entry exists in package.json.\n *\n * NOTE: no shebang in this source file — the tsdown entry's `banner` option\n * injects `#!/usr/bin/env node` into the compiled output (same pattern as\n * `src/mcp/cli.ts`).\n */\n\nimport { parseArgs } from 'node:util';\nimport type { CdpConnection } from '../mcp/cdp-connection.js';\nimport { discoverTestFiles } from './discover.js';\nimport type { RelayRunOptions, RelayRunReport } from './relay-worker.js';\nimport { runTestFilesOverRelay } from './relay-worker.js';\n\n/* -------------------------------------------------------------------------- */\n/* CLI help                                                                    */\n/* -------------------------------------------------------------------------- */\n\nconst USAGE = `\ndevtools-test — run mini-app tests on a real device WebView over the CDP relay\n\nUSAGE\n  devtools-test <glob> [<glob> ...] [options]\n\nOPTIONS\n  --timeout <ms>    Per-file evaluate timeout in ms (default: 30000)\n  --help, -h        Show this help message\n\nDESCRIPTION\n  Bundles each matched test file with esbuild (SDK imports redirected to\n  window.__sdk), injects the bundle into the attached WebView via\n  Runtime.evaluate, and returns a RunReport.\n\n  A live CDP relay connection must be active before running tests.\n  Use \\`/ait debug\\` (devtools-mcp) to attach and then call this CLI from\n  the same process context.\n\n  Full Vitest pool integration and the \\`run_tests\\` MCP tool are tracked in\n  issues #645 and #646 respectively. This MVP provides the transport layer.\n\nEXAMPLE\n  devtools-test 'src/**/*.phone.test.ts' --timeout 60000\n\n`.trimStart();\n\n/* -------------------------------------------------------------------------- */\n/* Pure run function (testable without a real relay)                           */\n/* -------------------------------------------------------------------------- */\n\n/** Options for `runWithConnection`. */\nexport interface RunWithConnectionOptions extends RelayRunOptions {\n  /** If true, print a summary to stdout. Defaults to false in tests. */\n  printSummary?: boolean;\n}\n\n/**\n * Runs `files` over `connection` and returns the aggregate report.\n * This pure function is the testable core of the CLI; it is separate from\n * `main()` so tests can call it without spawning a subprocess.\n *\n * TODO (#645): add real relay attach/detach lifecycle here (connect via\n * Chii relay URL, call enableDomains, run, then close).\n */\nexport async function runWithConnection(\n  connection: CdpConnection,\n  files: string[],\n  opts?: RunWithConnectionOptions,\n): Promise<RelayRunReport> {\n  const report = await runTestFilesOverRelay(connection, files, opts);\n\n  if (opts?.printSummary) {\n    const { totals } = report;\n    process.stdout.write(\n      `\\ndevtools-test: ${totals.passed} passed, ${totals.failed} failed, ${totals.skipped} skipped (${report.duration}ms)\\n`,\n    );\n  }\n\n  return report;\n}\n\n/* -------------------------------------------------------------------------- */\n/* main() — CLI entry point                                                    */\n/* -------------------------------------------------------------------------- */\n\n/**\n * CLI entry point.\n *\n * MVP: prints usage and a \"relay attach required\" notice. Real relay wiring\n * (resolve CDP URL, attach, run, close) is tracked in issues #645 / #646.\n */\nexport async function main(argv: string[] = process.argv.slice(2)): Promise<void> {\n  let parsed: ReturnType<typeof parseArgs>;\n  try {\n    parsed = parseArgs({\n      args: argv,\n      options: {\n        help: { type: 'boolean', short: 'h' },\n        timeout: { type: 'string' },\n      },\n      allowPositionals: true,\n    });\n  } catch (e) {\n    process.stderr.write(`devtools-test: ${e instanceof Error ? e.message : String(e)}\\n`);\n    process.exitCode = 1;\n    return;\n  }\n\n  if (parsed.values.help || argv.length === 0) {\n    process.stdout.write(USAGE);\n    return;\n  }\n\n  // Discovery is shared with the `run_tests` MCP tool (#646) via\n  // `discoverTestFiles`, so both expand patterns identically. We resolve the\n  // matched files here to give the operator concrete feedback before the\n  // (still-pending) relay attach wiring.\n  const files = await discoverTestFiles(parsed.positionals, process.cwd());\n  if (files.length === 0) {\n    process.stderr.write(`devtools-test: no test files matched ${parsed.positionals.join(', ')}\\n`);\n    process.exitCode = 1;\n    return;\n  }\n\n  // Relay attach lifecycle (resolve CDP URL, attach, close) is tracked in #645;\n  // until then the CLI cannot run on its own. The `run_tests` MCP tool (#646)\n  // already runs these files against the daemon's attached connection.\n  process.stderr.write(\n    `devtools-test: matched ${files.length} test file(s), but direct CLI relay attach is not yet wired.\\n` +\n      `  Use the devtools-mcp server (\\`devtools-mcp\\`) to start a debug session,\\n` +\n      `  then the \\`run_tests\\` MCP tool to run these files against the attached page.\\n` +\n      `  Direct CLI relay wiring is tracked in issue #645.\\n`,\n  );\n  process.exitCode = 1;\n}\n\n// Run main() when executed as a binary (not imported as a module).\n// Node ESM: `import.meta.url === pathToFileURL(process.argv[1]).href` is the\n// canonical \"am I the main module?\" check.\nif (import.meta.url === new URL(process.argv[1], 'file://').href) {\n  main().catch((e: unknown) => {\n    process.stderr.write(\n      `devtools-test: unexpected error: ${e instanceof Error ? e.message : String(e)}\\n`,\n    );\n    process.exitCode = 1;\n  });\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,80 @@
+import { i as createRelayPool, n as RelayConnectionFactory, t as RELAY_POOL_NAME } from "../pool-Dkp7I9Bf.js";
+
+//#region src/test-runner/config.d.ts
+/**
+ * Resolved phone-test configuration returned by `definePhoneTestConfig`.
+ */
+interface PhoneTestConfig {
+  /**
+   * Glob patterns (relative to cwd) for test files to run on the device.
+   * Defaults to `['**\/*.phone.test.ts']`.
+   */
+  include: string[];
+  /**
+   * Per-file evaluate timeout in milliseconds. Defaults to 30 000.
+   */
+  timeoutMs: number;
+  /**
+   * Additional esbuild `external` patterns for bundling.
+   * The SDK package is always external; add more here if needed.
+   */
+  extraExternals: string[];
+}
+/** User-facing config shape accepted by `definePhoneTestConfig`. */
+interface PhoneTestUserConfig {
+  include?: string[];
+  timeoutMs?: number;
+  extraExternals?: string[];
+}
+/**
+ * Define a phone-relay test configuration.
+ *
+ * Merges user overrides with sensible defaults and returns a resolved
+ * `PhoneTestConfig`. This object can be passed to `runTestFilesOverRelay`
+ * (via the CLI or custom scripts) to run tests on a real device WebView.
+ */
+declare function definePhoneTestConfig(userConfig?: PhoneTestUserConfig): PhoneTestConfig;
+/**
+ * The slice of a Vitest `test` config this helper produces — `pool`,
+ * `include`, and `testTimeout`. Typed structurally (not against Vitest's
+ * `InlineConfig`) so consumers can spread it into their own `defineConfig`
+ * without this module taking a value dependency on `vitest`.
+ */
+interface PhoneVitestTestConfig {
+  /** The relay `PoolRunnerInitializer`, matched by `getFilePoolName`. */
+  pool: ReturnType<typeof createRelayPool>;
+  /** Glob patterns for device test files. */
+  include: string[];
+  /** Per-test timeout in ms (mirrors the relay per-file evaluate timeout). */
+  testTimeout: number;
+}
+/** User config accepted by {@link definePhoneVitestConfig}. */
+interface PhoneVitestUserConfig extends PhoneTestUserConfig {
+  /**
+   * Opens/closes the CDP relay connection that tests run over. Required —
+   * without it there is no device to dispatch files to.
+   *
+   * SECRET-HANDLING: the factory owns the relay wss/TOTP; this config object
+   * never stores or logs those values.
+   */
+  connection: RelayConnectionFactory;
+}
+/**
+ * Build the Vitest `test` config slice for running tests on a device over the
+ * relay. Spread the result into your Vitest config:
+ *
+ * @example
+ *   // vitest.config.ts
+ *   import { defineConfig } from 'vitest/config';
+ *   import { definePhoneVitestConfig } from '@ait-co/devtools/test-runner';
+ *   export default defineConfig({
+ *     test: definePhoneVitestConfig({ connection: myRelayFactory }),
+ *   });
+ *
+ * Files matching `include` are dispatched to the relay pool (named
+ * {@link RELAY_POOL_NAME}); everything else runs in Vitest's default pool.
+ */
+declare function definePhoneVitestConfig(userConfig: PhoneVitestUserConfig): PhoneVitestTestConfig;
+//#endregion
+export { PhoneTestConfig, PhoneTestUserConfig, PhoneVitestTestConfig, PhoneVitestUserConfig, RELAY_POOL_NAME, type RelayConnectionFactory, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","names":[],"sources":["../../src/test-runner/config.ts"],"mappings":";;;;;AA6DA;UArCiB,eAAA;;;;;EAKf,OAAA;EAgCsF;;AAcxF;EA1CE,SAAA;;;;;EAKA,cAAA;AAAA;;UAIe,mBAAA;EACf,OAAA;EACA,SAAA;EACA,cAAA;AAAA;;;;;;;AAkEF;iBAlDgB,qBAAA,CAAsB,UAAA,GAAa,mBAAA,GAAsB,eAAA;;;;;;;UAcxD,qBAAA;;EAEf,IAAA,EAAM,UAAA,QAAkB,eAAA;;EAExB,OAAA;;EAEA,WAAA;AAAA;;UAIe,qBAAA,SAA8B,mBAAA;;;;;;;;EAQ7C,UAAA,EAAY,sBAAA;AAAA;;;;;;;;;;;;;;;;iBAkBE,uBAAA,CAAwB,UAAA,EAAY,qBAAA,GAAwB,qBAAA"}

package/dist/test-runner/config.js

@@ -0,0 +1,54 @@
+import { RELAY_POOL_NAME, createRelayPool } from "./pool.js";
+//#region src/test-runner/config.ts
+const DEFAULT_CONFIG = {
+	include: ["**/*.phone.test.ts"],
+	timeoutMs: 3e4,
+	extraExternals: []
+};
+/**
+* Define a phone-relay test configuration.
+*
+* Merges user overrides with sensible defaults and returns a resolved
+* `PhoneTestConfig`. This object can be passed to `runTestFilesOverRelay`
+* (via the CLI or custom scripts) to run tests on a real device WebView.
+*/
+function definePhoneTestConfig(userConfig) {
+	return {
+		include: userConfig?.include ?? DEFAULT_CONFIG.include,
+		timeoutMs: userConfig?.timeoutMs ?? DEFAULT_CONFIG.timeoutMs,
+		extraExternals: userConfig?.extraExternals ?? DEFAULT_CONFIG.extraExternals
+	};
+}
+/**
+* Build the Vitest `test` config slice for running tests on a device over the
+* relay. Spread the result into your Vitest config:
+*
+* @example
+*   // vitest.config.ts
+*   import { defineConfig } from 'vitest/config';
+*   import { definePhoneVitestConfig } from '@ait-co/devtools/test-runner';
+*   export default defineConfig({
+*     test: definePhoneVitestConfig({ connection: myRelayFactory }),
+*   });
+*
+* Files matching `include` are dispatched to the relay pool (named
+* {@link RELAY_POOL_NAME}); everything else runs in Vitest's default pool.
+*/
+function definePhoneVitestConfig(userConfig) {
+	const resolved = definePhoneTestConfig(userConfig);
+	return {
+		pool: createRelayPool({
+			connection: userConfig.connection,
+			run: {
+				timeoutMs: resolved.timeoutMs,
+				bundleOptions: { extraExternals: resolved.extraExternals }
+			}
+		}),
+		include: resolved.include,
+		testTimeout: resolved.timeoutMs
+	};
+}
+//#endregion
+export { RELAY_POOL_NAME, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
+
+//# sourceMappingURL=config.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","names":[],"sources":["../../src/test-runner/config.ts"],"sourcesContent":["/**\n * Configuration helper for phone-relay test runs.\n *\n * `definePhoneTestConfig` is the user-facing entry point for configuring the\n * relay test runner. It mirrors the pattern of Vitest's `defineConfig` so\n * users can write:\n *\n *   // phone-test.config.ts\n *   import { definePhoneTestConfig } from '@ait-co/devtools/test-runner';\n *   export default definePhoneTestConfig({ ... });\n *\n * The helper resolves user config and, when given a relay connection factory,\n * builds the Vitest `pool` (`createRelayPool`) so Vitest's own config\n * resolution routes matching files to the device over the relay (#645). Without\n * a connection factory it still returns the resolved config for use with the\n * lower-level `runTestFilesOverRelay` transport (#644).\n */\n\nimport type { RelayConnectionFactory } from './pool.js';\nimport { createRelayPool, RELAY_POOL_NAME } from './pool.js';\n\n/**\n * Resolved phone-test configuration returned by `definePhoneTestConfig`.\n */\nexport interface PhoneTestConfig {\n  /**\n   * Glob patterns (relative to cwd) for test files to run on the device.\n   * Defaults to `['**\\/*.phone.test.ts']`.\n   */\n  include: string[];\n  /**\n   * Per-file evaluate timeout in milliseconds. Defaults to 30 000.\n   */\n  timeoutMs: number;\n  /**\n   * Additional esbuild `external` patterns for bundling.\n   * The SDK package is always external; add more here if needed.\n   */\n  extraExternals: string[];\n}\n\n/** User-facing config shape accepted by `definePhoneTestConfig`. */\nexport interface PhoneTestUserConfig {\n  include?: string[];\n  timeoutMs?: number;\n  extraExternals?: string[];\n}\n\nconst DEFAULT_CONFIG: PhoneTestConfig = {\n  include: ['**/*.phone.test.ts'],\n  timeoutMs: 30_000,\n  extraExternals: [],\n};\n\n/**\n * Define a phone-relay test configuration.\n *\n * Merges user overrides with sensible defaults and returns a resolved\n * `PhoneTestConfig`. This object can be passed to `runTestFilesOverRelay`\n * (via the CLI or custom scripts) to run tests on a real device WebView.\n */\nexport function definePhoneTestConfig(userConfig?: PhoneTestUserConfig): PhoneTestConfig {\n  return {\n    include: userConfig?.include ?? DEFAULT_CONFIG.include,\n    timeoutMs: userConfig?.timeoutMs ?? DEFAULT_CONFIG.timeoutMs,\n    extraExternals: userConfig?.extraExternals ?? DEFAULT_CONFIG.extraExternals,\n  };\n}\n\n/**\n * The slice of a Vitest `test` config this helper produces — `pool`,\n * `include`, and `testTimeout`. Typed structurally (not against Vitest's\n * `InlineConfig`) so consumers can spread it into their own `defineConfig`\n * without this module taking a value dependency on `vitest`.\n */\nexport interface PhoneVitestTestConfig {\n  /** The relay `PoolRunnerInitializer`, matched by `getFilePoolName`. */\n  pool: ReturnType<typeof createRelayPool>;\n  /** Glob patterns for device test files. */\n  include: string[];\n  /** Per-test timeout in ms (mirrors the relay per-file evaluate timeout). */\n  testTimeout: number;\n}\n\n/** User config accepted by {@link definePhoneVitestConfig}. */\nexport interface PhoneVitestUserConfig extends PhoneTestUserConfig {\n  /**\n   * Opens/closes the CDP relay connection that tests run over. Required —\n   * without it there is no device to dispatch files to.\n   *\n   * SECRET-HANDLING: the factory owns the relay wss/TOTP; this config object\n   * never stores or logs those values.\n   */\n  connection: RelayConnectionFactory;\n}\n\n/**\n * Build the Vitest `test` config slice for running tests on a device over the\n * relay. Spread the result into your Vitest config:\n *\n * @example\n *   // vitest.config.ts\n *   import { defineConfig } from 'vitest/config';\n *   import { definePhoneVitestConfig } from '@ait-co/devtools/test-runner';\n *   export default defineConfig({\n *     test: definePhoneVitestConfig({ connection: myRelayFactory }),\n *   });\n *\n * Files matching `include` are dispatched to the relay pool (named\n * {@link RELAY_POOL_NAME}); everything else runs in Vitest's default pool.\n */\nexport function definePhoneVitestConfig(userConfig: PhoneVitestUserConfig): PhoneVitestTestConfig {\n  const resolved = definePhoneTestConfig(userConfig);\n  return {\n    pool: createRelayPool({\n      connection: userConfig.connection,\n      run: {\n        timeoutMs: resolved.timeoutMs,\n        bundleOptions: { extraExternals: resolved.extraExternals },\n      },\n    }),\n    include: resolved.include,\n    testTimeout: resolved.timeoutMs,\n  };\n}\n\nexport type { RelayConnectionFactory };\nexport { createRelayPool, RELAY_POOL_NAME };\n"],"mappings":";;AAgDA,MAAM,iBAAkC;CACtC,SAAS,CAAC,qBAAqB;CAC/B,WAAW;CACX,gBAAgB,EAAE;CACnB;;;;;;;;AASD,SAAgB,sBAAsB,YAAmD;AACvF,QAAO;EACL,SAAS,YAAY,WAAW,eAAe;EAC/C,WAAW,YAAY,aAAa,eAAe;EACnD,gBAAgB,YAAY,kBAAkB,eAAe;EAC9D;;;;;;;;;;;;;;;;;AA6CH,SAAgB,wBAAwB,YAA0D;CAChG,MAAM,WAAW,sBAAsB,WAAW;AAClD,QAAO;EACL,MAAM,gBAAgB;GACpB,YAAY,WAAW;GACvB,KAAK;IACH,WAAW,SAAS;IACpB,eAAe,EAAE,gBAAgB,SAAS,gBAAgB;IAC3D;GACF,CAAC;EACF,SAAS,SAAS;EAClB,aAAa,SAAS;EACvB"}

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

@@ -0,0 +1,2 @@
+import { i as createRelayPool, n as RelayConnectionFactory, r as RelayPoolOptions, t as RELAY_POOL_NAME } from "../pool-Dkp7I9Bf.js";
+export { RELAY_POOL_NAME, RelayConnectionFactory, RelayPoolOptions, createRelayPool };