feat: rn-mcp CLI with Snapshot + Refs pattern

[ohah]

Summary

• agent-browser 스타일의 Snapshot + Refs 패턴을 React Native에 적용한 CLI 도구 (rn-mcp)
• AI 에이전트(Claude Code, Codex 등)가 셸에서 직접 앱을 제어 — MCP 도구 대비 토큰 50~70% 절감
• init-agent 명령으로 AGENTS.md/CLAUDE.md에 CLI 가이드 자동 추가 (한영 지원)

주요 명령어

rn-mcp snapshot -i           # interactive 요소를 @e1, @e2 refs로 반환
rn-mcp tap @e3               # ref로 탭 (좌표 자동 변환)
rn-mcp type @e5 "텍스트"      # TextInput에 입력
rn-mcp assert text "..."     # 텍스트 검증 (exit 0/1)
rn-mcp init-agent --lang ko  # AGENTS.md/CLAUDE.md 가이드 추가

아키텍처

• WebSocket extension client로 기존 MCP 서버에 연결 (별도 서버 불필요)
• ~/.rn-mcp/session.json에 refs 매핑 저장 (CLI 호출 간 상태 공유)
• idb/adb 직접 실행 (기존 유틸 재사용)
• bin: rn-mcp → dist/cli.js (기존 패키지에 entry point 추가)

파일 구조

파일	역할
src/cli.ts	CLI entry point + --help + 라우팅
src/cli/ws-client.ts	WebSocket extension client
src/cli/session.ts	~/.rn-mcp/session.json 세션 관리
src/cli/ref-map.ts	Snapshot → @ref 할당
src/cli/commands.ts	명령어 구현 (status, snapshot, tap, type, assert, query, swipe, key, screenshot, init-agent)
src/cli/agent-guide.ts	AGENTS.md/CLAUDE.md 가이드 텍스트 (한영)
src/shared/interactive-types.ts	INTERACTIVE_TYPES 공유 상수 (take-snapshot + ref-map)
docs/cli-spec.md	CLI 설계 스펙 문서

CI 변경

• test.yml: CLI smoke test + init-agent 통합 테스트 추가
• e2e-ios.yml: YAML E2E 후 CLI smoke test 실행
• e2e-android.yml: YAML E2E 후 CLI smoke test 실행 + adb PATH 설정 + libgl1-mesa-dri 삭제 제거
• cli-smoke.sh: 10단계 CLI 통합 테스트 (status, snapshot, tap, assert, query, init-agent)

코드 리뷰 반영 (/simplify)

• eval 코드 빌더 중복 제거 → buildQuerySelectorEvalCode 등 기존 export 재사용
• INTERACTIVE_TYPES 중복 → shared/interactive-types.ts로 추출
• assert text false-positive 수정 → :text() 셀렉터 기반
• loadSession() 3회 호출 → 1회로
• Android screencap 이중 실행 제거
• WebSocket close 핸들러 추가
• 죽은 코드/import 제거

Test plan

• 유닛 테스트 24개 (ref-map, session, agent-guide, CLI help)
• CI smoke test (--help, --version, init-agent)
• E2E iOS — CLI smoke test 10단계 통과
• E2E Android — CLI smoke test 10단계 통과
• 린트 (oxlint + oxfmt) 통과
• 전체 CI 통과 확인

🤖 Generated with Claude Code