@ait-co/devtools 0.1.56 → 0.1.57

package/README.en.md

@@ -73,13 +73,12 @@ Attach a relay to a live OPENED app to observe runtime behavior.
 
 ```bash
 devtools-mcp   # start MCP server
-# In Claude Code: start_debug({mode: 'live', confirm: true})  ← arms LIVE guard
+# In Claude Code: start_debug({mode: 'relay-live', confirm: true})  ← arms LIVE guard
 # call build_attach_url → scan QR → live app loads + relay attaches
 # call_sdk / evaluate: confirm: true required (LIVE guard — real users affected)
-# (deprecated alias: MCP_ENV=relay-live devtools-mcp — kept for boot-time liveIntent seeding only)
 ```
 
-`start_debug({mode: 'live', confirm: true})` arms the LIVE guard in-session. Details: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
+`start_debug({mode: 'relay-live', confirm: true})` arms the LIVE guard in-session. Details: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
 
 ---
 
@@ -119,9 +118,20 @@ npm install -D @ait-co/devtools
 pnpm add -D @ait-co/devtools
 ```
 
-> **Supported SDK version**: `@apps-in-toss/web-framework 3.0.0-beta.9d42c0b` (beta, peer optional).
->
-> devtools currently tracks the web-framework **3.0.0-beta** pre-release. Since beta versions are not resolved by `^3.0.0`, install using an exact pin: `@apps-in-toss/web-framework@3.0.0-beta.9d42c0b`. The peer range and pin will be updated when stable 3.0.0 GA ships. Calling an API that devtools has not yet mocked will throw a runtime error — please [file an issue](https://github.com/apps-in-toss-community/devtools/issues) for missing APIs.
+### Two channels — stable and beta
+
+devtools runs two npm dist-tags off the same code at once. Pick the channel that matches your web-framework version.
+
+| Channel | Install | web-framework peer |
+|---|---|---|
+| **stable** (`latest`, default) | `pnpm add -D @ait-co/devtools` | `>=2.6.0 <2.7.0` (2.x) |
+| **beta** | `pnpm add -D @ait-co/devtools@beta` | `>=3.0.0-beta <4.0.0` (3.0 line) |
+
+- On web-framework **2.x**, the default install (stable) is all you need.
+- On the web-framework **3.0.0-beta** pre-release, install the `@beta` channel. It is a snapshot auto-published on every main push (`0.0.0-beta-<datetime>-<sha>`), so the versions are hard to pin — install with the `@beta` tag.
+- Both channels keep the web-framework peer `optional`, so MCP-only debugging users are never forced to pull the SDK.
+
+When 3.0 ships GA, the stable `latest` peer moves up to the 3.0 line and the beta channel is retired. Calling an API that devtools has not yet mocked will throw a runtime error — please [file an issue](https://github.com/apps-in-toss-community/devtools/issues) for missing APIs.
 
 ## Reference consumer
 
@@ -947,13 +957,13 @@ A local browser (env 1) and a phone Toss WebView (env 2/3) both speak CDP, so ev
 
 | Mode + target | Invocation | Env vars | Target | Tools |
 |---|---|---|---|---|
-| `--target=mobile` (env 2) | `devtools-mcp` → `start_debug({mode:'mobile'})` | `AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL` | Real-device Safari/WebKit PWA (external Chii relay + cloudflared tunnel, env 2) | console/network/page + DOM/snapshot/screenshot |
-| `--mode=debug --target=relay` (default, env 3) | `devtools-mcp` → `start_debug({mode: 'staging'})` | `MCP_ENV=relay-dev` (deprecated boot alias) | Dogfood bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 3) | same + `AIT.*` |
-| `--mode=debug --target=relay` LIVE (env 4) | `devtools-mcp` → `start_debug({mode: 'live', confirm: true})` | `MCP_ENV=relay-live` (deprecated boot alias, env 4 LIVE guard) | Live deployed app (env 4) — `call_sdk`/`evaluate` require `confirm: true` | same |
+| `--target=mobile` (env 2) | `devtools-mcp` → `start_debug({mode:'relay-sandbox'})` | `AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL` | Real-device Safari/WebKit PWA (external Chii relay + cloudflared tunnel, env 2) | console/network/page + DOM/snapshot/screenshot |
+| `--mode=debug --target=relay` (default, env 3) | `devtools-mcp` → `start_debug({mode: 'relay-staging'})` | — | Dogfood bundle on a phone (CDP/Chii relay + cloudflared tunnel, env 3) | same + `AIT.*` |
+| `--mode=debug --target=relay` LIVE (env 4) | `devtools-mcp` → `start_debug({mode: 'relay-live', confirm: true})` | — (env 4 LIVE guard) | Live deployed app (env 4) — `call_sdk`/`evaluate` require `confirm: true` | same |
 | `--mode=debug --target=local` (env 1) | `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. Switch environments in-session with `start_debug(mode)`: `mobile` (env 2 PWA), `staging` (env 3 dogfood), `live` (env 4, arms LIVE guard — `confirm: true` required), `local` (env 1). `MCP_ENV=relay-dev`/`MCP_ENV=relay-live` are deprecated boot-time aliases for liveIntent seeding — prefer `start_debug` for in-session switching.
