@ait-co/devtools 0.1.107 → 0.1.108

package/dist/relay-worker-BzFQ3fv9.d.ts

@@ -0,0 +1,74 @@
+import { t as BundleOptions } from "./bundle-BJm5jk56.js";
+import { t as CdpConnection } from "./cdp-connection-C0AP0tH2.js";
+import { n as TestResult, t as RunReport } from "./runtime-ORdrpizY.js";
+
+//#region src/test-runner/relay-worker.d.ts
+/** Per-file result in the aggregate `RunReport`. */
+interface FileResult {
+  /** Absolute or relative path to the test file. */
+  file: string;
+  /** Full run report for this file, or an error if bundling/injection failed. */
+  result: RunReport | {
+    error: string;
+  };
+}
+/** Aggregate report returned by `runTestFilesOverRelay`. */
+interface RelayRunReport {
+  /** ISO timestamp of when the run started. */
+  startedAt: string;
+  /** Total elapsed wall-clock milliseconds. */
+  duration: number;
+  /** Per-file results in execution order. */
+  files: FileResult[];
+  /** Flattened totals across all files. */
+  totals: {
+    passed: number;
+    failed: number;
+    skipped: number;
+    total: number;
+  };
+}
+/** Options for `runTestFilesOverRelay`. */
+interface RelayRunOptions {
+  /**
+   * Options forwarded to `bundleTestFile` for each file.
+   */
+  bundleOptions?: BundleOptions;
+  /**
+   * Per-file evaluate timeout in milliseconds. Defaults to 30 000.
+   * Increase for long-running suites or split the file.
+   */
+  timeoutMs?: number;
+}
+/**
+ * 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.
+ */
+declare function runTestFilesOverRelay(connection: CdpConnection, files: string[], opts?: RelayRunOptions): Promise<RelayRunReport>;
+/**
+ * Flattens all test results from a `RelayRunReport` into a single array.
+ * Files that errored during bundle/inject produce a synthetic failed entry.
+ */
+declare function flattenResults(report: RelayRunReport): Array<TestResult & {
+  file: string;
+}>;
+//#endregion
+export { runTestFilesOverRelay as a, flattenResults as i, RelayRunOptions as n, RelayRunReport as r, FileResult as t };
+//# sourceMappingURL=relay-worker-BzFQ3fv9.d.ts.map

package/dist/relay-worker-BzFQ3fv9.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-worker-BzFQ3fv9.d.ts","names":[],"sources":["../src/test-runner/relay-worker.ts"],"mappings":";;;;;;UAsBiB,UAAA;EAYf;EAVA,IAAA;EAYO;EAVP,MAAA,EAAQ,SAAA;IAAc,KAAA;EAAA;AAAA;;UAIP,cAAA;EAYR;EAVP,SAAA;EAe8B;EAb9B,QAAA;EAiB6B;EAf7B,KAAA,EAAO,UAAA;EAeS;EAbhB,MAAA;IACE,MAAA;IACA,MAAA;IACA,OAAA;IACA,KAAA;EAAA;AAAA;;UAKa,eAAA;EAqCd;;;EAjCD,aAAA,GAAgB,aAAA;EA8BhB;;;;EAzBA,SAAA;AAAA;;;AAoFF;;;;;;;;;;;;;;;;;;;iBA5DsB,qBAAA,CACpB,UAAA,EAAY,aAAA,EACZ,KAAA,YACA,IAAA,GAAO,eAAA,GACN,OAAA,CAAQ,cAAA;;;;;iBAwDK,cAAA,CAAe,MAAA,EAAQ,cAAA,GAAiB,KAAA,CAAM,UAAA;EAAe,IAAA;AAAA"}

package/dist/runtime-ORdrpizY.d.ts

