feat: 툴바에 지금 보고 있는 워크트리와 브랜치를 표시한다

[say8425]

왜

뷰어는 repo를 URL 파라미터로만 받아서, 화면 어디에도 **"지금 어느 리포의 어느 워크트리에서 무엇을 보고 있는가"**가 없었다.

실제로 밟은 사고: 워크트리를 4개 쓰는 리포에서 엉뚱한 워크트리(main, origin보다 1044 커밋 뒤처짐)를 열어 놓고 "changed files가 1개밖에 안 나온다"고 판단했다. 실제 작업 브랜치는 별도 워크트리에 있었고 거기선 176 files가 정상적으로 나왔다. 화면에 단서가 없으니 오진을 가려낼 수 없었다.

원인을 파다 보니 툴바 피커 자체가 틀린 축을 건드리고 있었다. 목록의 브랜치 이름은 "그 브랜치를 보여줘"로 읽히는데 실제로는 *견줄 기준(base)*을 골랐다 — 그래서 메인 워크트리에서 남의 브랜치를 골라도 1 file만 나왔다(같은 브랜치를 워크트리로 열면 176). 게다가 뒤처진 브랜치에서는 merge-base가 HEAD라 어떤 base를 골라도 결과가 같아 보인다 — "피커를 바꿔도 화면이 안 변한다"가 고장으로 읽힌다.

이 PR은 그 한 갈래를 끝까지 따라가 툴바를 다시 세운다: 표식을 만들고 → 피커를 head 축으로 돌리고 → 중복을 걷어내고 → 조작과 정보를 자리로 갈랐다.

Screenshots

Before (origin/main) — 툴바가 어느 리포/워크트리/브랜치인지 말하지 않는다. 탭 제목도 diffdeck뿐.

After ① 메인 워크트리 — 리포 접두를 생략해 diffdeck · feat/toolbar-repo-branch. 개수 오른쪽에 전체 변경량.

After ② 링크된 워크트리 — diffdeck / feat+SHOT-1-toolbar · shot/linked-preview. 세 조각이 서로 다른 축이다.

After ③ 브랜치를 head로 — 워크트리 조각이 통째로 빠지고 head가 주인공 자리를 가진다. 커밋된 rev의 diff는 어느 워크트리에서 보든 같으므로(실측) 워크트리 이름을 남기면 거짓 인상을 준다.

피커 — 워크트리 구역(각 행이 물고 있는 브랜치를 오른쪽에)과 브랜치 구역(default가 맨 위). 워크트리를 고르면 그 URL로 이동하고, 브랜치를 고르면 head만 바꾼다.

마지막 커밋 — 조작을 오른쪽으로. 왼쪽 그룹은 한 문장으로 읽혀야 하는데(무엇을 · 무엇과 견줘 · 몇 파일 · 몇 줄) Unified/Split과 새로고침이 첫 마디와 둘째 마디 사이에 앉아 그 문장을 두 동강 냈다.

Before
After

무엇을

1. 표식 — 트리거가 곧 표시다

세 조각이 서로 다른 축이다. 워크트리 이름만 보이면 어느 리포인지 모르고, 리포 이름만 보이면 어느 워크트리인지 모른다.