+`--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. Switch environments in-session with `start_debug(mode)`: `relay-sandbox` (env 2 PWA), `relay-staging` (env 3 dogfood), `relay-live` (env 4, arms LIVE guard — `confirm: true` required), `local-browser` (env 1).
 
 #### Environment 2 (real-device PWA CDP) — `--target=mobile`
 
@@ -987,7 +997,7 @@ Debug on a real phone using Safari/WebKit without Toss review. The Vite dev serv
 
 3. In a Claude Code session:
    ```
-   start_debug({mode: 'mobile'})
+   start_debug({mode: 'relay-sandbox'})
    build_attach_url()
    ```
    Scan the QR with your phone camera. The launcher PWA opens the app in a frame and injects Chii target.js.
@@ -1006,39 +1016,23 @@ 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) — `start_debug({mode: 'staging'})` is the primary in-session entry:
+Environments 3 and 4 (intoss-private relay) — start `devtools-mcp` as-is, then enter via `start_debug(mode)`:
 
 ```json
 {
   "mcpServers": {
     "ait-debug": {
       "command": "pnpm",
-      "args": ["exec", "devtools-mcp"],
-      "env": {
-        "MCP_ENV": "relay-dev"
-      }
+      "args": ["exec", "devtools-mcp"]
     }
   }
 }
 ```
 
-Environment 4 (LIVE relay, LIVE guard enabled) — `start_debug({mode: 'live', confirm: true})` is the primary in-session entry:
-
-```json
-{
-  "mcpServers": {
-    "ait-debug": {
-      "command": "pnpm",
-      "args": ["exec", "devtools-mcp"],
-      "env": {
-        "MCP_ENV": "relay-live"
-      }
-    }
-  }
-}
-```
+- Environment 3 (dogfood relay): `start_debug({mode: 'relay-staging'})`
+- Environment 4 (LIVE relay, LIVE guard enabled): `start_debug({mode: 'relay-live', confirm: true})`
 
-`MCP_ENV=relay-dev`/`MCP_ENV=relay-live` are deprecated boot-time aliases that ensure the relay tool surface is visible before the tunnel URL is auto-detected and seed liveIntent on boot. **Prefer `start_debug(mode)` for in-session switching**: `staging` (env 3), `live` (env 4, arms LIVE guard — `confirm: true` required). `MCP_ENV=relay` is a backward-compat alias for `relay-dev`, so **always use `relay-live` (or `start_debug(live)`) explicitly for env 4**.
+**`start_debug(mode)` is the single in-session entry path.** `MCP_ENV=relay-live` remains only as a deprecated alias that seeds `liveIntent` at boot — in a new session, enter via `start_debug({mode: 'relay-live', confirm: true})`.
 
 | Tool | CDP / AIT backing | Description |
 |---|---|---|

package/README.md

@@ -73,13 +73,12 @@ HMR 없음(토스 WebView cold-load만). 상세: [`docs/scenarios/env-3.md`](./d
 
 ```bash
 devtools-mcp   # MCP 서버 시작
-# Claude Code에서: start_debug({mode: 'live', confirm: true})  ← LIVE guard 활성화
+# Claude Code에서: start_debug({mode: 'relay-live', confirm: true})  ← LIVE guard 활성화
 # build_attach_url 호출 → QR 스캔 → LIVE 앱 로드 + relay attach
 # call_sdk / evaluate 는 confirm: true 필수 (LIVE guard — 실유저 영향)
-# (deprecated 별칭: MCP_ENV=relay-live devtools-mcp — 부팅 시 liveIntent 시드용으로만 남음)
 ```
 
-`start_debug({mode: 'live', confirm: true})`가 LIVE guard를 활성화합니다. 상세: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
+`start_debug({mode: 'relay-live', confirm: true})`가 LIVE guard를 활성화합니다. 상세: [`docs/scenarios/env-4.md`](./docs/scenarios/env-4.md)
 
 ---
 
@@ -119,9 +118,20 @@ npm install -D @ait-co/devtools
 pnpm add -D @ait-co/devtools
 ```
 
