@ait-co/devtools 0.1.144 → 0.2.1

package/dist/relay-url-store-CkVSQZMq.cjs

@@ -0,0 +1,110 @@
+let node_path = require("node:path");
+//#region src/unplugin/relay-url-store.ts
+/**
+* Project-local ephemeral URL store — WRITE/DELETE half (#424, relocated #818).
+*
+* Environment-2 ("AITC Sandbox PWA") cold-start needs two ephemeral URLs that
+* change on every run: the CDP relay's https base and the app tunnel's https
+* base. Rather than making the developer copy-paste them into env vars each
+* time, the dev server writes them to `<project>/.ait_urls` and the MCP daemon
+* (`@ait-co/debugger`) discovers them from there.
+*
+* Why this module is here and not in `@ait-co/debugger`: the writer IS the vite
+* dev-server plugin. `@ait-co/debugger` owns the READ half only — its daemon
+* reads `.ait_urls` read-only and never writes it. Splitting the file that way
+* matches who is allowed to mutate it, and it keeps the write path available
+* when `@ait-co/debugger` is not installed at all. The file format is the
+* contract between the two packages; changing it requires changing both sides.
+*
+* Kept deliberately minimal compared with the pre-split `src/mcp/relay-url-store.ts`
+* (that module now lives in `@ait-co/debugger` as
+* `packages/debugger/src/mcp/relay-url-store.ts`):
+* the read path (`readRelayUrls`) moved out with the daemon, so only
+* {@link writeRelayUrls} and {@link deleteRelayUrls} remain.
+*
+* SECRET-HANDLING: `relayBaseUrl` and `tunnelBaseUrl` carry the tunnel host —
+* the same sensitivity class as the `.ait_relay` TOTP secret. The raw values,
+* partial values, and the resolved file path MUST NOT appear in any log, error
+* message, stdout, stderr, or assertion output here or at any call site. Only
+* boolean pass/fail signals are safe to surface. The file is written mode 0600.
+*/
+/** Project-local ephemeral URL file name (single file, not a directory). */
+const URLS_FILE_NAME = ".ait_urls";
+/**
+* Walks upward from `start` and returns the nearest directory containing a
+* `package.json`. Falls back to `start` when none is found, so a write still
+* lands somewhere deterministic.
+*
+* The writer (this module) and the reader (`@ait-co/debugger`'s daemon) use the
+* SAME anchor rule, so URLs written by `pnpm dev` are the ones the daemon finds:
+* real mini-apps keep `vite.config.ts` and `package.json` in one directory, so
+* `server.config.root === package.json-dir`. In a monorepo subdir the anchor is
+* the package's own directory — the one the daemon also reaches via its
+* per-session projectRoot.
+*/
+function nearestPackageJsonDir(start, existsSyncFn) {
+	let dir = start;
+	while (true) {
+		if (existsSyncFn((0, node_path.join)(dir, "package.json"))) return dir;
+		const parent = (0, node_path.dirname)(dir);
+		if (parent === dir) return start;
+		dir = parent;
+	}
+}
+/**
+* Absolute path to the project-local `.ait_urls` file for a given start
+* directory (resolved against the nearest package.json directory).
+*
+* Exported so tests can compute the expected path without duplicating the
+* resolution logic.
+*/
+function urlsFilePath(start, existsSyncFn) {
+	return (0, node_path.join)(nearestPackageJsonDir(start, existsSyncFn), URLS_FILE_NAME);
+}
+/**
+* Writes the present URL keys to `<projectRoot>/.ait_urls` (mode 0600),
+* overwriting (`flag: 'w'`) because the URLs are ephemeral — a fresh URL
+* replaces the previous one on every boot.
+*
+* Unlike the `.ait_relay` secret store this does NOT use `O_EXCL` (`'wx'`):
+* only the dev server writes this file, so there is no race to guard, and the
+* value must be fresh on every cold-start.
+*
+* SECRET-HANDLING: URL values are never logged.
+*/
+async function writeRelayUrls(deps) {
+	const { projectRoot, relayBaseUrl, relayLocalUrl, tunnelBaseUrl, fs: fsDep, existsSync: existsSyncDep } = deps;
+	const fs = fsDep ?? await import("node:fs");
+	const filePath = urlsFilePath(projectRoot, existsSyncDep ?? fs.existsSync);
+	const payload = {};
+	if (typeof relayBaseUrl === "string" && relayBaseUrl !== "") payload.relayBaseUrl = relayBaseUrl;
+	if (typeof relayLocalUrl === "string" && relayLocalUrl !== "") payload.relayLocalUrl = relayLocalUrl;
+	if (typeof tunnelBaseUrl === "string" && tunnelBaseUrl !== "") payload.tunnelBaseUrl = tunnelBaseUrl;
+	fs.writeFileSync(filePath, JSON.stringify(payload), {
+		mode: 384,
+		flag: "w"
+	});
+}
+/**
+* Removes `<projectRoot>/.ait_urls` if present, swallowing every error so
+* cleanup always succeeds.
+*
+* Called from the unplugin's `cleanup()` on `httpServer 'close'` + signals. A
+* stale `.ait_urls` pointing at a dead tunnel would make the daemon attempt a
+* doomed attach on the next cold-start — deletion is non-negotiable.
+*
+* SECRET-HANDLING: the file path is never logged.
+*/
+async function deleteRelayUrls(deps) {
+	const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps;
+	const fs = fsDep ?? await import("node:fs");
+	const filePath = urlsFilePath(projectRoot, existsSyncDep ?? fs.existsSync);
+	try {
+		if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+	} catch {}
+}
+//#endregion
+exports.deleteRelayUrls = deleteRelayUrls;
+exports.writeRelayUrls = writeRelayUrls;
+
+//# sourceMappingURL=relay-url-store-CkVSQZMq.cjs.map

