debugger

한국어 · English

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

이 프로젝트는 더 이상 유지보수되지 않는다. repo는 archive되어 read-only가 되지만 소스와 이슈 기록은 GitHub에 그대로 남고, npm에 게시된 @ait-co/debugger · @ait-co/debug-console도 계속 설치할 수 있다 — 다만 더 이상 업데이트되지 않는다. aitc.dev 도메인과 그 위에서 돌던 사이트는 종료되므로, 문서는 docs repo의 소스 파일에서 본다. 실기기 attach에 쓰는 launcher PWA도 같은 도메인(devtools.aitc.dev/launcher/)에 있어 함께 사라진다 — @ait-co/debugger가 만드는 attach 딥링크가 이 호스트를 가리키므로, 도메인이 내려간 뒤에는 이 경로가 동작하지 않는다. 대체 호스트가 없어 상수 값은 그대로 두었다.

@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)으로 답해지도록 만든다.

패키지	repo	내용	소비 형태
@ait-co/devtools	devtools	mock · panel · unplugin	devDependency 전용, 번들 기여 0
@ait-co/debugger	여기	MCP 데몬 · CDP relay · test-runner · dev-bridge	devDependency / npx
@ait-co/debug-console	여기	on-device attach · eruda 콘솔	앱 번들에 들어갈 수 있는 유일한 패키지

분리는 완료됐다 — MCP 데몬·CDP relay·test-runner·on-device 콘솔 구현이 모두 이 workspace에 들어와 있고, 두 패키지는 npm에 출하 중이다. @ait-co/devtools는 0.2.0에서 debug 표면을 넘겨준 뒤 mock·panel·unplugin만 담는다.

설치

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를 참조하세요.

분리 때 devtools에서 이관되며 번호가 바뀐 이슈 10건의 매핑은 docs/issue-transfer-map.md에 있습니다 — 옛 devtools#N 참조를 만나면 여기서 찾으세요.

개발

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

---

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