@ait-co/devtools 0.1.44 → 0.1.46

package/README.en.md

@@ -101,6 +101,10 @@ The page on the phone died (OOM, JS exception, or native bridge crash). Relaunch
 
 When `call_sdk` returns `ok: false, error: "window.__sdkCall is not available"`, a non-dogfood bundle is loaded. Redeploy through the dogfood channel with the `__DEBUG_BUILD__` flag enabled and try again. This error is the expected result in environment 2 (PWA). (Related: [#285](https://github.com/apps-in-toss-community/devtools/issues/285))
 
+**"QR scanned but auth rejected" — TOTP code expired**
+
+When `AIT_DEBUG_TOTP_SECRET` is set, `build_attach_url` automatically splices the current one-time TOTP code (`at=`) into the returned `attachUrl`. The code is valid for a 30-second step. Scanning after `totp.expiresAt` causes the relay to reject the request. Fix: call `build_attach_url` again to get a fresh URL and QR, then scan within 30 seconds.
+
 ---
 
 ## Install
@@ -946,13 +950,13 @@ AI coding agents (Claude Code, Cursor, etc.) can observe a running mini-app dire
 
 A local browser (env 1) and a phone Toss WebView (env 2/3) both speak CDP, so every tool works identically in both environments — the only difference is the attach strategy (`--target=relay` vs `--target=local`).
 
-| Mode + target | Invocation | Target | Tools |
-|---|---|---|---|
-| `--mode=debug --target=relay` (default) | `devtools-mcp` | Production bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 2/3) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
-| `--mode=debug --target=local` | `devtools-mcp --target=local` | Local Chromium launched by the MCP server (CDP direct-attach, no relay needed, env 1) | same |
-| `--mode=dev` | `devtools-mcp --mode=dev` | Mock state from a running Vite dev server | `AIT.*` (+ `devtools_get_mock_state` alias) |
+| Mode + target | Invocation | Env var | Target | Tools |
+|---|---|---|---|---|
+| `--mode=debug --target=relay` (default) | `MCP_ENV=relay devtools-mcp` | `MCP_ENV=relay` recommended | Dogfood bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 2/3) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
+| `--mode=debug --target=local` | `devtools-mcp --target=local` | `MCP_ENV=mock` (auto) | Local Chromium launched by the MCP server (CDP direct-attach, no relay needed, env 1) | same |
+| `--mode=dev` | `devtools-mcp --mode=dev` | `MCP_ENV=mock` (auto) | Mock state from a running Vite dev server (AIT.* only, no CDP) | `AIT.*` (+ `devtools_get_mock_state` alias) |
 
-`--target=local` opens `AIT_DEVTOOLS_URL` (default `http://localhost:5173`) and attaches directly to a local Chromium — no relay or tunnel required. `--mode=dev` reads the mock-state HTTP endpoint of the Vite dev server. All three combinations expose the same `AIT.*` tool surface to the agent.
+`--target=local` opens `AIT_DEVTOOLS_URL` (default `http://localhost:5173`) and attaches directly to a local Chromium — no relay or tunnel required. `--mode=dev` reads the mock-state HTTP endpoint of the Vite dev server and does not provide CDP tools. For on-device sessions (env 3/4), setting `MCP_ENV=relay` explicitly ensures the relay tool surface is visible even before the tunnel URL is auto-detected.
 
 ### Debug mode (CDP via Chii)
 
