@ait-co/devtools 0.1.143 → 0.2.0

package/dist/unplugin/tunnel.d.cts

@@ -161,31 +161,37 @@ interface StartTunnelDashboardOptions {
   name?: string;
 }
 /**
- * Env-2 UX parity with env 3/4 (issue #408): when CDP wiring is on and a GUI is
+ * Env-2 UX parity with env 3 (issue #408): when CDP wiring is on and a GUI is
  * available, start the SAME `127.0.0.1` HTML dashboard (QR image + connect steps
- * + FAQ) that the MCP `start_attach` path serves, and auto-open it in the
+ * + FAQ) the debug daemon's `start_attach` path serves, and auto-open it in the
  * browser. headless / opt-out falls back to the terminal ASCII QR (printed
  * separately by {@link printTunnelBanner}).
  *
- * Every part the install-graph invariant depends on (`qrcode`, the MCP HTTP
- * server, the opener) is reached only through dynamic `import()` here, inside
- * the already-lazy `tunnel.js` chunk — nothing is added to the common build
- * graph or the MCP-only install graph.
+ * DELEGATED (issue #817): the implementation now lives in `@ait-co/debugger`'s
+ * `/dev-bridge` subpath — the one cross-repo code delegation of the package
+ * split. The dashboard needs the daemon's QR HTTP server, deep-link builder and
+ * TOTP minting, all of which moved into that package; keeping a second copy here
+ * would fork them. `@ait-co/debugger` is an OPTIONAL peer, so a consumer who
+ * never asks for env-2 CDP installs nothing extra.
  *
- * TOTP encapsulation: the dashboard's `getDashboardState` closure mints a FRESH
- * TOTP `at=` code on every call via `generateTotp(secret, Date.now())` and folds
- * it into a fresh `buildLauncherAttachUrl(...)`. Because the QR is re-rendered on
- * each SSE push / page reload from this closure, the code a phone scans is always
- * within its 30 s window — no stale code is baked into static HTML.
+ * Why this is not a separate plugin: the relay `wss://` URL must exist BEFORE
+ * the QR banner is printed (the launcher QR carries `&relay=`), so the relay and
+ * the dashboard are order-dependent and stay one composed call in the dev loop.
+ *
+ * Degradation: when `@ait-co/debugger` is not installed the import fails and we
+ * return `undefined` — exactly the same "no dashboard" outcome as a closed GUI
+ * gate, with the terminal ASCII QR standing alone. We do NOT fall back to a
+ * local copy of the daemon code. The caller (`./index.ts`) prints the install
+ * hint once when CDP was requested without the package.
  *
  * SECRET-HANDLING: the tunnel host, relay wssUrl, TOTP code, and `.ait_relay`
- * value/path are NEVER written to stdout/stderr/logs here. They live only inside
- * the attach URL (HTML body + `/qr.png` query, per qr-http-server's invariant).
- * The only thing opened/logged is `http://127.0.0.1:<port>` (local, safe).
+ * value/path are NEVER written to stdout/stderr/logs — neither here nor in the
+ * delegate. The only thing opened/logged is `http://127.0.0.1:<port>` (local).
  *
  * @returns the dashboard handle when it started (caller wires `close()` into the
- *   tunnel cleanup), or `undefined` when skipped (no relay, `qr:false`, headless,
- *   opt-out, or a start failure) — in which case ASCII QR fallback stands alone.
+ *   tunnel cleanup), or `undefined` when skipped (package absent, no relay,
+ *   `qr:false`, headless, opt-out, or a start failure) — in which case the ASCII
+ *   QR fallback stands alone.
  */
 declare function startTunnelDashboard(opts: StartTunnelDashboardOptions): Promise<TunnelDashboard | undefined>;
 interface QuickTunnel {

package/dist/unplugin/tunnel.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.cts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;;iBALgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAuCJ;EArCX,EAAA;EA6Ce;EA3Cf,GAAA,IAAO,GAAA;;;;;;;EAOP,WAAA;EAoEW;;AAiCb;;;EA/FE,IAAA;EAgGA;;;;;AAiCF;EA1HE,WAAA;;;;;;;;EAQA,iBAAA;EAqLe;;;;;;EA9Kf,WAAA;AAAA;;AAqLF;;UA7KiB,4BAAA;EA6K2B;;;;EAxK1C,WAAA;EAqLA;;;;EAhLA,IAAA;EAoNoB;;;;;;EA7MpB,WAAA;EA+MQ;;;;;;;EAvMR,iBAAA;EAwS0B;;;;AAiB5B;;EAlTE,WAAA;AAAA;;AAoUF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAnSgB,qBAAA,CACd,SAAA,UACA,WAAA,YAAuB,4BAAA;;;;;;;iBAgCH,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;;UAgEc,eAAA;;EAEf,GAAA;;EAEA,KAAA,QAAa,OAAA;AAAA;AAAA,UAGE,2BAAA;;EAEf,SAAA;;EAEA,WAAA;;EAEA,EAAA;;;;;EAKA,UAAA;;EAEA,GAAA,IAAO,GAAA;;;;;;EAMP,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BoB,oBAAA,CACpB,IAAA,EAAM,2BAAA,GACL,OAAA,CAAQ,eAAA;AAAA,UAiGM,WAAA;;EAEf,GAAA;;EAEA,IAAA;AAAA;;;;;;;;;;;iBAac,yBAAA,CAA0B,IAAA;;;;;;;iBAkBpB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}
+{"version":3,"file":"tunnel.d.cts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAyBA;;;;;AAKA;;;;;;;;;;iBALgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAuCJ;EArCX,EAAA;EA6Ce;EA3Cf,GAAA,IAAO,GAAA;;;;;;;EAOP,WAAA;EAoEW;;AAiCb;;;EA/FE,IAAA;EAgGA;;;;;AAiCF;EA1HE,WAAA;;;;;;;;EAQA,iBAAA;EAiKe;;;;;;EA1Jf,WAAA;AAAA;;AAiKF;;UAzJiB,4BAAA;EAyJ2B;;;;EApJ1C,WAAA;EAiKA;;;;EA5JA,IAAA;EAsMoB;;;;;;EA/LpB,WAAA;EAiMQ;;;;;;;EAzLR,iBAAA;EA6M0B;;;;AAiB5B;;EAvNE,WAAA;AAAA;;AAyOF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAxMgB,qBAAA,CACd,SAAA,UACA,WAAA,YAAuB,4BAAA;;;;;;;iBAgCH,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;;UA4Cc,eAAA;;EAEf,GAAA;;EAEA,KAAA,QAAa,OAAA;AAAA;AAAA,UAGE,2BAAA;;EAEf,SAAA;;EAEA,WAAA;;EAEA,EAAA;;;;;EAKA,UAAA;;EAEA,GAAA,IAAO,GAAA;;;;;;EAMP,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCoB,oBAAA,CACpB,IAAA,EAAM,2BAAA,GACL,OAAA,CAAQ,eAAA;AAAA,UAoBM,WAAA;;EAEf,GAAA;;EAEA,IAAA;AAAA;;;;;;;;;;;iBAac,yBAAA,CAA0B,IAAA;;;;;;;iBAkBpB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.d.ts

@@ -161,31 +161,37 @@ interface StartTunnelDashboardOptions {
   name?: string;
 }
 /**
- * Env-2 UX parity with env 3/4 (issue #408): when CDP wiring is on and a GUI is
+ * Env-2 UX parity with env 3 (issue #408): when CDP wiring is on and a GUI is
  * available, start the SAME `127.0.0.1` HTML dashboard (QR image + connect steps
- * + FAQ) that the MCP `start_attach` path serves, and auto-open it in the
+ * + FAQ) the debug daemon's `start_attach` path serves, and auto-open it in the
  * browser. headless / opt-out falls back to the terminal ASCII QR (printed
  * separately by {@link printTunnelBanner}).
  *
- * Every part the install-graph invariant depends on (`qrcode`, the MCP HTTP
- * server, the opener) is reached only through dynamic `import()` here, inside
- * the already-lazy `tunnel.js` chunk — nothing is added to the common build
- * graph or the MCP-only install graph.
+ * DELEGATED (issue #817): the implementation now lives in `@ait-co/debugger`'s
+ * `/dev-bridge` subpath — the one cross-repo code delegation of the package
+ * split. The dashboard needs the daemon's QR HTTP server, deep-link builder and
+ * TOTP minting, all of which moved into that package; keeping a second copy here
+ * would fork them. `@ait-co/debugger` is an OPTIONAL peer, so a consumer who
+ * never asks for env-2 CDP installs nothing extra.
  *
- * TOTP encapsulation: the dashboard's `getDashboardState` closure mints a FRESH
- * TOTP `at=` code on every call via `generateTotp(secret, Date.now())` and folds
- * it into a fresh `buildLauncherAttachUrl(...)`. Because the QR is re-rendered on
- * each SSE push / page reload from this closure, the code a phone scans is always
- * within its 30 s window — no stale code is baked into static HTML.
+ * Why this is not a separate plugin: the relay `wss://` URL must exist BEFORE
+ * the QR banner is printed (the launcher QR carries `&relay=`), so the relay and
+ * the dashboard are order-dependent and stay one composed call in the dev loop.
+ *
+ * Degradation: when `@ait-co/debugger` is not installed the import fails and we
+ * return `undefined` — exactly the same "no dashboard" outcome as a closed GUI
+ * gate, with the terminal ASCII QR standing alone. We do NOT fall back to a
+ * local copy of the daemon code. The caller (`./index.ts`) prints the install
+ * hint once when CDP was requested without the package.
  *
  * SECRET-HANDLING: the tunnel host, relay wssUrl, TOTP code, and `.ait_relay`
- * value/path are NEVER written to stdout/stderr/logs here. They live only inside
- * the attach URL (HTML body + `/qr.png` query, per qr-http-server's invariant).
- * The only thing opened/logged is `http://127.0.0.1:<port>` (local, safe).
+ * value/path are NEVER written to stdout/stderr/logs — neither here nor in the
+ * delegate. The only thing opened/logged is `http://127.0.0.1:<port>` (local).
  *
  * @returns the dashboard handle when it started (caller wires `close()` into the
- *   tunnel cleanup), or `undefined` when skipped (no relay, `qr:false`, headless,
- *   opt-out, or a start failure) — in which case ASCII QR fallback stands alone.
+ *   tunnel cleanup), or `undefined` when skipped (package absent, no relay,
+ *   `qr:false`, headless, opt-out, or a start failure) — in which case the ASCII
+ *   QR fallback stands alone.
  */
 declare function startTunnelDashboard(opts: StartTunnelDashboardOptions): Promise<TunnelDashboard | undefined>;
 interface QuickTunnel {

package/dist/unplugin/tunnel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;;iBALgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAuCJ;EArCX,EAAA;EA6Ce;EA3Cf,GAAA,IAAO,GAAA;;;;;;;EAOP,WAAA;EAoEW;;AAiCb;;;EA/FE,IAAA;EAgGA;;;;;AAiCF;EA1HE,WAAA;;;;;;;;EAQA,iBAAA;EAqLe;;;;;;EA9Kf,WAAA;AAAA;;AAqLF;;UA7KiB,4BAAA;EA6K2B;;;;EAxK1C,WAAA;EAqLA;;;;EAhLA,IAAA;EAoNoB;;;;;;EA7MpB,WAAA;EA+MQ;;;;;;;EAvMR,iBAAA;EAwS0B;;;;AAiB5B;;EAlTE,WAAA;AAAA;;AAoUF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAnSgB,qBAAA,CACd,SAAA,UACA,WAAA,YAAuB,4BAAA;;;;;;;iBAgCH,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;;UAgEc,eAAA;;EAEf,GAAA;;EAEA,KAAA,QAAa,OAAA;AAAA;AAAA,UAGE,2BAAA;;EAEf,SAAA;;EAEA,WAAA;;EAEA,EAAA;;;;;EAKA,UAAA;;EAEA,GAAA,IAAO,GAAA;;;;;;EAMP,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8BoB,oBAAA,CACpB,IAAA,EAAM,2BAAA,GACL,OAAA,CAAQ,eAAA;AAAA,UAiGM,WAAA;;EAEf,GAAA;;EAEA,IAAA;AAAA;;;;;;;;;;;iBAac,yBAAA,CAA0B,IAAA;;;;;;;iBAkBpB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}
+{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAyBA;;;;;AAKA;;;;;;;;;;iBALgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAuCJ;EArCX,EAAA;EA6Ce;EA3Cf,GAAA,IAAO,GAAA;;;;;;;EAOP,WAAA;EAoEW;;AAiCb;;;EA/FE,IAAA;EAgGA;;;;;AAiCF;EA1HE,WAAA;;;;;;;;EAQA,iBAAA;EAiKe;;;;;;EA1Jf,WAAA;AAAA;;AAiKF;;UAzJiB,4BAAA;EAyJ2B;;;;EApJ1C,WAAA;EAiKA;;;;EA5JA,IAAA;EAsMoB;;;;;;EA/LpB,WAAA;EAiMQ;;;;;;;EAzLR,iBAAA;EA6M0B;;;;AAiB5B;;EAvNE,WAAA;AAAA;;AAyOF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAxMgB,qBAAA,CACd,SAAA,UACA,WAAA,YAAuB,4BAAA;;;;;;;iBAgCH,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;;UA4Cc,eAAA;;EAEf,GAAA;;EAEA,KAAA,QAAa,OAAA;AAAA;AAAA,UAGE,2BAAA;;EAEf,SAAA;;EAEA,WAAA;;EAEA,EAAA;;;;;EAKA,UAAA;;EAEA,GAAA,IAAO,GAAA;;;;;;EAMP,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoCoB,oBAAA,CACpB,IAAA,EAAM,2BAAA,GACL,OAAA,CAAQ,eAAA;AAAA,UAoBM,WAAA;;EAEf,GAAA;;EAEA,IAAA;AAAA;;;;;;;;;;;iBAac,yBAAA,CAA0B,IAAA;;;;;;;iBAkBpB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.js

@@ -1,6 +1,42 @@
 import { existsSync } from "node:fs";
 import { mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
+//#region src/unplugin/optional-peers.ts
+/**
+* Optional-peer resolution gates for the debug surface (issue #817).
+*
+* The debug surface now ships as two SEPARATE packages, declared here as
+* OPTIONAL peerDependencies of `@ait-co/devtools`:
+*
+*   - `@ait-co/debugger`      — MCP daemon / test runner / dev-bridge. devDependency
+*                               or `npx` only; never part of an app bundle.
+*   - `@ait-co/debug-console` — on-device attach + eruda console. The ONLY debug
+*                               package that can legitimately enter an app bundle.
+*
+* Neither may become a hard dependency. The overwhelming majority of consumers
+* use environment 1 only (browser + mock SDK + panel) and must install NOTHING
+* extra — that is the whole point of splitting the packages apart. So every
+* call site reaches them through the resolution gates below and degrades
+* gracefully when they are absent:
+*
+*   - env-2 CDP wiring (`tunnel.cdp`) → falls back to the plain screen-preview
+*     tunnel (no relay, no dashboard) and prints {@link INSTALL_HINT}.
+*   - in-app attach injection → the snippet is simply not injected, so the
+*     attach code is STRUCTURALLY ABSENT from the bundle rather than merely
+*     gated at runtime. This gate is the technical enforcement point of the
+*     debug surface's security scope: no `@ait-co/debug-console` installed
+*     means no attach code can reach a bundle at all.
+*
+* The `import.meta.resolve` probe follows the `MOCK_PATH` precedent in
+* `./index.ts`: resolution is attempted once at plugin-load time and a failure
+* is a plain "not installed" signal, never an error.
+*
+* SECRET-HANDLING: nothing here touches a relay URL, tunnel host, TOTP secret
+* or code. The only strings emitted are fixed specifiers and the install hint.
+*/
+/** Subpath of `@ait-co/debugger` that the unplugin's dev loop delegates to. */
+const DEBUGGER_DEV_BRIDGE_ID = "@ait-co/debugger/dev-bridge";
+//#endregion
 //#region src/unplugin/tunnel.ts
 /**
 * Cloudflare quick-tunnel helper for the devtools unplugin.
@@ -105,97 +141,48 @@ async function printTunnelBanner(url, opts = {}) {
 	}
 }
 /**
-* Heuristic: can this process open a GUI browser? Mirrors `canOpenBrowser` in
-* `src/mcp/tools.ts` but is re-declared here (not imported) so the tunnel path
-* does not statically pull the heavy MCP `tools.ts` module graph into the lazy
-* `import('./tunnel.js')` chunk. Kept in sync with the MCP copy.
-*
-*   - macOS / Windows → assume yes (env-2 dev normally runs on the user's Mac).
-*   - Linux → require `DISPLAY` or `WAYLAND_DISPLAY`.
-*   - CI (`CI=true`/`CI=1`) → no.
-*/
-function canOpenBrowser() {
-	if (process.env.CI === "true" || process.env.CI === "1") return false;
-	const platform = process.platform;
-	if (platform === "darwin" || platform === "win32") return true;
-	if (platform === "linux") return Boolean(process.env.DISPLAY ?? process.env.WAYLAND_DISPLAY);
-	return false;
-}
-/**
-* Env-2 UX parity with env 3/4 (issue #408): when CDP wiring is on and a GUI is
+* Env-2 UX parity with env 3 (issue #408): when CDP wiring is on and a GUI is
 * available, start the SAME `127.0.0.1` HTML dashboard (QR image + connect steps
-* + FAQ) that the MCP `start_attach` path serves, and auto-open it in the
+* + FAQ) the debug daemon's `start_attach` path serves, and auto-open it in the
 * browser. headless / opt-out falls back to the terminal ASCII QR (printed
 * separately by {@link printTunnelBanner}).
 *
-* Every part the install-graph invariant depends on (`qrcode`, the MCP HTTP
-* server, the opener) is reached only through dynamic `import()` here, inside
-* the already-lazy `tunnel.js` chunk — nothing is added to the common build
-* graph or the MCP-only install graph.
+* DELEGATED (issue #817): the implementation now lives in `@ait-co/debugger`'s
+* `/dev-bridge` subpath — the one cross-repo code delegation of the package
+* split. The dashboard needs the daemon's QR HTTP server, deep-link builder and
+* TOTP minting, all of which moved into that package; keeping a second copy here
+* would fork them. `@ait-co/debugger` is an OPTIONAL peer, so a consumer who
+* never asks for env-2 CDP installs nothing extra.
+*
+* Why this is not a separate plugin: the relay `wss://` URL must exist BEFORE
+* the QR banner is printed (the launcher QR carries `&relay=`), so the relay and
+* the dashboard are order-dependent and stay one composed call in the dev loop.
 *
-* TOTP encapsulation: the dashboard's `getDashboardState` closure mints a FRESH
-* TOTP `at=` code on every call via `generateTotp(secret, Date.now())` and folds
-* it into a fresh `buildLauncherAttachUrl(...)`. Because the QR is re-rendered on
-* each SSE push / page reload from this closure, the code a phone scans is always
-* within its 30 s window — no stale code is baked into static HTML.
+* Degradation: when `@ait-co/debugger` is not installed the import fails and we
+* return `undefined` — exactly the same "no dashboard" outcome as a closed GUI
+* gate, with the terminal ASCII QR standing alone. We do NOT fall back to a
+* local copy of the daemon code. The caller (`./index.ts`) prints the install
+* hint once when CDP was requested without the package.
 *
 * SECRET-HANDLING: the tunnel host, relay wssUrl, TOTP code, and `.ait_relay`
-* value/path are NEVER written to stdout/stderr/logs here. They live only inside
-* the attach URL (HTML body + `/qr.png` query, per qr-http-server's invariant).
-* The only thing opened/logged is `http://127.0.0.1:<port>` (local, safe).
+* value/path are NEVER written to stdout/stderr/logs — neither here nor in the
+* delegate. The only thing opened/logged is `http://127.0.0.1:<port>` (local).
 *
 * @returns the dashboard handle when it started (caller wires `close()` into the
-*   tunnel cleanup), or `undefined` when skipped (no relay, `qr:false`, headless,
-*   opt-out, or a start failure) — in which case ASCII QR fallback stands alone.
+*   tunnel cleanup), or `undefined` when skipped (package absent, no relay,
+*   `qr:false`, headless, opt-out, or a start failure) — in which case the ASCII
+*   QR fallback stands alone.
 */
 async function startTunnelDashboard(opts) {
-	const log = opts.log ?? ((m) => console.log(m));
 	if (!opts.relayWssUrl) return void 0;
 	if (opts.qr === false) return void 0;
-	const { isAutoDevtoolsDisabled } = await import("../devtools-opener-BTl5A6Cd.js");
-	if (!(opts.shouldOpen ?? (() => !isAutoDevtoolsDisabled() && canOpenBrowser()))()) return void 0;
-	const { startQrHttpServer } = await import("../qr-http-server-Bb7lMeqi.js");
-	const { buildLauncherAttachUrl } = await import("../deeplink-BpO9qc-D.js");
-	const { generateTotp } = await import("../totp-95OAa20j.js");
-	const getDashboardState = () => {
-		const secret = process.env.AIT_DEBUG_TOTP_SECRET;
-		const totpCode = secret ? generateTotp(secret, Date.now()) : void 0;
-		const attachUrl = buildLauncherAttachUrl(opts.tunnelUrl, opts.relayWssUrl, totpCode, { name: opts.name });
-		return {
-			tunnel: {
-				up: true,
-				wssUrl: opts.relayWssUrl
-			},
-			pages: null,
-			attachUrl,
-			inspectorUrl: null,
-			mode: "relay-mobile",
-			phase: "active"
-		};
-	};
-	let server;
+	let devBridge;
 	try {
-		server = await startQrHttpServer(getDashboardState);
+		devBridge = await import(DEBUGGER_DEV_BRIDGE_ID);
 	} catch {
 		return;
 	}
-	let totpRefreshHandle = setInterval(() => {
-		server.notifyStateChange();
-	}, 2e4);
-	totpRefreshHandle.unref();
-	const dashboardUrl = `http://127.0.0.1:${server.port}`;
-	const { openUrlInBrowser } = await import("../devtools-opener-BTl5A6Cd.js");
-	log(openUrlInBrowser(dashboardUrl) ? `  │  Opened a QR dashboard in your browser: ${dashboardUrl}` : `  │  Open this QR dashboard in your browser: ${dashboardUrl}`);
-	return {
-		url: dashboardUrl,
-		close: () => {
-			if (totpRefreshHandle) {
-				clearInterval(totpRefreshHandle);
-				totpRefreshHandle = null;
-			}
-			return server.close();
-		}
-	};
+	return devBridge.startTunnelDashboard(opts);
 }
 /**
 * Sanitize cloudflared stderr output for error diagnostics (#421).

package/dist/unplugin/tunnel.js.map

@@ -1 +1 @@
-{"version":3,"file":"tunnel.js","names":[],"sources":["../../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n  /**\n   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When\n   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the\n   * framed PWA passes the in-app debug gate and attaches a Chii target — the\n   * same single scan opens screen preview *and* CDP debugging.\n   */\n  relayWssUrl?: string;\n  /**\n   * Human-readable app name to embed as `name=` in the launcher deep-link (#498).\n   * When provided (non-blank), the launcher partner bar shows this name instead of\n   * the generic default.\n   */\n  name?: string;\n  /**\n   * The miniapp's webViewType. When `'game'`, the deep-link carries `&navBarType=game`\n   * so the launcher enters game nav chrome automatically on scan (#584).\n   * `'partner'` (the default) is the launcher's implicit default — not added to\n   * keep the URL clean.\n   */\n  webViewType?: 'partner' | 'game';\n  /**\n   * Whether the miniapp's navigationBar has `transparentBackground: true`\n   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).\n   * When `true`, the deep-link carries `&navBarTransparent=1` so the launcher\n   * partner bar renders with a transparent background (content shows through).\n   * `false` / omitted → not added (URL clean, back-compat).\n   */\n  navBarTransparent?: boolean;\n  /**\n   * The miniapp's navigationBar theme (`granite.config `navigationBar.theme`,\n   * SDK 2.8.0, #587). When `'light'` or `'dark'`, the deep-link carries\n   * `&navBarTheme=<v>` so the launcher partner bar uses the matching foreground\n   * colour. Omitted / other values → not added (URL clean, back-compat).\n   */\n  navBarTheme?: 'light' | 'dark';\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Options for {@link buildLauncherDeepLink}.\n */\nexport interface BuildLauncherDeepLinkOptions {\n  /**\n   * `wss://` relay URL for env-2 CDP wiring. When present the deep-link carries\n   * `&debug=1&relay=<wss>`.\n   */\n  relayWssUrl?: string;\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param, #498).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * The miniapp's webViewType. When `'game'`, adds `&navBarType=game` to the\n   * deep-link so the launcher enters game nav chrome automatically on scan (#584).\n   * `'partner'` (the launcher's implicit default) is not added to keep the URL\n   * clean.\n   */\n  webViewType?: 'partner' | 'game';\n  /**\n   * Whether the miniapp's navigationBar has `transparentBackground: true`\n   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).\n   * When `true`, adds `&navBarTransparent=1` to the deep-link so the launcher\n   * partner bar renders with a transparent background. Omitted when `false` /\n   * undefined to keep the URL clean (back-compat).\n   */\n  navBarTransparent?: boolean;\n  /**\n   * The miniapp's navigationBar theme (granite.config `navigationBar.theme`,\n   * SDK 2.8.0, #587). When `'light'` or `'dark'`, adds `&navBarTheme=<v>` to\n   * the deep-link so the launcher partner bar uses the matching foreground colour.\n   * Omitted when undefined / other values to keep the URL clean (back-compat).\n   */\n  navBarTheme?: 'light' | 'dark';\n}\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n *\n * When `opts.relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries\n * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so\n * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and\n * a Chii target.js is injected into the live view.\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the launcher\n * partner bar shows the app name instead of the generic default (#498).\n *\n * When `opts.webViewType` is `'game'`, `&navBarType=game` is appended so the\n * launcher enters game nav chrome (floating capsule, no full bar) automatically\n * on scan. `'partner'` is the launcher's implicit default and is not added to\n * keep the URL clean (#584).\n *\n * When `opts.navBarTransparent` is `true`, `&navBarTransparent=1` is appended\n * so the launcher partner bar renders with a transparent background (#587).\n *\n * When `opts.navBarTheme` is `'light'` or `'dark'`, `&navBarTheme=<v>` is\n * appended so the launcher partner bar uses the matching foreground colour (#587).\n *\n * Back-compat: the second argument may also be a plain string (`relayWssUrl`)\n * for callers that haven't migrated to the options object yet.\n */\nexport function buildLauncherDeepLink(\n  tunnelUrl: string,\n  optsOrRelay?: string | BuildLauncherDeepLinkOptions,\n): string {\n  // Normalise the overloaded second argument.\n  const opts: BuildLauncherDeepLinkOptions =\n    typeof optsOrRelay === 'string' ? { relayWssUrl: optsOrRelay } : (optsOrRelay ?? {});\n\n  const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n  let url = base;\n  if (opts.relayWssUrl) {\n    url += `&debug=1&relay=${encodeURIComponent(opts.relayWssUrl)}`;\n  }\n  if (opts.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts.webViewType === 'game') {\n    url += '&navBarType=game';\n  }\n  if (opts.navBarTransparent === true) {\n    url += '&navBarTransparent=1';\n  }\n  if (opts.navBarTheme === 'light' || opts.navBarTheme === 'dark') {\n    url += `&navBarTheme=${opts.navBarTheme}`;\n  }\n  return url;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url, {\n    relayWssUrl: opts.relayWssUrl,\n    name: opts.name,\n    webViewType: opts.webViewType,\n    navBarTransparent: opts.navBarTransparent,\n    navBarTheme: opts.navBarTheme,\n  });\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    ...(opts.relayWssUrl\n      ? [\n          '  │  The same scan also attaches CDP — connect your AI host',\n          '  │  to the relay and debug the live view on-device.',\n        ]\n      : []),\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\n/**\n * Heuristic: can this process open a GUI browser? Mirrors `canOpenBrowser` in\n * `src/mcp/tools.ts` but is re-declared here (not imported) so the tunnel path\n * does not statically pull the heavy MCP `tools.ts` module graph into the lazy\n * `import('./tunnel.js')` chunk. Kept in sync with the MCP copy.\n *\n *   - macOS / Windows → assume yes (env-2 dev normally runs on the user's Mac).\n *   - Linux → require `DISPLAY` or `WAYLAND_DISPLAY`.\n *   - CI (`CI=true`/`CI=1`) → no.\n */\nfunction canOpenBrowser(): boolean {\n  if (process.env.CI === 'true' || process.env.CI === '1') return false;\n  const platform = process.platform;\n  if (platform === 'darwin' || platform === 'win32') return true;\n  if (platform === 'linux') {\n    return Boolean(process.env.DISPLAY ?? process.env.WAYLAND_DISPLAY);\n  }\n  return false;\n}\n\n/** Handle returned by {@link startTunnelDashboard}. */\nexport interface TunnelDashboard {\n  /** `http://127.0.0.1:<port>` — the local dashboard URL opened in the browser. */\n  url: string;\n  /** Tear down the local HTTP server. Idempotent via the underlying server. */\n  close: () => Promise<void>;\n}\n\nexport interface StartTunnelDashboardOptions {\n  /** The public `https://*.trycloudflare.com` app tunnel URL the launcher frames. */\n  tunnelUrl: string;\n  /** The `wss://` relay URL of the env-2 CDP tunnel. REQUIRED — the dashboard is a CDP-only UX. */\n  relayWssUrl: string;\n  /** Mirror of `tunnel.qr` — when `false` the dashboard is skipped (no browser open). */\n  qr?: boolean;\n  /**\n   * Override the GUI/opt-out gate (testing only). When omitted the real\n   * `canOpenBrowser()` + `AIT_AUTO_DEVTOOLS` checks decide.\n   */\n  shouldOpen?: () => boolean;\n  /** Sink for the one-line \"opened in browser\" note (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n  /**\n   * Human-readable app name to embed as `name=` in the launcher deep-link (#498).\n   * When provided (non-blank), the launcher partner bar shows this name instead of\n   * the generic default.\n   */\n  name?: string;\n}\n\n/**\n * Env-2 UX parity with env 3/4 (issue #408): when CDP wiring is on and a GUI is\n * available, start the SAME `127.0.0.1` HTML dashboard (QR image + connect steps\n * + FAQ) that the MCP `start_attach` path serves, and auto-open it in the\n * browser. headless / opt-out falls back to the terminal ASCII QR (printed\n * separately by {@link printTunnelBanner}).\n *\n * Every part the install-graph invariant depends on (`qrcode`, the MCP HTTP\n * server, the opener) is reached only through dynamic `import()` here, inside\n * the already-lazy `tunnel.js` chunk — nothing is added to the common build\n * graph or the MCP-only install graph.\n *\n * TOTP encapsulation: the dashboard's `getDashboardState` closure mints a FRESH\n * TOTP `at=` code on every call via `generateTotp(secret, Date.now())` and folds\n * it into a fresh `buildLauncherAttachUrl(...)`. Because the QR is re-rendered on\n * each SSE push / page reload from this closure, the code a phone scans is always\n * within its 30 s window — no stale code is baked into static HTML.\n *\n * SECRET-HANDLING: the tunnel host, relay wssUrl, TOTP code, and `.ait_relay`\n * value/path are NEVER written to stdout/stderr/logs here. They live only inside\n * the attach URL (HTML body + `/qr.png` query, per qr-http-server's invariant).\n * The only thing opened/logged is `http://127.0.0.1:<port>` (local, safe).\n *\n * @returns the dashboard handle when it started (caller wires `close()` into the\n *   tunnel cleanup), or `undefined` when skipped (no relay, `qr:false`, headless,\n *   opt-out, or a start failure) — in which case ASCII QR fallback stands alone.\n */\nexport async function startTunnelDashboard(\n  opts: StartTunnelDashboardOptions,\n): Promise<TunnelDashboard | undefined> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n\n  // Gate: dashboard is a CDP-only UX (needs a relay to attach to).\n  if (!opts.relayWssUrl) return undefined;\n  // Opt-out via `tunnel.qr:false` (same toggle that suppresses the ASCII QR).\n  if (opts.qr === false) return undefined;\n\n  // GUI + AIT_AUTO_DEVTOOLS gate. Reuse the MCP opener's opt-out predicate so\n  // the env-2 path honours the same `AIT_AUTO_DEVTOOLS=0` switch as env 3/4.\n  const { isAutoDevtoolsDisabled } = await import('../mcp/devtools-opener.js');\n  const gateOpen = opts.shouldOpen ?? (() => !isAutoDevtoolsDisabled() && canOpenBrowser());\n  if (!gateOpen()) return undefined;\n\n  const { startQrHttpServer } = await import('../mcp/qr-http-server.js');\n  const { buildLauncherAttachUrl } = await import('../mcp/deeplink.js');\n  const { generateTotp } = await import('../mcp/totp.js');\n\n  // getDashboardState — mints a fresh TOTP + attach URL on every call so the QR\n  // the dashboard renders (on load and on each SSE push) is never expired.\n  // SECRET-HANDLING: the secret is read from env AT CALL TIME (it was injected\n  // by ensureRelaySecret in the same CDP block) and is used only to compute the\n  // at= code folded into attachUrl. tunnel.up is always true here — the relay\n  // tunnel is already up by the time this runs.\n  const getDashboardState = () => {\n    const secret = process.env.AIT_DEBUG_TOTP_SECRET;\n    const totpCode = secret ? generateTotp(secret, Date.now()) : undefined;\n    const attachUrl = buildLauncherAttachUrl(opts.tunnelUrl, opts.relayWssUrl, totpCode, {\n      name: opts.name,\n    });\n    // pages: null — env 2(unplugin)는 데몬이 아니라 vite 플러그인 안이라\n    // startChiiRelay 핸들이 connected target을 노출하지 않는다. 라이브 page 목록을\n    // 알 수 없으므로 거짓 빈 목록 대신 \"연결된 Pages\" 섹션 자체를 숨긴다(#411).\n    // env 3/4(debug-server.ts)는 router.active.listTargets()로 실제 목록을 채운다.\n    // mode: 'relay-mobile' — 이 대시보드는 항상 환경 2(AITC Sandbox PWA) 전용이므로\n    // /attach 카피가 launcher PWA 절차(sandbox family)로 분기된다(#468).\n    // inspectorUrl: null — env 2에서는 unplugin relay가 connected target ID를 노출하지\n    // 않아 buildChiiInspectorUrl에 필요한 targetId를 알 수 없다. target attach 후\n    // target ID가 필요하므로 env 3/4에서만 non-null이 된다(#503).\n    return {\n      tunnel: { up: true, wssUrl: opts.relayWssUrl },\n      pages: null,\n      attachUrl,\n      inspectorUrl: null,\n      mode: 'relay-mobile' as const,\n      // phase (#730): this dev-tunnel dashboard has no CLI run lifecycle or\n      // daemon shutdown signal to drive — it stays 'active' for its lifetime.\n      phase: 'active' as const,\n    };\n  };\n\n  let server: Awaited<ReturnType<typeof startQrHttpServer>>;\n  try {\n    server = await startQrHttpServer(getDashboardState);\n  } catch {\n    // SECRET-HANDLING: do not surface the error (could embed paths/hosts). The\n    // ASCII QR printed by printTunnelBanner stays as the fallback.\n    return undefined;\n  }\n\n  // TOTP periodic refresh timer — pushes a fresh at= code to SSE clients every\n  // 20 s so a page left open never stales past the 90 s acceptance window (#448).\n  // tunnel.ts always has relayWssUrl available here (gated above), so no\n  // lastAttachParts guard is needed — getDashboardState mints a fresh TOTP on\n  // every call unconditionally.\n  // SECRET-HANDLING: callback is a plain trigger only — TOTP value and at= code\n  // must never be logged or written to stdout.\n  const TOTP_REFRESH_INTERVAL_MS = 20_000;\n  let totpRefreshHandle: ReturnType<typeof setInterval> | null = setInterval(() => {\n    server.notifyStateChange();\n  }, TOTP_REFRESH_INTERVAL_MS);\n  totpRefreshHandle.unref();\n\n  const dashboardUrl = `http://127.0.0.1:${server.port}`;\n\n  const { openUrlInBrowser } = await import('../mcp/devtools-opener.js');\n  const opened = openUrlInBrowser(dashboardUrl);\n  // SECRET-HANDLING: only the local 127.0.0.1 URL is logged — never the tunnel\n  // host, relay wssUrl, or TOTP code.\n  log(\n    opened\n      ? `  │  Opened a QR dashboard in your browser: ${dashboardUrl}`\n      : `  │  Open this QR dashboard in your browser: ${dashboardUrl}`,\n  );\n\n  return {\n    url: dashboardUrl,\n    close: () => {\n      if (totpRefreshHandle) {\n        clearInterval(totpRefreshHandle);\n        totpRefreshHandle = null;\n      }\n      return server.close();\n    },\n  };\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\n/**\n * Sanitize cloudflared stderr output for error diagnostics (#421).\n *\n * Masks `*.trycloudflare.com` hostnames and full `https://` / `wss://` URLs\n * that carry those hostnames so tunnel host values never appear in error\n * messages. Diagnostic content (error codes, reasons, JSON blobs) is preserved.\n *\n * SECRET-HANDLING: tunnel host is SECRET-class per harness policy — only\n * placeholder text is emitted.\n */\nexport function sanitizeCloudflaredOutput(line: string): string {\n  // Full URL forms: https://xxx.trycloudflare.com/… and wss://xxx.trycloudflare.com/…\n  let s = line.replace(/(?:https?|wss?):\\/\\/[a-z0-9-]+\\.trycloudflare\\.com(?:\\/[^\\s]*)*/gi, (m) =>\n    m.replace(/[a-z0-9-]+\\.trycloudflare\\.com/i, '<HOST>.trycloudflare.com'),\n  );\n  // Bare hostname without scheme (e.g. printed in cloudflared JSON logs)\n  s = s.replace(/[a-z0-9-]+\\.trycloudflare\\.com/gi, '<HOST>.trycloudflare.com');\n  return s;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    // #421: accumulate stderr to attach as diagnostics on failure.\n    // SECRET-HANDLING: lines are sanitized before inclusion in error messages.\n    const stderrLines: string[] = [];\n\n    /**\n     * Format the last `n` sanitized stderr lines as a diagnostic appendix.\n     * Returns an empty string when no lines have been collected.\n     */\n    const stderrTail = (n = 15): string => {\n      if (stderrLines.length === 0) return '';\n      const tail = stderrLines.slice(-n).map(sanitizeCloudflaredOutput).join('');\n      return `\\ncloudflared 출력 (마지막 ${Math.min(n, stderrLines.length)}줄):\\n${tail}`;\n    };\n\n    const timer = setTimeout(() => {\n      cleanup();\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.${stderrTail()}`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    // Accumulate stderr lines for diagnostics (#421). Named so it can be\n    // removed from the listener list when cleanup() runs.\n    const pushStderr = (line: string) => {\n      stderrLines.push(line);\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      tunnel.off('stderr', pushStderr);\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    // Second stderr listener: accumulate all lines for error diagnostics.\n    tunnel.on('stderr', pushStderr);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.${stderrTail()}`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":"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"}
+{"version":3,"file":"tunnel.js","names":[],"sources":["../../src/unplugin/optional-peers.ts","../../src/unplugin/tunnel.ts"],"sourcesContent":["/**\n * Optional-peer resolution gates for the debug surface (issue #817).\n *\n * The debug surface now ships as two SEPARATE packages, declared here as\n * OPTIONAL peerDependencies of `@ait-co/devtools`:\n *\n *   - `@ait-co/debugger`      — MCP daemon / test runner / dev-bridge. devDependency\n *                               or `npx` only; never part of an app bundle.\n *   - `@ait-co/debug-console` — on-device attach + eruda console. The ONLY debug\n *                               package that can legitimately enter an app bundle.\n *\n * Neither may become a hard dependency. The overwhelming majority of consumers\n * use environment 1 only (browser + mock SDK + panel) and must install NOTHING\n * extra — that is the whole point of splitting the packages apart. So every\n * call site reaches them through the resolution gates below and degrades\n * gracefully when they are absent:\n *\n *   - env-2 CDP wiring (`tunnel.cdp`) → falls back to the plain screen-preview\n *     tunnel (no relay, no dashboard) and prints {@link INSTALL_HINT}.\n *   - in-app attach injection → the snippet is simply not injected, so the\n *     attach code is STRUCTURALLY ABSENT from the bundle rather than merely\n *     gated at runtime. This gate is the technical enforcement point of the\n *     debug surface's security scope: no `@ait-co/debug-console` installed\n *     means no attach code can reach a bundle at all.\n *\n * The `import.meta.resolve` probe follows the `MOCK_PATH` precedent in\n * `./index.ts`: resolution is attempted once at plugin-load time and a failure\n * is a plain \"not installed\" signal, never an error.\n *\n * SECRET-HANDLING: nothing here touches a relay URL, tunnel host, TOTP secret\n * or code. The only strings emitted are fixed specifiers and the install hint.\n */\n\n/** Subpath of `@ait-co/debugger` that the unplugin's dev loop delegates to. */\nexport const DEBUGGER_DEV_BRIDGE_ID = '@ait-co/debugger/dev-bridge';\n\n/** The on-device attach package injected into a consumer entry point. */\nexport const DEBUG_CONSOLE_ID = '@ait-co/debug-console';\n\n/**\n * The pre-split in-app specifier. Still recognised for DEDUPE only — a consumer\n * who wired `@ait-co/devtools/in-app` by hand must not also receive the new\n * auto-injected snippet. It is never injected any more.\n */\nexport const LEGACY_IN_APP_ID = '@ait-co/devtools/in-app';\n\n/** One-line install hint printed whenever a gate closes on a missing package. */\nexport const INSTALL_HINT = 'pnpm add -D @ait-co/debugger @ait-co/debug-console';\n\n/**\n * Returns whether `specifier` resolves from this package's location.\n *\n * `import.meta.resolve` throws (rather than returning a falsy value) for an\n * unresolvable specifier, and is itself absent on a few older runtimes — both\n * are treated as \"not installed\", which is the safe direction: the caller then\n * takes the degraded path instead of importing something that is not there.\n */\nexport function canResolveOptionalPeer(specifier: string): boolean {\n  try {\n    return typeof import.meta.resolve(specifier) === 'string';\n  } catch {\n    return false;\n  }\n}\n\n/** Whether `@ait-co/debugger`'s dev-bridge is installed (env-2 CDP path). */\nexport function hasDebugger(): boolean {\n  return canResolveOptionalPeer(DEBUGGER_DEV_BRIDGE_ID);\n}\n\n/** Whether `@ait-co/debug-console` is installed (in-app attach injection). */\nexport function hasDebugConsole(): boolean {\n  return canResolveOptionalPeer(DEBUG_CONSOLE_ID);\n}\n\n/**\n * Whether `code` already wires the in-app debug attach itself.\n *\n * Both the current (`@ait-co/debug-console`) and the pre-split\n * (`@ait-co/devtools/in-app`) specifier count, so a consumer who wired either\n * one by hand never gets a duplicate auto-injection.\n */\nexport function hasInAppWiring(code: string): boolean {\n  return code.includes(DEBUG_CONSOLE_ID) || code.includes(LEGACY_IN_APP_ID);\n}\n\n/**\n * The gated dynamic-import snippet prepended to a consumer entry point.\n *\n * The runtime gate (`?debug=1` + a `relay` param) keeps the chunk unloaded on a\n * normal page load, and a production build dead-code-eliminates it. The\n * build-time gate is {@link hasDebugConsole} at the call site: when the package\n * is absent this snippet is never produced, so the attach code cannot be in the\n * bundle at all.\n */\nexport function buildInAppSnippet(): string {\n  return [\n    '// @ait-co/devtools: in-app attach auto-injected by unplugin — 수동 배선 불필요',\n    \"if (typeof window !== 'undefined') {\",\n    '  const __ait_p = new URLSearchParams(window.location.search);',\n    \"  if (__ait_p.get('debug') === '1' && __ait_p.get('relay')) {\",\n    `    void import('${DEBUG_CONSOLE_ID}').then((m) => m.maybeAttach());`,\n    '  }',\n    '}',\n  ].join('\\n');\n}\n","/**\n * Cloudflare quick-tunnel helper for the devtools unplugin.\n *\n * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is\n * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common\n * case. This is the one place in `@ait-co/devtools` that depends on Node-only\n * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of\n * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the\n * \"web 모드는 e2e\" rule in CLAUDE.md). The pure helpers below\n * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.\n */\n\nimport { existsSync } from 'node:fs';\nimport { mkdir } from 'node:fs/promises';\nimport { dirname } from 'node:path';\nimport { DEBUGGER_DEV_BRIDGE_ID } from './optional-peers.js';\n\n/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */\nconst TRYCLOUDFLARE_RE = /https:\\/\\/[a-z0-9-]+\\.trycloudflare\\.com/i;\n\n/**\n * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared\n * output, or `null` if the line doesn't contain one. Pulled out as a pure\n * function so it can be unit-tested without spawning anything.\n */\nexport function parseTrycloudflareUrl(line: string): string | null {\n  const m = line.match(TRYCLOUDFLARE_RE);\n  return m ? m[0] : null;\n}\n\nexport interface PrintTunnelBannerOptions {\n  /** Print an ASCII QR encoding the tunnel URL (default: true). */\n  qr?: boolean;\n  /** Sink for the banner text (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n  /**\n   * The `wss://` relay URL of the env-2 CDP tunnel, if `tunnel.cdp` is on. When\n   * present the QR deep-link additionally carries `&debug=1&relay=<wss>` so the\n   * framed PWA passes the in-app debug gate and attaches a Chii target — the\n   * same single scan opens screen preview *and* CDP debugging.\n   */\n  relayWssUrl?: string;\n  /**\n   * Human-readable app name to embed as `name=` in the launcher deep-link (#498).\n   * When provided (non-blank), the launcher partner bar shows this name instead of\n   * the generic default.\n   */\n  name?: string;\n  /**\n   * The miniapp's webViewType. When `'game'`, the deep-link carries `&navBarType=game`\n   * so the launcher enters game nav chrome automatically on scan (#584).\n   * `'partner'` (the default) is the launcher's implicit default — not added to\n   * keep the URL clean.\n   */\n  webViewType?: 'partner' | 'game';\n  /**\n   * Whether the miniapp's navigationBar has `transparentBackground: true`\n   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).\n   * When `true`, the deep-link carries `&navBarTransparent=1` so the launcher\n   * partner bar renders with a transparent background (content shows through).\n   * `false` / omitted → not added (URL clean, back-compat).\n   */\n  navBarTransparent?: boolean;\n  /**\n   * The miniapp's navigationBar theme (`granite.config `navigationBar.theme`,\n   * SDK 2.8.0, #587). When `'light'` or `'dark'`, the deep-link carries\n   * `&navBarTheme=<v>` so the launcher partner bar uses the matching foreground\n   * colour. Omitted / other values → not added (URL clean, back-compat).\n   */\n  navBarTheme?: 'light' | 'dark';\n}\n\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Options for {@link buildLauncherDeepLink}.\n */\nexport interface BuildLauncherDeepLinkOptions {\n  /**\n   * `wss://` relay URL for env-2 CDP wiring. When present the deep-link carries\n   * `&debug=1&relay=<wss>`.\n   */\n  relayWssUrl?: string;\n  /**\n   * Human-readable app name shown in the partner nav bar (`name=` param, #498).\n   * Blank / whitespace-only values are not added.\n   */\n  name?: string;\n  /**\n   * The miniapp's webViewType. When `'game'`, adds `&navBarType=game` to the\n   * deep-link so the launcher enters game nav chrome automatically on scan (#584).\n   * `'partner'` (the launcher's implicit default) is not added to keep the URL\n   * clean.\n   */\n  webViewType?: 'partner' | 'game';\n  /**\n   * Whether the miniapp's navigationBar has `transparentBackground: true`\n   * (granite.config `navigationBar.transparentBackground`, SDK 2.8.0, #587).\n   * When `true`, adds `&navBarTransparent=1` to the deep-link so the launcher\n   * partner bar renders with a transparent background. Omitted when `false` /\n   * undefined to keep the URL clean (back-compat).\n   */\n  navBarTransparent?: boolean;\n  /**\n   * The miniapp's navigationBar theme (granite.config `navigationBar.theme`,\n   * SDK 2.8.0, #587). When `'light'` or `'dark'`, adds `&navBarTheme=<v>` to\n   * the deep-link so the launcher partner bar uses the matching foreground colour.\n   * Omitted when undefined / other values to keep the URL clean (back-compat).\n   */\n  navBarTheme?: 'light' | 'dark';\n}\n\n/**\n * Build the deep-link URL that QR codes encode: when the launcher PWA is\n * already on the phone's home screen, scanning this opens it directly into the\n * live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).\n * Plain-text raw URL is no longer enough — the launcher gates its setup UI to\n * the installed PWA, so a raw tunnel URL opened in a normal browser tab would\n * land on a \"please install\" screen.\n *\n * When `opts.relayWssUrl` is given (env-2 CDP wiring), the deep-link also carries\n * `&debug=1&relay=<wss>`; the launcher folds those onto the framed tunnel URL so\n * the in-app debug gate's Layer C (`debug=1` opt-in + `relay=<wss>`) is met and\n * a Chii target.js is injected into the live view.\n *\n * When `opts.name` is given (non-blank), it is added as `&name=` so the launcher\n * partner bar shows the app name instead of the generic default (#498).\n *\n * When `opts.webViewType` is `'game'`, `&navBarType=game` is appended so the\n * launcher enters game nav chrome (floating capsule, no full bar) automatically\n * on scan. `'partner'` is the launcher's implicit default and is not added to\n * keep the URL clean (#584).\n *\n * When `opts.navBarTransparent` is `true`, `&navBarTransparent=1` is appended\n * so the launcher partner bar renders with a transparent background (#587).\n *\n * When `opts.navBarTheme` is `'light'` or `'dark'`, `&navBarTheme=<v>` is\n * appended so the launcher partner bar uses the matching foreground colour (#587).\n *\n * Back-compat: the second argument may also be a plain string (`relayWssUrl`)\n * for callers that haven't migrated to the options object yet.\n */\nexport function buildLauncherDeepLink(\n  tunnelUrl: string,\n  optsOrRelay?: string | BuildLauncherDeepLinkOptions,\n): string {\n  // Normalise the overloaded second argument.\n  const opts: BuildLauncherDeepLinkOptions =\n    typeof optsOrRelay === 'string' ? { relayWssUrl: optsOrRelay } : (optsOrRelay ?? {});\n\n  const base = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;\n  let url = base;\n  if (opts.relayWssUrl) {\n    url += `&debug=1&relay=${encodeURIComponent(opts.relayWssUrl)}`;\n  }\n  if (opts.name !== undefined && opts.name.trim() !== '') {\n    url += `&name=${encodeURIComponent(opts.name.trim())}`;\n  }\n  if (opts.webViewType === 'game') {\n    url += '&navBarType=game';\n  }\n  if (opts.navBarTransparent === true) {\n    url += '&navBarTransparent=1';\n  }\n  if (opts.navBarTheme === 'light' || opts.navBarTheme === 'dark') {\n    url += `&navBarTheme=${opts.navBarTheme}`;\n  }\n  return url;\n}\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding a launcher deep-link, and a one-line note that quick tunnels are\n * ephemeral, unauthenticated and not for production. Pure w.r.t. side effects\n * other than the injected `log` sink and `qrcode-terminal` — unit-tested.\n */\nexport async function printTunnelBanner(\n  url: string,\n  opts: PrintTunnelBannerOptions = {},\n): Promise<void> {\n  const log = opts.log ?? ((m: string) => console.log(m));\n  const deepLink = buildLauncherDeepLink(url, {\n    relayWssUrl: opts.relayWssUrl,\n    name: opts.name,\n    webViewType: opts.webViewType,\n    navBarTransparent: opts.navBarTransparent,\n    navBarTheme: opts.navBarTheme,\n  });\n  const lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,\n    '  │  Then scan the QR below — it opens the launcher directly',\n    '  │  into this tunnel URL (no manual paste needed).',\n    ...(opts.relayWssUrl\n      ? [\n          '  │  The same scan also attaches CDP — connect your AI host',\n          '  │  to the relay and debug the live view on-device.',\n        ]\n      : []),\n    '  │  Quick tunnels are unauthenticated, change every run, and are',\n    '  │  not for production use.',\n    '  └──────────────────────────────────────────────────────────────',\n    '',\n  ];\n  log(lines.join('\\n'));\n\n  if (opts.qr !== false) {\n    // qrcode-terminal is only pulled in on this code path (ambient types live\n    // in src/qrcode-terminal.d.ts).\n    const qrcode = (await import('qrcode-terminal')).default;\n    await new Promise<void>((resolve) => {\n      qrcode.generate(deepLink, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\n    });\n  }\n}\n\n/** Handle returned by {@link startTunnelDashboard}. */\nexport interface TunnelDashboard {\n  /** `http://127.0.0.1:<port>` — the local dashboard URL opened in the browser. */\n  url: string;\n  /** Tear down the local HTTP server. Idempotent via the underlying server. */\n  close: () => Promise<void>;\n}\n\nexport interface StartTunnelDashboardOptions {\n  /** The public `https://*.trycloudflare.com` app tunnel URL the launcher frames. */\n  tunnelUrl: string;\n  /** The `wss://` relay URL of the env-2 CDP tunnel. REQUIRED — the dashboard is a CDP-only UX. */\n  relayWssUrl: string;\n  /** Mirror of `tunnel.qr` — when `false` the dashboard is skipped (no browser open). */\n  qr?: boolean;\n  /**\n   * Override the GUI/opt-out gate (testing only). When omitted the real\n   * `canOpenBrowser()` + `AIT_AUTO_DEVTOOLS` checks decide.\n   */\n  shouldOpen?: () => boolean;\n  /** Sink for the one-line \"opened in browser\" note (default: `console.log`). Injected for testing. */\n  log?: (msg: string) => void;\n  /**\n   * Human-readable app name to embed as `name=` in the launcher deep-link (#498).\n   * When provided (non-blank), the launcher partner bar shows this name instead of\n   * the generic default.\n   */\n  name?: string;\n}\n\n/**\n * Env-2 UX parity with env 3 (issue #408): when CDP wiring is on and a GUI is\n * available, start the SAME `127.0.0.1` HTML dashboard (QR image + connect steps\n * + FAQ) the debug daemon's `start_attach` path serves, and auto-open it in the\n * browser. headless / opt-out falls back to the terminal ASCII QR (printed\n * separately by {@link printTunnelBanner}).\n *\n * DELEGATED (issue #817): the implementation now lives in `@ait-co/debugger`'s\n * `/dev-bridge` subpath — the one cross-repo code delegation of the package\n * split. The dashboard needs the daemon's QR HTTP server, deep-link builder and\n * TOTP minting, all of which moved into that package; keeping a second copy here\n * would fork them. `@ait-co/debugger` is an OPTIONAL peer, so a consumer who\n * never asks for env-2 CDP installs nothing extra.\n *\n * Why this is not a separate plugin: the relay `wss://` URL must exist BEFORE\n * the QR banner is printed (the launcher QR carries `&relay=`), so the relay and\n * the dashboard are order-dependent and stay one composed call in the dev loop.\n *\n * Degradation: when `@ait-co/debugger` is not installed the import fails and we\n * return `undefined` — exactly the same \"no dashboard\" outcome as a closed GUI\n * gate, with the terminal ASCII QR standing alone. We do NOT fall back to a\n * local copy of the daemon code. The caller (`./index.ts`) prints the install\n * hint once when CDP was requested without the package.\n *\n * SECRET-HANDLING: the tunnel host, relay wssUrl, TOTP code, and `.ait_relay`\n * value/path are NEVER written to stdout/stderr/logs — neither here nor in the\n * delegate. The only thing opened/logged is `http://127.0.0.1:<port>` (local).\n *\n * @returns the dashboard handle when it started (caller wires `close()` into the\n *   tunnel cleanup), or `undefined` when skipped (package absent, no relay,\n *   `qr:false`, headless, opt-out, or a start failure) — in which case the ASCII\n *   QR fallback stands alone.\n */\nexport async function startTunnelDashboard(\n  opts: StartTunnelDashboardOptions,\n): Promise<TunnelDashboard | undefined> {\n  // Gate: dashboard is a CDP-only UX (needs a relay to attach to). Checked here\n  // as well as in the delegate so an absent relay never even probes the package.\n  if (!opts.relayWssUrl) return undefined;\n  // Opt-out via `tunnel.qr:false` (same toggle that suppresses the ASCII QR).\n  if (opts.qr === false) return undefined;\n\n  let devBridge: { startTunnelDashboard: typeof startTunnelDashboard };\n  try {\n    devBridge = (await import(DEBUGGER_DEV_BRIDGE_ID)) as {\n      startTunnelDashboard: typeof startTunnelDashboard;\n    };\n  } catch {\n    // Not installed (or an unexpected load failure) — degrade to ASCII QR only.\n    // SECRET-HANDLING: the error is not surfaced (it can embed local paths).\n    return undefined;\n  }\n  return devBridge.startTunnelDashboard(opts);\n}\n\nexport interface QuickTunnel {\n  /** The public `https://*.trycloudflare.com` URL. */\n  url: string;\n  /** Stop the underlying `cloudflared` process. Idempotent. */\n  stop: () => void;\n}\n\n/**\n * Sanitize cloudflared stderr output for error diagnostics (#421).\n *\n * Masks `*.trycloudflare.com` hostnames and full `https://` / `wss://` URLs\n * that carry those hostnames so tunnel host values never appear in error\n * messages. Diagnostic content (error codes, reasons, JSON blobs) is preserved.\n *\n * SECRET-HANDLING: tunnel host is SECRET-class per harness policy — only\n * placeholder text is emitted.\n */\nexport function sanitizeCloudflaredOutput(line: string): string {\n  // Full URL forms: https://xxx.trycloudflare.com/… and wss://xxx.trycloudflare.com/…\n  let s = line.replace(/(?:https?|wss?):\\/\\/[a-z0-9-]+\\.trycloudflare\\.com(?:\\/[^\\s]*)*/gi, (m) =>\n    m.replace(/[a-z0-9-]+\\.trycloudflare\\.com/i, '<HOST>.trycloudflare.com'),\n  );\n  // Bare hostname without scheme (e.g. printed in cloudflared JSON logs)\n  s = s.replace(/[a-z0-9-]+\\.trycloudflare\\.com/gi, '<HOST>.trycloudflare.com');\n  return s;\n}\n\nconst URL_TIMEOUT_MS = 20_000;\n\n/**\n * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`\n * and resolve once the public URL is known. Downloads the `cloudflared` binary\n * on first use if it is not already installed. Rejects with a friendly error if\n * no URL appears within {@link URL_TIMEOUT_MS}.\n */\nexport async function startQuickTunnel(port: number): Promise<QuickTunnel> {\n  const cloudflared = await import('cloudflared');\n  const { bin, install, Tunnel } = cloudflared;\n\n  if (!existsSync(bin)) {\n    await mkdir(dirname(bin), { recursive: true });\n    await install(bin);\n  }\n\n  const tunnel = Tunnel.quick(`http://localhost:${port}`);\n  let stopped = false;\n  const stop = () => {\n    if (stopped) return;\n    stopped = true;\n    try {\n      tunnel.stop();\n    } catch {\n      // process may already be gone\n    }\n  };\n\n  return new Promise<QuickTunnel>((resolve, reject) => {\n    // #421: accumulate stderr to attach as diagnostics on failure.\n    // SECRET-HANDLING: lines are sanitized before inclusion in error messages.\n    const stderrLines: string[] = [];\n\n    /**\n     * Format the last `n` sanitized stderr lines as a diagnostic appendix.\n     * Returns an empty string when no lines have been collected.\n     */\n    const stderrTail = (n = 15): string => {\n      if (stderrLines.length === 0) return '';\n      const tail = stderrLines.slice(-n).map(sanitizeCloudflaredOutput).join('');\n      return `\\ncloudflared 출력 (마지막 ${Math.min(n, stderrLines.length)}줄):\\n${tail}`;\n    };\n\n    const timer = setTimeout(() => {\n      cleanup();\n      stop();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared did not report a tunnel URL within ${\n            URL_TIMEOUT_MS / 1000\n          }s. Check your network connection, or run \\`cloudflared tunnel --url http://localhost:${port}\\` manually.${stderrTail()}`,\n        ),\n      );\n    }, URL_TIMEOUT_MS);\n\n    const onUrl = (line: string) => {\n      const found = parseTrycloudflareUrl(line);\n      if (!found) return;\n      clearTimeout(timer);\n      // Stop scanning further output once we have the URL.\n      cleanup();\n      resolve({ url: found, stop });\n    };\n\n    // Accumulate stderr lines for diagnostics (#421). Named so it can be\n    // removed from the listener list when cleanup() runs.\n    const pushStderr = (line: string) => {\n      stderrLines.push(line);\n    };\n\n    const cleanup = () => {\n      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      tunnel.off('stderr', pushStderr);\n    };\n\n    // The library emits a parsed `url` event; we also scan raw stdout/stderr in\n    // case the output format shifts.\n    tunnel.once('url', onUrl);\n    tunnel.on('stdout', onUrl);\n    tunnel.on('stderr', onUrl);\n    // Second stderr listener: accumulate all lines for error diagnostics.\n    tunnel.on('stderr', pushStderr);\n    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      cleanup();\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      cleanup();\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.${stderrTail()}`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ait-co/devtools",
-  "version": "0.1.143",
-  "description": "Development tools for Apps in Toss mini-apps — mock SDK, floating devtools panel, and universal bundler plugin",
+  "version": "0.2.0",
+  "description": "Browser development tools for Apps in Toss mini-apps — mock SDK, floating devtools panel, and universal bundler plugin. devDependency only; contributes nothing to a production bundle",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -48,35 +48,36 @@
     }
   },
   "bin": {
-    "devtools-mcp": "./dist/mcp/cli.js",
-    "devtools-test": "./dist/test-runner/bin.js"
+    "devtools-mcp": "./dist/stubs/bin-devtools-mcp.js",
+    "devtools-test": "./dist/stubs/bin-devtools-test.js"
   },
   "files": [
     "dist"
   ],
   "peerDependencies": {
+    "@ait-co/debug-console": "^0.1.0",
+    "@ait-co/debugger": "^0.1.3",
     "@apps-in-toss/web-framework": ">=2.6.0 <3.0.0"
   },
   "peerDependenciesMeta": {
+    "@ait-co/debug-console": {
+      "optional": true
+    },
+    "@ait-co/debugger": {
+      "optional": true
+    },
     "@apps-in-toss/web-framework": {
       "optional": true
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@vitest/expect": "^4.1.9",
-    "@vitest/runner": "^4.1.9",
-    "ajv": "^8.20.0",
-    "chii": "^1.15.5",
     "cloudflared": "^0.7.1",
-    "eruda": "^3.4.3",
-    "esbuild": "^0.28.1",
-    "qrcode": "^1.5.4",
     "qrcode-terminal": "^0.12.0",
-    "unplugin": "^3.2.0",
-    "ws": "^8.21.0"
+    "unplugin": "^3.2.0"
   },
   "devDependencies": {
+    "@ait-co/debug-console": "^0.1.3",
+    "@ait-co/debugger": "^0.1.3",
     "@ait-co/polyfill": "^0.1.17",
     "@apps-in-toss/web-framework": "3.0.0-beta.3051978",
     "@apps-in-toss/web-framework-2x": "npm:@apps-in-toss/web-framework@2.10.7",
@@ -86,11 +87,9 @@
     "@playwright/test": "^1.61.1",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.0",
-    "@types/qrcode": "^1.5.6",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "@types/ws": "^8.18.0",
     "@vitejs/plugin-react": "^6.0.3",
     "jsdom": "^29.1.1",
     "qr-scanner": "^1.4.2",
@@ -130,12 +129,8 @@
     "url": "https://github.com/apps-in-toss-community/devtools/issues"
   },
   "scripts": {
-    "build:dashboard-html": "tsx --tsconfig scripts/tsconfig.json scripts/build-dashboard-html.ts",
-    "build": "pnpm build:dashboard-html && tsdown",
-    "check:mcp-react-free": "bash scripts/check-mcp-react-free.sh",
-    "check:test-runner-dist": "bash scripts/check-test-runner-dist.sh",
-    "check:debug-surface-absent": "bash scripts/check-debug-surface-absent.sh",
-    "check:dashboard-html-fresh": "pnpm build:dashboard-html && git diff --exit-code src/mcp/dashboard.generated.ts",
+    "build": "tsdown",
+    "check:footprint-absent": "bash scripts/check-devtools-footprint-absent.sh",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.2x.json && tsc --noEmit -p e2e/fixture/tsconfig.json && tsc --noEmit -p scripts/tsconfig.json",
     "test": "vitest run",