@@ -0,0 +1,50 @@
+//#region src/test-runner/runtime.d.ts
+/**
+ * Thin test runtime for WebView execution.
+ *
+ * This file is bundled by `bundle.ts` together with the user's test file
+ * into a single IIFE injected into the WebView via `Runtime.evaluate`.
+ * It MUST stay browser-compatible — no Node.js APIs allowed.
+ *
+ * Design: rather than shipping @vitest/runner verbatim into a WebView (where
+ * its Node-side internals cause issues), this runtime provides a minimal
+ * compatible API surface — describe/it/test/expect globals — collects results
+ * into a plain JSON-safe object, and exports `runTestModule` as the entry point.
+ *
+ * @vitest/runner and @vitest/expect are listed as dependencies so that the
+ * package's type contracts are available and so the browser-compatible subsets
+ * can be referenced. Full pool integration (PoolRunnerInitializer) is tracked
+ * in issue #645.
+ *
+ * NOTE: this file is imported by type from Node-side code (rpc.ts / relay-worker.ts)
+ * for the RunReport / TestResult type shapes. The runtime ITSELF is not imported
+ * at runtime on the Node side — only the types are used.
+ */
+/**
+ * Result of a single test case.
+ * All fields are JSON-serialisable.
+ */
+interface TestResult {
+  /** Full dot-joined test name including nested suite names. */
+  name: string;
+  /** `'pass'` or `'fail'`. `'skip'` for skipped tests. */
+  status: 'pass' | 'fail' | 'skip';
+  /** Duration in milliseconds. */
+  duration: number;
+  /** Error message (fail only). Does NOT include the expression/secret. */
+  error?: string;
+}
+/** Aggregate report returned by `runTestModule`. */
+interface RunReport {
+  /** ISO timestamp of when `runTestModule` was called. */
+  startedAt: string;
+  /** Total elapsed milliseconds (wall-clock). */
+  duration: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  tests: TestResult[];
+}
+//#endregion
+export { TestResult as n, RunReport as t };
+//# sourceMappingURL=runtime-ORdrpizY.d.ts.map

package/dist/runtime-ORdrpizY.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-ORdrpizY.d.ts","names":[],"sources":["../src/test-runner/runtime.ts"],"mappings":";;AA8BA;;;;;;;;;;AAYA;;;;;;;;;;;;;;UAZiB,UAAA;;EAEf,IAAA;;EAEA,MAAA;;EAEA,QAAA;;EAEA,KAAA;AAAA;;UAIe,SAAA;;EAEf,SAAA;;EAEA,QAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EACA,KAAA,EAAO,UAAA;AAAA"}

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

@@ -0,0 +1,2 @@
+import { n as BundleResult, r as bundleTestFile, t as BundleOptions } from "../bundle-BJm5jk56.js";
+export { BundleOptions, BundleResult, bundleTestFile };

package/dist/test-runner/bundle.js

@@ -0,0 +1,95 @@
+import * as path from "node:path";
+//#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
+export { bundleTestFile };
+
+//# sourceMappingURL=bundle.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","names":[],"sources":["../../src/test-runner/bundle.ts"],"sourcesContent":["/**\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"],"mappings":";;;;;;;;;;;;;;;;;;;AAwDA,MAAM,oBAAoB,IAAI,OAAO,IAPjB,8BAOiC,QAAQ,uBAAuB,OAAO,GAAG;;;;;;;;;;;;;AAc9F,SAAS,oBAAoC;AAC3C,QAAO;EACL,MAAM;EACN,MAAM,OAAO;AAEX,SAAM,UAAU,EAAE,QAAQ,mBAAmB,GAAG,UAAU;IACxD,MAAM,KAAK;IACX,WAAW;IACZ,EAAE;AAEH,SAAM,OAAO;IAAE,QAAQ;IAAM,WAAW;IAAgB,SAAS;IAO/D,UAAU;;;;;;;;;;IAUV,QAAQ;IACT,EAAE;;EAEN;;;;;;;;;;;AAYH,eAAsB,eAAe,SAAiB,MAA6C;CACjG,MAAM,aAAa,MAAM,cAAc;CACvC,MAAM,iBAAiB,MAAM,kBAAkB,EAAE;CAKjD,MAAM,SAAS,OAFC,MAAM,OAAO,YAEA,MAAM;EACjC,aAAa,CAAC,QAAQ;EACtB,QAAQ;EACR,QAAQ;EACR;EACA,UAAU;EACV,QAAQ;EACR,OAAO;EACP,SAAS,CAAC,mBAAmB,CAAC;EAG9B,UAAU;EAEV,aAAa;EACd,CAAC;CAEF,MAAM,WAAW,OAAO,SAAS,KAC9B,MACC,GAAG,KAAK,SAAS,QAAQ,KAAK,EAAE,EAAE,UAAU,QAAQ,GAAG,CAAC,GAAG,EAAE,UAAU,QAAQ,IAAI,IAAI,EAAE,OAC5F;CAED,MAAM,aAAa,OAAO,cAAc;AACxC,KAAI,CAAC,WACH,OAAM,IAAI,MAAM,iEAAiE;AAGnF,QAAO;EAAE,MAAM,WAAW;EAAM;EAAU"}

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

