@ait-co/devtools 0.1.45 → 0.1.48

package/README.en.md

@@ -70,12 +70,12 @@ No HMR (Toss WebView cold-load only). Details: [`docs/scenarios/env-3.md`](./doc
 Attach a relay to a live OPENED app to observe runtime behavior.
 
 ```bash
-devtools-mcp              # start MCP server
+MCP_ENV=relay-live devtools-mcp   # start MCP server (LIVE guard enabled)
 # call build_attach_url → scan QR → live app loads + relay attaches
-# call_sdk / evaluate: watch for side effects (real users may be affected)
+# call_sdk / evaluate: confirm: true required (LIVE guard — real users affected)
 ```
 
-Details: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
+`MCP_ENV=relay-live` is required — without it the LIVE side-effect guard is inactive and SDK calls can affect real users. Details: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.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
@@ -948,11 +952,12 @@ A local browser (env 1) and a phone Toss WebView (env 2/3) both speak CDP, so ev
 
 | 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=relay` (default) | `MCP_ENV=relay-dev devtools-mcp` | `MCP_ENV=relay-dev` recommended (env 3, dogfood) | Dogfood bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 3) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
+| `--mode=debug --target=relay` LIVE | `MCP_ENV=relay-live devtools-mcp` | `MCP_ENV=relay-live` **required** (env 4, LIVE guard enabled) | Live deployed app (env 4) — `call_sdk`/`evaluate` require `confirm: true` | same |
 | `--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 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.
+`--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), setting `MCP_ENV=relay-dev` explicitly ensures the relay tool surface is visible before the tunnel URL is auto-detected. For env 4 (LIVE), `MCP_ENV=relay-live` is required — only this value activates the LIVE side-effect guard that protects real users.
 
 ### Debug mode (CDP via Chii)
 
@@ -962,6 +967,24 @@ Read-only tools only. Tools are registered in two tiers based on attach state
 
 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.
 
+Environment 3 (dogfood relay):
+
+```json
+{
+  "mcpServers": {
+    "ait-debug": {
+      "command": "pnpm",
+      "args": ["exec", "devtools-mcp"],
+      "env": {
+        "MCP_ENV": "relay-dev"
+      }
+    }
+  }
+}
+```
+
+Environment 4 (LIVE relay, LIVE guard enabled):
+
 ```json
 {
   "mcpServers": {
@@ -969,14 +992,14 @@ Running `devtools-mcp` as a stdio server starts a local Chii relay on an OS-assi
       "command": "pnpm",
       "args": ["exec", "devtools-mcp"],
       "env": {
-        "MCP_ENV": "relay"
+        "MCP_ENV": "relay-live"
       }
     }
   }
 }
 ```
 
-Setting `MCP_ENV=relay` explicitly ensures the relay tool surface is visible before the tunnel URL is auto-detected.
+Setting `MCP_ENV=relay-dev` explicitly ensures the relay tool surface is visible before the tunnel URL is auto-detected. `MCP_ENV=relay-live` activates the LIVE side-effect guard — any `call_sdk`/`evaluate` call without `confirm: true` is rejected to protect real users. `MCP_ENV=relay` is a backward-compat alias for `relay-dev`, so **always use `relay-live` explicitly for env 4**.
 
 | Tool | CDP / AIT backing | Description |
 |---|---|---|
@@ -989,7 +1012,7 @@ Setting `MCP_ENV=relay` explicitly ensures the relay tool surface is visible bef
 | `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}` |
+| `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 3/4, mock SDK on env 1. Env 2 (PWA) does not inject the SDK — not available there. On env 4, `confirm: true` is required (LIVE guard). 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

