@ait-co/devtools 0.1.108 → 0.1.110

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

@@ -1 +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"}
+{"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 bundle includes the\n * test runtime (`runtime.ts`), which provides `describe/it/test/expect` and\n * the `runTestModule(factory)` entry point.\n *\n * ## How the wiring works\n *\n * The bundle exposes two exports on `globalThis.__testBundle`:\n *   - `runTestModule` — the runtime's entry function.\n *   - `__userFactory`  — an async function whose body is the user's top-level\n *     test registration code (describe/it/test calls).\n *\n * The Node-side RPC (`rpc.ts`) calls:\n *   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`\n *\n * `runTestModule` then installs `describe/it/test/expect` as globals, invokes\n * the factory (which registers all tests), runs them, and returns a `RunReport`.\n *\n * ## Why a factory wrapper is needed\n *\n * Naively adding the runtime to `entryPoints` and bundling the user file would\n * fail for two reasons:\n *   1. `describe/it/test/expect` from the runtime are module-local in the IIFE\n *      scope. The user's top-level `describe(...)` calls expect them as globals —\n *      they are not globals until `runTestModule` installs them.\n *   2. Even with globals pre-installed, the user file runs at IIFE-evaluation\n *      time, before the RPC layer calls `runTestModule` to reset state and start\n *      the test clock.\n *\n * The factory approach solves both: the user's registration code is deferred\n * into a function that `runTestModule` calls AFTER installing the globals.\n *\n * ## Factory extraction algorithm\n *\n * The `userFactoryPlugin` reads the user file and splits lines into:\n *   - **top-level**: `import …` and re-export lines — kept at module scope\n *     (the only valid position for static `import` in ESM).\n *   - **body**: all other statements — moved into the body of the exported\n *     `__userFactory` async function.\n *\n * esbuild processes the re-generated module, following each static import\n * through the normal dependency graph (including the SDK-redirect plugin).\n *\n * ## SDK redirect\n *\n * Imports of `@apps-in-toss/web-framework` (and sub-paths) are intercepted via\n * the `sdkRedirectPlugin` and replaced with a virtual `window.__sdk` proxy that\n * `src/in-app/auto.ts` installs at runtime. This 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 { accessSync } from 'node:fs';\nimport * as fs from 'node:fs/promises';\nimport * as path from 'node:path';\nimport { fileURLToPath } from 'node:url';\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(__userFactory)`.\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 * esbuild plugin that transforms the user test file into a module that exports\n * an async `__userFactory` function. The factory defers the user's top-level\n * test registration code (describe/it/test calls) so it only runs when\n * `runTestModule(__userFactory)` explicitly invokes it — AFTER the runtime has\n * installed describe/it/test/expect as globals.\n *\n * Algorithm:\n *   - Lines matching import declarations or re-export statements are kept at\n *     module top-level (the only valid ESM position for static `import`).\n *   - All other lines (describe/it/test calls, local declarations, etc.) are\n *     moved into the body of the exported async factory function.\n *\n * This preserves SDK import resolution (the sdk-redirect plugin processes\n * top-level imports normally) while deferring test registration to the factory.\n */\nfunction userFactoryPlugin(absPath: string): esbuild.Plugin {\n  const NAMESPACE = 'user-test-factory';\n  return {\n    name: 'user-test-factory',\n    setup(build) {\n      // Resolve the virtual \"user-test-factory\" specifier to our namespace.\n      build.onResolve({ filter: /^user-test-factory$/ }, () => ({\n        path: absPath,\n        namespace: NAMESPACE,\n      }));\n\n      // Load the user file, split imports from body, wrap body in the factory.\n      build.onLoad({ filter: /.*/, namespace: NAMESPACE }, async (args) => {\n        const source = await fs.readFile(args.path, 'utf8');\n        const lines = source.split('\\n');\n\n        const topLevelLines: string[] = [];\n        const bodyLines: string[] = [];\n\n        // Matches `export` value declarations that cannot appear inside a\n        // function body. We strip the `export` keyword so they become plain\n        // declarations inside the factory.\n        const EXPORT_DECLARATION_RE =\n          /^(export\\s+)(default\\s+|async\\s+function\\s+|function\\s+|class\\s+|const\\s+|let\\s+|var\\s+)/;\n\n        for (const line of lines) {\n          const trimmed = line.trimStart();\n          const indent = line.slice(0, line.length - trimmed.length);\n\n          // Static import declarations must stay at module top level\n          // (the ESM spec forbids `import` inside a function body).\n          if (\n            trimmed.startsWith('import ') ||\n            trimmed.startsWith('import{') ||\n            trimmed.startsWith(\"import'\") ||\n            trimmed.startsWith('import\"')\n          ) {\n            topLevelLines.push(line);\n          } else if (trimmed.startsWith('export ')) {\n            // Determine whether this is a re-export (stays top-level) or a value\n            // declaration (goes into the factory, export keyword stripped).\n            const m = trimmed.match(EXPORT_DECLARATION_RE);\n            if (m) {\n              // Value declaration — strip `export ` and move into factory body.\n              // e.g. `export function hello()` → `function hello()`\n              //       `export const x = 1`     → `const x = 1`\n              bodyLines.push(indent + trimmed.slice('export '.length));\n            } else {\n              // Re-export or `export type { … }` — stays at top level.\n              topLevelLines.push(line);\n            }\n          } else {\n            bodyLines.push(line);\n          }\n        }\n\n        const factoryContent = [\n          ...topLevelLines,\n          '',\n          '// biome-ignore lint: generated factory wrapper',\n          'export default async function __userFactory(): Promise<void> {',\n          ...bodyLines.map((l) => `  ${l}`),\n          '}',\n        ].join('\\n');\n\n        return {\n          contents: factoryContent,\n          loader: 'ts',\n          resolveDir: path.dirname(absPath),\n        };\n      });\n    },\n  };\n}\n\n/**\n * Returns the absolute path to the co-located runtime module.\n *\n * In the source tree (running via tsx / ts-node) the file is `runtime.ts`.\n * After `tsdown` compiles to `dist/test-runner/`, it becomes `runtime.js`.\n * We try both extensions to support both environments.\n */\nfunction getRuntimePath(): string {\n  const dir = path.dirname(fileURLToPath(import.meta.url));\n  for (const ext of ['.ts', '.js']) {\n    const candidate = path.join(dir, `runtime${ext}`);\n    try {\n      accessSync(candidate);\n      return candidate;\n    } catch {\n      // try next extension\n    }\n  }\n  // Let esbuild produce a \"file not found\" error with a clear path.\n  return path.join(dir, 'runtime.js');\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` — the runtime entry (from `runtime.ts`).\n *   - `__userFactory` — an async function wrapping the user's test registration\n *     code so it runs AFTER `runTestModule` installs the globals.\n *\n * Callers (rpc.ts) invoke:\n *   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`\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  const runtimePath = getRuntimePath();\n\n  // Stdin wrapper: import the runtime and the user factory, re-export both.\n  // esbuild follows the static imports to include runtime.ts and the user file\n  // (via the userFactoryPlugin) in the single IIFE output.\n  const wrapperContent = [\n    `import { runTestModule } from ${JSON.stringify(runtimePath)};`,\n    `import __userFactory from \"user-test-factory\";`,\n    `export { runTestModule, __userFactory };`,\n  ].join('\\n');\n\n  const result = await esbuild.build({\n    stdin: {\n      contents: wrapperContent,\n      loader: 'ts',\n      // resolveDir is used for relative imports from the wrapper. Since the\n      // wrapper only imports absolute paths (runtimePath) and the virtual\n      // \"user-test-factory\" specifier (resolved by plugin), the directory\n      // doesn't matter — but we still provide a sensible default.\n      resolveDir: path.dirname(absPath),\n    },\n    bundle: true,\n    format: 'iife',\n    globalName,\n    platform: 'browser',\n    target: 'es2022',\n    write: false,\n    plugins: [userFactoryPlugin(absPath), sdkRedirectPlugin()],\n    external: extraExternals,\n    treeShaking: true,\n    // Ensure the IIFE result is always reachable via globalThis regardless of\n    // the evaluation context.  esbuild's `globalName` emits:\n    //   var __testBundle = (() => { ... })();\n    // When `Runtime.evaluate` runs this bundle code inside an outer wrapper\n    // (rpc.ts's async IIFE), `var` creates a local variable — NOT a global\n    // property — so `globalThis.__testBundle` stays `undefined`.  The footer\n    // explicitly assigns the local variable to `globalThis` to close that gap.\n    footer: {\n      js: `globalThis[${JSON.stringify(globalName)}] = ${globalName};`,\n    },\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":"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"}

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

