@apps-in-toss/devtools 3.0.5 → 3.1.0-beta.1

package/dist/unplugin/tunnel.js

@@ -0,0 +1,186 @@
+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 `@apps-in-toss/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/";
+/**
+* Build the deep-link URL that QR codes encode: when the launcher PWA is
+* already on the phone's home screen, scanning this opens it directly into the
+* live view for `tunnelUrl` (the launcher consumes `?url=` and clears it).
+* Plain-text raw URL is no longer enough — the launcher gates its setup UI to
+* the installed PWA, so a raw tunnel URL opened in a normal browser tab would
+* land on a "please install" screen.
+*
+* When `opts.name` is given (non-blank), it is added as `&name=` so the launcher
+* partner bar shows the app name instead of the generic default (#498).
+*
+* When `opts.webViewType` is `'game'`, `&navBarType=game` is appended so the
+* launcher enters game nav chrome (floating capsule, no full bar) automatically
+* on scan. `'partner'` is the launcher's implicit default and is not added to
+* keep the URL clean (#584).
+*
+* When `opts.navBarTransparent` is `true`, `&navBarTransparent=1` is appended
+* so the launcher partner bar renders with a transparent background (#587).
+*
+* When `opts.navBarTheme` is `'light'` or `'dark'`, `&navBarTheme=<v>` is
+* appended so the launcher partner bar uses the matching foreground colour (#587).
+*/
+function buildLauncherDeepLink(tunnelUrl, optsParam) {
+	const opts = optsParam ?? {};
+	let url = `${LAUNCHER_URL}?url=${encodeURIComponent(tunnelUrl)}`;
+	if (opts.name !== void 0 && opts.name.trim() !== "") url += `&name=${encodeURIComponent(opts.name.trim())}`;
+	if (opts.webViewType === "game") url += "&navBarType=game";
+	if (opts.navBarTransparent === true) url += "&navBarTransparent=1";
+	if (opts.navBarTheme === "light" || opts.navBarTheme === "dark") url += `&navBarTheme=${opts.navBarTheme}`;
+	return url;
+}
+/**
+* Print the terminal banner announcing the live tunnel: the public URL, an ASCII
+* QR encoding a launcher deep-link, 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));
+	const deepLink = buildLauncherDeepLink(url, {
+		name: opts.name,
+		webViewType: opts.webViewType,
+		navBarTransparent: opts.navBarTransparent,
+		navBarTheme: opts.navBarTheme
+	});
+	log([
+		"",
+		"  ┌─ @apps-in-toss/devtools · live tunnel ────────────────────────────",
+		`  │  ${url}`,
+		"  │",
+		`  │  Install the launcher PWA once:  ${LAUNCHER_URL}`,
+		"  │  Then scan the QR below — it opens the launcher directly",
+		"  │  into this tunnel URL (no manual paste needed).",
+		"  │  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(deepLink, { small: true }, (out) => {
+				log(out);
+				resolve();
+			});
+		});
+	}
+}
+/**
+* Sanitize cloudflared stderr output for error diagnostics (#421).
+*
+* Masks `*.trycloudflare.com` hostnames and full `https://` / `wss://` URLs
+* that carry those hostnames so tunnel host values never appear in error
+* messages. Diagnostic content (error codes, reasons, JSON blobs) is preserved.
+*
+* SECRET-HANDLING: tunnel host is SECRET-class per harness policy — only
+* placeholder text is emitted.
+*/
+function sanitizeCloudflaredOutput(line) {
+	let s = line.replace(/(?:https?|wss?):\/\/[a-z0-9-]+\.trycloudflare\.com(?:\/[^\s]*)*/gi, (m) => m.replace(/[a-z0-9-]+\.trycloudflare\.com/i, "<HOST>.trycloudflare.com"));
+	s = s.replace(/[a-z0-9-]+\.trycloudflare\.com/gi, "<HOST>.trycloudflare.com");
+	return s;
+}
+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 stderrLines = [];
+		/**
+		* Format the last `n` sanitized stderr lines as a diagnostic appendix.
+		* Returns an empty string when no lines have been collected.
+		*/
+		const stderrTail = (n = 15) => {
+			if (stderrLines.length === 0) return "";
+			const tail = stderrLines.slice(-n).map(sanitizeCloudflaredOutput).join("");
+			return `\ncloudflared 출력 (마지막 ${Math.min(n, stderrLines.length)}줄):\n${tail}`;
+		};
+		const timer = setTimeout(() => {
+			cleanup();
+			stop();
+			reject(/* @__PURE__ */ new Error(`[@apps-in-toss/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.${stderrTail()}`));
+		}, URL_TIMEOUT_MS);
+		const onUrl = (line) => {
+			const found = parseTrycloudflareUrl(line);
+			if (!found) return;
+			clearTimeout(timer);
+			cleanup();
+			resolve({
+				url: found,
+				stop
+			});
+		};
+		const pushStderr = (line) => {
+			stderrLines.push(line);
+		};
+		const cleanup = () => {
+			tunnel.off("stdout", onUrl);
+			tunnel.off("stderr", onUrl);
+			tunnel.off("stderr", pushStderr);
+		};
+		tunnel.once("url", onUrl);
+		tunnel.on("stdout", onUrl);
+		tunnel.on("stderr", onUrl);
+		tunnel.on("stderr", pushStderr);
+		tunnel.once("error", (err) => {
+			clearTimeout(timer);
+			cleanup();
+			stop();
+			reject(err);
+		});
+		tunnel.once("exit", (code) => {
+			if (stopped) return;
+			clearTimeout(timer);
+			cleanup();
+			reject(/* @__PURE__ */ new Error(`[@apps-in-toss/devtools] cloudflared exited (code ${code ?? "null"}) before reporting a tunnel URL.${stderrTail()}`));
+		});
+	});
+}
+//#endregion
+export { buildLauncherDeepLink, parseTrycloudflareUrl, printTunnelBanner, sanitizeCloudflaredOutput, startQuickTunnel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apps-in-toss/devtools",
-  "version": "3.0.5",
+  "version": "3.1.0-beta.1",
   "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",
   "keywords": [
     "apps-in-toss",
@@ -15,7 +15,7 @@
     "vite-plugin",
     "webpack-plugin"
   ],
-  "license": "Apache-2.0",
+  "license": "BSD-3-Clause",
   "files": [
     "dist"
   ],
@@ -64,14 +64,17 @@
     "check:footprint-absent": "bash scripts/check-devtools-footprint-absent.sh"
   },
   "dependencies": {
+    "cloudflared": "^0.7.1",
+    "qrcode-terminal": "^0.12.0",
     "unplugin": "^3.2.0"
   },
   "devDependencies": {
-    "@apps-in-toss/web-framework": "^3.0.5",
+    "@apps-in-toss/web-framework": "^3.1.0-beta.1",
     "@apps-in-toss/web-framework-2x": "npm:@apps-in-toss/web-framework@2.10.8",
     "@testing-library/dom": "10.4.1",
     "@testing-library/react": "16.3.2",
     "@types/node": "~24.13.3",
+    "@types/qrcode-terminal": "0.12.2",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
     "jsdom": "29.1.1",
@@ -84,7 +87,7 @@
     "vitest": "4.1.9"
   },
   "peerDependencies": {
-    "@apps-in-toss/web-framework": ">=2.6.0 <3.0.0 || >=3.0.1 <4.0.0"
+    "@apps-in-toss/web-framework": ">=3.1.0-beta.0"
   },
   "peerDependenciesMeta": {
     "@apps-in-toss/web-framework": {
@@ -94,4 +97,4 @@
   "engines": {
     "node": ">=24"
   }
-}
+}

