@ait-co/devtools 0.1.34 → 0.1.36

package/README.en.md

@@ -835,18 +835,21 @@ import '@ait-co/devtools/panel';
 
 AI coding agents (Claude Code, Cursor, etc.) can observe a running mini-app directly via [MCP (Model Context Protocol)](https://modelcontextprotocol.io/). A single `devtools-mcp` binary provides two modes.
 
-| Mode | Invocation | Target | Tools |
+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 |
 |---|---|---|---|
-| **debug** (default) | `devtools-mcp` | Production bundle on a phone or dev browser (CDP/Chii) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
-| **dev** | `devtools-mcp --mode=dev` | Mock state from a running Vite dev server | `AIT.*` (+ `devtools_get_mock_state` alias) |
+| `--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) |
 
-Both modes expose the same `AIT.*` tool surface — debug mode backed by the Chii channel, dev mode by the dev server's mock-state HTTP endpoint — so an agent sees the same tools whether attached to a phone (debug) or a dev browser (dev).
+`--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.
 
 ### Debug mode (CDP via Chii)
 
-Read-only tools only. The phone attach roundtrip is fully wired; all that remains is a single on-device acceptance run. The tool layer is CI-verified via a mockable injectable CDP connection / AIT source.
+Read-only tools only. Tools are registered in two tiers based on attach state — before attach, only the bootstrap tools (`build_attach_url`, `list_pages`) are visible; once a relay/local page attaches, the attach-dependent tools are registered dynamically in the same session via `notifications/tools/list_changed` (no session restart needed). The phone attach roundtrip is fully wired; all that remains is a single on-device acceptance run. The tool layer is CI-verified via a mockable injectable CDP connection / AIT source.
 
-Running `devtools-mcp` as a stdio server starts a local Chii relay on `:9100` and opens a cloudflared quick tunnel, printing a public `wss://*.trycloudflare.com` URL, a QR code, and a secret token in the terminal. When the phone enters the dogfood entry point, the in-app attach UI connects to the relay with that URL and token, and the agent reads console/network/page state via `chrome-devtools-mcp`-compatible tools — diagnosing regressions without anyone watching the phone.
+Running `devtools-mcp` as a stdio server starts a local Chii relay on an OS-assigned port and opens a cloudflared quick tunnel, printing a public `wss://*.trycloudflare.com` URL and a QR code in the terminal (secrets/auth codes are never printed). When the phone enters the dogfood entry point, the in-app attach UI connects to the relay with that URL, and the agent reads console/network/page state via `chrome-devtools-mcp`-compatible tools — diagnosing regressions without anyone watching the phone.
 
 ```json
 {
@@ -864,10 +867,13 @@ Running `devtools-mcp` as a stdio server starts a local Chii relay on `:9100` an
 | `list_console_messages` | `Runtime.consoleAPICalled` | Recent console.log/warn/error messages (level, text, timestamp, args) |
 | `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | Recent XHR/fetch requests (url, method, status, timing) |
 | `list_pages` | Chii relay target list | Attached pages + tunnel status + wss URL |
-| `build_attach_url` | (pure synthesis) | Splices `debug=1` + the relay URL into an `ait deploy --scheme-only` URL to make a self-attaching deep link (no QR scan) |
+| `build_attach_url` | (pure synthesis) | Splices `debug=1` + the relay URL into an `ait deploy --scheme-only` URL, prints a QR. Scanning the QR with the phone camera is the single entry path for env 2/3 (requires `list_pages` first) |
 | `get_dom_document` | `DOM.getDocument` | DOM tree read (structural/layout regression diagnosis) |
 | `take_snapshot` | `DOMSnapshot.captureSnapshot` | Page snapshot (documents + interned strings, visual regression) |
 | `take_screenshot` | `Page.captureScreenshot` | Page PNG screenshot (returned as an MCP image content block) |
+| `measure_safe_area` | `Runtime.evaluate` | Runs a safe-area probe on the attached page → returns normalized safe-area insets, viewport geometry, DPR, and User-Agent. Read-only. Use in a relay session to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires attach (`list_pages` first) |
+| `evaluate` | `Runtime.evaluate` | Evaluates an arbitrary JS expression on the attached page (returnByValue) and returns the result. **Not read-only** — the expression can have side effects (DOM mutations, SDK calls, state changes). Requires attach |
+| `call_sdk` | `window.__sdkCall` bridge (via `Runtime.evaluate`) | Calls a dogfood SDK method via the `window.__sdkCall` bridge (exported by `@apps-in-toss/web-framework` in `__DEBUG_BUILD__` bundles only). **Not read-only** — SDK calls have side effects (navigation, payments, permissions, etc.). Hits the real SDK on env 2/3, mock SDK on env 1. Requires attach. Returns `{ok,value}` / `{ok,error}` |
 | `AIT.getSdkCallHistory` | AIT domain | SDK call trace (method, args, result/error, timestamp) |
 | `AIT.getMockState` | AIT domain | Mock state snapshot (`window.__ait`) |
 | `AIT.getOperationalEnvironment` | AIT domain | `getOperationalEnvironment()` + SDK version |

package/README.md

@@ -847,25 +847,29 @@ import '@ait-co/devtools/panel';
 AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)](https://modelcontextprotocol.io/)를
 통해 실행 중인 미니앱을 직접 관측할 수 있습니다. 단일 `devtools-mcp` bin이 두 모드를 제공합니다.
 
-| 모드 | 호출 | 대상 | tool |
+로컬 브라우저(환경 1)와 폰 토스 앱 WebView(환경 2·3)는 둘 다 CDP를 말하므로 모든 tool이 두 환경에서 동일하게 동작합니다 — 갈라지는 건 attach 전략(`--target=relay` vs `--target=local`)뿐입니다.
+
+| 모드 + 타깃 | 호출 | 대상 | tool |
 |---|---|---|---|
-| **debug** (기본값) | `devtools-mcp` | 폰 안 production 번들 또는 dev 브라우저 (CDP/Chii) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
-| **dev** | `devtools-mcp --mode=dev` | 실행 중인 Vite dev server의 mock state | `AIT.*` (+ `devtools_get_mock_state` alias) |
+| `--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) |
 
-두 모드는 같은 `AIT.*` tool surface를 노출합니다 — debug 모드는 Chii 채널로, dev 모드는 dev server의
-mock-state HTTP endpoint로 백킹되어, 에이전트가 폰(debug)에 붙든 dev 브라우저(dev)에 붙든 동일한
-tool을 봅니다.
+`--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를 노출합니다.
 
 ### Debug 모드 (CDP via Chii)
 
-read-only tool만 노출합니다. 폰 attach 라운드트립은 fully wired 상태이며 남은 것은 실기기 acceptance
-한 번뿐입니다. tool 계층은 주입 가능한 CDP 연결 / AIT 소스를 mock해 CI에서 검증됩니다.
+read-only tool만 노출합니다. 도구는 attach 상태에 따라 2단계로 등록됩니다 — attach 전에는 bootstrap
+도구(`build_attach_url`·`list_pages`)만 보이고, 릴레이/로컬 페이지가 attach되면 `notifications/tools/list_changed`로
+attach 의존 도구가 같은 세션에서 동적 등록됩니다(세션 재시작 불필요). 폰 attach 라운드트립은 fully wired
+상태이며 남은 것은 실기기 acceptance 한 번뿐입니다. tool 계층은 주입 가능한 CDP 연결 / AIT 소스를 mock해
+CI에서 검증됩니다.
 
-`devtools-mcp`를 stdio로 실행하면 로컬 Chii 릴레이(:9100)를 띄우고 cloudflared quick tunnel로
-공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR + secret token을 터미널에 출력합니다.
-폰이 dogfood 진입 시 in-app attach UI가 그 URL + token으로 릴레이에 붙으면, 에이전트가
-`chrome-devtools-mcp` 호환 tool로 console/network/page 상태를 read합니다. 사람이 폰을 지켜볼
-필요 없이 회귀를 단독 진단하는 것이 목표입니다.
+`devtools-mcp`를 stdio로 실행하면 로컬 Chii 릴레이를 OS가 할당한 포트에 띄우고 cloudflared quick
+tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미널에 출력합니다(시크릿/인증
+코드는 출력하지 않습니다). 폰이 dogfood 진입 시 in-app attach UI가 그 URL로 릴레이에 붙으면,
+에이전트가 `chrome-devtools-mcp` 호환 tool로 console/network/page 상태를 read합니다. 사람이 폰을
+지켜볼 필요 없이 회귀를 단독 진단하는 것이 목표입니다.
 
 ```json
 {
@@ -883,10 +887,13 @@ read-only tool만 노출합니다. 폰 attach 라운드트립은 fully wired 상
 | `list_console_messages` | `Runtime.consoleAPICalled` | 최근 console.log/warn/error 메시지 (level, text, timestamp, args) |
 | `list_network_requests` | `Network.requestWillBeSent` + `responseReceived` | 최근 XHR/fetch 요청 (url, method, status, timing) |
 | `list_pages` | Chii 릴레이 target 목록 | attach된 페이지 + tunnel 상태 + wss URL |
-| `build_attach_url` | (순수 합성) | `ait deploy --scheme-only` URL에 `debug=1`+릴레이 URL을 끼워 self-attach 딥링크 생성 (QR 스캔 불필요) |
+| `build_attach_url` | (순수 합성) | `ait deploy --scheme-only` URL에 `debug=1`+릴레이 URL을 끼워 self-attach 딥링크 합성 → QR을 터미널 출력. QR을 폰 카메라로 스캔하는 것이 환경 2·3의 단일 진입 경로 (`list_pages` 먼저 필요) |
 | `get_dom_document` | `DOM.getDocument` | DOM 트리 read (구조/레이아웃 회귀 진단) |
 | `take_snapshot` | `DOMSnapshot.captureSnapshot` | 페이지 스냅샷 (documents + interned strings, 시각 회귀 진단) |
 | `take_screenshot` | `Page.captureScreenshot` | 페이지 PNG 스크린샷 (MCP image content block 반환) |
+| `measure_safe_area` | `Runtime.evaluate` | attach된 페이지에서 safe-area 프로브 실행 → 정규화된 safe-area inset·뷰포트 geometry·DPR·User-Agent 반환. read-only. relay 세션(폰 attach)에서 viewport preset을 extrapolated/placeholder→measured로 승급할 ground truth 수집용. attach 필요 (`list_pages` 먼저) |
+| `evaluate` | `Runtime.evaluate` | attach된 페이지에서 임의 JS 표현식 평가(returnByValue) → 결과 반환. **read-only 아님** — 표현식이 부작용(DOM 변경·SDK 호출·상태 변경)을 일으킬 수 있음. attach 필요 |
+| `call_sdk` | `window.__sdkCall` 브리지 (`Runtime.evaluate` 경유) | dogfood SDK 메서드를 `window.__sdkCall` 브리지로 호출 (`@apps-in-toss/web-framework`가 `__DEBUG_BUILD__` 번들에서만 export). **read-only 아님** — SDK 호출은 부작용(내비게이션·결제·권한 등). 환경 2·3(실기기 relay)에선 실 SDK, 환경 1(로컬 mock)에선 mock SDK. attach 필요. `{ok,value}` / `{ok,error}` 반환 |
 | `AIT.getSdkCallHistory` | AIT 도메인 | SDK 호출 trace (method, args, result/error, timestamp) |
 | `AIT.getMockState` | AIT 도메인 | mock state 스냅샷 (`window.__ait`) |
 | `AIT.getOperationalEnvironment` | AIT 도메인 | `getOperationalEnvironment()` + SDK 버전 |

package/dist/mcp/cli.d.ts

@@ -3,18 +3,34 @@
 /**
  * `devtools-mcp` bin entry.
  *
- * Single bin, two transports selected by `--mode`:
- *   - (default, no flag) debug mode — CDP/Chii relay + cloudflared quick tunnel.
- *     Attach a running mini-app (real Toss WebView or a browser) and read its
- *     console + network over CDP without a human watching a phone.
- *   - `--mode=dev` — dev mode — reads the live browser mock state from a running
+ * Single bin, two modes selected by `--mode` and one target selected by
+ * `--target`:
+ *
+ *   --mode=debug (default)
+ *     --target=relay (default) — CDP/Chii relay + cloudflared quick tunnel.
+ *       Attach a running mini-app (real Toss WebView, env 2/3) and read its
+ *       console + network over CDP without a human watching a phone.
+ *     --target=local — CDP direct-attach to a local Chromium launched by the
+ *       MCP server (env 1). No relay or tunnel; the browser is launched
+ *       pointing at AIT_DEVTOOLS_URL (default http://localhost:5173).
+ *
+ *   --mode=dev — dev mode — reads the live browser mock state from a running
  *     Vite dev server (the devtools#130 `devtools_get_mock_state` surface).
  *
  * Node-only stdio process.
  */
 type Mode = 'debug' | 'dev';
+type Target = 'relay' | 'local';
 /** Parses `--mode=<value>` / `--mode <value>` from argv; default `debug`. */
 declare function parseMode(argv: readonly string[]): Mode;
+/**
+ * Parses `--target=<value>` / `--target <value>` from argv; default `relay`.
+ *
+ * Only meaningful when `--mode=debug`:
+ *   - `relay`  — phone/WebView attach over Chii relay + cloudflared tunnel (env 2/3).
+ *   - `local`  — local Chromium CDP attach (env 1, no relay needed).
+ */
+declare function parseTarget(argv: readonly string[]): Target;
 //#endregion
-export { parseMode };
+export { 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":";;;;;;;;AAqBA;;;;;;KAHK,IAAA;;iBAGW,SAAA,CAAU,IAAA,sBAA0B,IAAA"}
+{"version":3,"file":"cli.d.ts","names":[],"sources":["../../src/mcp/cli.ts"],"mappings":";;;;;;;;AAyBS;;;;;AAIT;;;;;AAyBA;;;KA7BK,IAAA;AAAA,KACA,MAAA;;iBAGW,SAAA,CAAU,IAAA,sBAA0B,IAAA;;;;;;;;iBAyBpC,WAAA,CAAY,IAAA,sBAA0B,MAAA"}