@@ -279,11 +279,53 @@ interface CdpConnection {
  * 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).
+ * injected into a WebView via `Runtime.evaluate`. The bundle includes the
+ * test runtime (`runtime.ts`), which provides `describe/it/test/expect` and
+ * the `runTestModule(factory)` entry point.
+ *
+ * ## How the wiring works
+ *
+ * The bundle exposes two exports on `globalThis.__testBundle`:
+ *   - `runTestModule` — the runtime's entry function.
+ *   - `__userFactory`  — an async function whose body is the user's top-level
+ *     test registration code (describe/it/test calls).
+ *
+ * The Node-side RPC (`rpc.ts`) calls:
+ *   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
+ *
+ * `runTestModule` then installs `describe/it/test/expect` as globals, invokes
+ * the factory (which registers all tests), runs them, and returns a `RunReport`.
+ *
+ * ## Why a factory wrapper is needed
+ *
+ * Naively adding the runtime to `entryPoints` and bundling the user file would
+ * fail for two reasons:
+ *   1. `describe/it/test/expect` from the runtime are module-local in the IIFE
+ *      scope. The user's top-level `describe(...)` calls expect them as globals —
+ *      they are not globals until `runTestModule` installs them.
+ *   2. Even with globals pre-installed, the user file runs at IIFE-evaluation
+ *      time, before the RPC layer calls `runTestModule` to reset state and start
+ *      the test clock.
+ *
+ * The factory approach solves both: the user's registration code is deferred
+ * into a function that `runTestModule` calls AFTER installing the globals.
+ *
+ * ## Factory extraction algorithm
+ *
+ * The `userFactoryPlugin` reads the user file and splits lines into:
+ *   - **top-level**: `import …` and re-export lines — kept at module scope
+ *     (the only valid position for static `import` in ESM).
+ *   - **body**: all other statements — moved into the body of the exported
+ *     `__userFactory` async function.
+ *
+ * esbuild processes the re-generated module, following each static import
+ * through the normal dependency graph (including the SDK-redirect plugin).
+ *
+ * ## SDK redirect
+ *
+ * Imports of `@apps-in-toss/web-framework` (and sub-paths) are intercepted via
+ * the `sdkRedirectPlugin` and replaced with a virtual `window.__sdk` proxy that
+ * `src/in-app/auto.ts` installs at runtime. This works for both 2.x and 3.x SDK.
  *
  * SECRET-HANDLING: the returned bundle code is caller-managed; never log it.
  */
