0021. 터미널 링크는 Orca의 탐지기를 가져오고, 열기는 main이 판정한다

상태: 채택
날짜: 2026-10-07
관련: 0008-module-structure.md, 0020-claude-chat-composer.md, THIRD_PARTY_NOTICES.md, stablyai/orca

맥락

Claude가 터미널에 출력한 파일 경로나 URL을 Orca에서는 ⌘(Ctrl)+클릭으로 열 수 있지만, Belloga 터미널에는 링크 처리가 없었다. 경로 탐지는 생각보다 어렵다. 공백이 든 경로, :줄:열, file://, 괄호가 든 프레임워크 경로를 다뤄야 하고, TUI가 줄 끝에서 경로를 끊어 다음 줄에 이어 쓰는 경우(hard wrap)도 있다.

터미널 출력은 신뢰할 수 없는 입력이다. 클릭 한 번으로 프로젝트 밖 파일이나 실행 파일이 열릴 수 있으므로, 무엇을 어디서 열지 정해야 했다.

결정

Orca v1.4.215의 터미널 링크 탐지기와 줄바꿈 처리를 가져오고, 파일을 여는 쪽은 Belloga에 맞춰 새로 쓴다. 경로 풀기와 열기 판정은 main 프로세스가 맡는다.

가져온 것: 경로 후보 추출(VSCode 탐지기를 Orca가 포팅한 것), :줄:열과 file:// 해석, soft/hard wrap과 테두리, 가장자리에서 끊긴 경로와 URL 잇기, URL 추출, OSC 8 분기. 순수 함수는 src/shared/terminalLinks/, xterm 버퍼를 다루는 것은 src/renderer/src/workspace/terminalLinks/에 둔다.
가져오지 않은 것: 수정키 없는 클릭의 액션 팝오버, 터미널 핸들(term_*), SSH, WSL, 원격 런타임, 앱 안 브라우저, localhost 라벨, xterm 비공개 내부를 쓰는 첫 클릭 보정.
URL은 @xterm/addon-web-links를 들이지 않고 같은 줄바꿈 처리 위에서 직접 링크로 등록한다. 여는 것은 기존 window.links.open(http, https만 허용)이다.
열기 판정(terminal-links:open)은 symlink를 푼 실제 경로로 한다.

대상	⌘(Ctrl)+클릭	⇧⌘(Ctrl+Shift)+클릭
프로젝트 안의 텍스트 파일, PDF	앱 파일 탭, 줄이 있으면 그 줄로 이동	시스템 기본 앱
프로젝트 밖 파일, 바이너리	시스템 기본 앱	시스템 기본 앱
디렉터리	Finder(파일 관리자)	Finder
실행 파일(실행 권한, `.app`, `.command`, `.sh` 등)을 시스템에 넘길 때	Finder에서 위치만 보임	Finder에서 위치만 보임
없는 파일	알림	알림

바이너리 판정은 git과 같이 앞 8000바이트에 NUL 바이트가 있는지로 한다.
마우스 리포팅을 켠 프로그램 위에서 링크를 수정키와 함께 누르면, 그 클릭의 마우스 리포트는 pty로 보내지 않는다.

근거 / 검토한 대안

탐지기를 직접 쓴다: 정규식 몇 개로 시작할 수 있지만, Orca가 쌓은 경계 사례(공백 경로, 문장 속 파일 이름, 긴 줄의 정규식 성능)와 테스트를 다시 만들어야 한다.
Orca 파일 열기 코드도 가져온다: zustand store, SSH, WSL, 원격 다운로드, 앱 안 브라우저가 한데 얽혀 있어 걷어 내는 비용이 새로 쓰는 비용보다 크다.
@xterm/addon-web-links를 쓴다: 공식 애드온이지만 물리 줄만 알아서 TUI가 끊은 URL을 놓친다. Orca도 애드온 위에 직접 구현한 보정을 따로 둔다.
프로젝트 밖 경로는 알림만 띄운다: 마크다운 링크와 같은 규칙이라 단순하지만, Claude가 ~/.claude/...나 /tmp 결과물을 가리킬 때 열 방법이 없다. 시스템 기본 앱으로 넘기되, 실행 파일만은 실행되지 않게 위치만 보이도록 했다.
렌더러에서 경로를 푼다: 렌더러는 홈 경로를 모르고 파일 시스템에 접근하지 못한다. 경계 판정을 신뢰할 수 있는 쪽은 main이다.
Orca의 PTY 마우스 보류를 가져온다: 액션 팝오버와 묶여 있어서, 링크 위 수정키 누름일 때 마우스 리포트만 거르는 작은 방식으로 대신했다.

결과

상대 경로는 터미널을 연 cwd 기준으로 푼다. 셸에서 cd로 옮긴 뒤 찍힌 상대 경로는 실제 파일이 없으면 링크가 되지 않는다(OSC 7 추적은 하지 않음).
링크 존재 확인 결과는 터미널마다 LRU(1024개)로 캐시하고 만료하지 않는다. 나중에 생긴 파일은 터미널을 다시 열어야 링크가 된다.
포인터가 터미널 밖에서 링크가 있는 셀로 곧바로 들어오거나, 포인터를 둔 채 그 아래 출력이 바뀌면 xterm이 링크를 다시 계산하지 않아 첫 hover와 클릭을 놓칠 수 있다. 포인터를 조금 움직이면 풀린다. Orca의 보정(click priming)은 xterm 비공개 내부에 기대고 Orca와 xterm 버전이 달라 가져오지 않았다.
프로젝트 안의 실행 권한 있는 스크립트는 앱 탭으로 연다. 실행 파일 규칙은 시스템으로 넘기는 경우에만 적용된다.