@ait-co/devtools 0.1.43 → 0.1.45

package/README.en.md

@@ -18,6 +18,91 @@ Lets you develop and test Apps in Toss mini-apps in a **regular browser** — wi
 
 Live demo: <https://devtools.aitc.dev/> (the `e2e/fixture/` from this repo deployed to GitHub Pages as a self-contained demo).
 
+## 15-second quickstart — pick your environment
+
+There are four runtime environments. Pick the card that fits your situation and follow the link to the detailed scenario doc.
+
+---
+
+**Environment 1 — Local browser** (fastest, HMR on)
+
+Develop with the mock SDK + DevTools panel in desktop Chrome. No Toss app or phone needed.
+
+```bash
+pnpm add -D @ait-co/devtools
+# add the unplugin to vite.config.ts → pnpm dev
+```
+
+DevTools panel: click the **AIT** button in the bottom-right corner. Details: [`docs/scenarios/env-1.md`](./docs/scenarios/env-1.md)
+
+---
+
+**Environment 2 — Real-device PWA** (real WebKit engine, HMR on, no Toss review required)
+
+Preview your mini-app on a real phone using Safari/WebKit. Install the launcher PWA once, then scan a QR code each session.
+
+```bash
+# add the tunnel option to vite.config.ts, then:
+pnpm dev:phone          # same as AIT_TUNNEL=1 pnpm dev
+# QR appears in the terminal → scan with your phone camera → opens in the launcher PWA
+```
+
+One-time prerequisite: add `https://devtools.aitc.dev/launcher/` to your phone's home screen. Details: [`docs/scenarios/env-2.md`](./docs/scenarios/env-2.md)
+
+---
+
+**Environment 3 — intoss-private** (Toss WebView, HMR off, debug only)
+
+Load a dogfood bundle in the real Toss app WebView and debug it via the MCP relay.
+
+```bash
+devtools-mcp              # start MCP server → QR printed in terminal
+# ait build && ait deploy --scheme-only
+# call build_attach_url → scan QR → Toss app loads bundle + relay attaches
+```
+
+No HMR (Toss WebView cold-load only). Details: [`docs/scenarios/env-3.md`](./docs/scenarios/env-3.md)
+
+---
+
+**Environment 4 — Live deployed app** (passed review, HMR off, read-only debug)
+
+Attach a relay to a live OPENED app to observe runtime behavior.
+
+```bash
+devtools-mcp              # start MCP server
+# call build_attach_url → scan QR → live app loads + relay attaches
+# call_sdk / evaluate: watch for side effects (real users may be affected)
+```
+
+Details: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
+
+---
+
+## Five common problems
+
+**"QR window doesn't open"**
+
+Either `build_attach_url` wasn't called first, or `open_in_browser` failed silently in a headless environment. The terminal output includes a path to a saved PNG — open that file directly, or scan the text QR printed in the terminal. (Related: [#288](https://github.com/apps-in-toss-community/devtools/issues/288))
+
+**"Page not attached" — list_pages returns an empty array**
+
+No page has joined the relay yet. Re-enter via `build_attach_url` → QR scan on your phone. When the MCP error message reads "page not attached — run build_attach_url then scan QR", this is the case.
+
+**"Tunnel down" — no response or timeout**
+
+A cloudflared quick tunnel can drop after a few hours. Restart the `devtools-mcp` process to get a new tunnel URL, then scan the new QR. (Related: [#290](https://github.com/apps-in-toss-community/devtools/issues/290))
+
+**"Page crash" — list_pages shows a non-null crashDetectedAt**
+
+The page on the phone died (OOM, JS exception, or native bridge crash). Relaunch the app, then re-attach via `build_attach_url` → QR scan. (Related: [#265](https://github.com/apps-in-toss-community/devtools/issues/265))
+
+**"SDK not available" — window.__sdkCall not injected**
+
+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))
+
+---
+
 ## Install
 
 ```bash
@@ -861,13 +946,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)
 
@@ -882,12 +967,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

@@ -18,6 +18,91 @@
 
 라이브 데모: <https://devtools.aitc.dev/> (이 repo의 `e2e/fixture/`를 GitHub Pages에 그대로 배포한 self-contained 데모).
 
+## 15초 quickstart — 내 상황에 맞는 환경 고르기
+
+4가지 실행 환경이 있습니다. 지금 상황에 맞는 카드 하나를 고르고, 해당 상세 시나리오 문서로 이동하세요.
+
+---
+
+**환경 1 — 로컬 브라우저** (가장 빠름, HMR O)
+
+데스크탑 Chrome에서 mock SDK + DevTools 패널로 개발합니다. 토스 앱·폰 없이 즉시 시작.
+
+```bash
+pnpm add -D @ait-co/devtools
+# vite.config.ts에 unplugin 추가 → pnpm dev
+```
+
+DevTools 패널: 화면 우하단 **AIT** 버튼. 상세: [`docs/scenarios/env-1.md`](./docs/scenarios/env-1.md)
+
+---
+
+**환경 2 — 실기기 PWA** (실 WebKit 엔진, HMR O, 토스 검수 불필요)
+
+폰에서 실기기 Safari/WebKit 엔진으로 미니앱을 확인합니다. launcher PWA를 한 번 설치하고, 매 세션마다 QR 스캔.
+
+```bash
+# vite.config.ts에 tunnel 옵션 추가 후:
+pnpm dev:phone          # AIT_TUNNEL=1 pnpm dev 와 동일
+# 터미널에 QR 출력 → 폰 카메라로 스캔 → launcher PWA에서 자동 열림
+```
+
+사전: 폰에 `https://devtools.aitc.dev/launcher/` 를 홈 화면에 한 번 추가. 상세: [`docs/scenarios/env-2.md`](./docs/scenarios/env-2.md)
+
+---
+
+**환경 3 — intoss-private** (토스 WebView, HMR X, debug 전용)
+
+실기기 토스 앱 WebView에서 dogfood 번들을 로드하고 MCP relay로 디버깅합니다.
+
+```bash
+devtools-mcp              # MCP 서버 시작 → QR 출력
+# ait build && ait deploy --scheme-only
+# build_attach_url 호출 → QR 스캔 → 토스 앱 로드 + relay attach
+```
+
+HMR 없음(토스 WebView cold-load만). 상세: [`docs/scenarios/env-3.md`](./docs/scenarios/env-3.md)
+
+---
+
+**환경 4 — 배포된 앱 (LIVE)** (검수 통과 앱, HMR X, read-only debug)
+
+검수를 통과하고 OPENED 상태인 실 출시 앱에 relay를 붙여 런타임을 관측합니다.
+
+```bash
+devtools-mcp              # MCP 서버 시작
+# build_attach_url 호출 → QR 스캔 → LIVE 앱 로드 + relay attach
+# call_sdk / evaluate 는 side-effect 주의 (실유저 영향)
+```
+
+상세: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
+
+---
+
+## 자주 겪는 문제 5가지
+
+**"QR 창이 안 열림"**
+
+`build_attach_url`을 먼저 호출하지 않았거나, GUI 없는 headless 환경에서 `open_in_browser`가 실패한 경우입니다. 터미널에 PNG 저장 경로가 출력됩니다 — 그 파일을 직접 열거나, 텍스트 QR을 터미널에서 스캔하세요. (관련: [#288](https://github.com/apps-in-toss-community/devtools/issues/288))
+
+**"page 미attach" — list_pages가 빈 배열 반환**
+
+relay에 붙은 페이지가 없는 상태입니다. `build_attach_url` → QR 스캔 순서로 폰을 다시 진입시키세요. MCP 에러 메시지가 "페이지가 attach 안 됨. build_attach_url → QR 스캔."으로 뜨면 이 케이스입니다.
+
+**"tunnel down" — 터널 응답 없음 또는 timeout**
+
+cloudflared quick tunnel은 수 시간 후 drop될 수 있습니다. `devtools-mcp` 프로세스를 재시작하면 새 tunnel URL이 발급됩니다. 재발급 후 QR을 다시 스캔하세요. (관련: [#290](https://github.com/apps-in-toss-community/devtools/issues/290))
+
+**"page crash" — list_pages에 crashDetectedAt이 찍힘**
+
+폰 측 페이지가 OOM·JS exception·native bridge crash로 죽은 상태입니다. 앱을 재실행 후 `build_attach_url` → QR 스캔으로 다시 attach하세요. (관련: [#265](https://github.com/apps-in-toss-community/devtools/issues/265))
+
+**"SDK 부재" — window.__sdkCall 미주입**
+
+`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))
+
+---
+
 ## 설치
 
 ```bash
@@ -866,6 +951,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/)를
@@ -873,13 +976,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)
 
@@ -902,12 +1005,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"}