@@ -70,12 +70,12 @@ HMR 없음(토스 WebView cold-load만). 상세: [`docs/scenarios/env-3.md`](./d
 검수를 통과하고 OPENED 상태인 실 출시 앱에 relay를 붙여 런타임을 관측합니다.
 
 ```bash
-devtools-mcp              # MCP 서버 시작
+MCP_ENV=relay-live devtools-mcp   # MCP 서버 시작 (LIVE guard 활성화)
 # build_attach_url 호출 → QR 스캔 → LIVE 앱 로드 + relay attach
-# call_sdk / evaluate 는 side-effect 주의 (실유저 영향)
+# call_sdk / evaluate 는 confirm: true 필수 (LIVE guard — 실유저 영향)
 ```
 
-상세: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
+`MCP_ENV=relay-live` 필수 — 미설정 시 LIVE side-effect guard가 비활성화되어 실유저에게 영향을 줄 수 있습니다. 상세: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.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초 이내에 스캔하세요.
+
 ---
 
 ## 설치
@@ -978,11 +982,12 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 
 | 모드 + 타깃 | 호출 | 환경 변수 | 대상 | 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=relay` (기본값) | `MCP_ENV=relay-dev devtools-mcp` | `MCP_ENV=relay-dev` 권장 (환경 3, dogfood) | 폰 안 dogfood 번들 (CDP/Chii relay + cloudflared 터널, 환경 3) | console/network/page + DOM/snapshot/screenshot + `AIT.*` |
+| `--mode=debug --target=relay` LIVE | `MCP_ENV=relay-live devtools-mcp` | `MCP_ENV=relay-live` **필수** (환경 4, LIVE guard 활성화) | LIVE 배포 앱 (환경 4) — `call_sdk`/`evaluate`에 `confirm: true` 필요 | 동일 |
 | `--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를 읽으며 CDP tool은 제공하지 않습니다. 실기기(환경 3·4) 진입 시 `MCP_ENV=relay`를 명시하면 터널 감지 전 bootstrap 단계에서도 relay tool이 올바르게 노출됩니다.
+`--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) 진입 시 `MCP_ENV=relay-dev`를 명시하면 터널 감지 전에도 relay tool이 올바르게 노출됩니다. 환경 4(LIVE)는 `MCP_ENV=relay-live` 필수 — LIVE side-effect guard(실유저 보호)가 이 값일 때만 활성화됩니다.
 
 ### Debug 모드 (CDP via Chii)
 
@@ -1000,6 +1005,24 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 에이전트가 `chrome-devtools-mcp` 호환 tool로 console/network/page 상태를 read합니다. 사람이 폰을
 지켜볼 필요 없이 회귀를 단독 진단하는 것이 목표입니다.
 
+환경 3 (dogfood relay):
+
+```json
+{
+  "mcpServers": {
+    "ait-debug": {
+      "command": "pnpm",
+      "args": ["exec", "devtools-mcp"],
+      "env": {
+        "MCP_ENV": "relay-dev"
+      }
+    }
+  }
+}
+```
+
+환경 4 (LIVE relay, LIVE guard 활성화):
+
 ```json
 {
   "mcpServers": {
@@ -1007,14 +1030,14 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
       "command": "pnpm",
       "args": ["exec", "devtools-mcp"],
       "env": {
-        "MCP_ENV": "relay"
+        "MCP_ENV": "relay-live"
       }
     }
   }
 }
 ```
 
-`MCP_ENV=relay`를 명시하면 터널 URL 자동 감지 전에도 relay tool surface가 올바르게 노출됩니다.
+`MCP_ENV=relay-dev`를 명시하면 터널 URL 자동 감지 전에도 relay tool surface가 올바르게 노출됩니다. `MCP_ENV=relay-live`는 LIVE side-effect guard를 활성화합니다 — `call_sdk`/`evaluate`에 `confirm: true`가 없으면 거부하여 실유저 영향을 방지합니다. `MCP_ENV=relay`는 backward-compat alias로 `relay-dev`로 해석되므로 **환경 4에서는 `relay-live`를 명시해야 합니다**.
 
 | Tool | CDP / AIT 백킹 | 설명 |
 |---|---|---|
@@ -1027,7 +1050,7 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 | `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}` 반환 |
+| `call_sdk` | `window.__sdkCall` 브리지 (`Runtime.evaluate` 경유) | dogfood SDK 메서드를 `window.__sdkCall` 브리지로 호출 (`@apps-in-toss/web-framework`가 `__DEBUG_BUILD__` 번들에서만 export). **read-only 아님** — SDK 호출은 부작용(내비게이션·결제·권한 등). 환경 3·4(실기기 relay)에선 실 SDK, 환경 1(로컬 mock)에선 mock SDK. 환경 2(PWA)는 SDK 미주입으로 사용 불가. 환경 4에서는 `confirm: true` 필수(LIVE guard). 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 버전 |