-> **지원 SDK 버전**: `@apps-in-toss/web-framework 3.0.0-beta.9d42c0b` (beta, peer optional).
->
-> 현재 devtools는 web-framework **3.0.0-beta** 프리릴리즈를 추적합니다. beta 버전은 `^3.0.0`으로 resolve되지 않으므로 설치 시 exact pin(`@apps-in-toss/web-framework@3.0.0-beta.9d42c0b`)을 사용하세요. stable 3.0.0 GA 출시 후 peer range와 pin이 업데이트됩니다. devtools가 아직 mock하지 않은 API를 호출하면 런타임에 에러가 발생합니다 — 누락된 API는 [이슈](https://github.com/apps-in-toss-community/devtools/issues)로 알려주세요.
+### 두 채널 — stable과 beta
+
+devtools는 같은 코드에서 두 개의 npm dist-tag를 동시에 운영합니다. 쓰는 web-framework 버전에 맞는 채널을 고르세요.
+
+| 채널 | 설치 | web-framework peer |
+|---|---|---|
+| **stable** (`latest`, 기본) | `pnpm add -D @ait-co/devtools` | `>=2.6.0 <2.7.0` (2.x) |
+| **beta** | `pnpm add -D @ait-co/devtools@beta` | `>=3.0.0-beta <4.0.0` (3.0 라인) |
+
+- web-framework **2.x**를 쓰면 위 기본 설치(stable)면 됩니다.
+- web-framework **3.0.0-beta** 프리릴리즈를 쓰면 `@beta` 채널을 설치하세요. 이 채널은 main push마다 자동 publish되는 스냅샷(`0.0.0-beta-<datetime>-<sha>`)이라 버전을 핀하기 어려우니 `@beta` 태그로 설치하는 걸 권장합니다.
+- 두 채널 모두 web-framework peer는 `optional`이라 MCP 디버깅만 쓰는 경우 SDK를 강제로 끌어오지 않습니다.
+
+3.0이 정식(GA) 출시되면 stable `latest` peer가 3.0 라인으로 올라가고 beta 채널은 정리됩니다. devtools가 아직 mock하지 않은 API를 호출하면 런타임에 에러가 발생합니다 — 누락된 API는 [이슈](https://github.com/apps-in-toss-community/devtools/issues)로 알려주세요.
 
 ## Reference consumer
 
@@ -977,13 +987,13 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 
 | 모드 + 타깃 | 호출 | 환경 변수 | 대상 | tool |
 |---|---|---|---|---|
-| `--target=mobile` (env 2) | `devtools-mcp` → `start_debug({mode:'mobile'})` | `AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL` | 실기기 Safari/WebKit PWA (외부 Chii relay + cloudflared 터널, 환경 2) | console/network/page + DOM/snapshot/screenshot |
-| `--mode=debug --target=relay` (기본값, env 3) | `devtools-mcp` → `start_debug({mode: 'staging'})` | `MCP_ENV=relay-dev` (deprecated 부팅 별칭) | 폰 안 dogfood 번들 (CDP/Chii relay + cloudflared 터널, 환경 3) | 동일 + `AIT.*` |
-| `--mode=debug --target=relay` LIVE (env 4) | `devtools-mcp` → `start_debug({mode: 'live', confirm: true})` | `MCP_ENV=relay-live` (deprecated 부팅 별칭, **환경 4 LIVE guard**) | LIVE 배포 앱 (환경 4) — `call_sdk`/`evaluate`에 `confirm: true` 필요 | 동일 |
+| `--target=mobile` (env 2) | `devtools-mcp` → `start_debug({mode:'relay-sandbox'})` | `AIT_RELAY_BASE_URL`, `AIT_TUNNEL_BASE_URL` | 실기기 Safari/WebKit PWA (외부 Chii relay + cloudflared 터널, 환경 2) | console/network/page + DOM/snapshot/screenshot |
+| `--mode=debug --target=relay` (기본값, env 3) | `devtools-mcp` → `start_debug({mode: 'relay-staging'})` | — | 폰 안 dogfood 번들 (CDP/Chii relay + cloudflared 터널, 환경 3) | 동일 + `AIT.*` |
+| `--mode=debug --target=relay` LIVE (env 4) | `devtools-mcp` → `start_debug({mode: 'relay-live', confirm: true})` | — (**환경 4 LIVE guard**) | LIVE 배포 앱 (환경 4) — `call_sdk`/`evaluate`에 `confirm: true` 필요 | 동일 |
 | `--mode=debug --target=local` (env 1) | `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은 제공하지 않습니다. 세션 내 환경 전환은 `start_debug(mode)` 한 번으로 처리됩니다: `mobile`(env 2 PWA), `staging`(env 3 dogfood), `live`(env 4 LIVE guard 활성화, `confirm: true` 필수), `local`(env 1). `MCP_ENV=relay-dev`/`MCP_ENV=relay-live`는 부팅 시 liveIntent 시드용 deprecated 별칭 — 새 세션에서는 `start_debug`로 전환하세요.
+`--target=local`은 `AIT_DEVTOOLS_URL`(기본 `http://localhost:5173`)을 열고 로컬 Chromium에 CDP direct-attach합니다 — relay나 터널이 필요하지 않습니다. `--mode=dev`는 Vite dev server의 mock-state HTTP endpoint를 읽으며 CDP tool은 제공하지 않습니다. 세션 내 환경 전환은 `start_debug(mode)` 한 번으로 처리됩니다: `relay-sandbox`(env 2 PWA), `relay-staging`(env 3 dogfood), `relay-live`(env 4 LIVE guard 활성화, `confirm: true` 필수), `local-browser`(env 1).
 
 #### 환경 2 (실기기 PWA CDP) — `--target=mobile`
 
@@ -1017,7 +1027,7 @@ AI 코딩 에이전트(Claude Code, Cursor 등)가 [MCP(Model Context Protocol)]
 
 3. Claude Code 세션에서 진입:
    ```
-   start_debug({mode: 'mobile'})
+   start_debug({mode: 'relay-sandbox'})
    build_attach_url()
    ```
    QR을 폰 카메라로 스캔하면 런처 PWA가 앱을 프레임에 열고 Chii target.js를 주입합니다.
@@ -1044,39 +1054,23 @@ tunnel로 공개 `wss://*.trycloudflare.com` URL을 발급한 뒤 QR을 터미
 에이전트가 `chrome-devtools-mcp` 호환 tool로 console/network/page 상태를 read합니다. 사람이 폰을
 지켜볼 필요 없이 회귀를 단독 진단하는 것이 목표입니다.
 
-환경 3 (dogfood relay) — `start_debug({mode: 'staging'})`이 세션 내 1차 진입:
+환경 3·4 (intoss-private relay) — `devtools-mcp`를 그대로 기동한 뒤 `start_debug(mode)`로 진입합니다:
 
 ```json
 {
   "mcpServers": {
     "ait-debug": {
       "command": "pnpm",
-      "args": ["exec", "devtools-mcp"],
-      "env": {
-        "MCP_ENV": "relay-dev"
-      }
+      "args": ["exec", "devtools-mcp"]
     }
   }
 }
 ```
 
-환경 4 (LIVE relay, LIVE guard 활성화) — `start_debug({mode: 'live', confirm: true})`이 세션 내 1차 진입:
-
-```json
-{
-  "mcpServers": {
-    "ait-debug": {
-      "command": "pnpm",
-      "args": ["exec", "devtools-mcp"],
-      "env": {
-        "MCP_ENV": "relay-live"
-      }
-    }
-  }
-}
-```
+- 환경 3 (dogfood relay): `start_debug({mode: 'relay-staging'})`
+- 환경 4 (LIVE relay, LIVE guard 활성화): `start_debug({mode: 'relay-live', confirm: true})`
 
-`MCP_ENV=relay-dev`/`MCP_ENV=relay-live`는 부팅 시 env 힌트로 relay tool surface 노출을 앞당기는 deprecated 별칭입니다. **세션 내 환경 전환은 `start_debug(mode)` 사용이 1차 경로**: `staging`(env 3), `live`(env 4, LIVE guard 활성화 — `confirm: true` 필수). `MCP_ENV=relay`는 backward-compat alias로 `relay-dev`로 해석되므로 **환경 4에서는 `relay-live` 별칭(또는 `start_debug(live)`)을 명시해야 합니다**.
+**세션 내 환경 전환은 `start_debug(mode)`가 단일 진입 경로**입니다. `MCP_ENV=relay-live`는 부팅 시 `liveIntent`를 미리 시드하는 deprecated 별칭으로만 남아 있습니다 — 새 세션에서는 `start_debug({mode: 'relay-live', confirm: true})`로 진입하세요.
 
 | Tool | CDP / AIT 백킹 | 설명 |
 |---|---|---|