@@ -298,7 +340,7 @@ interface BundleOptions {
   extraExternals?: string[];
   /**
    * Global name for the IIFE output object. Defaults to `__testBundle`.
-   * The runtime entry uses this to call `__testBundle.runTestModule()`.
+   * The runtime entry uses this to call `__testBundle.runTestModule(__userFactory)`.
    */
   globalName?: string;
 }
@@ -318,8 +360,8 @@ interface BundleOptions {
  *
  * @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.
+ * can be referenced. The Vitest custom pool that drives this runtime through
+ * Vitest's `PoolRunnerInitializer` lives in `pool.ts`.
  *
  * 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
@@ -398,18 +440,21 @@ interface RunWithConnectionOptions extends RelayRunOptions {
 }
 /**
  * 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.
+ * This pure function is the testable core of the CLI (and is what the
+ * `run_tests` MCP tool calls against the daemon's attached connection); it is
+ * separate from `main()` so tests can call it without spawning a subprocess.
  *
- * TODO (#645): add real relay attach/detach lifecycle here (connect via
- * Chii relay URL, call enableDomains, run, then close).
+ * A standalone CLI relay attach/detach lifecycle (connect via Chii relay URL,
+ * `enableDomains`, run, then close) is not wired into `main()` yet.
  */
 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.
+ * Resolves the matched test files and prints a "relay attach required" notice:
+ * the CLI's own standalone relay attach (resolve CDP URL, attach, run, close) is
+ * not wired yet, so today these files run via the `run_tests` MCP tool against
+ * the daemon's attached page.
  */
 declare function main(argv?: string[]): Promise<void>;
 //#endregion

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":"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"}
+{"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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"}

package/dist/test-runner/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
+import * as fs from "node:fs/promises";
 import { glob } from "node:fs/promises";
 import * as path from "node:path";
 import { isAbsolute, resolve } from "node:path";
+import { accessSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 //#region src/test-runner/discover.ts
 /**
 * Test-file discovery shared by the `devtools-test` CLI and the `run_tests`
@@ -39,11 +42,53 @@ async function discoverTestFiles(patterns, cwd) {
 * 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).
+* injected into a WebView via `Runtime.evaluate`. The bundle includes the
+* test runtime (`runtime.ts`), which provides `describe/it/test/expect` and
+* the `runTestModule(factory)` entry point.
+*
+* ## How the wiring works
+*
+* The bundle exposes two exports on `globalThis.__testBundle`:
+*   - `runTestModule` — the runtime's entry function.
+*   - `__userFactory`  — an async function whose body is the user's top-level
+*     test registration code (describe/it/test calls).
+*
+* The Node-side RPC (`rpc.ts`) calls:
+*   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
+*
+* `runTestModule` then installs `describe/it/test/expect` as globals, invokes
+* the factory (which registers all tests), runs them, and returns a `RunReport`.
+*
+* ## Why a factory wrapper is needed
+*
+* Naively adding the runtime to `entryPoints` and bundling the user file would
+* fail for two reasons:
+*   1. `describe/it/test/expect` from the runtime are module-local in the IIFE
+*      scope. The user's top-level `describe(...)` calls expect them as globals —
+*      they are not globals until `runTestModule` installs them.
+*   2. Even with globals pre-installed, the user file runs at IIFE-evaluation
+*      time, before the RPC layer calls `runTestModule` to reset state and start
+*      the test clock.
+*
+* The factory approach solves both: the user's registration code is deferred
+* into a function that `runTestModule` calls AFTER installing the globals.
+*
+* ## Factory extraction algorithm
+*
+* The `userFactoryPlugin` reads the user file and splits lines into:
+*   - **top-level**: `import …` and re-export lines — kept at module scope
+*     (the only valid position for static `import` in ESM).
+*   - **body**: all other statements — moved into the body of the exported
+*     `__userFactory` async function.
+*
+* esbuild processes the re-generated module, following each static import
+* through the normal dependency graph (including the SDK-redirect plugin).
+*
+* ## SDK redirect
+*
+* Imports of `@apps-in-toss/web-framework` (and sub-paths) are intercepted via
+* the `sdkRedirectPlugin` and replaced with a virtual `window.__sdk` proxy that
+* `src/in-app/auto.ts` installs at runtime. This works for both 2.x and 3.x SDK.
 *
 * SECRET-HANDLING: the returned bundle code is caller-managed; never log it.
 */
@@ -93,10 +138,90 @@ module.exports = __proxy;
 	};
 }
 /**
+* esbuild plugin that transforms the user test file into a module that exports
+* an async `__userFactory` function. The factory defers the user's top-level
+* test registration code (describe/it/test calls) so it only runs when
+* `runTestModule(__userFactory)` explicitly invokes it — AFTER the runtime has
+* installed describe/it/test/expect as globals.
+*
+* Algorithm:
+*   - Lines matching import declarations or re-export statements are kept at
+*     module top-level (the only valid ESM position for static `import`).
+*   - All other lines (describe/it/test calls, local declarations, etc.) are
+*     moved into the body of the exported async factory function.
+*
+* This preserves SDK import resolution (the sdk-redirect plugin processes
+* top-level imports normally) while deferring test registration to the factory.
+*/
+function userFactoryPlugin(absPath) {
+	const NAMESPACE = "user-test-factory";
+	return {
+		name: "user-test-factory",
+		setup(build) {
+			build.onResolve({ filter: /^user-test-factory$/ }, () => ({
+				path: absPath,
+				namespace: NAMESPACE
+			}));
+			build.onLoad({
+				filter: /.*/,
+				namespace: NAMESPACE
+			}, async (args) => {
+				const lines = (await fs.readFile(args.path, "utf8")).split("\n");
+				const topLevelLines = [];
+				const bodyLines = [];
+				const EXPORT_DECLARATION_RE = /^(export\s+)(default\s+|async\s+function\s+|function\s+|class\s+|const\s+|let\s+|var\s+)/;
+				for (const line of lines) {
+					const trimmed = line.trimStart();
+					const indent = line.slice(0, line.length - trimmed.length);
+					if (trimmed.startsWith("import ") || trimmed.startsWith("import{") || trimmed.startsWith("import'") || trimmed.startsWith("import\"")) topLevelLines.push(line);
+					else if (trimmed.startsWith("export ")) if (trimmed.match(EXPORT_DECLARATION_RE)) bodyLines.push(indent + trimmed.slice(7));
+					else topLevelLines.push(line);
+					else bodyLines.push(line);
+				}
+				return {
+					contents: [
+						...topLevelLines,
+						"",
+						"// biome-ignore lint: generated factory wrapper",
+						"export default async function __userFactory(): Promise<void> {",
+						...bodyLines.map((l) => `  ${l}`),
+						"}"
+					].join("\n"),
+					loader: "ts",
+					resolveDir: path.dirname(absPath)
+				};
+			});
+		}
+	};
+}
+/**
+* Returns the absolute path to the co-located runtime module.
+*
+* In the source tree (running via tsx / ts-node) the file is `runtime.ts`.
+* After `tsdown` compiles to `dist/test-runner/`, it becomes `runtime.js`.
+* We try both extensions to support both environments.
+*/
+function getRuntimePath() {
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	for (const ext of [".ts", ".js"]) {
+		const candidate = path.join(dir, `runtime${ext}`);
+		try {
+			accessSync(candidate);
+			return candidate;
+		} catch {}
+	}
+	return path.join(dir, "runtime.js");
+}
+/**
 * Bundles `absPath` into a single IIFE string suitable for `Runtime.evaluate`.
 *
-* The IIFE installs `window.__testBundle` (or the custom `globalName`) with
-* `runTestModule` as the callable entry point.
+* The IIFE installs `window.__testBundle` (or the custom `globalName`) with:
+*   - `runTestModule` — the runtime entry (from `runtime.ts`).
+*   - `__userFactory` — an async function wrapping the user's test registration
+*     code so it runs AFTER `runTestModule` installs the globals.
+*
+* Callers (rpc.ts) invoke:
+*   `globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory)`
 *
 * @param absPath - Absolute path to the user test file.
 * @param opts    - Optional bundling overrides.
@@ -104,17 +229,29 @@ module.exports = __proxy;
 async function bundleTestFile(absPath, opts) {
 	const globalName = opts?.globalName ?? "__testBundle";
 	const extraExternals = opts?.extraExternals ?? [];
-	const result = await (await import("esbuild")).build({
-		entryPoints: [absPath],
+	const esbuild = await import("esbuild");
+	const runtimePath = getRuntimePath();
+	const wrapperContent = [
+		`import { runTestModule } from ${JSON.stringify(runtimePath)};`,
+		`import __userFactory from "user-test-factory";`,
+		`export { runTestModule, __userFactory };`
+	].join("\n");
+	const result = await esbuild.build({
+		stdin: {
+			contents: wrapperContent,
+			loader: "ts",
+			resolveDir: path.dirname(absPath)
+		},
 		bundle: true,
 		format: "iife",
 		globalName,
 		platform: "browser",
 		target: "es2022",
 		write: false,
-		plugins: [sdkRedirectPlugin()],
+		plugins: [userFactoryPlugin(absPath), sdkRedirectPlugin()],
 		external: extraExternals,
-		treeShaking: true
+		treeShaking: true,
+		footer: { js: `globalThis[${JSON.stringify(globalName)}] = ${globalName};` }
 	});
 	const warnings = result.warnings.map((w) => `${path.relative(process.cwd(), w.location?.file ?? "")}:${w.location?.line ?? "?"}: ${w.text}`);
 	const outputFile = result.outputFiles?.[0];
@@ -141,7 +278,7 @@ const DEFAULT_TIMEOUT_MS = 3e4;
 * 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)});  }})()`;
+	return `(async () => {  try { ${bundleCode} } catch(e) {    return JSON.stringify({ok:false,error:'bundle-eval: ' + String(e && e.message || e)});  }  if (typeof globalThis.__testBundle !== 'object' || typeof globalThis.__testBundle.runTestModule !== 'function' || typeof globalThis.__testBundle.__userFactory !== 'function') {    return JSON.stringify({ok:false,error:'bundle-missing-export: __testBundle.runTestModule or __userFactory is not a function'});  }  try {    const report = await globalThis.__testBundle.runTestModule(globalThis.__testBundle.__userFactory);    return JSON.stringify({ok:true,value:report});  } catch(e) {    return JSON.stringify({ok:false,error:'test-run: ' + String(e && e.message || e)});  }})()`;
 }
 /**
 * Parses the raw CDP `returnByValue` result from a `buildRunTestsExpression`
@@ -274,14 +411,15 @@ async function runTestFilesOverRelay(connection, files, opts) {
 //#endregion
 //#region src/test-runner/cli.ts
 /**
-* `devtools-test` CLI — MVP skeleton.
+* `devtools-test` CLI.
 *
-* 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.
+* Shares test-file discovery with the `run_tests` MCP tool (`discoverTestFiles`)
+* and exposes `runWithConnection` — the pure run core that bundles, injects, and
+* collects each file over a CDP connection. Today the run path that has a live
+* connection is the `run_tests` MCP tool (it runs these files against the
+* daemon's attached page); the CLI's own standalone relay attach (resolve CDP
+* URL → attach → run → close) is not wired yet, so `main()` resolves the matched
+* files and points the operator at the MCP tool.
 *
 * NOTE: no shebang in this source file — the tsdown entry's `banner` option
 * injects `#!/usr/bin/env node` into the compiled output (same pattern as
@@ -302,12 +440,10 @@ DESCRIPTION
   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.
+  A live CDP relay connection must be active before running tests. Use the
+  \`run_tests\` MCP tool (via \`devtools-mcp\` / \`/ait debug\`) to run these files
+  against an attached page — the CLI's own standalone relay attach is not wired
+  yet (it currently resolves the matched files and defers to that tool).
 
 EXAMPLE
   devtools-test 'src/**/*.phone.test.ts' --timeout 60000