@@ -967,12 +971,17 @@ Running `devtools-mcp` as a stdio server starts a local Chii relay on an OS-assi
   "mcpServers": {
     "ait-debug": {
       "command": "pnpm",
-      "args": ["exec", "devtools-mcp"]
+      "args": ["exec", "devtools-mcp"],
+      "env": {
+        "MCP_ENV": "relay"
+      }
     }
   }
 }
 ```
 
+Setting `MCP_ENV=relay` explicitly ensures the relay tool surface is visible before the tunnel URL is auto-detected.
+
 | Tool | CDP / AIT backing | Description |
 |---|---|---|
 | `list_console_messages` | `Runtime.consoleAPICalled` | Recent console.log/warn/error messages (level, text, timestamp, args) |

package/README.md

@@ -101,6 +101,10 @@ cloudflared quick tunnel은 수 시간 후 drop될 수 있습니다. `devtools-m
 
 `call_sdk` 호출 시 `ok: false, error: "window.__sdkCall is not available"` 에러가 뜨면 dogfood 빌드가 아닌 일반 번들이 로드된 것입니다. `__DEBUG_BUILD__` 플래그가 켜진 dogfood 채널로 재배포 후 다시 시도하세요. 환경 2(PWA)에서는 이 에러가 예상 결과입니다. (관련: [#285](https://github.com/apps-in-toss-community/devtools/issues/285))
 
+**"QR 스캔했는데 인증 실패" — TOTP 만료**
+
+`AIT_DEBUG_TOTP_SECRET` 설정 시 `build_attach_url`이 반환하는 attachUrl에는 30초 유효 TOTP 코드(`at=`)가 자동으로 포함됩니다. 응답의 `totp.expiresAt` 이후 스캔하면 relay가 인증을 거부합니다. 해결: `build_attach_url`을 재호출해 새 URL과 QR을 발급받은 뒤 30초 이내에 스캔하세요.
+
 ---
 
 ## 설치
@@ -951,6 +955,24 @@ Turbopack은 unplugin을 지원하지 않으므로, `next.config.js`에서 `reso
 import '@ait-co/devtools/panel';
 ```
 
+### `devtools-mcp` — 이미 실행 중인 세션이 있을 때
+
+두 번째 `devtools-mcp` 실행 시 "기존 debug-mode 세션이 이미 실행 중" 메시지가 stderr에 출력됩니다. 기존 PID와 wssUrl이 함께 표시됩니다.
+
+회복 방법:
+
+```bash
+# 기존 세션을 직접 종료
+kill <PID>
+
+# 또는 --force 플래그로 기존 세션을 종료하고 takeover
+npx @ait-co/devtools devtools-mcp --force
+# local 모드라면:
+npx @ait-co/devtools devtools-mcp --target=local --force
+```
+
+`--takeover`도 `--force`의 alias로 동일하게 동작합니다.
+
 ## MCP Server
 
 AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)](https://modelcontextprotocol.io/)를
@@ -958,13 +980,13 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 
 로컬 브라우저(환경 1)와 폰 토스 앱 WebView(환경 2·3)는 둘 다 CDP를 말하므로 모든 tool이 두 환경에서 동일하게 동작합니다 — 갈라지는 건 attach 전략(`--target=relay` vs `--target=local`)뿐입니다.
 
-| 모드 + 타깃 | 호출 | 대상 | tool |
-|---|---|---|---|
-| `--mode=debug --target=relay` (기본값) | `devtools-mcp` | 폰 안 production 번들 (CDP/Chii relay + cloudflared 터널, 환경 2·3) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
-| `--mode=debug --target=local` | `devtools-mcp --target=local` | MCP가 직접 기동한 로컬 Chromium (CDP direct-attach, relay 불필요, 환경 1) | 동일 |
-| `--mode=dev` | `devtools-mcp --mode=dev` | 실행 중인 Vite dev server의 mock state | `AIT.*` (+ `devtools_get_mock_state` alias) |
+| 모드 + 타깃 | 호출 | 환경 변수 | 대상 | tool |
+|---|---|---|---|---|
+| `--mode=debug --target=relay` (기본값) | `MCP_ENV=relay devtools-mcp` | `MCP_ENV=relay` 권장 | 폰 안 dogfood 번들 (CDP/Chii relay + cloudflared 터널, 환경 2·3) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
+| `--mode=debug --target=local` | `devtools-mcp --target=local` | `MCP_ENV=mock` (자동) | MCP가 직접 기동한 로컬 Chromium (CDP direct-attach, relay 불필요, 환경 1) | 동일 |
+| `--mode=dev` | `devtools-mcp --mode=dev` | `MCP_ENV=mock` (자동) | 실행 중인 Vite dev server의 mock state (AIT.* 전용, CDP 없음) | `AIT.*` (+ `devtools_get_mock_state` alias) |
 
-`--target=local`은 `AIT_DEVTOOLS_URL`(기본 `http://localhost:5173`)을 열고 로컬 Chromium에 CDP direct-attach합니다 — relay나 터널이 필요하지 않습니다. `--mode=dev`는 Vite dev server의 mock-state HTTP endpoint를 읽습니다. 세 조합 모두 에이전트에게 동일한 `AIT.*` tool surface를 노출합니다.
+`--target=local`은 `AIT_DEVTOOLS_URL`(기본 `http://localhost:5173`)을 열고 로컬 Chromium에 CDP direct-attach합니다 — relay나 터널이 필요하지 않습니다. `--mode=dev`는 Vite dev server의 mock-state HTTP endpoint를 읽으며 CDP tool은 제공하지 않습니다. 실기기(환경 3·4) 진입 시 `MCP_ENV=relay`를 명시하면 터널 감지 전 bootstrap 단계에서도 relay tool이 올바르게 노출됩니다.
 
 ### Debug 모드 (CDP via Chii)
 
@@ -987,12 +1009,17 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
   "mcpServers": {
     "ait-debug": {
       "command": "pnpm",
-      "args": ["exec", "devtools-mcp"]
+      "args": ["exec", "devtools-mcp"],
+      "env": {
+        "MCP_ENV": "relay"
+      }
     }
   }
 }
 ```
 
+`MCP_ENV=relay`를 명시하면 터널 URL 자동 감지 전에도 relay tool surface가 올바르게 노출됩니다.
+
 | Tool | CDP / AIT 백킹 | 설명 |
 |---|---|---|
 | `list_console_messages` | `Runtime.consoleAPICalled` | 최근 console.log/warn/error 메시지 (level, text, timestamp, args) |

package/dist/mcp/cli.d.ts

@@ -21,6 +21,13 @@
  */
 type Mode = 'debug' | 'dev';
 type Target = 'relay' | 'local';
+/**
+ * Returns `true` when `--force` or `--takeover` is present in argv.
+ *
+ * Both flags are accepted as aliases — `--force` is the short form listed in
+ * the `--help` output; `--takeover` is a longer synonym.
+ */
+declare function parseForce(argv: readonly string[]): boolean;
 /** Parses `--mode=<value>` / `--mode <value>` from argv; default `debug`. */
 declare function parseMode(argv: readonly string[]): Mode;
 /**
@@ -32,5 +39,5 @@ declare function parseMode(argv: readonly string[]): Mode;
  */
 declare function parseTarget(argv: readonly string[]): Target;
 //#endregion
-export { parseMode, parseTarget };
+export { parseForce, parseMode, parseTarget };
 //# sourceMappingURL=cli.d.ts.map

package/dist/mcp/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","names":[],"sources":["../../src/mcp/cli.ts"],"mappings":";;;;;;;;AA0BS;;;;;AAIT;;;;;AAyBA;;;KA7BK,IAAA;AAAA,KACA,MAAA;;iBAGW,SAAA,CAAU,IAAA,sBAA0B,IAAA;;;;;;;;iBAyBpC,WAAA,CAAY,IAAA,sBAA0B,MAAA"}
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../../src/mcp/cli.ts"],"mappings":";;;;;;;;AA0BS;;;;;AAST;;;;;AAKA;;;KAdK,IAAA;AAAA,KACA,MAAA;AAsCL;;;;;;AAAA,iBA9BgB,UAAA,CAAW,IAAA;;iBAKX,SAAA,CAAU,IAAA,sBAA0B,IAAA;;;;;;;;iBAyBpC,WAAA,CAAY,IAAA,sBAA0B,MAAA"}