package/dist/relay-url-store-CkVSQZMq.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-url-store-CkVSQZMq.cjs","names":[],"sources":["../src/unplugin/relay-url-store.ts"],"sourcesContent":["/**\n * Project-local ephemeral URL store — WRITE/DELETE half (#424, relocated #818).\n *\n * Environment-2 (\"AITC Sandbox PWA\") cold-start needs two ephemeral URLs that\n * change on every run: the CDP relay's https base and the app tunnel's https\n * base. Rather than making the developer copy-paste them into env vars each\n * time, the dev server writes them to `<project>/.ait_urls` and the MCP daemon\n * (`@ait-co/debugger`) discovers them from there.\n *\n * Why this module is here and not in `@ait-co/debugger`: the writer IS the vite\n * dev-server plugin. `@ait-co/debugger` owns the READ half only — its daemon\n * reads `.ait_urls` read-only and never writes it. Splitting the file that way\n * matches who is allowed to mutate it, and it keeps the write path available\n * when `@ait-co/debugger` is not installed at all. The file format is the\n * contract between the two packages; changing it requires changing both sides.\n *\n * Kept deliberately minimal compared with the pre-split `src/mcp/relay-url-store.ts`\n * (that module now lives in `@ait-co/debugger` as\n * `packages/debugger/src/mcp/relay-url-store.ts`):\n * the read path (`readRelayUrls`) moved out with the daemon, so only\n * {@link writeRelayUrls} and {@link deleteRelayUrls} remain.\n *\n * SECRET-HANDLING: `relayBaseUrl` and `tunnelBaseUrl` carry the tunnel host —\n * the same sensitivity class as the `.ait_relay` TOTP secret. The raw values,\n * partial values, and the resolved file path MUST NOT appear in any log, error\n * message, stdout, stderr, or assertion output here or at any call site. Only\n * boolean pass/fail signals are safe to surface. The file is written mode 0600.\n */\n\nimport { dirname, join } from 'node:path';\n\n/** Project-local ephemeral URL file name (single file, not a directory). */\nexport const URLS_FILE_NAME = '.ait_urls';\n\n/** Minimal fs subset needed by {@link writeRelayUrls} — injectable for tests. */\nexport interface RelayUrlWriteFs {\n  writeFileSync(path: string, data: string, options: { mode: number; flag: string }): void;\n  existsSync(path: string): boolean;\n}\n\n/** Minimal fs subset needed by {@link deleteRelayUrls} — injectable for tests. */\nexport interface RelayUrlDeleteFs {\n  existsSync(path: string): boolean;\n  unlinkSync(path: string): void;\n}\n\n/**\n * Walks upward from `start` and returns the nearest directory containing a\n * `package.json`. Falls back to `start` when none is found, so a write still\n * lands somewhere deterministic.\n *\n * The writer (this module) and the reader (`@ait-co/debugger`'s daemon) use the\n * SAME anchor rule, so URLs written by `pnpm dev` are the ones the daemon finds:\n * real mini-apps keep `vite.config.ts` and `package.json` in one directory, so\n * `server.config.root === package.json-dir`. In a monorepo subdir the anchor is\n * the package's own directory — the one the daemon also reaches via its\n * per-session projectRoot.\n */\nexport function nearestPackageJsonDir(\n  start: string,\n  existsSyncFn: (path: string) => boolean,\n): string {\n  let dir = start;\n  // Stop at the filesystem root (dirname of root === root).\n  while (true) {\n    if (existsSyncFn(join(dir, 'package.json'))) return dir;\n    const parent = dirname(dir);\n    if (parent === dir) return start;\n    dir = parent;\n  }\n}\n\n/**\n * Absolute path to the project-local `.ait_urls` file for a given start\n * directory (resolved against the nearest package.json directory).\n *\n * Exported so tests can compute the expected path without duplicating the\n * resolution logic.\n */\nexport function urlsFilePath(start: string, existsSyncFn: (path: string) => boolean): string {\n  return join(nearestPackageJsonDir(start, existsSyncFn), URLS_FILE_NAME);\n}\n\nexport interface WriteRelayUrlsDeps {\n  /** Project root (typically Vite `server.config.root`). */\n  projectRoot: string;\n  /**\n   * The CDP relay's https base URL. Omit when the relay was not started.\n   * SECRET-HANDLING: never log this value.\n   */\n  relayBaseUrl?: string;\n  /**\n   * The CDP relay's LOCAL http base URL (`http://127.0.0.1:<relay-port>`), used\n   * by the daemon to build the Chii inspector URL without a tunnel round-trip\n   * (issue #530). Loopback only — no tunnel host, safe to surface.\n   */\n  relayLocalUrl?: string;\n  /**\n   * The app tunnel's https base URL. Omit when unavailable.\n   * SECRET-HANDLING: never log this value.\n   */\n  tunnelBaseUrl?: string;\n  /** Filesystem operations. Defaults to node:fs synchronous functions. */\n  fs?: RelayUrlWriteFs;\n  /** existsSync used to resolve the nearest package.json directory. Defaults to node:fs. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Writes the present URL keys to `<projectRoot>/.ait_urls` (mode 0600),\n * overwriting (`flag: 'w'`) because the URLs are ephemeral — a fresh URL\n * replaces the previous one on every boot.\n *\n * Unlike the `.ait_relay` secret store this does NOT use `O_EXCL` (`'wx'`):\n * only the dev server writes this file, so there is no race to guard, and the\n * value must be fresh on every cold-start.\n *\n * SECRET-HANDLING: URL values are never logged.\n */\nexport async function writeRelayUrls(deps: WriteRelayUrlsDeps): Promise<void> {\n  const {\n    projectRoot,\n    relayBaseUrl,\n    relayLocalUrl,\n    tunnelBaseUrl,\n    fs: fsDep,\n    existsSync: existsSyncDep,\n  } = deps;\n\n  const fs: RelayUrlWriteFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  // Build the payload — omit keys whose values are absent or blank.\n  const payload: { relayBaseUrl?: string; relayLocalUrl?: string; tunnelBaseUrl?: string } = {};\n  if (typeof relayBaseUrl === 'string' && relayBaseUrl !== '') payload.relayBaseUrl = relayBaseUrl;\n  if (typeof relayLocalUrl === 'string' && relayLocalUrl !== '') {\n    payload.relayLocalUrl = relayLocalUrl;\n  }\n  if (typeof tunnelBaseUrl === 'string' && tunnelBaseUrl !== '') {\n    payload.tunnelBaseUrl = tunnelBaseUrl;\n  }\n\n  // SECRET-HANDLING: the JSON content (which includes URL values) goes to the\n  // file only — never to any log, stdout, or stderr.\n  fs.writeFileSync(filePath, JSON.stringify(payload), { mode: 0o600, flag: 'w' });\n}\n\nexport interface DeleteRelayUrlsDeps {\n  /** Project root. */\n  projectRoot: string;\n  /** Filesystem operations. Defaults to node:fs (existsSync + unlinkSync). */\n  fs?: RelayUrlDeleteFs;\n  /** existsSync used to resolve the nearest package.json directory. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Removes `<projectRoot>/.ait_urls` if present, swallowing every error so\n * cleanup always succeeds.\n *\n * Called from the unplugin's `cleanup()` on `httpServer 'close'` + signals. A\n * stale `.ait_urls` pointing at a dead tunnel would make the daemon attempt a\n * doomed attach on the next cold-start — deletion is non-negotiable.\n *\n * SECRET-HANDLING: the file path is never logged.\n */\nexport async function deleteRelayUrls(deps: DeleteRelayUrlsDeps): Promise<void> {\n  const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps;\n\n  const fs: RelayUrlDeleteFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  try {\n    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);\n  } catch {\n    // Swallow ENOENT and any other error — cleanup is best-effort.\n    // SECRET-HANDLING: the path is not logged.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,iBAAiB;;;;;;;;;;;;;AA0B9B,SAAgB,sBACd,OACA,cACQ;CACR,IAAI,MAAM;AAEV,QAAO,MAAM;AACX,MAAI,cAAA,GAAA,UAAA,MAAkB,KAAK,eAAe,CAAC,CAAE,QAAO;EACpD,MAAM,UAAA,GAAA,UAAA,SAAiB,IAAI;AAC3B,MAAI,WAAW,IAAK,QAAO;AAC3B,QAAM;;;;;;;;;;AAWV,SAAgB,aAAa,OAAe,cAAiD;AAC3F,SAAA,GAAA,UAAA,MAAY,sBAAsB,OAAO,aAAa,EAAE,eAAe;;;;;;;;;;;;;AAuCzE,eAAsB,eAAe,MAAyC;CAC5E,MAAM,EACJ,aACA,cACA,eACA,eACA,IAAI,OACJ,YAAY,kBACV;CAEJ,MAAM,KAAsB,SAAU,MAAM,OAAO;CAGnD,MAAM,WAAW,aAAa,aAFkB,iBAAiB,GAAG,WAEZ;CAGxD,MAAM,UAAqF,EAAE;AAC7F,KAAI,OAAO,iBAAiB,YAAY,iBAAiB,GAAI,SAAQ,eAAe;AACpF,KAAI,OAAO,kBAAkB,YAAY,kBAAkB,GACzD,SAAQ,gBAAgB;AAE1B,KAAI,OAAO,kBAAkB,YAAY,kBAAkB,GACzD,SAAQ,gBAAgB;AAK1B,IAAG,cAAc,UAAU,KAAK,UAAU,QAAQ,EAAE;EAAE,MAAM;EAAO,MAAM;EAAK,CAAC;;;;;;;;;;;;AAsBjF,eAAsB,gBAAgB,MAA0C;CAC9E,MAAM,EAAE,aAAa,IAAI,OAAO,YAAY,kBAAkB;CAE9D,MAAM,KAAuB,SAAU,MAAM,OAAO;CAGpD,MAAM,WAAW,aAAa,aAFkB,iBAAiB,GAAG,WAEZ;AAExD,KAAI;AACF,MAAI,GAAG,WAAW,SAAS,CAAE,IAAG,WAAW,SAAS;SAC9C"}

package/dist/relay-url-store-dkII-DHD.js

@@ -0,0 +1,109 @@
+import { dirname, join } from "node:path";
+//#region src/unplugin/relay-url-store.ts
+/**
+* Project-local ephemeral URL store — WRITE/DELETE half (#424, relocated #818).
+*
+* Environment-2 ("AITC Sandbox PWA") cold-start needs two ephemeral URLs that
+* change on every run: the CDP relay's https base and the app tunnel's https
+* base. Rather than making the developer copy-paste them into env vars each
+* time, the dev server writes them to `<project>/.ait_urls` and the MCP daemon
+* (`@ait-co/debugger`) discovers them from there.
+*
+* Why this module is here and not in `@ait-co/debugger`: the writer IS the vite
+* dev-server plugin. `@ait-co/debugger` owns the READ half only — its daemon
+* reads `.ait_urls` read-only and never writes it. Splitting the file that way
+* matches who is allowed to mutate it, and it keeps the write path available
+* when `@ait-co/debugger` is not installed at all. The file format is the
+* contract between the two packages; changing it requires changing both sides.
+*
+* Kept deliberately minimal compared with the pre-split `src/mcp/relay-url-store.ts`
+* (that module now lives in `@ait-co/debugger` as
+* `packages/debugger/src/mcp/relay-url-store.ts`):
+* the read path (`readRelayUrls`) moved out with the daemon, so only
+* {@link writeRelayUrls} and {@link deleteRelayUrls} remain.
+*
+* SECRET-HANDLING: `relayBaseUrl` and `tunnelBaseUrl` carry the tunnel host —
+* the same sensitivity class as the `.ait_relay` TOTP secret. The raw values,
+* partial values, and the resolved file path MUST NOT appear in any log, error
+* message, stdout, stderr, or assertion output here or at any call site. Only
+* boolean pass/fail signals are safe to surface. The file is written mode 0600.
+*/
+/** Project-local ephemeral URL file name (single file, not a directory). */
+const URLS_FILE_NAME = ".ait_urls";
+/**
+* Walks upward from `start` and returns the nearest directory containing a
+* `package.json`. Falls back to `start` when none is found, so a write still
+* lands somewhere deterministic.
+*
+* The writer (this module) and the reader (`@ait-co/debugger`'s daemon) use the
+* SAME anchor rule, so URLs written by `pnpm dev` are the ones the daemon finds:
+* real mini-apps keep `vite.config.ts` and `package.json` in one directory, so
+* `server.config.root === package.json-dir`. In a monorepo subdir the anchor is
+* the package's own directory — the one the daemon also reaches via its
+* per-session projectRoot.
+*/
+function nearestPackageJsonDir(start, existsSyncFn) {
+	let dir = start;
+	while (true) {
+		if (existsSyncFn(join(dir, "package.json"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return start;
+		dir = parent;
+	}
+}
+/**
+* Absolute path to the project-local `.ait_urls` file for a given start
+* directory (resolved against the nearest package.json directory).
+*
+* Exported so tests can compute the expected path without duplicating the
+* resolution logic.
+*/
+function urlsFilePath(start, existsSyncFn) {
+	return join(nearestPackageJsonDir(start, existsSyncFn), URLS_FILE_NAME);
+}
+/**
+* Writes the present URL keys to `<projectRoot>/.ait_urls` (mode 0600),
+* overwriting (`flag: 'w'`) because the URLs are ephemeral — a fresh URL
+* replaces the previous one on every boot.
+*
+* Unlike the `.ait_relay` secret store this does NOT use `O_EXCL` (`'wx'`):
+* only the dev server writes this file, so there is no race to guard, and the
+* value must be fresh on every cold-start.
+*
+* SECRET-HANDLING: URL values are never logged.
+*/
+async function writeRelayUrls(deps) {
+	const { projectRoot, relayBaseUrl, relayLocalUrl, tunnelBaseUrl, fs: fsDep, existsSync: existsSyncDep } = deps;
+	const fs = fsDep ?? await import("node:fs");
+	const filePath = urlsFilePath(projectRoot, existsSyncDep ?? fs.existsSync);
+	const payload = {};
+	if (typeof relayBaseUrl === "string" && relayBaseUrl !== "") payload.relayBaseUrl = relayBaseUrl;
+	if (typeof relayLocalUrl === "string" && relayLocalUrl !== "") payload.relayLocalUrl = relayLocalUrl;
+	if (typeof tunnelBaseUrl === "string" && tunnelBaseUrl !== "") payload.tunnelBaseUrl = tunnelBaseUrl;
+	fs.writeFileSync(filePath, JSON.stringify(payload), {
+		mode: 384,
+		flag: "w"
+	});
+}
+/**
+* Removes `<projectRoot>/.ait_urls` if present, swallowing every error so
+* cleanup always succeeds.
+*
+* Called from the unplugin's `cleanup()` on `httpServer 'close'` + signals. A
+* stale `.ait_urls` pointing at a dead tunnel would make the daemon attempt a
+* doomed attach on the next cold-start — deletion is non-negotiable.
+*
+* SECRET-HANDLING: the file path is never logged.
+*/
+async function deleteRelayUrls(deps) {
+	const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps;
+	const fs = fsDep ?? await import("node:fs");
+	const filePath = urlsFilePath(projectRoot, existsSyncDep ?? fs.existsSync);
+	try {
+		if (fs.existsSync(filePath)) fs.unlinkSync(filePath);
+	} catch {}
+}
+//#endregion
+export { deleteRelayUrls, writeRelayUrls };
+
+//# sourceMappingURL=relay-url-store-dkII-DHD.js.map

package/dist/relay-url-store-dkII-DHD.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-url-store-dkII-DHD.js","names":[],"sources":["../src/unplugin/relay-url-store.ts"],"sourcesContent":["/**\n * Project-local ephemeral URL store — WRITE/DELETE half (#424, relocated #818).\n *\n * Environment-2 (\"AITC Sandbox PWA\") cold-start needs two ephemeral URLs that\n * change on every run: the CDP relay's https base and the app tunnel's https\n * base. Rather than making the developer copy-paste them into env vars each\n * time, the dev server writes them to `<project>/.ait_urls` and the MCP daemon\n * (`@ait-co/debugger`) discovers them from there.\n *\n * Why this module is here and not in `@ait-co/debugger`: the writer IS the vite\n * dev-server plugin. `@ait-co/debugger` owns the READ half only — its daemon\n * reads `.ait_urls` read-only and never writes it. Splitting the file that way\n * matches who is allowed to mutate it, and it keeps the write path available\n * when `@ait-co/debugger` is not installed at all. The file format is the\n * contract between the two packages; changing it requires changing both sides.\n *\n * Kept deliberately minimal compared with the pre-split `src/mcp/relay-url-store.ts`\n * (that module now lives in `@ait-co/debugger` as\n * `packages/debugger/src/mcp/relay-url-store.ts`):\n * the read path (`readRelayUrls`) moved out with the daemon, so only\n * {@link writeRelayUrls} and {@link deleteRelayUrls} remain.\n *\n * SECRET-HANDLING: `relayBaseUrl` and `tunnelBaseUrl` carry the tunnel host —\n * the same sensitivity class as the `.ait_relay` TOTP secret. The raw values,\n * partial values, and the resolved file path MUST NOT appear in any log, error\n * message, stdout, stderr, or assertion output here or at any call site. Only\n * boolean pass/fail signals are safe to surface. The file is written mode 0600.\n */\n\nimport { dirname, join } from 'node:path';\n\n/** Project-local ephemeral URL file name (single file, not a directory). */\nexport const URLS_FILE_NAME = '.ait_urls';\n\n/** Minimal fs subset needed by {@link writeRelayUrls} — injectable for tests. */\nexport interface RelayUrlWriteFs {\n  writeFileSync(path: string, data: string, options: { mode: number; flag: string }): void;\n  existsSync(path: string): boolean;\n}\n\n/** Minimal fs subset needed by {@link deleteRelayUrls} — injectable for tests. */\nexport interface RelayUrlDeleteFs {\n  existsSync(path: string): boolean;\n  unlinkSync(path: string): void;\n}\n\n/**\n * Walks upward from `start` and returns the nearest directory containing a\n * `package.json`. Falls back to `start` when none is found, so a write still\n * lands somewhere deterministic.\n *\n * The writer (this module) and the reader (`@ait-co/debugger`'s daemon) use the\n * SAME anchor rule, so URLs written by `pnpm dev` are the ones the daemon finds:\n * real mini-apps keep `vite.config.ts` and `package.json` in one directory, so\n * `server.config.root === package.json-dir`. In a monorepo subdir the anchor is\n * the package's own directory — the one the daemon also reaches via its\n * per-session projectRoot.\n */\nexport function nearestPackageJsonDir(\n  start: string,\n  existsSyncFn: (path: string) => boolean,\n): string {\n  let dir = start;\n  // Stop at the filesystem root (dirname of root === root).\n  while (true) {\n    if (existsSyncFn(join(dir, 'package.json'))) return dir;\n    const parent = dirname(dir);\n    if (parent === dir) return start;\n    dir = parent;\n  }\n}\n\n/**\n * Absolute path to the project-local `.ait_urls` file for a given start\n * directory (resolved against the nearest package.json directory).\n *\n * Exported so tests can compute the expected path without duplicating the\n * resolution logic.\n */\nexport function urlsFilePath(start: string, existsSyncFn: (path: string) => boolean): string {\n  return join(nearestPackageJsonDir(start, existsSyncFn), URLS_FILE_NAME);\n}\n\nexport interface WriteRelayUrlsDeps {\n  /** Project root (typically Vite `server.config.root`). */\n  projectRoot: string;\n  /**\n   * The CDP relay's https base URL. Omit when the relay was not started.\n   * SECRET-HANDLING: never log this value.\n   */\n  relayBaseUrl?: string;\n  /**\n   * The CDP relay's LOCAL http base URL (`http://127.0.0.1:<relay-port>`), used\n   * by the daemon to build the Chii inspector URL without a tunnel round-trip\n   * (issue #530). Loopback only — no tunnel host, safe to surface.\n   */\n  relayLocalUrl?: string;\n  /**\n   * The app tunnel's https base URL. Omit when unavailable.\n   * SECRET-HANDLING: never log this value.\n   */\n  tunnelBaseUrl?: string;\n  /** Filesystem operations. Defaults to node:fs synchronous functions. */\n  fs?: RelayUrlWriteFs;\n  /** existsSync used to resolve the nearest package.json directory. Defaults to node:fs. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Writes the present URL keys to `<projectRoot>/.ait_urls` (mode 0600),\n * overwriting (`flag: 'w'`) because the URLs are ephemeral — a fresh URL\n * replaces the previous one on every boot.\n *\n * Unlike the `.ait_relay` secret store this does NOT use `O_EXCL` (`'wx'`):\n * only the dev server writes this file, so there is no race to guard, and the\n * value must be fresh on every cold-start.\n *\n * SECRET-HANDLING: URL values are never logged.\n */\nexport async function writeRelayUrls(deps: WriteRelayUrlsDeps): Promise<void> {\n  const {\n    projectRoot,\n    relayBaseUrl,\n    relayLocalUrl,\n    tunnelBaseUrl,\n    fs: fsDep,\n    existsSync: existsSyncDep,\n  } = deps;\n\n  const fs: RelayUrlWriteFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  // Build the payload — omit keys whose values are absent or blank.\n  const payload: { relayBaseUrl?: string; relayLocalUrl?: string; tunnelBaseUrl?: string } = {};\n  if (typeof relayBaseUrl === 'string' && relayBaseUrl !== '') payload.relayBaseUrl = relayBaseUrl;\n  if (typeof relayLocalUrl === 'string' && relayLocalUrl !== '') {\n    payload.relayLocalUrl = relayLocalUrl;\n  }\n  if (typeof tunnelBaseUrl === 'string' && tunnelBaseUrl !== '') {\n    payload.tunnelBaseUrl = tunnelBaseUrl;\n  }\n\n  // SECRET-HANDLING: the JSON content (which includes URL values) goes to the\n  // file only — never to any log, stdout, or stderr.\n  fs.writeFileSync(filePath, JSON.stringify(payload), { mode: 0o600, flag: 'w' });\n}\n\nexport interface DeleteRelayUrlsDeps {\n  /** Project root. */\n  projectRoot: string;\n  /** Filesystem operations. Defaults to node:fs (existsSync + unlinkSync). */\n  fs?: RelayUrlDeleteFs;\n  /** existsSync used to resolve the nearest package.json directory. */\n  existsSync?: (path: string) => boolean;\n}\n\n/**\n * Removes `<projectRoot>/.ait_urls` if present, swallowing every error so\n * cleanup always succeeds.\n *\n * Called from the unplugin's `cleanup()` on `httpServer 'close'` + signals. A\n * stale `.ait_urls` pointing at a dead tunnel would make the daemon attempt a\n * doomed attach on the next cold-start — deletion is non-negotiable.\n *\n * SECRET-HANDLING: the file path is never logged.\n */\nexport async function deleteRelayUrls(deps: DeleteRelayUrlsDeps): Promise<void> {\n  const { projectRoot, fs: fsDep, existsSync: existsSyncDep } = deps;\n\n  const fs: RelayUrlDeleteFs = fsDep ?? (await import('node:fs'));\n  const existsSyncFn: (path: string) => boolean = existsSyncDep ?? fs.existsSync;\n\n  const filePath = urlsFilePath(projectRoot, existsSyncFn);\n\n  try {\n    if (fs.existsSync(filePath)) fs.unlinkSync(filePath);\n  } catch {\n    // Swallow ENOENT and any other error — cleanup is best-effort.\n    // SECRET-HANDLING: the path is not logged.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,iBAAiB;;;;;;;;;;;;;AA0B9B,SAAgB,sBACd,OACA,cACQ;CACR,IAAI,MAAM;AAEV,QAAO,MAAM;AACX,MAAI,aAAa,KAAK,KAAK,eAAe,CAAC,CAAE,QAAO;EACpD,MAAM,SAAS,QAAQ,IAAI;AAC3B,MAAI,WAAW,IAAK,QAAO;AAC3B,QAAM;;;;;;;;;;AAWV,SAAgB,aAAa,OAAe,cAAiD;AAC3F,QAAO,KAAK,sBAAsB,OAAO,aAAa,EAAE,eAAe;;;;;;;;;;;;;AAuCzE,eAAsB,eAAe,MAAyC;CAC5E,MAAM,EACJ,aACA,cACA,eACA,eACA,IAAI,OACJ,YAAY,kBACV;CAEJ,MAAM,KAAsB,SAAU,MAAM,OAAO;CAGnD,MAAM,WAAW,aAAa,aAFkB,iBAAiB,GAAG,WAEZ;CAGxD,MAAM,UAAqF,EAAE;AAC7F,KAAI,OAAO,iBAAiB,YAAY,iBAAiB,GAAI,SAAQ,eAAe;AACpF,KAAI,OAAO,kBAAkB,YAAY,kBAAkB,GACzD,SAAQ,gBAAgB;AAE1B,KAAI,OAAO,kBAAkB,YAAY,kBAAkB,GACzD,SAAQ,gBAAgB;AAK1B,IAAG,cAAc,UAAU,KAAK,UAAU,QAAQ,EAAE;EAAE,MAAM;EAAO,MAAM;EAAK,CAAC;;;;;;;;;;;;AAsBjF,eAAsB,gBAAgB,MAA0C;CAC9E,MAAM,EAAE,aAAa,IAAI,OAAO,YAAY,kBAAkB;CAE9D,MAAM,KAAuB,SAAU,MAAM,OAAO;CAGpD,MAAM,WAAW,aAAa,aAFkB,iBAAiB,GAAG,WAEZ;AAExD,KAAI;AACF,MAAI,GAAG,WAAW,SAAS,CAAE,IAAG,WAAW,SAAS;SAC9C"}

package/dist/stubs/bin-devtools-mcp.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+//#region src/stubs/moved.ts
+/**
+* Shared copy for the transition stubs left behind by the debug-surface split
+* (#818).
+*
+* TRANSITION — REMOVE IN 1.0.0. Everything in `src/stubs/` exists only so a
+* consumer still on a pre-0.2.0 wiring gets a sentence telling them where the
+* code went, instead of a bare `ERR_PACKAGE_PATH_NOT_EXPORTED`. Once 1.0.0
+* drops them, the same import fails with the resolver's own error — which is
+* the correct end state, just a worse first encounter.
+*
+* Two stub shapes, and the difference between them is a safety property, not a
+* style choice:
+*
+*   - Node-side tooling subpaths (`/mcp/server`, `/mcp/cli`, `/test-runner`)
+*     THROW on import. They only ever run in a developer's terminal, so failing
+*     loudly at the earliest possible moment is right.
+*   - The in-app subpaths (`/in-app`, `/in-app/auto`) MUST NOT throw. That code
+*     could be sitting in a shipped production bundle; a throw there takes the
+*     user's mini-app down. They degrade to a no-op plus one `console.error`.
+*/
+/** The package that now owns the MCP daemon, test runner, and dev bridge. */
+const DEBUGGER_PACKAGE = "@ait-co/debugger";
+/**
+* Builds the migration sentence for a moved subpath.
+*
+* SECRET-HANDLING: fixed text plus the two specifiers only — no paths, hosts,
+* URLs, or environment values.
+*/
+function movedMessage(oldSubpath, newPackage, install) {
+	return [
+		`[@ait-co/devtools] '${oldSubpath}' 는 0.2.0에서 제거되었습니다.`,
+		`이 기능은 '${newPackage}' 로 이동했습니다.`,
+		`설치: ${install}`
+	].join(" ");
+}
+//#endregion
+//#region src/stubs/bin-devtools-mcp.ts
+/**
+* TRANSITION STUB — REMOVE IN 1.0.0.
+*
+* The `devtools-mcp` bin moved to `@ait-co/debugger`, where it is named
+* `debugger` (#818). The rename is why this stub can exist at all: had the new
+* package kept the old bin name, both packages installed side by side would
+* fight over the same `node_modules/.bin/devtools-mcp` symlink and whichever
+* won would be arbitrary. Different names, no collision.
+*
+* Prints the migration notice to stderr (not stdout — an MCP host may be
+* reading stdout as a JSON-RPC stream) and exits non-zero so a script that
+* still calls the old bin fails rather than silently continuing.
+*/
+process.stderr.write(`${movedMessage("devtools-mcp", `${DEBUGGER_PACKAGE} (bin: debugger)`, `pnpm add -D ${DEBUGGER_PACKAGE}`)}\n`);
+process.exit(1);
+//#endregion
+export {};
+
+//# sourceMappingURL=bin-devtools-mcp.js.map

package/dist/stubs/bin-devtools-mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-devtools-mcp.js","names":[],"sources":["../../src/stubs/moved.ts","../../src/stubs/bin-devtools-mcp.ts"],"sourcesContent":["/**\n * Shared copy for the transition stubs left behind by the debug-surface split\n * (#818).\n *\n * TRANSITION — REMOVE IN 1.0.0. Everything in `src/stubs/` exists only so a\n * consumer still on a pre-0.2.0 wiring gets a sentence telling them where the\n * code went, instead of a bare `ERR_PACKAGE_PATH_NOT_EXPORTED`. Once 1.0.0\n * drops them, the same import fails with the resolver's own error — which is\n * the correct end state, just a worse first encounter.\n *\n * Two stub shapes, and the difference between them is a safety property, not a\n * style choice:\n *\n *   - Node-side tooling subpaths (`/mcp/server`, `/mcp/cli`, `/test-runner`)\n *     THROW on import. They only ever run in a developer's terminal, so failing\n *     loudly at the earliest possible moment is right.\n *   - The in-app subpaths (`/in-app`, `/in-app/auto`) MUST NOT throw. That code\n *     could be sitting in a shipped production bundle; a throw there takes the\n *     user's mini-app down. They degrade to a no-op plus one `console.error`.\n */\n\n/** The package that now owns the MCP daemon, test runner, and dev bridge. */\nexport const DEBUGGER_PACKAGE = '@ait-co/debugger';\n\n/** The package that now owns the on-device attach + eruda console. */\nexport const DEBUG_CONSOLE_PACKAGE = '@ait-co/debug-console';\n\n/**\n * Builds the migration sentence for a moved subpath.\n *\n * SECRET-HANDLING: fixed text plus the two specifiers only — no paths, hosts,\n * URLs, or environment values.\n */\nexport function movedMessage(oldSubpath: string, newPackage: string, install: string): string {\n  return [\n    `[@ait-co/devtools] '${oldSubpath}' 는 0.2.0에서 제거되었습니다.`,\n    `이 기능은 '${newPackage}' 로 이동했습니다.`,\n    `설치: ${install}`,\n  ].join(' ');\n}\n","/**\n * TRANSITION STUB — REMOVE IN 1.0.0.\n *\n * The `devtools-mcp` bin moved to `@ait-co/debugger`, where it is named\n * `debugger` (#818). The rename is why this stub can exist at all: had the new\n * package kept the old bin name, both packages installed side by side would\n * fight over the same `node_modules/.bin/devtools-mcp` symlink and whichever\n * won would be arbitrary. Different names, no collision.\n *\n * Prints the migration notice to stderr (not stdout — an MCP host may be\n * reading stdout as a JSON-RPC stream) and exits non-zero so a script that\n * still calls the old bin fails rather than silently continuing.\n */\n\nimport { DEBUGGER_PACKAGE, movedMessage } from './moved.js';\n\nprocess.stderr.write(\n  `${movedMessage('devtools-mcp', `${DEBUGGER_PACKAGE} (bin: debugger)`, `pnpm add -D ${DEBUGGER_PACKAGE}`)}\\n`,\n);\nprocess.exit(1);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,mBAAmB;;;;;;;AAWhC,SAAgB,aAAa,YAAoB,YAAoB,SAAyB;AAC5F,QAAO;EACL,uBAAuB,WAAW;EAClC,UAAU,WAAW;EACrB,OAAO;EACR,CAAC,KAAK,IAAI;;;;;;;;;;;;;;;;;ACtBb,QAAQ,OAAO,MACb,GAAG,aAAa,gBAAgB,GAAG,iBAAiB,mBAAmB,eAAe,mBAAmB,CAAC,IAC3G;AACD,QAAQ,KAAK,EAAE"}

package/dist/stubs/bin-devtools-test.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/stubs/bin-devtools-test.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+//#region src/stubs/moved.ts
+/**
+* Shared copy for the transition stubs left behind by the debug-surface split
+* (#818).
+*
+* TRANSITION — REMOVE IN 1.0.0. Everything in `src/stubs/` exists only so a
+* consumer still on a pre-0.2.0 wiring gets a sentence telling them where the
+* code went, instead of a bare `ERR_PACKAGE_PATH_NOT_EXPORTED`. Once 1.0.0
+* drops them, the same import fails with the resolver's own error — which is
+* the correct end state, just a worse first encounter.
+*
+* Two stub shapes, and the difference between them is a safety property, not a
+* style choice:
+*
+*   - Node-side tooling subpaths (`/mcp/server`, `/mcp/cli`, `/test-runner`)
+*     THROW on import. They only ever run in a developer's terminal, so failing
+*     loudly at the earliest possible moment is right.
+*   - The in-app subpaths (`/in-app`, `/in-app/auto`) MUST NOT throw. That code
+*     could be sitting in a shipped production bundle; a throw there takes the
+*     user's mini-app down. They degrade to a no-op plus one `console.error`.
+*/
+/** The package that now owns the MCP daemon, test runner, and dev bridge. */
+const DEBUGGER_PACKAGE = "@ait-co/debugger";
+/**
+* Builds the migration sentence for a moved subpath.
+*
+* SECRET-HANDLING: fixed text plus the two specifiers only — no paths, hosts,
+* URLs, or environment values.
+*/
+function movedMessage(oldSubpath, newPackage, install) {
+	return [
+		`[@ait-co/devtools] '${oldSubpath}' 는 0.2.0에서 제거되었습니다.`,
+		`이 기능은 '${newPackage}' 로 이동했습니다.`,
+		`설치: ${install}`
+	].join(" ");
+}
+//#endregion
+//#region src/stubs/bin-devtools-test.ts
+/**
+* TRANSITION STUB — REMOVE IN 1.0.0.
+*
+* The `devtools-test` bin moved to `@ait-co/debugger`, where it is named
+* `debugger-test` (#818). See `src/stubs/bin-devtools-mcp.ts` for why the
+* rename is what makes a stub bin safe to keep.
+*
+* Prints the migration notice to stderr and exits non-zero so a CI step still
+* calling the old bin fails loudly instead of reporting a vacuous success.
+*/
+process.stderr.write(`${movedMessage("devtools-test", `${DEBUGGER_PACKAGE} (bin: debugger-test)`, `pnpm add -D ${DEBUGGER_PACKAGE}`)}\n`);
+process.exit(1);
+//#endregion
+export {};
+
+//# sourceMappingURL=bin-devtools-test.js.map

package/dist/stubs/bin-devtools-test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-devtools-test.js","names":[],"sources":["../../src/stubs/moved.ts","../../src/stubs/bin-devtools-test.ts"],"sourcesContent":["/**\n * Shared copy for the transition stubs left behind by the debug-surface split\n * (#818).\n *\n * TRANSITION — REMOVE IN 1.0.0. Everything in `src/stubs/` exists only so a\n * consumer still on a pre-0.2.0 wiring gets a sentence telling them where the\n * code went, instead of a bare `ERR_PACKAGE_PATH_NOT_EXPORTED`. Once 1.0.0\n * drops them, the same import fails with the resolver's own error — which is\n * the correct end state, just a worse first encounter.\n *\n * Two stub shapes, and the difference between them is a safety property, not a\n * style choice:\n *\n *   - Node-side tooling subpaths (`/mcp/server`, `/mcp/cli`, `/test-runner`)\n *     THROW on import. They only ever run in a developer's terminal, so failing\n *     loudly at the earliest possible moment is right.\n *   - The in-app subpaths (`/in-app`, `/in-app/auto`) MUST NOT throw. That code\n *     could be sitting in a shipped production bundle; a throw there takes the\n *     user's mini-app down. They degrade to a no-op plus one `console.error`.\n */\n\n/** The package that now owns the MCP daemon, test runner, and dev bridge. */\nexport const DEBUGGER_PACKAGE = '@ait-co/debugger';\n\n/** The package that now owns the on-device attach + eruda console. */\nexport const DEBUG_CONSOLE_PACKAGE = '@ait-co/debug-console';\n\n/**\n * Builds the migration sentence for a moved subpath.\n *\n * SECRET-HANDLING: fixed text plus the two specifiers only — no paths, hosts,\n * URLs, or environment values.\n */\nexport function movedMessage(oldSubpath: string, newPackage: string, install: string): string {\n  return [\n    `[@ait-co/devtools] '${oldSubpath}' 는 0.2.0에서 제거되었습니다.`,\n    `이 기능은 '${newPackage}' 로 이동했습니다.`,\n    `설치: ${install}`,\n  ].join(' ');\n}\n","/**\n * TRANSITION STUB — REMOVE IN 1.0.0.\n *\n * The `devtools-test` bin moved to `@ait-co/debugger`, where it is named\n * `debugger-test` (#818). See `src/stubs/bin-devtools-mcp.ts` for why the\n * rename is what makes a stub bin safe to keep.\n *\n * Prints the migration notice to stderr and exits non-zero so a CI step still\n * calling the old bin fails loudly instead of reporting a vacuous success.\n */\n\nimport { DEBUGGER_PACKAGE, movedMessage } from './moved.js';\n\nprocess.stderr.write(\n  `${movedMessage('devtools-test', `${DEBUGGER_PACKAGE} (bin: debugger-test)`, `pnpm add -D ${DEBUGGER_PACKAGE}`)}\\n`,\n);\nprocess.exit(1);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,mBAAmB;;;;;;;AAWhC,SAAgB,aAAa,YAAoB,YAAoB,SAAyB;AAC5F,QAAO;EACL,uBAAuB,WAAW;EAClC,UAAU,WAAW;EACrB,OAAO;EACR,CAAC,KAAK,IAAI;;;;;;;;;;;;;;ACzBb,QAAQ,OAAO,MACb,GAAG,aAAa,iBAAiB,GAAG,iBAAiB,wBAAwB,eAAe,mBAAmB,CAAC,IACjH;AACD,QAAQ,KAAK,EAAE"}

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

@@ -1,231 +1 @@
-import { i as createRelayPool, n as RelayConnectionFactory, t as RELAY_POOL_NAME } from "../pool-DcaaOwUq.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.
-   *
-   * Ignored when {@link attachLauncher} is `true` — the env-2 launcher path
-   * builds its attach URL from {@link appUrl} + the relay wss, not a scheme URL.
-   * Pass `''` in that case.
-   */
-  schemeUrl: string;
-  /**
-   * env-2 (AITC Sandbox PWA) attach mode (devtools#774). When `true`, `open()`
-   * builds the attach URL as a **launcher deep-link**
-   * (`buildLauncherAttachUrl(appUrl, wssUrl, totp)` — the same env-2 path the
-   * MCP daemon takes via `prepareAttach(deps, 'relay-mobile', …)`, issue #378)
-   * instead of an intoss-private scheme deep-link. The relay boot, QR
-   * rendering, dashboard, and attach-wait are byte-for-byte identical to env 3;
-   * only the URL family differs. Omitted/false keeps the env-3 scheme path
-   * unchanged (zero behavior change).
-   */
-  attachLauncher?: boolean;
-  /**
-   * The consumer dev server's HTTP tunnel URL (e.g. an sdk-example
-   * `dev:phone:cdp` `*.trycloudflare.com` URL) that the launcher PWA frames.
-   * REQUIRED when {@link attachLauncher} is `true`; ignored otherwise.
-   *
-   * Threaded to the `relay-mobile` `prepareAttach` branch via the
-   * `AIT_TUNNEL_BASE_URL` env var (the same key the MCP daemon reads), so the
-   * exact same env-2 assembly runs — no divergent code path.
-   *
-   * SECRET-HANDLING: this is a tunnel host at the same sensitivity as the relay
-   * wss — NEVER logged. It rides only inside the QR/dashboard attach capsule.
-   */
-  appUrl?: 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. Omitted (the default) means **wait indefinitely** —
-   * the runner stays up until the user stops it (Ctrl-C/SIGTERM). QR-scan
-   * wait is a human-paced action; there is no sound default bound for it
-   * (devtools#735). Pass an explicit value to opt into a bounded wait (CI/
-   * headless callers — `--attach-timeout` on the CLI). (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;
-  };
-  /**
-   * When `true`, injects `__AIT_STUB_BLOCKING__ = true` before the first test
-   * bundle runs (devtools#740, DT-2) — `bundle.ts`'s sdk-redirect module reads
-   * this flag via `isStubBlockingEnabled()` and answers the blocking-UI APIs
-   * in `bridge-stub.ts`'s `STUB_REGISTRY` from fixtures instead of forwarding
-   * them to native. Optional — omitted/false means no flag is injected, which
-   * is byte-for-byte the pre-#740 behavior (the sdk-redirect module treats
-   * absence the same as `false`). Not a secret.
-   */
-  stubBlocking?: boolean;
-  /**
-   * Injects `__AIT_PACE_MS__ = paceMs` before the first test bundle runs
-   * (devtools#767) — `runtime.ts`'s test-execution loop reads this page
-   * global and waits `paceMs` before every test after the first one that
-   * actually runs. Optional — omitted/0 means no flag is injected, which is
-   * byte-for-byte the pre-#767 behavior (the loop treats an absent/non-
-   * positive value as "no pacing"). Not a secret. This is the PAGE-side half
-   * of `--pace`; the RUNNER-side (file-to-file) half is a plain `opts.paceMs`
-   * forwarded to `runTestFilesOverRelay` by the caller (cli.ts) — this
-   * factory only owns the page-global injection.
-   */
-  paceMs?: number;
-  /**
-   * Injects `__AIT_PACE_METHOD_MS__ = paceMethodMs` before the first test
-   * bundle runs (devtools#769) — `bundle.ts`'s sdk-redirect virtual module
-   * reads this page global via `method-pace.ts#getPaceMethodMs()` and paces
-   * every SDK call to a minimum interval BETWEEN calls to the SAME named
-   * function, independent of `--pace`'s test-to-test/file-to-file spacing.
-   * Optional — omitted/0 means no flag is injected, which is byte-for-byte
-   * the pre-#769 behavior (`getPaceMethodMs()` treats an absent/non-positive
-   * value as "no pacing", and `wrapWithMethodPacing` returns the SDK object
-   * untouched in that case). Not a secret.
-   */
-  paceMethodMs?: number;
-  /**
-   * Overrides the dashboard HTTP server's bind base port (devtools#752).
-   * Threaded straight through to `startQrHttpServer`'s `dashboardPort`
-   * option — see that option's doc for the increment-on-EADDRINUSE scan
-   * behaviour and the `AIT_DEBUG_HTTP_PORT` env fallback. Omitted means
-   * `startQrHttpServer` resolves its own default (env → fixed default).
-   */
-  dashboardPort?: number;
-  /**
-   * 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 relay
- * connection for env 3 (intoss-private scheme, default) or env 2 (AITC Sandbox
- * PWA launcher deep-link, when `opts.attachLauncher` is set — devtools#774).
- *
- * `open()` performs the full attach lifecycle and BLOCKS while a human scans
- * the rendered QR with their phone — there is no way around the manual scan.
- * By default the wait is UNBOUNDED (`opts.timeoutMs` omitted): the
- * runner stays up until the user stops it (Ctrl-C/SIGTERM), since QR-scan is
- * a human-paced action with no sound default bound (devtools#735). Passing an
- * explicit `timeoutMs` opts into the old bounded behavior (CI/headless
- * callers). 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`.
- */
-interface PhoneTestConfig {
-  /**
-   * Glob patterns (relative to cwd) for test files to run on the device.
-   * Defaults to `['**\/*.ait.test.ts']`.
-   */
-  include: string[];
-  /**
-   * Per-file evaluate timeout in milliseconds. Defaults to 30 000.
-   */
-  timeoutMs: number;
-  /**
-   * Additional esbuild `external` patterns for bundling.
-   * The SDK package is always external; add more here if needed.
-   */
-  extraExternals: string[];
-}
-/** User-facing config shape accepted by `definePhoneTestConfig`. */
-interface PhoneTestUserConfig {
-  include?: string[];
-  timeoutMs?: number;
-  extraExternals?: string[];
-}
-/**
- * Define a phone-relay test configuration.
- *
- * Merges user overrides with sensible defaults and returns a resolved
- * `PhoneTestConfig`. This object can be passed to `runTestFilesOverRelay`
- * (via the CLI or custom scripts) to run tests on a real device WebView.
- */
-declare function definePhoneTestConfig(userConfig?: PhoneTestUserConfig): PhoneTestConfig;
-/**
- * The slice of a Vitest `test` config this helper produces — `pool`,
- * `include`, and `testTimeout`. Typed structurally (not against Vitest's
- * `InlineConfig`) so consumers can spread it into their own `defineConfig`
- * without this module taking a value dependency on `vitest`.
- */
-interface PhoneVitestTestConfig {
-  /** The relay `PoolRunnerInitializer`, matched by `getFilePoolName`. */
-  pool: ReturnType<typeof createRelayPool>;
-  /** Glob patterns for device test files. */
-  include: string[];
-  /** Per-test timeout in ms (mirrors the relay per-file evaluate timeout). */
-  testTimeout: number;
-}
-/** User config accepted by {@link definePhoneVitestConfig}. */
-interface PhoneVitestUserConfig extends PhoneTestUserConfig {
-  /**
-   * Opens/closes the CDP relay connection that tests run over. Required —
-   * without it there is no device to dispatch files to.
-   *
-   * SECRET-HANDLING: the factory owns the relay wss/TOTP; this config object
-   * never stores or logs those values.
-   */
-  connection: RelayConnectionFactory;
-  /**
-   * 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
- * relay. Spread the result into your Vitest config:
- *
- * @example
- *   // vitest.config.ts
- *   import { defineConfig } from 'vitest/config';
- *   import { definePhoneVitestConfig } from '@ait-co/devtools/test-runner';
- *   export default defineConfig({
- *     test: definePhoneVitestConfig({ connection: myRelayFactory }),
- *   });
- *
- * Files matching `include` are dispatched to the relay pool (named
- * {@link RELAY_POOL_NAME}); everything else runs in Vitest's default pool.
- */
-declare function definePhoneVitestConfig(userConfig: PhoneVitestUserConfig): PhoneVitestTestConfig;
-//#endregion
-export { PhoneTestConfig, PhoneTestUserConfig, PhoneVitestTestConfig, PhoneVitestUserConfig, RELAY_POOL_NAME, type RelayConnectionFactory, type RelayConnectionFactoryOptions, createRelayConnectionFactory, createRelayPool, definePhoneTestConfig, definePhoneVitestConfig };
-//# sourceMappingURL=config.d.ts.map
+export { };