@ait-co/devtools 0.1.74 → 0.1.76

package/dist/mcp/cli.js

@@ -1169,9 +1169,8 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 * Chii serves its own DevTools frontend at
 * `<relayHttpBaseUrl>/front_end/chii_app.html`. The `ws=` (plain HTTP relay)
 * or `wss=` (HTTPS relay) query parameter is a URL-encoded string of the form
-* `<relay-host>/client/<uuid>?target=<id>` (and optionally `&at=<totp>`) —
-* the same format used by Chii's own target list page (derived from
-* `chii/public/index.js`).
+* `<relay-host>/client/<uuid>?target=<id>&at=<totp>` — the same format used
+* by Chii's own target list page (derived from `chii/public/index.js`).
 *
 * The `at=` TOTP code is minted at call time via `mintTotp()`.  It is valid
 * for ~3 minutes (relay gate accepts ±RELAY_VERIFY_SKEW_STEPS=6 steps =
@@ -1179,6 +1178,15 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 * If the window expires before the browser connects, the relay will reject the
 * WebSocket upgrade with close code 4401.
 *
+* FAIL-CLOSED (issue #509): `mintTotp` is REQUIRED.  When omitted (i.e.
+* `undefined`), this function returns `null` — the caller must treat `null` as
+* "inspector not yet available" and show a waiting hint instead of a broken
+* link. Relay sessions gate every WS upgrade with TOTP (#452), so a URL built
+* without `at=` would be rejected with WS 4401 immediately — there is no
+* non-TOTP relay path in production. Returning `null` surfaces this cleanly as
+* a "TOTP not yet configured" state rather than silently producing a URL that
+* will always fail at the WS handshake.
+*
 * SECRET-HANDLING: `mintTotp` returns a code, not a secret. The code is
 * embedded in the `wss=` parameter (inside the `at=` param) of the returned
 * URL. Callers MUST NOT log the returned URL to stdout (stderr is OK — it is
@@ -1187,11 +1195,14 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 * @param relayHttpBaseUrl - Local HTTP base URL of the Chii relay, e.g.
 *   `http://127.0.0.1:9100`. No trailing slash.
 * @param targetId - Chii target id (from `GET <relay>/targets`).
-* @param mintTotp - Optional function that returns a fresh 6-digit TOTP code
-*   string. Called at most once. When omitted (TOTP disabled) no `at=` param
-*   is added.
+* @param mintTotp - Function that returns a fresh 6-digit TOTP code string.
+*   Called at most once. **Required** — when `undefined`, the function returns
+*   `null` (fail-closed: no `at=` param means the relay WS gate rejects the
+*   handshake, so a null result is safer than a URL that always 404s).
 * @param panel - Initial panel. Defaults to `"console"`.
 *
+* @returns The inspector URL string, or `null` when `mintTotp` is absent.
+*
 * @example
 * buildChiiInspectorUrl(
 *   'http://127.0.0.1:9100',
@@ -1201,6 +1212,7 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 * // → 'http://127.0.0.1:9100/front_end/chii_app.html?ws=127.0.0.1%3A9100%2Fclient%2F<uuid>%3Ftarget%3Dabc123%26at%3D<code>'
 */
 function buildChiiInspectorUrl(relayHttpBaseUrl, targetId, mintTotp, panel = "console") {
+	if (!mintTotp) return null;
 	let relayHost;
 	let wsParamName;
 	try {
@@ -1212,11 +1224,8 @@ function buildChiiInspectorUrl(relayHttpBaseUrl, targetId, mintTotp, panel = "co
 		wsParamName = /^https:/i.test(relayHttpBaseUrl) ? "wss" : "ws";
 	}
 	const clientId = `devtools-opener-${Date.now().toString(36)}`;
-	let wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}`;
-	if (mintTotp) {
-		const code = mintTotp();
-		wsPath += `&at=${encodeURIComponent(code)}`;
-	}
+	const code = mintTotp();
+	const wsPath = `${relayHost}/client/${clientId}?target=${encodeURIComponent(targetId)}&at=${encodeURIComponent(code)}`;
 	const params = new URLSearchParams({
 		[wsParamName]: wsPath,
 		panel
@@ -1325,6 +1334,10 @@ var AutoDevtoolsOpener = class {
 		if (!options.targetId) return;
 		this._opened = true;
 		const inspectorUrl = buildChiiInspectorUrl(options.relayHttpBaseUrl, options.targetId, options.mintTotp);
+		if (inspectorUrl === null) {
+			process.stderr.write("[ait-debug] 기기가 연결됐습니다 — TOTP secret 미설정으로 인스펙터 URL을 생성할 수 없습니다.\n[ait-debug] relay 세션은 AIT_DEBUG_TOTP_SECRET 설정이 필요합니다.\n");
+			return;
+		}
 		process.stderr.write(`[ait-debug] 기기가 연결됐습니다 — Chii DevTools를 자동으로 엽니다.
 [ait-debug] DevTools URL: ${inspectorUrl}\n[ait-debug] (AIT_AUTO_DEVTOOLS=0 으로 자동 열기를 끌 수 있습니다)
 [ait-debug] 주의: URL의 at= 코드는 ~3분 안에서만 유효합니다.
@@ -2142,6 +2155,7 @@ const en = {
 	"launcher.diagNo": "no",
 	"launcher.letterboxDetected": "Display area is {pt}pt short — likely an iOS standalone letterbox. Removing and re-adding the launcher to the home screen may fix it.",
 	"launcher.navbar.defaultTitle": "Mini App",
+	"launcher.navbar.back": "Back",
 	"launcher.navbar.menu": "Menu",
 	"launcher.navbar.close": "Close",
 	"launcher.navbar.menuRescan": "Rescan",
@@ -2393,6 +2407,7 @@ const tables = {
 		"launcher.diagNo": "아니요",
 		"launcher.letterboxDetected": "표시 영역이 {pt}pt 부족합니다 — iOS standalone letterbox로 보입니다. 런처를 홈 화면에서 제거 후 다시 설치하면 해소될 수 있어요.",
 		"launcher.navbar.defaultTitle": "미니앱",
+		"launcher.navbar.back": "뒤로가기",
 		"launcher.navbar.menu": "메뉴",
 		"launcher.navbar.close": "닫기",
 		"launcher.navbar.menuRescan": "다시 스캔",
@@ -3100,8 +3115,9 @@ function buildAttachHtml(qrDataUrl, safeLabel, safeAttachUrl, locale, path = "/a
 *
 * @param getDashboardState - dashboard 상태를 반환하는 클로저. 주입 시 `GET /` dashboard와
 *   `GET /events` SSE 스트림이 활성화된다. 미주입 시 두 라우트는 204/서비스 없음으로 응답.
+* @param options - 서버 옵션. `sseRefreshIntervalMs`로 idle 탭 TOTP 만료 방지 주기를 조정.
 */
-async function startQrHttpServer(getDashboardState) {
+async function startQrHttpServer(getDashboardState, options) {
 	const { default: QRCode } = await import("qrcode");
 	/** SSE 활성 연결 목록 — `notifyStateChange()` 시 전체 push. */
 	const sseClients = [];
@@ -3234,19 +3250,28 @@ async function startQrHttpServer(getDashboardState) {
 	const address = server.address();
 	if (!address || typeof address === "string") throw new Error("qr-http-server: server.address()가 예상하지 못한 형태입니다.");
 	const port = address.port;
+	/** idle 탭 TOTP 만료 방지용 주기 SSE 갱신 interval. */
+	function notifyStateChangeInternal() {
+		if (!getDashboardState) return;
+		const state = getDashboardState();
+		for (const client of sseClients) try {
+			pushStateToClient(client, state);
+		} catch {}
+	}
+	const refreshIntervalMs = options?.sseRefreshIntervalMs ?? 9e4;
+	const refreshHandle = setInterval(() => {
+		if (sseClients.length > 0 && getDashboardState) notifyStateChangeInternal();
+	}, refreshIntervalMs).unref();
 	return {
 		port,
 		buildAttachPageUrl(attachUrl) {
 			return `http://127.0.0.1:${port}/attach?u=${encodeURIComponent(attachUrl)}`;
 		},
 		notifyStateChange() {
-			if (!getDashboardState) return;
-			const state = getDashboardState();
-			for (const client of sseClients) try {
-				pushStateToClient(client, state);
-			} catch {}
+			notifyStateChangeInternal();
 		},
 		close() {
+			clearInterval(refreshHandle);
 			return new Promise((resolve, reject) => {
 				server.close((err) => err ? reject(err) : resolve());
 			});
@@ -4635,7 +4660,7 @@ async function readMcpSdkVersion() {
 * some test environments that skip the build step).
 */
 function readDevtoolsVersion() {
-	return "0.1.74";
+	return "0.1.76";
 }
 /**
 * Derives the next recommended action from a completed diagnostics snapshot.
@@ -5139,7 +5164,7 @@ function createDebugServer(deps) {
 	const collector = collectorDep ?? new InMemoryDiagnosticsCollector();
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.74"
+		version: "0.1.76"
 	}, { capabilities: { tools: { listChanged: true } } });
 	server.setRequestHandler(ListToolsRequestSchema, () => {
 		const conn = router.active;
@@ -5738,37 +5763,52 @@ function errorResult(err, name, isLocal = false) {
 	return classifyToolError(err, name, isLocal);
 }
 /**
-* Starts a polling watcher that detects the first 0→N target transition on
+* Starts a polling watcher that detects target-set changes on
 * `connection.listTargets()` and sends a `notifications/tools/list_changed`
 * notification on the given server.
 *
 * The watcher polls every `intervalMs` (default 1 000 ms). It fires
-* `server.sendToolListChanged()` exactly once — on the first transition — then
-* clears itself. Shutdown calls `stop()` to clear the interval.
+* `server.sendToolListChanged()` + `onAttach()` whenever the sorted target-id
+* signature changes AND the new target set is non-empty. This covers:
+*   - 0→N first attach
+*   - 1→1 target replacement (same count, different id — e.g. rescan)
+*   - N→M any change where the result is still non-empty
+*
+* Full detach (→ empty) updates the stored signature but does NOT fire the
+* callback — `onAttach` semantics are about a live target being present.
+*
+* The interval is **never cleared automatically** — it keeps running until
+* `stop()` is called during shutdown. This ensures that a target replacement
+* after the first attach is always detected.
 *
-* `onFirstAttach` is called once on the 0→N transition (or immediately when
-* already attached). Use this to trigger side-effects such as auto-opening
-* Chrome DevTools (issue #282). The callback is optional; omitting it preserves
-* the previous behaviour exactly.
+* `onAttach` is called on every non-empty signature change (or immediately when
+* already attached). Use this to trigger side-effects such as pushing a fresh
+* SSE state to open dashboard tabs (issue #509). The callback is optional;
+* omitting it preserves the previous behaviour exactly.
 *
 * SECRET-HANDLING: target `id`/`title`/`url` are not written to any log here.
 * Only an attach-detected stderr line is emitted (no target details).
 *
 * @returns `stop` — call this during shutdown to clear the interval.
 */
-function startAttachWatcher(connection, server, intervalMs = 1e3, onFirstAttach) {
-	let wasAttached = connection.listTargets().length > 0;
-	if (wasAttached) {
+function startAttachWatcher(connection, server, intervalMs = 1e3, onAttach) {
+	/** Sorted, comma-joined target-id string — '' means no targets attached. */
+	function signature() {
+		return connection.listTargets().map((t) => t.id).sort().join(",");
+	}
+	let lastSignature = signature();
+	if (lastSignature !== "") {
 		server.sendToolListChanged();
-		onFirstAttach?.();
+		onAttach?.();
 	}
 	const handle = setInterval(() => {
-		const isAttached = connection.listTargets().length > 0;
-		if (!wasAttached && isAttached) {
-			wasAttached = true;
-			server.sendToolListChanged();
-			onFirstAttach?.();
-			clearInterval(handle);
+		const current = signature();
+		if (current !== lastSignature) {
+			lastSignature = current;
+			if (current !== "") {
+				server.sendToolListChanged();
+				onAttach?.();
+			}
 		}
 	}, intervalMs);
 	return { stop() {
@@ -7065,7 +7105,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.74"
+		version: "0.1.76"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {