@ait-co/devtools 0.1.18 → 0.1.20

package/dist/unplugin/index.js

@@ -49,6 +49,9 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 	const shouldEnable = isDev || (options?.forceEnable ?? false);
 	const shouldMock = shouldEnable && (options?.mock ?? isDev);
 	const shouldPanel = shouldEnable && (options?.panel ?? true);
+	const tunnelOpt = options?.tunnel;
+	const shouldTunnel = isDev && !!tunnelOpt;
+	const tunnelConfig = typeof tunnelOpt === "object" ? tunnelOpt : {};
 	return {
 		name: "ait-co-devtools",
 		enforce: "pre",
@@ -65,6 +68,37 @@ const aitDevtoolsPlugin = createUnplugin((options) => {
 			if (!shouldPanel) return null;
 			if (code.includes("@ait-co/devtools/panel")) return null;
 			return `import '@ait-co/devtools/panel';\n${code}`;
+		},
+		vite: {
+			config() {
+				if (!shouldTunnel) return;
+				return { server: { allowedHosts: [".trycloudflare.com"] } };
+			},
+			configureServer(server) {
+				if (!shouldTunnel) return;
+				let tunnel = null;
+				const httpServer = server.httpServer;
+				httpServer?.once("listening", () => {
+					const address = httpServer?.address();
+					const port = tunnelConfig.port ?? (address && typeof address === "object" ? address.port : void 0);
+					if (!port) {
+						console.warn("[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.");
+						return;
+					}
+					import("../tunnel-BbcgVy4L.js").then(async ({ startQuickTunnel, printTunnelBanner }) => {
+						const t = await startQuickTunnel(port);
+						tunnel = t;
+						await printTunnelBanner(t.url, { qr: tunnelConfig.qr });
+					}).catch((err) => {
+						console.warn(`[@ait-co/devtools] tunnel failed to start: ${err instanceof Error ? err.message : String(err)}`);
+					});
+				});
+				const cleanup = () => tunnel?.stop();
+				httpServer?.once("close", cleanup);
+				process.once("SIGINT", cleanup);
+				process.once("SIGTERM", cleanup);
+				process.once("exit", cleanup);
+			}
 		}
 	};
 });

