@ait-co/devtools 0.1.117 → 0.1.119

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

@@ -345,6 +345,44 @@ interface BundleOptions {
   globalName?: string;
 }
 //#endregion
+//#region src/test-runner/capture.d.ts
+/**
+ * `__AIT_CAPTURE__` console-line parser (devtools#696).
+ *
+ * env3 test runs inject sdk-example's `aitCapture.ts`, which — when running in a
+ * WebView (no filesystem) — emits one `console.log` line per category in the
+ * stable form:
+ *
+ *   __AIT_CAPTURE__ <category> <json>
+ *
+ * The relay-worker harvests `Runtime.consoleAPICalled` events as plain text
+ * lines (see `relay-worker.ts`) and hands them here. This module's only job is
+ * to recognise the allowlisted prefix, split off the category, and keep the
+ * remaining JSON string OPAQUE — devtools does NOT own or interpret the
+ * `__AIT_CAPTURE__` record shape (that lives in sdk-example). We carry
+ * `{ category, json }` through untouched so the 2.x↔3.0 line comparison stays a
+ * downstream concern.
+ *
+ * Why a strict allowlist prefix (SECRET-HANDLING): the raw console stream may
+ * also contain wss/scheme/relay noise lines. Only lines that EXACTLY start with
+ * `'__AIT_CAPTURE__ '` pass; everything else is discarded, so a stray relay URL
+ * can never be serialised into a capture artifact.
+ *
+ * react-free, dependency-free — safe to import from any test-runner entry
+ * without dragging in the chii/cloudflared Node graph.
+ */
+/**
+ * One parsed capture line. `json` is the raw JSON string exactly as the page
+ * emitted it (an array of sdk-example capture records). devtools treats it as
+ * opaque — it is validated as parseable JSON but never inspected.
+ */
+interface AitCaptureLine {
+  /** The capture category (first whitespace-delimited token after the prefix). */
+  category: string;
+  /** The remaining JSON payload, verbatim. Opaque to devtools. */
+  json: string;
+}
+//#endregion
 //#region src/test-runner/runtime.d.ts
 /**
  * Thin test runtime for WebView execution.
@@ -418,6 +456,17 @@ interface RelayRunReport {
     skipped: number;
     total: number;
   };
+  /**
+   * `__AIT_CAPTURE__` lines harvested from the page console during the run
+   * (additive field, devtools#696). Empty unless `collectCaptures` was set.
+   * Each entry is opaque (`{ category, json }`) — devtools does not interpret
+   * the record shape, only forwards it for downstream 2.x↔3.0 diffing.
+   *
+   * SECRET-HANDLING: only lines matching the `__AIT_CAPTURE__ ` allowlist
+   * prefix reach here; relay/wss/scheme noise lines are dropped in
+   * `parseCaptureLines`.
+   */
+  captures: AitCaptureLine[];
 }
 /** Options for `runTestFilesOverRelay`. */
 interface RelayRunOptions {
@@ -430,6 +479,18 @@ interface RelayRunOptions {
    * Increase for long-running suites or split the file.
    */
   timeoutMs?: number;
+  /**
+   * When `true`, registers a live `Runtime.consoleAPICalled` listener for the
+   * duration of the run and harvests `__AIT_CAPTURE__` lines into
+   * `RelayRunReport.captures`. Defaults to **false** so the build-only
+   * eval/e2e path (and the Vitest pool) pay no listener/state overhead —
+   * `captures` is then an empty array.
+   *
+   * The listener is registered just BEFORE the first file runs and removed in a
+   * `finally` so it never accumulates across runs (no ring-buffer drain — the
+   * default 500-entry buffer would silently drop lines via `shift`).
+   */
+  collectCaptures?: boolean;
 }
 //#endregion
 //#region src/test-runner/cli.d.ts
@@ -445,30 +506,42 @@ interface RunWithConnectionOptions extends RelayRunOptions {
  * separate from `main()` so tests can call it without spawning a subprocess.
  */
 declare function runWithConnection(connection: CdpConnection, files: string[], opts?: RunWithConnectionOptions): Promise<RelayRunReport>;
+/**
+ * Decides whether to suppress the QR/attach block on stdout.
+ *
+ * Suppress when EITHER the user passed `--no-qr-stdout`, OR stdout is not a TTY
+ * / `CI` is set / `AIT_NO_QR_STDOUT` is set (non-interactive — a captured stdout
+ * must not leak the relay wss + TOTP `at=` code that the QR block encodes). The
+ * suppression is whole-chunk: `attachUrl` AND `relayUrl` ride in the same block.
+ *
+ * Exported for unit testing.
+ */
+declare function shouldSuppressQr(noQrFlag: boolean): boolean;
 /**
  * CLI entry point.
  *
- * Performs a standalone relay attach → run lifecycle:
+ * Performs a standalone relay attach → run lifecycle, sharing the attach
+ * assembly with the Vitest pool via `createRelayConnectionFactory` (single
+ * source — no drift):
  *
  * 1. Parse args: globs, --timeout, --cell-sdk-line, --cell-platform,
- *    --scheme-url (required for env3), --headless, --project-root.
+ *    --scheme-url (required for env3), --report-dir, --no-qr-stdout,
+ *    --headless, --project-root.
  * 2. Discover test files; exit 1 if none.
- * 3. Load .ait_relay secret into AIT_DEBUG_TOTP_SECRET, then boot relay family.
- * 4. Assemble AttachDeps (no qrHttpServer → text QR).
- * 5. prepareAttach(deps, 'relay-dev', { scheme_url }, conn).
- * 6. renderAndMaybeWait(deps, prep, true, timeoutMs, conn) — text QR + wait.
- * 7. If cell flags present, injectGlobals({ __AIT_CELL__: cell }) before run.
- * 8. runWithConnection(conn, files, { timeoutMs, printSummary: true }).
- * 9. family.stop(); process.exitCode = failed > 0 ? 1 : 0.
+ * 3. factory.open() — boot relay → render QR (suppressed on non-interactive
+ *    stdout) → wait for phone → inject cell → enableDomains. Returns the conn.
+ * 4. runWithConnection(conn, files, { timeoutMs, collectCaptures, printSummary }).
+ * 5. With --report-dir: write the runner-agnostic report + capture files.
+ * 6. factory.close(); process.exitCode = failed > 0 ? 1 : 0.
  *
  * The CLI is not a daemon — no lock, router, SSE, or tools_list is needed.
  * Attach timeout exits with code 1; test failures exit with code 1.
  *
  * SECRET-HANDLING: scheme_url / relay wssUrl / TOTP codes are never written to
- * stdout/stderr directly. text QR renders via renderAndMaybeWait which encodes
- * the TOTP `at=` code inside the QR payload (not in plain log lines).
+ * stdout/stderr directly. The QR block (which encodes the TOTP `at=` code) is
+ * printed only when stdout is interactive AND not suppressed.
  */
 declare function main(argv?: string[]): Promise<void>;
 //#endregion
-export { RunWithConnectionOptions, main, runWithConnection };
+export { RunWithConnectionOptions, main, runWithConnection, shouldSuppressQr };
 //# sourceMappingURL=cli.d.ts.map

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

@@ -1 +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":";;;AAwBA;;;;;;;;;AAUA;;;;;;;;;;;AASA;;UAnBiB,SAAA;EA2BI;EAzBnB,EAAA;EAoBA;EAlBA,KAAA;EAoBA;EAlBA,GAAA;AAAA;;UAIe,eAAA;EACf,IAAA;EACA,OAAA;EACA,KAAA;EACA,WAAA;EACA,SAAA;AAAA;AAsBF;AAAA,UAlBiB,qBAAA;;EAEf,IAAA;EACA,IAAA,EAAM,eAAA;EAiBN;EAfA,SAAA;EACA,kBAAA;EACA,UAAA;IACE,UAAA,EAAY,KAAA;MACV,YAAA;MACA,GAAA;MACA,UAAA;MACA,YAAA;IAAA;EAAA;AAAA;;UAMW,6BAAA;EACf,SAAA;EACA,OAAA;IACE,GAAA;IACA,MAAA;IACA,OAAA,GAAU,MAAA;EAAA;EAkBZ;EAfA,SAAA;EAgBI;EAdJ,QAAA;EACA,IAAA;AAAA;;UAIe,4BAAA;EACf,SAAA;EACA,QAAA;IACE,GAAA;IACA,MAAA;IACA,UAAA;IACA,QAAA;EAAA;EAEF,SAAA;EACA,IAAA;AAAA;;;;;UAOe,YAAA;EACf,YAAA;EACA,QAAA;EACA,GAAA;EACA,UAAA;EACA,YAAA;AAAA;;UAIe,2BAAA;EAcD;EAZd,SAAA;EACA,gBAAA;IACE,WAAA;IACA,IAAA;IACA,UAAA;IACA,YAAA;IACA,QAAA;IACA,GAAA;IACA,UAAA;MACE,UAAA,EAAY,YAAA;IAAA,GAShB;IANE,SAAA,GAAY,eAAA;EAAA;AAAA;;UAKC,WAAA;EACf,0BAAA,EAA4B,qBAAA;EAC5B,2BAAA,EAA6B,6BAAA;EAC7B,0BAAA,EAA4B,4BAAA;EAC5B,yBAAA,EAA2B,2BAAA;AAAA;AAAA,KAGjB,YAAA,SAAqB,WAAA;;UAOhB,UAAA;EACf,MAAA;EADe;EAGf,QAAA;EACA,QAAA;EAOqB;EALrB,SAAA;EACA,SAAA;EAHA;EAKA,UAAA;EACA,cAAA;EACA,QAAA,GAAW,UAAA;EACX,WAAA;EACA,OAAA;AAAA;;UAIe,oBAAA;EACf,IAAA,EAAM,UAAA;AAAA;AADR;AAAA,UAKiB,iBAAA;EACf,SAAA;EACA,OAAA;AAAA;AAFF;AAAA,UAMiB,2BAAA;;EAEf,IAAA;AAAA;AAFF;;;;AAAA,UASiB,qBAAA;EAAA;EAEf,UAAA;;EAEA,aAAA;EAFA;EAIA,YAAA;AAAA;;UAIe,qBAAA;EAAA;EAEf,MAAA,EAAQ,eAAA;;EAER,gBAAA;IACE,IAAA;IACA,SAAA,GAAY,eAAA;EAAA;AAAA;;;;;UAQC,aAAA;EACf,iBAAA;IACE,MAAA;MAAU,KAAA;MAAgB,MAAA;IAAA;IAC1B,MAAA,EAAQ,oBAAA;EAAA;EAEV,6BAAA;IACE,MAAA;MAAU,cAAA;IAAA;IACV,MAAA,EAAQ,iBAAA;EAAA;EAEV,wBAAA;IACE,MAAA;MAAU,MAAA;MAAkC,OAAA;IAAA;IAC5C,MAAA,EAAQ,2BAAA;EAAA;EAEV,kBAAA;IACE,MAAA,EAAQ,qBAAA;IACR,MAAA,EAAQ,qBAAA;EAAA;AAAA;AAAA,KAIA,cAAA,SAAuB,aAAA;;;;;;;;UASlB,aAAA;EATS;;;;AAS1B;;;;;;;;;;;EAT0B,SAyBf,IAAA;EAgBgD;;;;;EATzD,aAAA,IAAiB,OAAA;EAmBN;EAhBX,WAAA,IAAe,SAAA;EAgBZ;EAbH,iBAAA,WAA4B,YAAA,EAAc,KAAA,EAAO,CAAA,GAAI,aAAA,CAAc,WAAA,CAAY,CAAA;EAgC5D;EA7BnB,EAAA,WAAa,YAAA,EAAc,KAAA,EAAO,CAAA,EAAG,QAAA,GAAW,OAAA,EAAS,WAAA,CAAY,CAAA;EA8C1D;;;;;EAvCX,IAAA,WAAe,cAAA,EACb,MAAA,EAAQ,CAAA,EACR,MAAA,GAAS,aAAA,CAAc,CAAA,cACtB,OAAA,CAAQ,aAAA,CAAc,CAAA;EAnBR;;;;;;EA2BjB,KAAA;EArB0C;;;;;;;;;EAgC1C,cAAA,KAAmB,OAAA,CAAQ,SAAA;EA7B0C;;;;;;;;;;;EA0CrE,kBAAA,EACE,QAAA,GAAW,OAAA,EAAS,SAAA,gBACpB,SAAA,WACA,cAAA,YACC,OAAA,CAAQ,SAAA;AAAA;;;;AArRb;;;;;;;;;AAUA;;;;;;;;;;;AASA;;;;;;;;;;;;;;;;;;AAkBA;;;;;;;;;;;;;;;AAeA;AAAA,UCPiB,aAAA;;;;;;;EAOf,cAAA;EDME;;;;ECDF,UAAA;AAAA;;;;ADzDF;;;;;;;;;AAUA;;;;;;;;;;;AASA;;;;AAAA,UEbiB,UAAA;EFgBf;EEdA,IAAA;EFgBA;EEdA,MAAA;EFgBA;EEdA,QAAA;EFec;EEbd,KAAA;AAAA;;UAIe,SAAA;EFaC;EEXhB,SAAA;EFiBe;EEff,QAAA;EACA,MAAA;EACA,MAAA;EACA,OAAA;EACA,KAAA,EAAO,UAAA;AAAA;;;;UC3BQ,UAAA;EHoBA;EGlBf,IAAA;;EAEA,MAAA,EAAQ,SAAA;IAAc,KAAA;EAAA;AAAA;;UAIP,cAAA;EHmBf;EGjBA,SAAA;EHkBc;EGhBd,QAAA;EHkBI;EGhBJ,KAAA,EAAO,UAAA;EHkBH;EGhBJ,MAAA;IACE,MAAA;IACA,MAAA;IACA,OAAA;IACA,KAAA;EAAA;AAAA;;UAKa,eAAA;EHiBb;;;EGbF,aAAA,GAAgB,aAAA;EHmBhB;;;;EGdA,SAAA;AAAA;;;;UCUe,wBAAA,SAAiC,eAAA;EJ9BhD;EIgCA,YAAA;AAAA;;;AJ1BF;;;;iBImCsB,iBAAA,CACpB,UAAA,EAAY,aAAA,EACZ,KAAA,YACA,IAAA,GAAO,wBAAA,GACN,OAAA,CAAQ,cAAA;;;;;;;;;;;;;;AJrBX;;;;;;;;;;iBI6DsB,IAAA,CAAK,IAAA,cAAyC,OAAA"}
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../../src/mcp/cdp-connection.ts","../../src/test-runner/bundle.ts","../../src/test-runner/capture.ts","../../src/test-runner/runtime.ts","../../src/test-runner/relay-worker.ts","../../src/test-runner/cli.ts"],"mappings":"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"}

package/dist/test-runner/cli.js

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { n as runWithConnection, t as main } from "../cli-CvUNQKqw.js";
-export { main, runWithConnection };
+import { n as runWithConnection, r as shouldSuppressQr, t as main } from "../cli-RhzASQef.js";
+export { main, runWithConnection, shouldSuppressQr };

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

@@ -1,5 +1,71 @@
-import { i as createRelayPool, n as RelayConnectionFactory, t as RELAY_POOL_NAME } from "../pool-htlVnEFl.js";
+import { i as createRelayPool, n as RelayConnectionFactory, t as RELAY_POOL_NAME } from "../pool-U9FrxEuR.js";
 
+//#region src/test-runner/relay-factory.d.ts
+/** Options for {@link createRelayConnectionFactory}. */
+interface RelayConnectionFactoryOptions {
+  /**
+   * intoss-private:// scheme URL from `ait deploy --scheme-only` (env3). The
+   * phone cold-loads the candidate bundle this URL points at. SECRET-HANDLING:
+   * never logged.
+   */
+  schemeUrl: string;
+  /**
+   * Project root for the `.ait_relay` secret lookup (read-only). Defaults to
+   * `process.cwd()`.
+   */
+  projectRoot?: string;
+  /**
+   * Attach wait timeout in ms — how long `open()` waits for the phone to scan
+   * the QR and attach. Defaults to 600 000 (10 min) to give time for a manual
+   * scan. (The per-file evaluate timeout is separate, passed via the pool's
+   * `run` options.)
+   */
+  timeoutMs?: number;
+  /** Disable browser auto-open of the QR dashboard (text QR only). */
+  headless?: boolean;
+  /**
+   * Cell axes injected as `__AIT_CELL__` before the first test bundle runs, so
+   * sdk-example's capture picks up the correct sdkLine/platform. Optional — when
+   * omitted no cell is injected. The values are not secrets.
+   */
+  cell?: {
+    sdkLine: string;
+    platform: string;
+  };
+  /**
+   * Receives the QR/attach render content (text chunks) from
+   * `renderAndMaybeWait`, so the caller decides whether to print them — e.g.
+   * suppress on non-interactive stdout.
+   *
+   * REQUIRED (not optional) on purpose: these chunks contain the QR payload
+   * (which encodes the relay wss + TOTP `at=` code) and the attach JSON block.
+   * Making the hook mandatory means the factory never falls back to printing
+   * them itself — a downstream `vitest.config.ts` consumer that wires this via
+   * the `@ait-co/devtools/test-runner` barrel is forced to make an explicit
+   * stdout decision rather than silently leaking the secret-bearing block.
+   *
+   * SECRET-HANDLING: when a non-interactive caller is detected the hook MUST
+   * suppress the WHOLE chunk (not just `attachUrl`), since `relayUrl` rides in
+   * the same block.
+   */
+  onQrContent: (textChunks: string[]) => void;
+}
+/**
+ * Builds a {@link RelayConnectionFactory} that opens a standalone env3 relay
+ * connection.
+ *
+ * `open()` performs the full attach lifecycle and BLOCKS for tens of seconds (up
+ * to `timeoutMs`) while a human scans the rendered QR with their phone — there
+ * is no way around the manual scan for env3. It resolves with the live
+ * `CdpConnection` once a matching page attaches; `close()` tears the relay
+ * family down.
+ *
+ * The factory holds the booted relay family in a closure so `close()` can stop
+ * it. A second `open()` on the same factory boots a fresh family (the previous
+ * one should have been `close()`d first).
+ */
+declare function createRelayConnectionFactory(opts: RelayConnectionFactoryOptions): RelayConnectionFactory;
+//#endregion
 //#region src/test-runner/config.d.ts
 /**
  * Resolved phone-test configuration returned by `definePhoneTestConfig`.
@@ -58,6 +124,14 @@ interface PhoneVitestUserConfig extends PhoneTestUserConfig {
    * never stores or logs those values.
    */
   connection: RelayConnectionFactory;
+  /**
+   * When `true`, the relay pool harvests `__AIT_CAPTURE__` console lines during
+   * the run (forwarded as `collectCaptures` to `runTestFilesOverRelay`), so
+   * `RelayRunReport.captures` is populated; a downstream consumer persists the
+   * artifacts (pool-side artifact writing + cell-meta wiring lands in PR-S1).
+   * Omitted/`false` = no capture harvest (build-only, zero listener overhead).
+   */
+  collectCaptures?: boolean;
 }
 /**
  * Build the Vitest `test` config slice for running tests on a device over the
@@ -76,5 +150,5 @@ interface PhoneVitestUserConfig extends PhoneTestUserConfig {
  */
 declare function definePhoneVitestConfig(userConfig: PhoneVitestUserConfig): PhoneVitestTestConfig;
 //#endregion
-export { PhoneTestConfig, PhoneTestUserConfig, PhoneVitestTestConfig, PhoneVitestUserConfig, RELAY_POOL_NAME, type RelayConnectionFactory, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
+export { PhoneTestConfig, PhoneTestUserConfig, PhoneVitestTestConfig, PhoneVitestUserConfig, RELAY_POOL_NAME, type RelayConnectionFactory, type RelayConnectionFactoryOptions, createRelayConnectionFactory, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
 //# sourceMappingURL=config.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"config.d.ts","names":[],"sources":["../../src/test-runner/relay-factory.ts","../../src/test-runner/config.ts"],"mappings":";;;;UAgDiB,6BAAA;ECFA;;;;;EDQf,SAAA;ECLA;;;AAgBF;EDNE,WAAA;;;;;;;EAOA,SAAA;ECae;EDXf,QAAA;;;;;;EAMA,IAAA;IAAS,OAAA;IAAiB,QAAA;EAAA;ECeX;;;;;;;;;;AAkCjB;;;;;;EDhCE,WAAA,GAAc,UAAA;AAAA;;;;;;;;;;;;;;;iBAiBA,4BAAA,CACd,IAAA,EAAM,6BAAA,GACL,sBAAA;;;;;;UClFc,eAAA;EDkFd;;;;EC7ED,OAAA;;AALF;;EASE,SAAA;EAT8B;;;;EAc9B,cAAA;AAAA;AAIF;AAAA,UAAiB,mBAAA;EACf,OAAA;EACA,SAAA;EACA,cAAA;AAAA;;;;AAgBF;;;;iBAAgB,qBAAA,CAAsB,UAAA,GAAa,mBAAA,GAAsB,eAAA;;;;;AAczE;;UAAiB,qBAAA;EAEC;EAAhB,IAAA,EAAM,UAAA,QAAkB,eAAA;EAAlB;EAEN,OAAA;EAAA;EAEA,WAAA;AAAA;;UAIe,qBAAA,SAA8B,mBAAA;EAAR;;;;;;;EAQrC,UAAA,EAAY,sBAAA;EAQG;AAkBjB;;;;;;EAlBE,eAAA;AAAA;;;;;;;;;;;;;;;;iBAkBc,uBAAA,CAAwB,UAAA,EAAY,qBAAA,GAAwB,qBAAA"}

package/dist/test-runner/config.js

@@ -1,4 +1,5 @@
 import { RELAY_POOL_NAME, createRelayPool } from "./pool.js";
+import { t as createRelayConnectionFactory } from "../relay-factory-DVI7TrX4.js";
 //#region src/test-runner/config.ts
 const DEFAULT_CONFIG = {
 	include: ["**/*.ait.test.ts"],
@@ -41,7 +42,8 @@ function definePhoneVitestConfig(userConfig) {
 			connection: userConfig.connection,
 			run: {
 				timeoutMs: resolved.timeoutMs,
-				bundleOptions: { extraExternals: resolved.extraExternals }
+				bundleOptions: { extraExternals: resolved.extraExternals },
+				collectCaptures: userConfig.collectCaptures === true
 			}
 		}),
 		include: resolved.include,
@@ -49,6 +51,6 @@ function definePhoneVitestConfig(userConfig) {
 	};
 }
 //#endregion
-export { RELAY_POOL_NAME, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
+export { RELAY_POOL_NAME, createRelayConnectionFactory, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
 
 //# sourceMappingURL=config.js.map

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

@@ -1 +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 *   // ait-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 `['**\\/*.ait.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: ['**/*.ait.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,mBAAmB;CAC7B,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"}
+{"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 *   // ait-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';\nimport {\n  createRelayConnectionFactory,\n  type RelayConnectionFactoryOptions,\n} from './relay-factory.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 `['**\\/*.ait.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: ['**/*.ait.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   * When `true`, the relay pool harvests `__AIT_CAPTURE__` console lines during\n   * the run (forwarded as `collectCaptures` to `runTestFilesOverRelay`), so\n   * `RelayRunReport.captures` is populated; a downstream consumer persists the\n   * artifacts (pool-side artifact writing + cell-meta wiring lands in PR-S1).\n   * Omitted/`false` = no capture harvest (build-only, zero listener overhead).\n   */\n  collectCaptures?: boolean;\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        // Harvest captures only when explicitly opted in — keeps the build-only\n        // path free of the live console listener (#696).\n        collectCaptures: userConfig.collectCaptures === true,\n      },\n    }),\n    include: resolved.include,\n    testTimeout: resolved.timeoutMs,\n  };\n}\n\nexport type { RelayConnectionFactory, RelayConnectionFactoryOptions };\n// Re-exported so a downstream `vitest.config.ts` can build the connection\n// factory straight from the `@ait-co/devtools/test-runner` barrel. relay-factory\n// keeps its heavy MCP graph behind dynamic imports, so this static re-export does\n// NOT drag chii/cloudflared/tools onto this Node-config entry (verified by\n// scripts/check-test-runner-dist.sh).\nexport { createRelayConnectionFactory, createRelayPool, RELAY_POOL_NAME };\n"],"mappings":";;;AAoDA,MAAM,iBAAkC;CACtC,SAAS,CAAC,mBAAmB;CAC7B,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;;;;;;;;;;;;;;;;;AAqDH,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;IAG1D,iBAAiB,WAAW,oBAAoB;IACjD;GACF,CAAC;EACF,SAAS,SAAS;EAClB,aAAa,SAAS;EACvB"}

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

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