pubuilder 03. 라우트 스캔 CLI와 AI 퍼블리싱 서버 구축
수동 IA(페이지 구조) 설정 비용을 줄일 라우트 스캔 CLI를 만들고, 오후에는 선택한 블록을 실제 코드로 잇는 Phase 3 AI 퍼블리싱의 서버 코어까지 세웠다.
Phase 3 전에 scan CLI를 먼저 만들었다
Phase 3에 바로 들어가는 대신 라우트 자동 스캔 CLI를 먼저 만들었다(v0.2.0). IA를 손으로 하나씩 적는 비용이 계속 쌓이고 있었기 때문이다.
CLI는 Next.js App Router와 Pages Router의 파일 구조를 스캔해 IAPage 트리를 만든다. 이때 route group(URL 경로에 포함되지 않는 (...) 그룹 폴더)은 URL에서 제외하고, 동적·catch-all 세그먼트([...slug]처럼 여러 경로를 한 번에 받는 동적 세그먼트)는 패턴으로 보존하며, private·API·병렬·인터셉트 라우트는 제외했다. 파일 기반 라우팅 스캔은 파일명을 모으는 일이 아니라 프레임워크의 "URL에 포함되지 않는 세그먼트" 규칙을 정확히 모델링하는 일이 핵심이었다.
스캔 결과는 ia.config.ts로 직렬화하고 기존 설정과 보존 머지했다. 생성·머지·--dry-run·미지원 프로젝트 처리까지 CLI 하나로 연결하고, Vitest 픽스처와 단위 테스트를 붙인 뒤 CLI 전용 빌드 타깃과 bin 엔트리를 구성했다.
여기서 자동 생성 도구는 최초 생성보다 재실행 시 사용자 수정을 보존하는 머지 정책이 더 중요하다는 걸 확인했다. 스캔 결과로 파일 전체를 덮어쓰면 사용자가 손으로 넣은 title·metadata·variants가 사라지기 때문이다.
npm 공개 배포를 준비했다
CLI가 돌아가는 걸 확인한 뒤 npm 공개 배포를 준비했다(v0.3.0). production 환경에서는 PageMap이 렌더되지 않도록 자동 가드를 넣었다. 개발 도구용 오버레이가 실제 배포 화면에 새어 나가면 안 되기 때문이다.
license, engines, keywords, description, publishConfig와 패키지 README를 정비하고, 실제 배포 tarball을 만들어 내용물을 검증했다.
Phase 3 서버 코어 — Figma·스킬·프롬프트·잡으로 쪼갰다
오후에는 Figma 링크와 선택 블록을 로컬 에이전트에 전달하는 전체 흐름을 스펙과 TDD(테스트를 먼저 쓰고 구현하는 방식) 계획으로 구체화했다. 그 위에서 서버 코어를 구현했다.
먼저 Figma URL 파싱, 토큰 로드 우선순위(credentials → env → .env), 노드 JSON·PNG 조회를 구현했다. 로컬 스킬 레지스트리에는 스캔·토글·업로드·삭제 기능을 넣고, 삭제 경로에서 경로 traversal(../ 같은 입력으로 지정된 폴더 밖 파일에 접근하는 공격)을 차단했다. 선택 HTML, Figma 데이터, 활성 스킬을 조립하는 프롬프트와 AgentAdapter, Claude 어댑터, 퍼블리싱 잡 매니저까지 세웠다.
토큰·파일 삭제·에이전트 권한처럼 로컬에서 도는 도구의 경계도 서버 제품과 같은 수준으로 명시해야 했다. 로컬이라고 권한을 느슨하게 두면 삭제 한 번에 저장소 밖 파일이 날아갈 수 있었다. Phase 3을 Figma, 스킬, 프롬프트, 에이전트 잡 네 축으로 나눈 덕에 외부 의존성을 격리한 단위 테스트를 붙일 수 있었다.
구현하며 막힌 네 지점
기능을 붙이는 동안 네 곳에서 막혔고, 원인과 해결을 정리해두면 아래와 같다.
| 문제 | 원인 | 해결 |
|---|---|---|
| metadata title 정규식 오탐 | 소스 문자열을 단순 정규식으로 읽으며 다른 표현까지 title로 인식 | 허용 패턴을 좁히고 회귀 테스트 추가 |
| 기존 config 재생성 시 사용자 설정 손실 위험 | 스캔 결과로 파일 전체를 덮어쓰는 접근 | 동적 route 패턴을 비교해 기존 title·metadata·variants를 보존 머지 |
| 짧은 Figma 토큰이 로그에 노출될 위험 | 앞뒤 일부만 남기는 마스킹이 짧은 값에 부적합 | 짧은 토큰은 전체 마스킹 |
| 스킬 삭제 시 저장소 밖 경로 접근 가능 | 사용자 입력을 파일 경로로 직접 결합 | 이름 검증과 경로 경계 확인, INVALID_NAME 오류 분리 |
오전에는 수동 IA 작성 비용을 scan CLI로 줄였고, 오후에는 선택한 블록을 실제 코드 변경으로 잇는 Phase 3 기반까지 확장했다. 설계 리뷰에서 보존 머지, 권한 화이트리스트, 타임아웃, UI 포털 계층을 먼저 확정한 덕분에 구현 단계의 경계가 선명했다.
브라우저 단독으로는 파일 쓰기가 안 되니 이 서버 코어를 로컬에서 돌려야 한다. 남은 일은 서버 코어를 컴패니언 HTTP 서버로 올리고 SSE(Server-Sent Events, 서버가 클라이언트로 이벤트를 계속 흘려보내는 단방향 스트림)로 진행 상황을 스트리밍하는 것, CLI serve/dev 명령으로 서버 실행 경로를 여는 것, 스킬함·Figma 입력·퍼블리싱 로그 UI를 붙여 실제 프로젝트에서 end-to-end 퍼블리싱을 검증하는 것이다.