package/dist/unplugin/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../../src/unplugin/index.ts"],"sourcesContent":["/**\n * @ait-co/devtools unplugin\n *\n * 모든 주요 번들러를 지원하는 단일 플러그인.\n * @apps-in-toss/web-framework → @ait-co/devtools/mock 으로 alias 설정.\n *\n * Usage:\n *   import aitDevtools from '@ait-co/devtools/unplugin';\n *\n *   // Vite\n *   export default { plugins: [aitDevtools.vite()] };\n *\n *   // Webpack / Next.js\n *   config.plugins.push(aitDevtools.webpack());\n *\n *   // Rspack\n *   config.plugins.push(aitDevtools.rspack());\n *\n *   // esbuild\n *   { plugins: [aitDevtools.esbuild()] }\n *\n *   // Rollup\n *   { plugins: [aitDevtools.rollup()] }\n */\n\nimport { fileURLToPath } from 'node:url';\nimport { createUnplugin } from 'unplugin';\n\n/**\n * Resolve `@ait-co/devtools/mock` to its real file path at plugin-load time.\n *\n * Returning the bare specifier from `resolveId` would stop the bundler from\n * walking node_modules for it — Vite 8+ treats such a non-null string as the\n * final resolved id and serves it via the virtual `/@id/` prefix, which 404s\n * because we don't provide a `load` hook. Resolving to an absolute path here\n * lets every supported bundler load the file the normal way.\n */\nconst MOCK_PATH = (() => {\n  try {\n    return fileURLToPath(import.meta.resolve('@ait-co/devtools/mock'));\n  } catch {\n    // Fallback for runtimes where `import.meta.resolve` is unavailable.\n    return '@ait-co/devtools/mock';\n  }\n})();\n\nexport interface AitDevtoolsOptions {\n  /**\n   * 패널 자동 주입 여부 (default: true)\n   * true이면 진입점에 floating panel import를 자동 추가한다.\n   */\n  panel?: boolean;\n  /**\n   * production 환경에서도 devtools를 강제로 활성화 (default: false)\n   */\n  forceEnable?: boolean;\n  /**\n   * mock alias 활성화 여부. default: true (development), false (production + forceEnable)\n   */\n  mock?: boolean;\n}\n\nconst FRAMEWORK_ID = '@apps-in-toss/web-framework';\nconst BRIDGE_ID = '@apps-in-toss/web-bridge';\nconst ANALYTICS_ID = '@apps-in-toss/web-analytics';\n\nconst aitDevtoolsPlugin = createUnplugin((options?: AitDevtoolsOptions) => {\n  const isDev = process.env.NODE_ENV !== 'production';\n  const shouldEnable = isDev || (options?.forceEnable ?? false);\n  const shouldMock = shouldEnable && (options?.mock ?? isDev);\n  const shouldPanel = shouldEnable && (options?.panel ?? true);\n\n  return {\n    name: 'ait-co-devtools',\n    enforce: 'pre' as const,\n\n    resolveId(id: string) {\n      if (!shouldMock) return null;\n      // @apps-in-toss/web-framework → @ait-co/devtools/mock (absolute path)\n      if (id === FRAMEWORK_ID || id === BRIDGE_ID || id === ANALYTICS_ID) {\n        return MOCK_PATH;\n      }\n      return null;\n    },\n\n    transformInclude(id: string) {\n      if (!shouldPanel) return false;\n      // 진입점 파일에만 패널 import를 주입\n      return (\n        /\\.(tsx?|jsx?)$/.test(id) &&\n        /\\/(main|index|entry|app)\\.[tj]sx?$/i.test(id) &&\n        !id.includes('node_modules')\n      );\n    },\n\n    transform(code: string) {\n      // transformInclude가 이미 shouldPanel을 확인하지만, 안전망으로 유지\n      if (!shouldPanel) return null;\n      // 이미 패널이 import 되어있으면 스킵\n      if (code.includes('@ait-co/devtools/panel')) return null;\n      // transformInclude가 진입점 파일만 통과시키므로 바로 prepend\n      return `import '@ait-co/devtools/panel';\\n${code}`;\n    },\n  };\n});\n\nexport const vite = aitDevtoolsPlugin.vite;\nexport const webpack = aitDevtoolsPlugin.webpack;\nexport const rollup = aitDevtoolsPlugin.rollup;\nexport const esbuild = aitDevtoolsPlugin.esbuild;\nexport const rspack = aitDevtoolsPlugin.rspack;\n\nexport default aitDevtoolsPlugin;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,MAAM,mBAAmB;AACvB,KAAI;AACF,SAAO,cAAc,OAAO,KAAK,QAAQ,wBAAwB,CAAC;SAC5D;AAEN,SAAO;;IAEP;AAkBJ,MAAM,eAAe;AACrB,MAAM,YAAY;AAClB,MAAM,eAAe;AAErB,MAAM,oBAAoB,gBAAgB,YAAiC;CACzE,MAAM,QAAQ,QAAQ,IAAI,aAAa;CACvC,MAAM,eAAe,UAAU,SAAS,eAAe;CACvD,MAAM,aAAa,iBAAiB,SAAS,QAAQ;CACrD,MAAM,cAAc,iBAAiB,SAAS,SAAS;AAEvD,QAAO;EACL,MAAM;EACN,SAAS;EAET,UAAU,IAAY;AACpB,OAAI,CAAC,WAAY,QAAO;AAExB,OAAI,OAAO,gBAAgB,OAAO,aAAa,OAAO,aACpD,QAAO;AAET,UAAO;;EAGT,iBAAiB,IAAY;AAC3B,OAAI,CAAC,YAAa,QAAO;AAEzB,UACE,iBAAiB,KAAK,GAAG,IACzB,sCAAsC,KAAK,GAAG,IAC9C,CAAC,GAAG,SAAS,eAAe;;EAIhC,UAAU,MAAc;AAEtB,OAAI,CAAC,YAAa,QAAO;AAEzB,OAAI,KAAK,SAAS,yBAAyB,CAAE,QAAO;AAEpD,UAAO,qCAAqC;;EAE/C;EACD;AAEF,MAAa,OAAO,kBAAkB;AACtC,MAAa,UAAU,kBAAkB;AACzC,MAAa,SAAS,kBAAkB;AACxC,MAAa,UAAU,kBAAkB;AACzC,MAAa,SAAS,kBAAkB"}
+{"version":3,"file":"index.js","names":[],"sources":["../../src/unplugin/index.ts"],"sourcesContent":["/**\n * @ait-co/devtools unplugin\n *\n * 모든 주요 번들러를 지원하는 단일 플러그인.\n * @apps-in-toss/web-framework → @ait-co/devtools/mock 으로 alias 설정.\n *\n * Usage:\n *   import aitDevtools from '@ait-co/devtools/unplugin';\n *\n *   // Vite\n *   export default { plugins: [aitDevtools.vite()] };\n *\n *   // Webpack / Next.js\n *   config.plugins.push(aitDevtools.webpack());\n *\n *   // Rspack\n *   config.plugins.push(aitDevtools.rspack());\n *\n *   // esbuild\n *   { plugins: [aitDevtools.esbuild()] }\n *\n *   // Rollup\n *   { plugins: [aitDevtools.rollup()] }\n */\n\nimport { fileURLToPath } from 'node:url';\nimport { createUnplugin } from 'unplugin';\n\n/**\n * Resolve `@ait-co/devtools/mock` to its real file path at plugin-load time.\n *\n * Returning the bare specifier from `resolveId` would stop the bundler from\n * walking node_modules for it — Vite 8+ treats such a non-null string as the\n * final resolved id and serves it via the virtual `/@id/` prefix, which 404s\n * because we don't provide a `load` hook. Resolving to an absolute path here\n * lets every supported bundler load the file the normal way.\n */\nconst MOCK_PATH = (() => {\n  try {\n    return fileURLToPath(import.meta.resolve('@ait-co/devtools/mock'));\n  } catch {\n    // Fallback for runtimes where `import.meta.resolve` is unavailable.\n    return '@ait-co/devtools/mock';\n  }\n})();\n\nexport interface AitDevtoolsOptions {\n  /**\n   * 패널 자동 주입 여부 (default: true)\n   * true이면 진입점에 floating panel import를 자동 추가한다.\n   */\n  panel?: boolean;\n  /**\n   * production 환경에서도 devtools를 강제로 활성화 (default: false)\n   */\n  forceEnable?: boolean;\n  /**\n   * mock alias 활성화 여부. default: true (development), false (production + forceEnable)\n   */\n  mock?: boolean;\n  /**\n   * Vite dev 서버를 Cloudflare quick tunnel(`*.trycloudflare.com`, 계정 불필요)로\n   * 외부 노출해 실제 폰에서 미리보기. **Vite dev 모드 전용** — production은\n   * `forceEnable`이어도 터널을 띄우지 않는다 (의도치 않은 노출 방지). 다른 번들러는\n   * 무시. `true`면 기본 동작, 객체로 세부 설정 가능.\n   */\n  tunnel?:\n    | boolean\n    | {\n        /** 노출할 포트 (미지정 시 dev 서버가 실제 listen한 포트 자동 감지). */\n        port?: number;\n        /** 터미널 ASCII QR 출력 (default: true). */\n        qr?: boolean;\n      };\n}\n\nconst FRAMEWORK_ID = '@apps-in-toss/web-framework';\nconst BRIDGE_ID = '@apps-in-toss/web-bridge';\nconst ANALYTICS_ID = '@apps-in-toss/web-analytics';\n\nconst aitDevtoolsPlugin = createUnplugin((options?: AitDevtoolsOptions) => {\n  const isDev = process.env.NODE_ENV !== 'production';\n  const shouldEnable = isDev || (options?.forceEnable ?? false);\n  const shouldMock = shouldEnable && (options?.mock ?? isDev);\n  const shouldPanel = shouldEnable && (options?.panel ?? true);\n  // Tunnel is dev-only and Vite-only. Never under production — even with\n  // forceEnable — so a production build can't accidentally expose itself.\n  const tunnelOpt = options?.tunnel;\n  const shouldTunnel = isDev && !!tunnelOpt;\n  const tunnelConfig = typeof tunnelOpt === 'object' ? tunnelOpt : {};\n\n  return {\n    name: 'ait-co-devtools',\n    enforce: 'pre' as const,\n\n    resolveId(id: string) {\n      if (!shouldMock) return null;\n      // @apps-in-toss/web-framework → @ait-co/devtools/mock (absolute path)\n      if (id === FRAMEWORK_ID || id === BRIDGE_ID || id === ANALYTICS_ID) {\n        return MOCK_PATH;\n      }\n      return null;\n    },\n\n    transformInclude(id: string) {\n      if (!shouldPanel) return false;\n      // 진입점 파일에만 패널 import를 주입\n      return (\n        /\\.(tsx?|jsx?)$/.test(id) &&\n        /\\/(main|index|entry|app)\\.[tj]sx?$/i.test(id) &&\n        !id.includes('node_modules')\n      );\n    },\n\n    transform(code: string) {\n      // transformInclude가 이미 shouldPanel을 확인하지만, 안전망으로 유지\n      if (!shouldPanel) return null;\n      // 이미 패널이 import 되어있으면 스킵\n      if (code.includes('@ait-co/devtools/panel')) return null;\n      // transformInclude가 진입점 파일만 통과시키므로 바로 prepend\n      return `import '@ait-co/devtools/panel';\\n${code}`;\n    },\n\n    // Vite-only: start a Cloudflare quick tunnel once the dev server is\n    // listening. unplugin passes this through to Vite's plugin object; other\n    // bundlers ignore it.\n    vite: {\n      config() {\n        if (!shouldTunnel) return;\n        // Vite blocks requests whose Host header isn't in `server.allowedHosts`\n        // (defaults to localhost only). The quick-tunnel hostname is random per\n        // run, so allow the whole `.trycloudflare.com` suffix while the tunnel\n        // is on. (A leading `.` makes Vite match the domain and its subdomains.)\n        return { server: { allowedHosts: ['.trycloudflare.com'] } };\n      },\n\n      configureServer(server: import('vite').ViteDevServer) {\n        if (!shouldTunnel) return;\n        let tunnel: { stop: () => void } | null = null;\n        const httpServer = server.httpServer;\n\n        httpServer?.once('listening', () => {\n          const address = httpServer?.address();\n          const port =\n            tunnelConfig.port ??\n            (address && typeof address === 'object' ? address.port : undefined);\n          if (!port) {\n            console.warn(\n              '[@ait-co/devtools] tunnel: could not determine the dev server port; skipping.',\n            );\n            return;\n          }\n          // Dynamic import keeps `cloudflared` / `qrcode-terminal` off the\n          // module graph unless the tunnel is actually used.\n          import('./tunnel.js')\n            .then(async ({ startQuickTunnel, printTunnelBanner }) => {\n              const t = await startQuickTunnel(port);\n              tunnel = t;\n              await printTunnelBanner(t.url, { qr: tunnelConfig.qr });\n            })\n            .catch((err: unknown) => {\n              console.warn(\n                `[@ait-co/devtools] tunnel failed to start: ${\n                  err instanceof Error ? err.message : String(err)\n                }`,\n              );\n            });\n        });\n\n        const cleanup = () => tunnel?.stop();\n        httpServer?.once('close', cleanup);\n        process.once('SIGINT', cleanup);\n        process.once('SIGTERM', cleanup);\n        process.once('exit', cleanup);\n      },\n    },\n  };\n});\n\nexport const vite = aitDevtoolsPlugin.vite;\nexport const webpack = aitDevtoolsPlugin.webpack;\nexport const rollup = aitDevtoolsPlugin.rollup;\nexport const esbuild = aitDevtoolsPlugin.esbuild;\nexport const rspack = aitDevtoolsPlugin.rspack;\n\nexport default aitDevtoolsPlugin;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,MAAM,mBAAmB;AACvB,KAAI;AACF,SAAO,cAAc,OAAO,KAAK,QAAQ,wBAAwB,CAAC;SAC5D;AAEN,SAAO;;IAEP;AAgCJ,MAAM,eAAe;AACrB,MAAM,YAAY;AAClB,MAAM,eAAe;AAErB,MAAM,oBAAoB,gBAAgB,YAAiC;CACzE,MAAM,QAAQ,QAAQ,IAAI,aAAa;CACvC,MAAM,eAAe,UAAU,SAAS,eAAe;CACvD,MAAM,aAAa,iBAAiB,SAAS,QAAQ;CACrD,MAAM,cAAc,iBAAiB,SAAS,SAAS;CAGvD,MAAM,YAAY,SAAS;CAC3B,MAAM,eAAe,SAAS,CAAC,CAAC;CAChC,MAAM,eAAe,OAAO,cAAc,WAAW,YAAY,EAAE;AAEnE,QAAO;EACL,MAAM;EACN,SAAS;EAET,UAAU,IAAY;AACpB,OAAI,CAAC,WAAY,QAAO;AAExB,OAAI,OAAO,gBAAgB,OAAO,aAAa,OAAO,aACpD,QAAO;AAET,UAAO;;EAGT,iBAAiB,IAAY;AAC3B,OAAI,CAAC,YAAa,QAAO;AAEzB,UACE,iBAAiB,KAAK,GAAG,IACzB,sCAAsC,KAAK,GAAG,IAC9C,CAAC,GAAG,SAAS,eAAe;;EAIhC,UAAU,MAAc;AAEtB,OAAI,CAAC,YAAa,QAAO;AAEzB,OAAI,KAAK,SAAS,yBAAyB,CAAE,QAAO;AAEpD,UAAO,qCAAqC;;EAM9C,MAAM;GACJ,SAAS;AACP,QAAI,CAAC,aAAc;AAKnB,WAAO,EAAE,QAAQ,EAAE,cAAc,CAAC,qBAAqB,EAAE,EAAE;;GAG7D,gBAAgB,QAAsC;AACpD,QAAI,CAAC,aAAc;IACnB,IAAI,SAAsC;IAC1C,MAAM,aAAa,OAAO;AAE1B,gBAAY,KAAK,mBAAmB;KAClC,MAAM,UAAU,YAAY,SAAS;KACrC,MAAM,OACJ,aAAa,SACZ,WAAW,OAAO,YAAY,WAAW,QAAQ,OAAO,KAAA;AAC3D,SAAI,CAAC,MAAM;AACT,cAAQ,KACN,gFACD;AACD;;AAIF,YAAO,yBACJ,KAAK,OAAO,EAAE,kBAAkB,wBAAwB;MACvD,MAAM,IAAI,MAAM,iBAAiB,KAAK;AACtC,eAAS;AACT,YAAM,kBAAkB,EAAE,KAAK,EAAE,IAAI,aAAa,IAAI,CAAC;OACvD,CACD,OAAO,QAAiB;AACvB,cAAQ,KACN,8CACE,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,GAEnD;OACD;MACJ;IAEF,MAAM,gBAAgB,QAAQ,MAAM;AACpC,gBAAY,KAAK,SAAS,QAAQ;AAClC,YAAQ,KAAK,UAAU,QAAQ;AAC/B,YAAQ,KAAK,WAAW,QAAQ;AAChC,YAAQ,KAAK,QAAQ,QAAQ;;GAEhC;EACF;EACD;AAEF,MAAa,OAAO,kBAAkB;AACtC,MAAa,UAAU,kBAAkB;AACzC,MAAa,SAAS,kBAAkB;AACxC,MAAa,UAAU,kBAAkB;AACzC,MAAa,SAAS,kBAAkB"}

package/dist/unplugin/tunnel.cjs

@@ -0,0 +1,117 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_fs = require("node:fs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+//#region src/unplugin/tunnel.ts
+/**
+* Cloudflare quick-tunnel helper for the devtools unplugin.
+*
+* Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+* on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+* case. This is the one place in `@ait-co/devtools` that depends on Node-only
+* APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+* jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+* "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+* (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+*/
+/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */
+const TRYCLOUDFLARE_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+/**
+* Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+* output, or `null` if the line doesn't contain one. Pulled out as a pure
+* function so it can be unit-tested without spawning anything.
+*/
+function parseTrycloudflareUrl(line) {
+	const m = line.match(TRYCLOUDFLARE_RE);
+	return m ? m[0] : null;
+}
+const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
+/**
+* Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+* QR encoding it, and a one-line note that quick tunnels are ephemeral,
+* unauthenticated and not for production. Pure w.r.t. side effects other than
+* the injected `log` sink and `qrcode-terminal` — unit-tested.
+*/
+async function printTunnelBanner(url, opts = {}) {
+	const log = opts.log ?? ((m) => console.log(m));
+	log([
+		"",
+		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
+		`  │  ${url}`,
+		"  │",
+		`  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,
+		"  │  Scan the QR below from there (or paste the URL).",
+		"  │  Quick tunnels are unauthenticated, change every run, and are",
+		"  │  not for production use.",
+		"  └──────────────────────────────────────────────────────────────",
+		""
+	].join("\n"));
+	if (opts.qr !== false) {
+		const qrcode = (await import("qrcode-terminal")).default;
+		await new Promise((resolve) => {
+			qrcode.generate(url, { small: true }, (out) => {
+				log(out);
+				resolve();
+			});
+		});
+	}
+}
+const URL_TIMEOUT_MS = 2e4;
+/**
+* Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+* and resolve once the public URL is known. Downloads the `cloudflared` binary
+* on first use if it is not already installed. Rejects with a friendly error if
+* no URL appears within {@link URL_TIMEOUT_MS}.
+*/
+async function startQuickTunnel(port) {
+	const { bin, install, Tunnel } = await import("cloudflared");
+	if (!(0, node_fs.existsSync)(bin)) {
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(bin), { recursive: true });
+		await install(bin);
+	}
+	const tunnel = Tunnel.quick(`http://localhost:${port}`);
+	let stopped = false;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		try {
+			tunnel.stop();
+		} catch {}
+	};
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			stop();
+			reject(/* @__PURE__ */ new Error(`[@ait-co/devtools] cloudflared did not report a tunnel URL within ${URL_TIMEOUT_MS / 1e3}s. Check your network connection, or run \`cloudflared tunnel --url http://localhost:${port}\` manually.`));
+		}, URL_TIMEOUT_MS);
+		const onUrl = (line) => {
+			const found = parseTrycloudflareUrl(line);
+			if (!found) return;
+			clearTimeout(timer);
+			tunnel.off("stdout", onUrl);
+			tunnel.off("stderr", onUrl);
+			resolve({
+				url: found,
+				stop
+			});
+		};
+		tunnel.once("url", onUrl);
+		tunnel.on("stdout", onUrl);
+		tunnel.on("stderr", onUrl);
+		tunnel.once("error", (err) => {
+			clearTimeout(timer);
+			stop();
+			reject(err);
+		});
+		tunnel.once("exit", (code) => {
+			if (stopped) return;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`[@ait-co/devtools] cloudflared exited (code ${code ?? "null"}) before reporting a tunnel URL.`));
+		});
+	});
+}
+//#endregion
+exports.parseTrycloudflareUrl = parseTrycloudflareUrl;
+exports.printTunnelBanner = printTunnelBanner;
+exports.startQuickTunnel = startQuickTunnel;
+
+//# sourceMappingURL=tunnel.cjs.map

