debugger

한국어 · English

앱인토스(Apps in Toss) 미니앱의 원격 디버깅 인프라 — MCP 디버깅 데몬, on-device CDP relay, test-runner, on-device 콘솔을 담는 pnpm workspace.

@ait-co/devtools가 8개 기능 표면(mock·panel·unplugin·phone preview·on-device debug·remote CDP·MCP server·test runner·in-app console)을 한 패키지에 담고 있었는데, 이를 3 패키지 / 2 repo로 쪼개는 중이며 이 repo가 debug·관측 쪽 절반을 담당한다. 분리의 명시적 동기는 보안 스코프다 — "무엇이 프로덕션 번들에 들어갈 수 있는가"가 package.json 한 장(dep 1개: eruda)으로 답해지도록 만든다.

현재 초기 스캐폴딩 단계입니다. 실제 MCP 데몬·CDP relay·test-runner·on-device 콘솔 구현은 devtools로부터의 후속 vendor 커밋으로 채워질 예정이며, 지금은 workspace 구조 + 빌드/린트/테스트 파이프라인만 갖춰져 있습니다.

설치

pnpm add -D @ait-co/debugger        # MCP 데몬 · CDP relay · test-runner · dev-bridge
pnpm add @ait-co/debug-console      # on-device attach + eruda 콘솔 (프로덕션 번들에 들어갈 수 있는 유일한 패키지)

설치 없이 npx로 바로 실행할 수도 있습니다. 패키지 이름과 bin 이름이 다르므로 -p 형태로 호출합니다:

npx -p @ait-co/debugger debugger

구조

packages/
  debugger/            @ait-co/debugger      — bins: debugger, debugger-test
  debug-console/        @ait-co/debug-console — exports: . 와 ./auto (bin 없음)
  internal-protocol/    비공개, 미publish     — 두 패키지가 공유하는 device<->host 프로토콜 원본

각 패키지의 상세 사용법 · exports · 보안 스코프는 packages/debugger/README.md · packages/debug-console/README.md를 참조하세요.

세 패키지 사이에 필수 의존 edge는 0개다 — 교차 패키지 참조가 필요하면 항상 optional peer로만 선언한다. 자세한 불변식과 시크릿 취급 규칙은 CLAUDE.md를 참조하세요.

개발

pnpm install
pnpm build
pnpm typecheck
pnpm test
pnpm lint

이 repo는 pnpm workspace이므로 build/typecheck/test는 pnpm -r로 각 패키지에 팬아웃되고, lint/format은 Biome이 workspace 전체를 한 번에 검사합니다.

Pre-commit hook

선택 사항이지만 권장합니다. clone 후 표준 pre-commit hook을 활성화하면 staged 파일에 biome check가 자동으로 실행됩니다:

git config core.hooksPath .githooks

push 전 빠른 피드백을 위한 개발자 편의 기능입니다. CI에서도 동일한 검사가 강제 계층으로 실행되므로 hook을 활성화하지 않은 contributor도 PR에서 lint 실패를 확인할 수 있습니다.

릴리즈

Changesets fixed 페어(@ait-co/debugger · @ait-co/debug-console)로 두 패키지의 버전을 항상 함께 올립니다 — 두 패키지는 컴파일 링크 없는 값-복제 wire protocol로 통신하므로, "버전 X = 상호 테스트된 쌍"을 보장하려면 linked가 아니라 fixed가 맞습니다. internal-protocol은 비공개라 이 페어에 들어가지 않습니다.

라이선스

BSD-3-Clause

커뮤니티 오픈소스 프로젝트입니다.