디자인 세션 프리뷰 (Barbelic-preview)

2026-09-15 사용자 결정, Barbelic-preview #2. 디자인 세션이 앱 화면을 보면서 스타일을 고치는 데 쓰는 라이브 프리뷰는 앱 밖의 독립 저장소 dekerd/Barbelic-preview가 소유한다. 앱은 블랙박스이며 프리뷰 도구는 앱 소스를 읽거나 복사하지 않는다.

기준 (사용자, 2026-09-15)

1. 세션은 main 과 동기화된 지점에서 브랜치를 따고, 프리뷰는 그 브랜치를 따라간다. 같은 디자인 세션 여러 개가 병렬로 돌 수 있고 서로 독립이다.
2. 작업이 끝난 브랜치는 release 브랜치에 병합되어 반영된다(기존 경로: PR base = 목적 release → merge:request).
3. 병렬 세션은 각자 포트 1개를 점유한다.
4. DB 는 staging 에 연결한다. Production·로컬 샌드박스에 붙이는 옵션은 없다.

왜 도구로 만들었나

2026-09-15 실측: 디자인 세션 4개를 수작업 7단계(이슈 → 브랜치·워크트리 → npm ci → .env.local → launch.json + skip-worktree → 개발 서버 → 제목)로 셋업했더니 프리뷰 서버 6개 중 4개가 Production DB 를 보고 있었다. 개발 서버는 대상이 없으면 local 로 뜨고 local 의 기본값이 Production 이라, .env.local 을 빠뜨리면 막는 것이 없었다. 포트 규칙도 세션마다 달랐고 앱 저장소의 launch.json 을 세션마다 고쳐 숨겨야 했다. 지침을 더 자세히 적는 대안(A)과 앱에 스크립트를 넣는 대안(B)은 기각하고, 프리뷰를 만드는 주체를 앱 밖에 두는 C 를 채택했다.

사용법

앱 저장소는 D:\LiftGuild-2026\Claude\lift-guild, 워크트리는 D:\LiftGuild-2026\Claude\wt<이슈번호> (환경변수 BARBELIC_APP_REPO·BARBELIC_WORKTREE_ROOT 로 변경). 도구 저장소는 D:\LiftGuild-2026\Claude\barbelic-preview.

node D:\LiftGuild-2026\Claude\barbelic-preview\bin\preview.mjs up <이슈번호>   # 셋업 + 실행
node …\preview.mjs ls        # 세션 목록(포트·상태·브랜치·기준·정리 조건)
node …\preview.mjs down <N>  # 서버만 종료
node …\preview.mjs rm <N>    # 병합·clean·push 확인 뒤 워크트리·브랜치·포트 정리 (--force)
node …\preview.mjs prune     # 조건이 다 맞는 세션 일괄 정리
node …\preview.mjs logs <N>  # 서버 로그
node …\preview.mjs doctor    # 환경·등록부 점검

up <이슈번호> 는 ① 앱 저장소 fetch ② 기준 브랜치 결정(기본: origin/main 을 포함한 가장 낮은 origin/release/vX.Y.Z, --base 로 지정) ③ 워크트리 wt<N>·브랜치 design/<N>-design-fix 준비(없을 때만 생성, 손으로 만든 폴더는 브랜치만 확인) ④ npm ci(없을 때만) ⑤ 포트 풀 5300~5319 에서 배정(이슈당 고정, 동시 실행 잠금) ⑥ 분리 프로세스로 서버 실행 — .env.local 의 staging 세 줄을 맞추고 앱이 선언한 배포 대상이 staging 이 아니면 서버를 내리고 실패 ⑦ origin/staging 에 없는 마이그레이션 경고 ⑧ 주소 http://127.0.0.1:<포트>/__preview/?device=<기기> 출력. 상세는 도구 저장소 README.

세션은 그 주소를 브라우저 도구(navigate)로 열면 된다. 앱 저장소의 launch.json 편집·skip-worktree 는 더 하지 않는다. 로그인은 사용자가 직접 한다(공용 staging 테스트 계정).

기기 틀: iPhone 17 Pro·iPhone SE·Galaxy S25·iPad mini 프리셋, 틀 페이지의 "안전 영역 표시" 로 --safe-top/bottom/left/right 값을 앱 화면 위에 띠로 그려 대조한다. 앱과의 약속(틀이 앱 문서 :root 에 넣는 CSS 변수 네 개 등)은 도구 README "앱과의 약속" 표가 정본이다.

정리 규칙

워크트리·로컬 브랜치·포트는 ① 브랜치 head 가 기준 release 에 포함되고(큐가 병합함) ② 커밋 안 된 변경이 없고 ③ push 안 된 커밋이 없을 때만 지운다(prune, up·ls 때 자동). 하나라도 어긋나면 남기고 ls 에 이유를 보인다. 병합을 확인한 세션은 [vX.Y.Z 병합완료] 턴에 rm <N> 으로 정리한다. 원격 브랜치와 도구가 등록하지 않은 워크트리는 건드리지 않는다.

알려진 한계

• staging DB 스키마가 release 보다 뒤일 때(2026-09-15 기준 마이그레이션 10개) 새 서버 기능에 기대는 화면은 프리뷰에서 오류가 난다. 도구는 경고 목록만 내고 해결은 승격이다.
• 공용 staging 테스트 계정을 병렬 세션이 함께 쓴다 — 한 세션의 시험 데이터가 다른 세션에도 보인다.
• 소셜 로그인(카카오·구글·애플)의 되돌아오기 주소: 2026-09-15 사용자가 staging Auth 의 Redirect URLs 에 프리뷰 주소를 등록했고, 콜백 실측으로 127.0.0.1 의 5300~5319(그 밖의 포트도) 허용·외부 주소 거부를 확인했다. 실제 계정으로 끝까지 로그인하는 것은 자동 확인 대상이 아니며 문제가 있으면 이슈로 보고한다.
• Vite 미들웨어 모드 API 에 결합된다. 앱이 Vite 메이저를 올리면 doctor 로 확인한다.
• 앱 기본 체크아웃의 git fetch 가 20초 넘게 걸린다(워크트리 80여 개, loose objects 경고). ls·down·logs 는 fetch 하지 않는다.

도구 자체의 변경

Barbelic-preview 저장소의 PR → main. 앱 release 큐·앱 CI·문서 저장소 CI 와 무관하다. 검사는 그 저장소의 npm run check(외부 의존성 0, Node 22+).