@@ -0,0 +1,417 @@
+
+//#region src/mcp/cdp-connection.d.ts
+/**
+ * Injectable CDP connection abstraction for the debug-mode MCP server.
+ *
+ * The Phase 1 tool layer (`list_console_messages`, `list_network_requests`,
+ * `list_pages`) reads from CDP events captured off a Chii relay connection.
+ * To keep that tool layer CI-verifiable without a phone roundtrip, the actual
+ * relay websocket sits behind this interface. Production wires
+ * `ChiiCdpConnection` (see `chii-connection.ts`); tests inject a fake that
+ * emits canned `Runtime.consoleAPICalled` / `Network.*` events.
+ *
+ * Phase 2 adds CDP *commands* (request→response): `DOM.getDocument`,
+ * `DOMSnapshot.captureSnapshot`, `Page.captureScreenshot`. Unlike Phase 1's
+ * event streams these need a `send(method, params)` round-trip, so the
+ * connection grows a typed `send`. The fake returns canned command results.
+ *
+ * Phase 2 extension: `Runtime.evaluate` (read-only probe) added for the
+ * `measure_safe_area` tool — executes a JS snippet on the attached page and
+ * returns the result as a `RemoteObject`. The fake returns canned results for
+ * unit tests without a phone roundtrip.
+ *
+ * Only the slice of the Chrome DevTools Protocol the tools need is typed here.
+ */
+/** A target (page) the Chii relay currently sees attached. */
+interface CdpTarget {
+  /** Chii's internal target id (session UUID). */
+  id: string;
+  /** Page title reported by the in-app target. */
+  title: string;
+  /** Page URL reported by the in-app target. */
+  url: string;
+}
+/** `Runtime.RemoteObject` subset we surface for console args. */
+interface CdpRemoteObject {
+  type: string;
+  subtype?: string;
+  value?: unknown;
+  description?: string;
+  className?: string;
+}
+/** Payload of a `Runtime.consoleAPICalled` event. */
+interface ConsoleApiCalledEvent {
+  /** log | warning | error | info | debug | … */
+  type: string;
+  args: CdpRemoteObject[];
+  /** Milliseconds since epoch (CDP `Runtime.Timestamp`). */
+  timestamp: number;
+  executionContextId?: number;
+  stackTrace?: {
+    callFrames: Array<{
+      functionName: string;
+      url: string;
+      lineNumber: number;
+      columnNumber: number;
+    }>;
+  };
+}
+/** Payload of a `Network.requestWillBeSent` event (subset). */
+interface NetworkRequestWillBeSentEvent {
+  requestId: string;
+  request: {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+  };
+  /** CDP `Network.MonotonicTime` (seconds). */
+  timestamp: number;
+  /** Wall-clock seconds since epoch, when available. */
+  wallTime?: number;
+  type?: string;
+}
+/** Payload of a `Network.responseReceived` event (subset). */
+interface NetworkResponseReceivedEvent {
+  requestId: string;
+  response: {
+    url: string;
+    status: number;
+    statusText: string;
+    mimeType?: string;
+  };
+  timestamp: number;
+  type?: string;
+}
+/**
+ * A single call frame in a `Runtime.exceptionThrown` stack trace.
+ * Subset of the CDP `Runtime.CallFrame` shape.
+ */
+interface CdpCallFrame {
+  functionName: string;
+  scriptId?: string;
+  url: string;
+  lineNumber: number;
+  columnNumber: number;
+}
+/** Payload of a `Runtime.exceptionThrown` event. */
+interface RuntimeExceptionThrownEvent {
+  /** Milliseconds since epoch (CDP `Runtime.Timestamp`). */
+  timestamp: number;
+  exceptionDetails: {
+    exceptionId: number;
+    text: string;
+    lineNumber: number;
+    columnNumber: number;
+    scriptId?: string;
+    url?: string;
+    stackTrace?: {
+      callFrames: CdpCallFrame[];
+    }; /** The thrown value as a CDP `RemoteObject`. */
+    exception?: CdpRemoteObject;
+  };
+}
+/** Map of the CDP event names Phase 1 consumes to their payload shapes. */
+interface CdpEventMap {
+  'Runtime.consoleAPICalled': ConsoleApiCalledEvent;
+  'Network.requestWillBeSent': NetworkRequestWillBeSentEvent;
+  'Network.responseReceived': NetworkResponseReceivedEvent;
+  'Runtime.exceptionThrown': RuntimeExceptionThrownEvent;
+}
+type CdpEventName = keyof CdpEventMap;
+/** A `DOM.Node` subset (recursive) returned by `DOM.getDocument`. */
+interface CdpDomNode {
+  nodeId: number;
+  /** CDP node type (1 = element, 3 = text, 9 = document, …). */
+  nodeType: number;
+  nodeName: string;
+  /** Tag/local name for elements. */
+  localName?: string;
+  nodeValue?: string;
+  /** Flattened attribute list: `[name, value, name, value, …]`. */
+  attributes?: string[];
+  childNodeCount?: number;
+  children?: CdpDomNode[];
+  documentURL?: string;
+  baseURL?: string;
+}
+/** Result of `DOM.getDocument`. */
+interface DomGetDocumentResult {
+  root: CdpDomNode;
+}
+/** Result of `DOMSnapshot.captureSnapshot` (subset we surface). */
+interface DomSnapshotResult {
+  documents: unknown[];
+  strings: string[];
+}
+/** Result of `Page.captureScreenshot`. */
+interface PageCaptureScreenshotResult {
+  /** Base64-encoded image bytes (PNG by default). */
+  data: string;
+}
+/**
+ * Params for `Runtime.evaluate`.
+ * Covers the subset used by the `measure_safe_area` read-only probe.
+ */
+interface RuntimeEvaluateParams {
+  /** JavaScript expression to evaluate in the page context. */
+  expression: string;
+  /** Return the result as a plain JSON value (vs. a handle). Default false. */
+  returnByValue?: boolean;
+  /** Await a returned Promise before resolving. Default false. */
+  awaitPromise?: boolean;
+}
+/** Result of `Runtime.evaluate`. */
+interface RuntimeEvaluateResult {
+  /** The evaluation result. */
+  result: CdpRemoteObject;
+  /** Present when evaluation threw an uncaught exception. */
+  exceptionDetails?: {
+    text: string;
+    exception?: CdpRemoteObject;
+  };
+}
+/**
+ * Map of CDP command method → params/result shape. Keeps `send` typed so a
+ * `DOM.getDocument` call resolves to a `DomGetDocumentResult`, etc.
+ */
+interface CdpCommandMap {
+  'DOM.getDocument': {
+    params: {
+      depth?: number;
+      pierce?: boolean;
+    };
+    result: DomGetDocumentResult;
+  };
+  'DOMSnapshot.captureSnapshot': {
+    params: {
+      computedStyles?: string[];
+    };
+    result: DomSnapshotResult;
+  };
+  'Page.captureScreenshot': {
+    params: {
+      format?: 'png' | 'jpeg' | 'webp';
+      quality?: number;
+    };
+    result: PageCaptureScreenshotResult;
+  };
+  'Runtime.evaluate': {
+    params: RuntimeEvaluateParams;
+    result: RuntimeEvaluateResult;
+  };
+}
+type CdpCommandName = keyof CdpCommandMap;
+/**
+ * The connection the tool layer reads from. The production implementation
+ * wraps the Chii relay's CDP websocket; tests inject a fake.
+ *
+ * Implementations are expected to maintain an internal ring buffer of recent
+ * events (so a tool call returns recent history rather than only live events).
+ */
+interface CdpConnection {
+  /**
+   * Authoritative kind of this connection's transport (issue #348).
+   *
+   * - `'relay'` — backed by the Chii relay + cloudflared tunnel (a real-device
+   *   WebView, env 3/4). `ChiiCdpConnection`.
+   * - `'local'` — backed by a direct CDP websocket to a local Chromium (env 1).
+   *   `LocalCdpConnection`.
+   *
+   * This replaces the old `getEnvironment()` URL-pattern sniffing: the
+   * `mock` vs `relay` split is now a free, authoritative property of the
+   * connection itself, known before any target attaches. The `relay-dev` vs
+   * `relay-live` distinction is orthogonal (operator-supplied `liveIntent`,
+   * see `environment.ts`) because dog-food and production relays are
+   * byte-identical on the wire.
+   */
+  readonly kind: 'relay' | 'local';
+  /**
+   * Enable the CDP domains Phase 1 needs (`Runtime.enable`, `Network.enable`).
+   * Idempotent. Resolves once the relay has acknowledged (or immediately for a
+   * fake connection).
+   */
+  enableDomains(): Promise<void>;
+  /** Targets (pages) the relay currently sees attached. */
+  listTargets(): CdpTarget[];
+  /** Recent buffered events for a domain, oldest-first. */
+  getBufferedEvents<E extends CdpEventName>(event: E): ReadonlyArray<CdpEventMap[E]>;
+  /** Subscribe to live events. Returns an unsubscribe function. */
+  on<E extends CdpEventName>(event: E, listener: (payload: CdpEventMap[E]) => void): () => void;
+  /**
+   * Issue a CDP command (request → response). Phase 2's DOM/snapshot/screenshot
+   * tools use this; resolves with the typed result or rejects on a CDP error.
+   * Implementations must have called {@link enableDomains} first.
+   */
+  send<M extends CdpCommandName>(method: M, params?: CdpCommandMap[M]['params']): Promise<CdpCommandMap[M]['result']>;
+  /**
+   * Close the underlying transport and reject any in-flight commands.
+   * Optional so that minimal test fakes that don't need teardown remain
+   * compatible without change. Both `ChiiCdpConnection` and
+   * `LocalCdpConnection` already implement this.
+   */
+  close?(): void;
+  /**
+   * Refresh the attached-target list from the relay and return the result.
+   * Emits an internal `'target:attached'` event when a new target appears so
+   * that {@link waitForFirstTarget} can race against the polling round.
+   *
+   * Optional — only `ChiiCdpConnection` (relay mode) supports this; local
+   * connections and test fakes may omit it. Callers should guard with
+   * `connection.refreshTargets?.()`.
+   */
+  refreshTargets?(): Promise<CdpTarget[]>;
+  /**
+   * Waits until at least one target satisfying `filterFn` is attached, then
+   * resolves with the full target list at that moment.
+   *
+   * Optional — only `ChiiCdpConnection` provides the event-driven
+   * implementation. When absent, callers fall back to a generic polling loop.
+   *
+   * @param filterFn      - Predicate the resolved targets must satisfy.
+   * @param timeoutMs     - Reject after this many ms (default 90 000).
+   * @param pollIntervalMs - Fallback poll interval (default 500 ms).
+   */
+  waitForFirstTarget?(filterFn: (targets: CdpTarget[]) => boolean, timeoutMs?: number, pollIntervalMs?: number): Promise<CdpTarget[]>;
+}
+//#endregion
+//#region src/test-runner/bundle.d.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.
+ */
+/** Options accepted by `bundleTestFile`. */
+interface BundleOptions {
+  /**
+   * Additional esbuild `external` patterns. The SDK package
+   * (`@apps-in-toss/web-framework` and `@apps-in-toss/web-framework/*`) is
+   * always handled by the SDK redirect plugin — callers may add more patterns
+   * to be left as globals.
+   */
+  extraExternals?: string[];
+  /**
+   * Global name for the IIFE output object. Defaults to `__testBundle`.
+   * The runtime entry uses this to call `__testBundle.runTestModule()`.
+   */
+  globalName?: string;
+}
+//#endregion
+//#region src/test-runner/runtime.d.ts
+/**
+ * Thin test runtime for WebView execution.
+ *
+ * This file is bundled by `bundle.ts` together with the user's test file
+ * into a single IIFE injected into the WebView via `Runtime.evaluate`.
+ * It MUST stay browser-compatible — no Node.js APIs allowed.
+ *
+ * Design: rather than shipping @vitest/runner verbatim into a WebView (where
+ * its Node-side internals cause issues), this runtime provides a minimal
+ * compatible API surface — describe/it/test/expect globals — collects results
+ * into a plain JSON-safe object, and exports `runTestModule` as the entry point.
+ *
+ * @vitest/runner and @vitest/expect are listed as dependencies so that the
+ * package's type contracts are available and so the browser-compatible subsets
+ * can be referenced. Full pool integration (PoolRunnerInitializer) is tracked
+ * in issue #645.
+ *
+ * NOTE: this file is imported by type from Node-side code (rpc.ts / relay-worker.ts)
+ * for the RunReport / TestResult type shapes. The runtime ITSELF is not imported
+ * at runtime on the Node side — only the types are used.
+ */
+/**
+ * Result of a single test case.
+ * All fields are JSON-serialisable.
+ */
+interface TestResult {
+  /** Full dot-joined test name including nested suite names. */
+  name: string;
+  /** `'pass'` or `'fail'`. `'skip'` for skipped tests. */
+  status: 'pass' | 'fail' | 'skip';
+  /** Duration in milliseconds. */
+  duration: number;
+  /** Error message (fail only). Does NOT include the expression/secret. */
+  error?: string;
+}
+/** Aggregate report returned by `runTestModule`. */
+interface RunReport {
+  /** ISO timestamp of when `runTestModule` was called. */
+  startedAt: string;
+  /** Total elapsed milliseconds (wall-clock). */
+  duration: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  tests: TestResult[];
+}
+//#endregion
+//#region src/test-runner/relay-worker.d.ts
+/** Per-file result in the aggregate `RunReport`. */
+interface FileResult {
+  /** Absolute or relative path to the test file. */
+  file: string;
+  /** Full run report for this file, or an error if bundling/injection failed. */
+  result: RunReport | {
+    error: string;
+  };
+}
+/** Aggregate report returned by `runTestFilesOverRelay`. */
+interface RelayRunReport {
+  /** ISO timestamp of when the run started. */
+  startedAt: string;
+  /** Total elapsed wall-clock milliseconds. */
+  duration: number;
+  /** Per-file results in execution order. */
+  files: FileResult[];
+  /** Flattened totals across all files. */
+  totals: {
+    passed: number;
+    failed: number;
+    skipped: number;
+    total: number;
+  };
+}
+/** Options for `runTestFilesOverRelay`. */
+interface RelayRunOptions {
+  /**
+   * Options forwarded to `bundleTestFile` for each file.
+   */
+  bundleOptions?: BundleOptions;
+  /**
+   * Per-file evaluate timeout in milliseconds. Defaults to 30 000.
+   * Increase for long-running suites or split the file.
+   */
+  timeoutMs?: number;
+}
+//#endregion
+//#region src/test-runner/cli.d.ts
+/** Options for `runWithConnection`. */
+interface RunWithConnectionOptions extends RelayRunOptions {
+  /** If true, print a summary to stdout. Defaults to false in tests. */
+  printSummary?: boolean;
+}
+/**
+ * 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).
+ */
+declare function runWithConnection(connection: CdpConnection, files: string[], opts?: RunWithConnectionOptions): Promise<RelayRunReport>;
+/**
+ * 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.
+ */
+declare function main(argv?: string[]): Promise<void>;
+//#endregion
+export { RunWithConnectionOptions, main, runWithConnection };
+//# sourceMappingURL=cli.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../../src/mcp/cdp-connection.ts","../../src/test-runner/bundle.ts","../../src/test-runner/runtime.ts","../../src/test-runner/relay-worker.ts","../../src/test-runner/cli.ts"],"mappings":"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"}