package/CHANGELOG.md

@@ -1,32 +0,0 @@
-# @apps-in-toss/devtools
-
-## 3.0.5
-
-## 3.0.4
-
-### Patch Changes
-
-- 6e935ed: - webView.pullToRefreshEnabled 기본값을 false로 변경해요.
-  - ait --help를 개선해요 (ko/en, --version, 컬러/라우팅 정리).
-  - 빌드 시 appName·brand·webBundle validation을 추가해요.
-  - 라이선스를 Apache-2.0으로 변경해요.
-- 006f22a: feat: mock 커스터마이즈 수단과 충실도를 개선해요.
-
-  - unplugin에 `initialState` 옵션을 추가해요 — 번들러 설정에서 초기 mock 상태(IAP 상품 카탈로그 등)를 선언적으로 구성할 수 있어요. 객체는 재귀 병합되고 배열은 통째로 교체돼요.
-  - README에만 있던 `forceEnable`을 실제로 구현하고, 비표준 엔트리 파일명에서도 패널을 주입할 수 있는 `entryPattern` 옵션을 추가해요.
-  - 기본 IAP mock 카탈로그에 SUBSCRIPTION 상품(`mock-sub-monthly`)을 추가해요 — 상품 목록 조회만으로 구독 결제 플로우를 테스트할 수 있어요.
-  - Floating Panel IAP 탭에 상품 카탈로그 추가/편집 UI를 추가해요.
-  - `setScreenAwakeMode`가 Screen Wake Lock API를 지원하는 브라우저에서 실제로 화면 꺼짐 방지를 적용해요(미지원·거부 시 기존 동작 유지).
-  - `partner.addAccessoryButton`이 placeholder 버튼을 렌더하고, 탭하면 `tdsEvent.navigationAccessoryEvent`로 `{ id }`를 전달해요.
-
-## 3.0.3
-
-## 3.0.2
-
-### Patch Changes
-
-- 5519b6f: feat: `@apps-in-toss/devtools` 패키지를 추가해요 — 브라우저에서 미니앱을 개발할 수 있는 mock SDK, devtools 패널, 번들러 unplugin(vite/webpack/rspack/rollup/esbuild)을 제공해요. `ait init`과 `ait migrate v3`가 devtools를 devDependencies에 추가하고, 번들러 설정의 plugins 맨 앞에 unplugin을 자동으로 꽂은 뒤 의존성 설치까지 실행해요.
-- Updated dependencies [5519b6f]
-- Updated dependencies [c50c421]
-- Updated dependencies [c50c421]
-  - @apps-in-toss/web-framework@3.0.2