@ait-co/debug-console 0.1.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DaveDev42
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.en.md

@@ -0,0 +1,75 @@
+# @ait-co/debug-console
+
+[한국어](./README.md) · **English**
+
+[![npm](https://img.shields.io/npm/v/@ait-co/debug-console)](https://www.npmjs.com/package/@ait-co/debug-console)
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
+
+On-device attach + eruda console for Apps in Toss mini-apps. **The only package in this split that can enter a production bundle** — it has exactly one dependency, [`eruda`](https://github.com/liriliri/eruda), and zero peerDependencies, so it is completely agnostic to the SDK version (2.x/3.x) it ships alongside.
+
+## Install
+
+```sh
+pnpm add @ait-co/debug-console
+```
+
+With no peerDependency, you can add this regardless of whether `@apps-in-toss/web-framework` is installed or which version it is. The SDK bridge (`window.__sdk` below) probes for the SDK at runtime via a dynamic import and silently skips itself when the SDK is absent.
+
+## Usage
+
+### Self-gating entry (recommended)
+
+Add a single line to your mini-app entry. With no debug activation signal present (`?debug=1` + `?relay=`, or a DEV build), it does nothing:
+
+```ts
+import '@ait-co/debug-console/auto';
+```
+
+Once activated, it installs two things: (1) an on-device Chii target injection (remote CDP attach), and (2) `window.__sdk` / `window.__sdkCall` — a bridge letting an agent call any SDK API directly over the CDP relay.
+
+`/auto` is a runtime self-gate — it does not guarantee "zero bytes of code" in the release bundle (a dormant, unactivated chunk remains). If you need that guarantee, gate the import yourself at build time:
+
+```ts
+if (__DEBUG_BUILD__) {
+  import('@ait-co/debug-console').then((m) => m.maybeAttach());
+}
+```
+
+Building the release with `define: { __DEBUG_BUILD__: 'false' }` lets the bundler dead-code-eliminate the entire `@ait-co/debug-console` graph.
+
+### Bonus: standalone eruda console, no relay
+
+`mountEruda()` / `unmountEruda()` are exports you can call directly, independent of the gate above. To show only an in-page eruda console on the phone screen — no relay, no attach:
+
+```ts
+import { mountEruda } from '@ait-co/debug-console';
+
+if (import.meta.env.DEV) {
+  mountEruda();
+}
+```
+
+## Exports
+
+| subpath | contents |
+|---|---|
+| `@ait-co/debug-console` | full API — `checkDebugGate`, `maybeAttach`, `mountEruda`/`unmountEruda`, gate types/helpers |
+| `@ait-co/debug-console/auto` | side-effect-only self-gating entry (usage example above) |
+
+No bins are shipped.
+
+## Relationship with `@ait-co/devtools`
+
+`@ait-co/devtools` owns the mock SDK, the DevTools panel, and the unplugin (the browser dev environment, station 2), while this package owns the in-app half of real-device attach (station 3). If `@ait-co/debugger` is the host-side (PC) MCP daemon and CDP relay, `@ait-co/debug-console` is the phone-side (device) target that relay attaches to — the Chii target injection and the eruda console overlay. This split breaks what used to be a single `@ait-co/devtools` package holding all 8 feature surfaces into "browser dev environment" and "real-device debugging," and this package is the half that must keep the narrowest dependency surface of all — it is the only piece that can ship to production.
+
+## Security scope
+
+**This package can genuinely end up in a production bundle** — which is exactly why its dependency is pinned to `eruda` alone with zero peerDependencies. Attach only happens after a 3-layer activation gate passes: (B) host allowlist + deployment entry param, (C) `debug=1` opt-in + a valid `wss:` relay URL + (when configured) a TOTP code. If the gate does not pass, no attach occurs, and a gate failure is only ever surfaced as one of the enum values `'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth'` — no secret, code value, or relay URL itself ever reaches any log.
+
+## License
+
+BSD-3-Clause
+
+---
+
+Community open-source project.

package/README.md

@@ -0,0 +1,75 @@
+# @ait-co/debug-console
+
+**한국어** · [English](./README.en.md)
+
+[![npm](https://img.shields.io/npm/v/@ait-co/debug-console)](https://www.npmjs.com/package/@ait-co/debug-console)
+[![license](https://img.shields.io/badge/license-BSD--3--Clause-blue)](./LICENSE)
+
+앱인토스(Apps in Toss) 미니앱의 on-device attach + eruda 콘솔. **이번 분리에서 프로덕션 번들에 들어갈 수 있는 유일한 패키지**다 — dependency는 [`eruda`](https://github.com/liriliri/eruda) 하나뿐이고 peerDependency는 0개라, SDK 버전(2.x/3.x)과 완전히 무관하게 동작한다.
+
+## 설치
+
+```sh
+pnpm add @ait-co/debug-console
+```
+
+peerDependency가 없으므로 `@apps-in-toss/web-framework`의 설치 여부·버전과 무관하게 그대로 추가할 수 있다. SDK 브릿지(아래 `window.__sdk`)는 런타임에 동적 import로 SDK 존재 여부를 probe하며, SDK가 없으면 조용히 스킵된다.
+
+## 사용
+
+### 자동 게이팅 엔트리 (권장)
+
+미니앱 엔트리에 한 줄만 추가한다. 디버그 활성화 신호(`?debug=1` + `?relay=`, 또는 DEV 빌드)가 없으면 아무 동작도 하지 않는다:
+
+```ts
+import '@ait-co/debug-console/auto';
+```
+
+활성화되면 두 가지가 설치된다: (1) on-device Chii 타겟 injection(원격 CDP attach), (2) `window.__sdk` / `window.__sdkCall` — 에이전트가 CDP relay 너머로 임의의 SDK API를 직접 호출할 수 있게 해주는 브릿지.
+
+`/auto`는 런타임 self-gate다 — release 번들에서 "코드가 물리적으로 0바이트"를 보장하지는 않는다(활성화되지 않은 채로 잠들어 있는 청크는 남는다). 그 보장이 필요하면 consumer가 직접 build-time 게이트를 두고 명시적으로 import한다:
+
+```ts
+if (__DEBUG_BUILD__) {
+  import('@ait-co/debug-console').then((m) => m.maybeAttach());
+}
+```
+
+`define: { __DEBUG_BUILD__: 'false' }`로 release 빌드하면 번들러가 `@ait-co/debug-console` 그래프 전체를 dead-code-eliminate한다.
+
+### 보너스: relay 없는 단독 eruda 콘솔
+
+`mountEruda()` / `unmountEruda()`는 위 gate와 무관하게 직접 호출할 수 있는 export다. relay·attach 없이 폰 화면 위에 eruda 콘솔만 띄우고 싶다면:
+
+```ts
+import { mountEruda } from '@ait-co/debug-console';
+
+if (import.meta.env.DEV) {
+  mountEruda();
+}
+```
+
+## Exports
+
+| subpath | 내용 |
+|---|---|
+| `@ait-co/debug-console` | `checkDebugGate`, `maybeAttach`, `mountEruda`/`unmountEruda`, gate 타입/헬퍼 등 전체 API |
+| `@ait-co/debug-console/auto` | side-effect 전용 자동 게이팅 엔트리 (위 사용 예시) |
+
+bin은 없다.
+
+## `@ait-co/devtools`와의 관계
+
+`@ait-co/devtools`는 mock SDK · DevTools 패널 · unplugin(브라우저 dev 환경, station 2)을 담당하고, 이 패키지는 실기기 attach의 in-app 절반(station 3)을 담당한다. `@ait-co/debugger`가 host(PC) 쪽 MCP 데몬·CDP relay라면, `@ait-co/debug-console`은 phone(device) 쪽에서 그 relay에 붙는 대상 — Chii 타겟 injection과 eruda 콘솔 오버레이다. 8개 기능 표면을 담던 하나의 `devtools` 패키지를 이번 분리에서 "브라우저 dev 환경"과 "실기기 디버깅"으로 나눈 결과이며, 이 패키지는 그중에서도 dependency 표면이 가장 좁아야 하는 쪽 — 프로덕션에 실릴 수 있는 유일한 조각이기 때문이다.
+
+## 보안 스코프
+
+**이 패키지는 프로덕션 번들에 실제로 들어갈 수 있다** — 그래서 dependency가 `eruda` 하나로 고정되어 있고 peerDependency는 0개다. attach는 3단계 활성화 게이트를 통과해야만 이뤄진다: (B) 호스트 allowlist + 배포 엔트리 파라미터, (C) `debug=1` opt-in + 유효한 `wss:` relay URL + (설정된 경우) TOTP 코드. 이 게이트를 통과하지 못하면 attach는 일어나지 않으며, gate 실패 사유는 `'host' | 'entry' | 'opt-in' | 'invalid-relay' | 'auth'` enum 값으로만 노출된다 — 시크릿·코드 값·relay URL 자체는 어떤 로그에도 남지 않는다.
+
+## 라이선스
+
+BSD-3-Clause
+
+---
+
+커뮤니티 오픈소스 프로젝트입니다.