한때 피커 트리거와 개수 왼쪽 라벨이 따로였다. 피커가 base를 고르던 시절엔 서로 다른 축이라 중복이 아니었지만, 피커가 head를 고르게 된 순간 둘이 같은 말을 하게 됐다. 그래서 고르는 컨트롤이 곧 표시다 — 고르는 자리와 지금 무엇을 보는지 말하는 자리가 하나면 어긋날 수 없고, 남은 자리(#base-label)는 트리거가 결코 말하지 않는 축(base)만 가진다.

색은 구별되는 조각 하나만 밝힌다(#picker-name = --vd-fg, 나머지 muted). 리포 이름은 그 리포의 워크트리마다 같아서 화면을 가르지 못하기 때문이고, 같은 이유로 탭 제목에는 리포 접두를 넣지 않는다(탭은 좁고 오른쪽부터 잘린다).

git 호출은 늘지 않는다. /api/refs가 이미 주는 worktrees[]에 리포 루트 하나만 더했고, parseRepoRoot가 worktree list --porcelain 원본의 첫 레코드를 읽는다.

parseWorktreeList의 결과를 대신 쓰면 안 된다 — 그쪽은 bare·prunable을 걸러내는데, bare 리포는 메인 항목이 바로 그 bare라 첫 항목이 링크된 워크트리로 밀린다. 그러면 라벨이 남의 워크트리를 리포 이름이라 말한다(실측).

• browser/repoLabel.ts — DOM에 닿는 문자열 전량을 만드는 순수 모듈. main.ts는 커버리지 게이트 밖이라 거기 조립을 두면 게이트가 100% 초록인 채로 버그가 산다(isLargeFile 사건과 같은 구조).
• findWorktree는 세그먼트 경계 최장 접두 일치. repo는 기동 시점의 process.cwd()라 리포 루트라는 보장이 없고, 중첩 워크트리에서 바깥이 이기면 라벨이 엉뚱한 워크트리를 말한다. 피커의 HEAD 태그 판정도 같은 함수를 쓴다.
• 갱신 시점 셋: load(), 피커 열림, watch의 poll(). poll()이 빠지면 watch 중에 diff만 갈리고 라벨은 옛 브랜치에 굳는다 — 같은 화면의 빈 상태 카드는 살아 있는 브랜치를 말하므로 한 화면이 두 브랜치를 주장하게 된다.

2. 피커가 base가 아니라 head를 고른다

wire는 head=<ref>, 없으면 워킹트리. base=HEAD와 달리 head=HEAD는 정규화하지 않는다 — base=HEAD는 "커밋 안 한 것만"이라 워킹트리 뷰와 결과가 같지만 head=HEAD는 커밋된 HEAD를 보는 것이라 미커밋 변경이 빠진다.

• 갈림점은 head 기준이어야 한다. merge-base(ref, HEAD)로 재면 지금 워크트리의 HEAD와 갈림점을 잡는데 그 둘은 아무 관계도 없고, base 브랜치가 그 사이 만든 파일이 "head에서 삭제됨"으로 끼어든다(뮤테이션 확인).
• 커밋된 rev에는 untracked가 없다 — 토글이 켜져 있어도 건너뛴다.
• head도 verifyBaseRef의 보안 경계를 탄다. 그 값이 이제 git diff의 두 번째 인자로도 가므로 -로 시작하는 참조가 닿으면 --output=<path>가 된다. 표식은 x-diff-error: unknown-head로 base와 가른다(자가복구가 다르다).
• /api/summary의 workingFiles·untrackedFiles가 number | null이 됐다 — 재지 않은 것을 0으로 적으면 주장이 되어, 실제로는 미커밋 변경이 있는데도 카드가 "Nothing to show in any mode"라고 말한다.
• head는 저장하지 않는다 — URL이 진실이라야 새로고침·링크가 재현되고, 저장하면 다음에 그 리포를 열 때 남의 브랜치 뷰에 갇힌 채 시작한다.
• 캐시 키와 지문에 head가 들어간다 — selectionCacheKey는 "flight 클로저가 읽는 모든 입력의 전함수"라는 기존 계약이다.

e2e 함정 기록: 픽스처에 git remote add를 쓰면 base 해석의 첫 단계인 gh pr view가 그것을 GitHub 리포로 풀어 보려 하고, 그때부터 스펙 하나가 수십 초씩 걸린다(실측: ref-picker.e2e.ts 전체가 16초 → 15.5분). update-ref + symbolic-ref로 symref만 직접 세운다.

3. 전체 변경량 · 자동 base 전환

• #change-totals — 파일 수만으로는 규모를 못 읽는다(176 file(s)가 한 줄씩인지 통째로 새로 쓴 것인지). 세는 값의 출처가 계약이다: hunk의 숫자 필드이지 FileDiffMetadata의 동명 string[] 필드가 아니다(그 착각이 대형 파일 자동 접힘을 오작동시킨 적이 있다). e2e가 스펙 안에서 git diff --numstat을 돌려 매번 대조한다.
• 빈 워킹트리에서 자동으로 base 뷰를 연다 — 워크트리 워크플로에서는 작업이 브랜치에 커밋돼 있어 기본 뷰가 구조적으로 비어 있다. 불변식 셋: ① 사용자가 고른 적 있으면 안 덮는다, ② 토글로 감춰졌을 뿐 이 뷰에도 볼 것이 있으면(untracked) 안 데려간다, ③ 저장하지 않는다(추론이지 선택이 아니다 — 저장하면 ①이 이후 모든 자동 전환을 영구히 막는다). 셋 다 뮤테이션으로 판별력 확인.

4. 조작과 정보를 자리로 가른다 (마지막 커밋)

옮겨도 폭은 손해 보지 않는다(실측): 총 폭이 그대로라 트리거가 줄어들 몫도 그대로여서, 560px 창에서 트리거 160px · 넘침 54px로 옮기기 전과 완전히 같은 값이다.

오른쪽 순서 찾기 · 새로고침 │ Unified/Split · 트리 │ ⋯ 의 근거:

근거	종류
찾기가 맨 앞 — find 바가 그 자리에서 340px로 펼쳐지고 그룹은 오른쪽 끝에 고정이라, 바가 자라면 왼쪽 이웃만 밀린다. 찾기 우선이면 이동량 0px, 세그먼트를 앞에 두면 −285px 점프	실측
가운데 셋은 순간 동작 / 상태 토글로 갈랐다 — 118px 세그먼트가 두 무리 사이에 놓여 축의 경계와 시각적 경계가 겹친다	설계
트리 토글이 ⋯ 옆 — 메뉴의 Hide file tree가 같은 토글이고, 메뉴 여섯 중 넷이 레이아웃	설계
⋯가 마지막 — 메뉴는 툴바 아래로 떨어져 이웃을 가리지 않으므로 기계적 제약이 아니다	관례

CSS 사슬 한 마디가 새로 필요했다: .tb-picker { display: flex }. 블록이면 안쪽 inline-flex 버튼이 flex item이 아니라 줄어드는 몫을 못 받고 자연폭 그대로 넘쳐, 트리거가 아무리 좁아져도 라벨이 한 번도 잘리지 않는다(실측: 1280px 창에서 161자 브랜치인데 scrollWidth == clientWidth).

max-width는 두지 않는다 — 좁은 창에서 두 안의 수치가 완전히 같고(700/560/460px에서 221/81/0px) 161자 브랜치에서도 넘치지 않았다. 즉 상한은 오버플로 방어에 아무것도 안 보태면서 공간이 남는 넓은 창에서 세 조각을 잘라 이 표식의 존재 이유를 깎는다.

테스트 플랜

bun test              # 775 pass
bun run test:coverage # 100% 게이트 통과
bun run typecheck     # 통과
bun run lint          # 신규 에러 없음
bun run format:check  # 통과
bunx playwright test  # 107 passed (apps/viewer에서)

유닛 — 커버리지 게이트는 branch를 세지 않으므로 폴백 분기마다 따로 찔렀다.

파일	종	무엇을
repo-label.test.ts	35	후행 슬래시·루트·빈 경로, 하위 디렉토리 기동, 중첩 워크트리 최장 일치, detached, bare .git 접미, head 뷰의 워크트리 제거
ref-picker-model.test.ts	19	두 구역의 정렬(default → 지금 보는 것 → 받은 순서), 워크트리 구역 생략 조건, 필터
change-totals.test.ts	9	합산, 한쪽 0, 센 줄 없음
diff-refs.test.ts (parseRepoRoot)	4	bare가 핵심 — 필터 전 원본을 읽어야 한다는 계약
diff-selection / diff-command / diff-server / summary / empty-state	+22	head 파싱·갈림점 기준·HTTP 400(unknown-head, 옵션 꼴 차단)·null 요약·shouldAutoViewBase

e2e — 배선은 커버리지 밖이라 여기가 유일한 그물이다.

파일	종	핵심
toolbar-repo.e2e.ts	8	링크된 워크트리 두 축, --watch 무-focus 수렴, 브랜치 head가 워크트리 이름을 버림, 넓은 창·좁은 창 레이아웃
ref-picker.e2e.ts	9	브랜치를 고르면 커밋된 작업을 본다, 워크트리를 고르면 이동, default 최상단, 키보드 조작
toolbar-totals.e2e.ts	3	git과 대조(하드코딩 없이 스펙 안에서 --numstat 합산)
toolbar-order.e2e.ts	3	두 그룹의 소속·순서, 바를 열어도 아무것도 안 움직임, 좁은 창에서 오른쪽 그룹 유지
empty-state.e2e.ts	5	자동 전환 + 무-저장, URL base=는 안 덮음

뮤테이션으로 판별력 확인한 것들

지운 것	죽는 것
poll()의 라벨 갱신	toolbar-repo ⑥만
.tb-picker { display: flex }	toolbar-repo ⑧의 넓은 창·좁은 창 clipped 둘 다 (rightEdge는 통과 — 상자만 줄고 버튼이 그 위로 넘칠 뿐)
.tb-left의 min-width:0 / flex:none	toolbar-repo ⑧의 좁은 창만
.tb-right의 margin-left: auto	toolbar-order ②만 (①은 통과 — 순서는 그대로다. 즉 ②는 ①의 중복이 아니라 그 순서의 이유를 지킨다)
renderPatch의 합산 배선	toolbar-totals ①②
갈림점을 HEAD 기준으로 되돌림	diff-command 2종
자동 전환을 persist: true로	empty-state ④만

문서 의무 없음 — CLI 플래그를 추가하지 않으므로 docs-flags-parity.test.ts의 일곱 문서는 그대로다. CLAUDE.md에는 이 UI 계약들을 전부 기록했다.

🤖 Generated with Claude Code

https://claude.ai/code/session_013LwoJdwzqo3Ln6y8g5ivMM

[say8425]

리뷰 라운드 결과 (fe22571)

5개 관점(정확성·배선·CSS/레이아웃·테스트 판별력·레포 관례)으로 리뷰하고 지적마다 반증을 시도해 검증했습니다. 확인된 것만 고쳤고, 반증된 것은 고치지 않았습니다.

고친 것

① 중대 — --watch에서 라벨이 무한정 낡는다
갱신을 load()와 피커 열림에만 달아 뒀는데, watch는 창을 안 보고 있을 때 쓰는 기능이라 focus가 발화하지 않습니다. diff만 2초마다 새 브랜치 것으로 갈리고 툴바·탭 제목은 옛 브랜치에 굳었습니다. 더 나쁜 건 같은 화면의 빈 상태 카드가 /api/summary(캐시 없음)로 살아 있는 브랜치를 말한다는 점 — 한 화면이 두 브랜치를 동시에 주장했고, 이 기능이 없애려던 오진을 새로 만드는 셈이었습니다. poll()에서도 갱신합니다. 비용은 /api/refs의 5초 TTL이 흡수합니다(폴이 2초여도 git 호출은 5초에 두 번이 상한). "내용이 바뀐 폴에서만" 같은 조건은 쓸 수 없습니다 — 워킹트리가 깨끗한 채로 브랜치만 갈아타면 지문이 그대로라 304로 흘러 한 번도 안 돕니다(그게 정확히 고쳐야 할 경우입니다).

② 회귀 — 좁은 창에서 툴바가 화면을 벗어난다

창 폭	base(라벨 없음)	수정 전	수정 후
900px	✓ h43	✓ h43	✓ h43
700px	✓ h43	✓ h49	✓ h43
560px	✓ h43	❌ 화면 밖	✓ h43
460px	—	❌ 화면 밖	✓ h43

flex item의 기본 min-width:auto가 라벨 폭만큼 툴바의 하드 최소폭을 늘려 .tb-right를 밀어냈고, #status가 두 줄로 접혀 높이도 뛰었습니다. .tb-left { min-width: 0 } + .tb-left > * { flex: none }으로 줄어드는 몫을 라벨이 전담하게 했습니다 — 조작과 개수는 정보 라벨보다 우선합니다.

③ 사실이 틀린 주석 둘

• 모듈 헤더가 typecheck를 분리 근거로 들었는데, apps/viewer/tsconfig.json의 include에 browser/**가 없어 새 모듈도 typecheck 밖입니다(확인함). 분리 근거는 커버리지 게이트뿐입니다.
• SHORT_OID_LENGTH = 7이 rev-parse --short의 기본과 같다고 적었는데 그쪽은 core.abbrev(auto)를 따라 길어집니다(실측: 3.5k 객체 리포 7자, 37k 객체 리포 8자). 카드와 한 글자 갈릴 수 있다는 사실과, 그럼에도 카드를 자르지 않는 이유(auto는 git이 고른 모호하지 않은 길이다)를 적었습니다.

④ 무력했던 테스트 계약
toHaveText는 공백을 정규화해서 name · main도 통과합니다 — "조각 사이 공백 텍스트 노드 금지"는 textContent를 그대로 봐야 잡힙니다.

반증한 것 (고치지 않음)

• "findWorktree의 최장 일치에 판별력 있는 테스트가 없다" — 최초 일치로 퇴화시키면 기존 유닛이 죽습니다(뮤테이션 확인).
• "창 폭 축소로는 ellipsis가 절대 발동하지 않는다" — 700px에서 실제로 발동합니다(clipped=true 실측).

판별력 검증

새 계약이 실제로 지켜지는지 뮤테이션으로 확인했습니다. 각 뮤테이션이 해당 스펙만 죽입니다:

뮤테이션	죽는 테스트
poll()의 refreshRepoLabel() 제거	⑤ watch 무-focus 수렴 only
.tb-left { min-width: 0 } 제거	⑥ 좁은 창 레이아웃 only
.tb-left > * { flex: none } 제거	⑥ 좁은 창 레이아웃 only

검증

bun test 723 pass · coverage 100%(신규 모듈 100.00/100.00) · typecheck · lint · format · toolbar-repo.e2e.ts 6/6.

로컬 전체 e2e에서 worker-highlight가 빨간불인데 이 PR과 무관합니다 — 실패 지점이 #status의 "Loading…" 대기라 CLAUDE.md에 기록된 Bun $ never-settle 재현이고(그 스펙은 해당 3종 중 하나로 이미 문서화돼 있습니다), base 코드에서도 나옵니다. 부하가 큰 로컬 맥의 알려진 조건이라 retries로 가리지 않고 CI를 심판으로 둡니다.

CLAUDE.md에 이 UI 계약(갱신 시점 셋·CSS 짝 규칙·OID 길이 차이·findWorktree 규칙)을 기록했습니다.

[say8425]

빈 워킹트리에서의 자동 base 전환 (8bbe009)

로컬 테스트 중 발견한 문제를 함께 고쳤습니다. 워크트리를 열었더니 Working tree clean만 뜨는 현상인데, 조사해 보니 데이터 버그가 아니라 기본값 문제였습니다.

git status --porcelain   → 0줄      (미커밋 변경 없음)
git diff main...HEAD     → 176 files (커밋된 작업)

기본 뷰가 "미커밋 변경"이라 정말로 비어 있습니다. 그런데 워크트리 워크플로에서는 작업이 브랜치에 커밋돼 있으니 이 상태가 구조적입니다 — 볼 게 가장 많은 순간에 빈 화면이 뜨고, 프리퍼런스 키가 리포 경로별이라 새 워크트리를 팔 때마다 카드의 버튼을 한 번씩 눌러야 했습니다.

이제 고른 적이 없으면 볼 것이 있는 쪽을 엽니다. 판정을 새로 세우지 않고 카드 자신의 액션을 읽습니다(model.actions의 switch-mode 유무) — 카드가 전환을 권할 상황이 곧 전환할 가치가 있는 상황이라 조건이 두 곳으로 갈라지지 않습니다.

불변식 셋이 계약

① 사용자의 선택은 절대 덮지 않는다. URL base=든 저장된 프리퍼런스든. resolveCompareBase가 null을 주는 것이 "고른 적 없음"의 정의입니다. 모듈 초기화 때 캐시하면 피커로 고른 뒤에도 옛 값이 남아 선택을 덮으므로 호출 시점에 다시 읽습니다.

② 토글로 감춰졌을 뿐 이 뷰에도 볼 것이 있으면(untracked) 데려가지 않습니다. 카드가 두 선택지를 나란히 보여주는 편이 낫고, 이 경계선이 없으면 기존 카드 스펙이 죽습니다.

③ 저장하지 않는다. 추론이지 사용자의 선택이 아닙니다. 저장하면 고른 적 없는 프리퍼런스가 생겨 불변식 ①이 이후 모든 자동 전환을 영구히 막습니다.

그래서 applySelection(사용자 경로, 저장함)과 selectBase(next, {persist})(공통 코어)가 갈라졌습니다. applySelection이 패널 닫기·포커스 복귀를 조기 반환보다 앞에 두는 순서는 그대로 보존했습니다 — 이미 고른 행을 눌러도 피커는 닫혀야 하니까요.

판별력 (뮤테이션)

뮤테이션	죽는 스펙
untracked 경계선(②) 제거	기존 카드 스펙 only
persist: false → true (③ 위반)	새 자동 전환 스펙 only

검증

bun test 738 pass · coverage 100%(emptyState.ts 포함) · typecheck · lint · format · empty-state.e2e.ts 5/5(기존 3 + 신규 2).

기존 3종이 그대로 통과하는 게 핵심입니다 — 불변식 ②가 없었으면 첫 번째 스펙이 깨졌을 겁니다.

[say8425]

피커 목록 맨 위를 지금 체크아웃한 브랜치에 (1a16899)

실측 리포의 브랜치가 679개라, 목록에서 "나는 어디 있나"를 확인하려면 훑거나 검색어를 쳐야 했습니다. 맨 위 자리를 그 답에 줍니다.

UNCOMMITTED
  Working tree                       nothing yet
COMPARE WITH A BRANCH
  feature/FE-25807-common-comment    HEAD     ← 올라옴
  FE-20527-review-i18n
  chore/MEC-294-revive-ui-contents-storybook
  …

설계 결정 셋

올리는 근거는 태그가 아니라 위치다. 자기 브랜치가 기본 브랜치이기도 하면 toRow의 태그는 default로 남지만(그 삼항의 우선순위는 그대로 뒀습니다) 지금 있는 곳이라는 사실은 변하지 않으므로 여전히 올립니다.

올림은 로컬 안에서만. 체크아웃된 브랜치는 언제나 로컬이고(원격 레코드 이름은 origin/main 꼴이라 짧은 현재 브랜치명과 애초에 안 맞습니다), 로컬이 원격보다 앞이므로 그것으로 구역 맨 위가 됩니다.

순서는 유닛이 정하지만 배선은 못 잡는다. main.ts가 현재 브랜치를 넘기지 않으면 유닛 전부가 통과한 채 화면만 조용히 옛 순서로 돌아갑니다. 그래서 e2e를 짝으로 뒀고 뮤테이션으로 확인했습니다 — current를 null로 바꾸면 그 e2e 하나만 죽고 나머지 7종은 통과합니다.

회귀망

ref-picker-model.test.ts 4종(올림 · 기본브랜치 겸용 · 로컬우선 유지 · detached 무변화) + ref-picker.e2e.ts 1종.

기존 순서 의존 스펙 2곳은 그대로 통과합니다 — 필터 후 단일 행을 보거나(filters the list as you type), allTextContents()로 위치를 동적으로 찾기(moves with the arrow keys) 때문입니다.

검증

bun test 742 pass · coverage 100%(refPicker/model.ts 포함) · typecheck · lint · format · ref-picker.e2e.ts 8/8.