@@ -315,11 +451,12 @@ EXAMPLE
 `.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.
+* This pure function is the testable core of the CLI (and is what the
+* `run_tests` MCP tool calls against the daemon's attached connection); it is
+* separate from `main()` so tests can call it without spawning a subprocess.
 *
-* TODO (#645): add real relay attach/detach lifecycle here (connect via
-* Chii relay URL, call enableDomains, run, then close).
+* A standalone CLI relay attach/detach lifecycle (connect via Chii relay URL,
+* `enableDomains`, run, then close) is not wired into `main()` yet.
 */
 async function runWithConnection(connection, files, opts) {
 	const report = await runTestFilesOverRelay(connection, files, opts);
@@ -332,8 +469,10 @@ async function runWithConnection(connection, files, opts) {
 /**
 * 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.
+* Resolves the matched test files and prints a "relay attach required" notice:
+* the CLI's own standalone relay attach (resolve CDP URL, attach, run, close) is
+* not wired yet, so today these files run via the `run_tests` MCP tool against
+* the daemon's attached page.
 */
 async function main(argv = process.argv.slice(2)) {
 	let parsed;
@@ -364,7 +503,7 @@ async function main(argv = process.argv.slice(2)) {
 		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.stderr.write(`devtools-test: matched ${files.length} test file(s), but direct CLI relay attach is not yet wired.\n  Use the devtools-mcp server (\`devtools-mcp\`) to start a debug session,\n  then the \`run_tests\` MCP tool to run these files against the attached page.\n`);
 	process.exitCode = 1;
 }
 if (import.meta.url === new URL(process.argv[1], "file://").href) main().catch((e) => {