package/dist/unplugin/tunnel.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.cjs","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\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding it, and a one-line note that quick tunnels are ephemeral,\n * unauthenticated and not for production. Pure w.r.t. side effects other than\n * 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 lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,\n    '  │  Scan the QR below from there (or paste the URL).',\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(url, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\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\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    const timer = setTimeout(() => {\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.`,\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      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\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    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;AAQrB,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;AAatD,KAZwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,0CAA0C;EAC1C;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,KAAK,EAAE,OAAO,MAAM,GAAG,QAAQ;AAC7C,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,EAAA,GAAA,QAAA,YAAY,IAAI,EAAE;AACpB,SAAA,GAAA,iBAAA,QAAA,GAAA,UAAA,SAAoB,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/dist/unplugin/tunnel.d.cts

@@ -0,0 +1,47 @@
+//#region src/unplugin/tunnel.d.ts
+/**
+ * Cloudflare quick-tunnel helper for the devtools unplugin.
+ *
+ * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+ * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+ * case. This is the one place in `@ait-co/devtools` that depends on Node-only
+ * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+ * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+ * "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+ * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+ */
+/**
+ * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+ * output, or `null` if the line doesn't contain one. Pulled out as a pure
+ * function so it can be unit-tested without spawning anything.
+ */
+declare function parseTrycloudflareUrl(line: string): string | null;
+interface PrintTunnelBannerOptions {
+  /** Print an ASCII QR encoding the tunnel URL (default: true). */
+  qr?: boolean;
+  /** Sink for the banner text (default: `console.log`). Injected for testing. */
+  log?: (msg: string) => void;
+}
+/**
+ * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+ * QR encoding it, and a one-line note that quick tunnels are ephemeral,
+ * unauthenticated and not for production. Pure w.r.t. side effects other than
+ * the injected `log` sink and `qrcode-terminal` — unit-tested.
+ */
+declare function printTunnelBanner(url: string, opts?: PrintTunnelBannerOptions): Promise<void>;
+interface QuickTunnel {
+  /** The public `https://*.trycloudflare.com` URL. */
+  url: string;
+  /** Stop the underlying `cloudflared` process. Idempotent. */
+  stop: () => void;
+}
+/**
+ * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+ * and resolve once the public URL is known. Downloads the `cloudflared` binary
+ * on first use if it is not already installed. Rejects with a friendly error if
+ * no URL appears within {@link URL_TIMEOUT_MS}.
+ */
+declare function startQuickTunnel(port: number): Promise<QuickTunnel>;
+//#endregion
+export { PrintTunnelBannerOptions, QuickTunnel, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
+//# sourceMappingURL=tunnel.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.cts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;AAeA;iBApBgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAkBP;EAhBR,EAAA;EAeM;EAbN,GAAA,IAAO,GAAA;AAAA;;;AA2CT;;;;iBAhCsB,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UA6Bc,WAAA;EAeqB;EAbpC,GAAA;EAa2D;EAX3D,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.d.ts

@@ -0,0 +1,47 @@
+//#region src/unplugin/tunnel.d.ts
+/**
+ * Cloudflare quick-tunnel helper for the devtools unplugin.
+ *
+ * Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+ * on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+ * case. This is the one place in `@ait-co/devtools` that depends on Node-only
+ * APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+ * jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+ * "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+ * (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+ */
+/**
+ * Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+ * output, or `null` if the line doesn't contain one. Pulled out as a pure
+ * function so it can be unit-tested without spawning anything.
+ */
+declare function parseTrycloudflareUrl(line: string): string | null;
+interface PrintTunnelBannerOptions {
+  /** Print an ASCII QR encoding the tunnel URL (default: true). */
+  qr?: boolean;
+  /** Sink for the banner text (default: `console.log`). Injected for testing. */
+  log?: (msg: string) => void;
+}
+/**
+ * Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+ * QR encoding it, and a one-line note that quick tunnels are ephemeral,
+ * unauthenticated and not for production. Pure w.r.t. side effects other than
+ * the injected `log` sink and `qrcode-terminal` — unit-tested.
+ */
+declare function printTunnelBanner(url: string, opts?: PrintTunnelBannerOptions): Promise<void>;
+interface QuickTunnel {
+  /** The public `https://*.trycloudflare.com` URL. */
+  url: string;
+  /** Stop the underlying `cloudflared` process. Idempotent. */
+  stop: () => void;
+}
+/**
+ * Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+ * and resolve once the public URL is known. Downloads the `cloudflared` binary
+ * on first use if it is not already installed. Rejects with a friendly error if
+ * no URL appears within {@link URL_TIMEOUT_MS}.
+ */
+declare function startQuickTunnel(port: number): Promise<QuickTunnel>;
+//#endregion
+export { PrintTunnelBannerOptions, QuickTunnel, parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
+//# sourceMappingURL=tunnel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel.d.ts","names":[],"sources":["../../src/unplugin/tunnel.ts"],"mappings":";;AAwBA;;;;;AAKA;;;;;;;;;AAeA;iBApBgB,qBAAA,CAAsB,IAAA;AAAA,UAKrB,wBAAA;EAkBP;EAhBR,EAAA;EAeM;EAbN,GAAA,IAAO,GAAA;AAAA;;;AA2CT;;;;iBAhCsB,iBAAA,CACpB,GAAA,UACA,IAAA,GAAM,wBAAA,GACL,OAAA;AAAA,UA6Bc,WAAA;EAeqB;EAbpC,GAAA;EAa2D;EAX3D,IAAA;AAAA;;;;;;;iBAWoB,gBAAA,CAAiB,IAAA,WAAe,OAAA,CAAQ,WAAA"}

package/dist/unplugin/tunnel.js

@@ -0,0 +1,114 @@
+import { existsSync } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+//#region src/unplugin/tunnel.ts
+/**
+* Cloudflare quick-tunnel helper for the devtools unplugin.
+*
+* Loaded lazily (`await import('./tunnel.js')`) only when the `tunnel` option is
+* on, so `cloudflared` / `qrcode-terminal` are never pulled in for the common
+* case. This is the one place in `@ait-co/devtools` that depends on Node-only
+* APIs (`child_process` via the `cloudflared` wrapper) — keep it thin and out of
+* jsdom unit tests; the spawn path is verified by hand / e2e (same spirit as the
+* "web 모드는 e2e" rule in CLAUDE.md). The pure helpers below
+* (`parseTrycloudflareUrl`, `printTunnelBanner`) are unit-tested.
+*/
+/** Matches the public URL cloudflared prints for an unauthenticated quick tunnel. */
+const TRYCLOUDFLARE_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/i;
+/**
+* Extract the `https://<sub>.trycloudflare.com` URL from a line of cloudflared
+* output, or `null` if the line doesn't contain one. Pulled out as a pure
+* function so it can be unit-tested without spawning anything.
+*/
+function parseTrycloudflareUrl(line) {
+	const m = line.match(TRYCLOUDFLARE_RE);
+	return m ? m[0] : null;
+}
+const LAUNCHER_URL = "https://devtools.aitc.dev/launcher/";
+/**
+* Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+* QR encoding it, and a one-line note that quick tunnels are ephemeral,
+* unauthenticated and not for production. Pure w.r.t. side effects other than
+* the injected `log` sink and `qrcode-terminal` — unit-tested.
+*/
+async function printTunnelBanner(url, opts = {}) {
+	const log = opts.log ?? ((m) => console.log(m));
+	log([
+		"",
+		"  ┌─ @ait-co/devtools · live tunnel ────────────────────────────",
+		`  │  ${url}`,
+		"  │",
+		`  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,
+		"  │  Scan the QR below from there (or paste the URL).",
+		"  │  Quick tunnels are unauthenticated, change every run, and are",
+		"  │  not for production use.",
+		"  └──────────────────────────────────────────────────────────────",
+		""
+	].join("\n"));
+	if (opts.qr !== false) {
+		const qrcode = (await import("qrcode-terminal")).default;
+		await new Promise((resolve) => {
+			qrcode.generate(url, { small: true }, (out) => {
+				log(out);
+				resolve();
+			});
+		});
+	}
+}
+const URL_TIMEOUT_MS = 2e4;
+/**
+* Start an unauthenticated Cloudflare quick tunnel to `http://localhost:<port>`
+* and resolve once the public URL is known. Downloads the `cloudflared` binary
+* on first use if it is not already installed. Rejects with a friendly error if
+* no URL appears within {@link URL_TIMEOUT_MS}.
+*/
+async function startQuickTunnel(port) {
+	const { bin, install, Tunnel } = await import("cloudflared");
+	if (!existsSync(bin)) {
+		await mkdir(dirname(bin), { recursive: true });
+		await install(bin);
+	}
+	const tunnel = Tunnel.quick(`http://localhost:${port}`);
+	let stopped = false;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		try {
+			tunnel.stop();
+		} catch {}
+	};
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			stop();
+			reject(/* @__PURE__ */ new Error(`[@ait-co/devtools] cloudflared did not report a tunnel URL within ${URL_TIMEOUT_MS / 1e3}s. Check your network connection, or run \`cloudflared tunnel --url http://localhost:${port}\` manually.`));
+		}, URL_TIMEOUT_MS);
+		const onUrl = (line) => {
+			const found = parseTrycloudflareUrl(line);
+			if (!found) return;
+			clearTimeout(timer);
+			tunnel.off("stdout", onUrl);
+			tunnel.off("stderr", onUrl);
+			resolve({
+				url: found,
+				stop
+			});
+		};
+		tunnel.once("url", onUrl);
+		tunnel.on("stdout", onUrl);
+		tunnel.on("stderr", onUrl);
+		tunnel.once("error", (err) => {
+			clearTimeout(timer);
+			stop();
+			reject(err);
+		});
+		tunnel.once("exit", (code) => {
+			if (stopped) return;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error(`[@ait-co/devtools] cloudflared exited (code ${code ?? "null"}) before reporting a tunnel URL.`));
+		});
+	});
+}
+//#endregion
+export { parseTrycloudflareUrl, printTunnelBanner, startQuickTunnel };
+
+//# sourceMappingURL=tunnel.js.map

package/dist/unplugin/tunnel.js.map

@@ -0,0 +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\nconst LAUNCHER_URL = 'https://devtools.aitc.dev/launcher/';\n\n/**\n * Print the terminal banner announcing the live tunnel: the public URL, an ASCII\n * QR encoding it, and a one-line note that quick tunnels are ephemeral,\n * unauthenticated and not for production. Pure w.r.t. side effects other than\n * 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 lines: string[] = [\n    '',\n    '  ┌─ @ait-co/devtools · live tunnel ────────────────────────────',\n    `  │  ${url}`,\n    '  │',\n    `  │  Open the launcher on your phone:  ${LAUNCHER_URL}`,\n    '  │  Scan the QR below from there (or paste the URL).',\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(url, { small: true }, (out) => {\n        log(out);\n        resolve();\n      });\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\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    const timer = setTimeout(() => {\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.`,\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      tunnel.off('stdout', onUrl);\n      tunnel.off('stderr', onUrl);\n      resolve({ url: found, stop });\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    tunnel.once('error', (err: Error) => {\n      clearTimeout(timer);\n      stop();\n      reject(err);\n    });\n    tunnel.once('exit', (code: number | null) => {\n      if (stopped) return;\n      clearTimeout(timer);\n      reject(\n        new Error(\n          `[@ait-co/devtools] cloudflared exited (code ${code ?? 'null'}) before reporting a tunnel URL.`,\n        ),\n      );\n    });\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,mBAAmB;;;;;;AAOzB,SAAgB,sBAAsB,MAA6B;CACjE,MAAM,IAAI,KAAK,MAAM,iBAAiB;AACtC,QAAO,IAAI,EAAE,KAAK;;AAUpB,MAAM,eAAe;;;;;;;AAQrB,eAAsB,kBACpB,KACA,OAAiC,EAAE,EACpB;CACf,MAAM,MAAM,KAAK,SAAS,MAAc,QAAQ,IAAI,EAAE;AAatD,KAZwB;EACtB;EACA;EACA,QAAQ;EACR;EACA,0CAA0C;EAC1C;EACA;EACA;EACA;EACA;EACD,CACS,KAAK,KAAK,CAAC;AAErB,KAAI,KAAK,OAAO,OAAO;EAGrB,MAAM,UAAU,MAAM,OAAO,oBAAoB;AACjD,QAAM,IAAI,SAAe,YAAY;AACnC,UAAO,SAAS,KAAK,EAAE,OAAO,MAAM,GAAG,QAAQ;AAC7C,QAAI,IAAI;AACR,aAAS;KACT;IACF;;;AAWN,MAAM,iBAAiB;;;;;;;AAQvB,eAAsB,iBAAiB,MAAoC;CAEzE,MAAM,EAAE,KAAK,SAAS,WADF,MAAM,OAAO;AAGjC,KAAI,CAAC,WAAW,IAAI,EAAE;AACpB,QAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAC9C,QAAM,QAAQ,IAAI;;CAGpB,MAAM,SAAS,OAAO,MAAM,oBAAoB,OAAO;CACvD,IAAI,UAAU;CACd,MAAM,aAAa;AACjB,MAAI,QAAS;AACb,YAAU;AACV,MAAI;AACF,UAAO,MAAM;UACP;;AAKV,QAAO,IAAI,SAAsB,SAAS,WAAW;EACnD,MAAM,QAAQ,iBAAiB;AAC7B,SAAM;AACN,0BACE,IAAI,MACF,qEACE,iBAAiB,IAClB,uFAAuF,KAAK,cAC9F,CACF;KACA,eAAe;EAElB,MAAM,SAAS,SAAiB;GAC9B,MAAM,QAAQ,sBAAsB,KAAK;AACzC,OAAI,CAAC,MAAO;AACZ,gBAAa,MAAM;AAEnB,UAAO,IAAI,UAAU,MAAM;AAC3B,UAAO,IAAI,UAAU,MAAM;AAC3B,WAAQ;IAAE,KAAK;IAAO;IAAM,CAAC;;AAK/B,SAAO,KAAK,OAAO,MAAM;AACzB,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,GAAG,UAAU,MAAM;AAC1B,SAAO,KAAK,UAAU,QAAe;AACnC,gBAAa,MAAM;AACnB,SAAM;AACN,UAAO,IAAI;IACX;AACF,SAAO,KAAK,SAAS,SAAwB;AAC3C,OAAI,QAAS;AACb,gBAAa,MAAM;AACnB,0BACE,IAAI,MACF,+CAA+C,QAAQ,OAAO,kCAC/D,CACF;IACD;GACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ait-co/devtools",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Development tools for Apps in Toss mini-apps — mock SDK, floating devtools panel, and universal bundler plugin",
   "type": "module",
   "engines": {
@@ -39,6 +39,8 @@
     }
   },
   "dependencies": {
+    "cloudflared": "^0.7.1",
+    "qrcode-terminal": "^0.12.0",
     "unplugin": "^3.0.0"
   },
   "devDependencies": {
@@ -48,6 +50,7 @@
     "@playwright/test": "^1.59.1",
     "@types/react": "^19.2.14",
     "jsdom": "^29.1.1",
+    "qr-scanner": "^1.4.2",
     "react": "^19.2.5",
     "satori": "^0.26.0",
     "sharp": "^0.34.5",
@@ -63,7 +66,12 @@
     "mini-app",
     "devtools",
     "mock",
-    "sdk"
+    "sdk",
+    "miniapp",
+    "simulator",
+    "testing",
+    "vite-plugin",
+    "webpack-plugin"
   ],
   "license": "BSD-3-Clause",
   "publishConfig": {
@@ -73,7 +81,7 @@
     "type": "git",
     "url": "https://github.com/apps-in-toss-community/devtools"
   },
-  "homepage": "https://www.npmjs.com/package/@ait-co/devtools",
+  "homepage": "https://devtools.aitc.dev/",
   "bugs": {
     "url": "https://github.com/apps-in-toss-community/devtools/issues"
   },