RAWP-CRS

7. 파일 브라우저 (File Browser)

세션 생성 전에 사용자가 노드와 에이전트를 선택한 후 작업 디렉토리(workspace_path)를 지정하기 위한 파일 브라우저 UI 규격이다. RAWP 1.0 §4.5(POST /v1/fs/browse) 및 §9.2.6(POST /v1/edge/nodes/{node_id}/fs/browse)의 응답 데이터를 시각적으로 렌더링한다.

7.1. 용도 및 진입점

파일 브라우저는 세션 생성 워크플로우에서 workspace_path를 선택하는 단계에 사용한다.

진입점: 노드 선택 → 에이전트 선택 완료 후, "작업 디렉토리 선택" 버튼 또는 자동 트리거로 모달 다이얼로그를 표시해야 한다 (MUST). 다이얼로그는 트리 뷰(§7.2), 경로 브레드크럼(§7.3), 수동 입력 필드(§7.6)를 포함한다.

초기 로딩: 다이얼로그가 열리면 path 생략 모드(루트 탐색)로 API를 호출하여 초기 트리를 구성해야 한다 (MUST).

7.2. 트리 뷰 컴포넌트

재귀적 트리 구조의 파일시스템 항목을 렌더링하는 핵심 컴포넌트다. entries 배열의 재귀 children 구조를 그대로 반영한다.

7.2.1. 항목 렌더링

각 Entry 항목은 한 줄로 렌더링하며, 다음 요소를 좌측에서 우측 순서로 배치해야 한다 (MUST):

순서	요소	규칙
1	들여쓰기	트리 깊이당 16~24px 패딩. 시각적 계층 구조를 명확히 전달한다 (MUST).
2	펼침/접기 chevron	디렉토리(directory, symlink_directory)에만 표시. ▶(접힌 상태) / ▼(펼친 상태). 파일 항목에는 chevron 영역만큼 빈 공간을 유지한다 (MUST).
3	아이콘	§7.2.3의 아이콘 매핑에 따라 타입별 아이콘을 표시한다 (MUST).
4	이름	entry.name을 표시한다. readable: false인 항목은 연한 색상(muted color)으로 렌더링하고 잠금 아이콘(🔒)을 우측에 병기한다 (MUST).
5	부가 정보	파일 항목에 한해 size를 사람이 읽기 쉬운 단위(KB, MB 등)로 우측 정렬 표시한다 (SHOULD).

호버 및 선택 스타일: 항목 호버 시 배경색 변경으로 포커스를 표시해야 한다 (MUST). 현재 선택된 디렉토리는 강조 배경색과 좌측 보더(2~3px, primary color)로 구분한다 (MUST).

7.2.2. 디렉토리 펼침/접기

• chevron 클릭 또는 디렉토리 더블 클릭으로 펼침/접기를 토글한다 (MUST).
• 이미 children이 로딩된 디렉토리는 즉시 토글한다. children이 없고 깊이 경계에 해당하는 디렉토리는 API를 재호출하여 하위를 로딩한다 (Lazy Expansion).
• Lazy Expansion 중에는 해당 디렉토리의 chevron을 스피너로 교체하여 로딩 상태를 표시해야 한다 (MUST).
• 로딩 실패 시 chevron을 원래 상태로 복원하고 해당 항목 하위에 인라인 에러 메시지를 표시한다 (MUST).

7.2.3. 아이콘 매핑

항목의 type 필드에 따라 아이콘을 매핑한다 (MUST):

type	아이콘	비고
directory	📁 폴더	펼친 상태 시 📂(열린 폴더)로 전환 (MAY)
file	📄 파일	확장자별 세분화는 구현에 위임 (MAY)
symlink_directory	📁↗ 폴더+링크	링크 표시를 겸한 폴더 아이콘
symlink_file	📄↗ 파일+링크	링크 표시를 겸한 파일 아이콘

아이콘 세트는 구현체의 디자인 시스템에 위임하되, 타입 간 시각적 구분이 가능해야 한다 (MUST).

7.3. 경로 브레드크럼

트리 뷰 상단에 현재 탐색 경로를 브레드크럼 형태로 표시해야 한다 (MUST).

• 각 경로 세그먼트는 클릭 가능하며, 클릭 시 해당 레벨로 트리 뷰를 이동한다 (MUST).
• 경로 구분자는 os_type에 따라 결정한다: unix → /, windows → \.
• 루트 모드(base_path가 빈 문자열)에서는 OS 루트 아이콘(🖥 또는 컴퓨터 아이콘)을 최좌측에 표시한다 (SHOULD).
• Windows 환경에서 드라이브 문자(C:\, D:\ 등)는 최상위 브레드크럼 세그먼트로 표시한다 (MUST).
• 경로가 길어 한 줄을 초과할 경우, 중간 세그먼트를 …으로 축약하되 첫 세그먼트와 마지막 2개 세그먼트는 항상 표시한다 (SHOULD).

7.4. 로딩 및 에러 상태

초기 로딩: 트리 뷰 영역 전체에 중앙 정렬 스피너를 표시해야 한다 (MUST). 로딩 중에도 수동 입력 필드(§7.6)는 사용 가능해야 한다 (SHOULD).

Lazy Expansion 로딩: §7.2.2에 따라 해당 디렉토리의 chevron을 스피너로 교체한다.

에러 상태:

상황	렌더링
노드 오프라인	트리 뷰 전체를 에러 패널로 교체. "노드에 연결할 수 없습니다" 메시지와 재시도 버튼 표시 (MUST).
권한 없음 (readable: false)	해당 항목에 잠금 아이콘(🔒)과 tooltip("접근 권한 없음")을 표시. 디렉토리인 경우 펼침을 비활성화 (MUST).
심링크 순환	해당 항목을 비활성(disabled) 상태로 렌더링하고 tooltip("순환 심링크")을 표시한다 (MUST).
Truncation	잘린 디렉토리 하위에 "외 N개 항목" 안내를 표시한다 (MUST). total_children_count 활용.
API 타임아웃/5xx	부분 결과가 있으면 표시하고 하단에 "일부 항목을 불러오지 못했습니다" 경고를 표시한다 (SHOULD).

7.5. 키보드 내비게이션

파일 브라우저는 WAI-ARIA Treeview 패턴을 준수해야 한다 (MUST):

키	동작
↑ / ↓	트리 항목 간 포커스 이동
→	포커스된 디렉토리 펼침. 이미 펼쳐져 있으면 첫 번째 자식으로 이동
←	포커스된 디렉토리 접기. 이미 접혀 있으면 부모 디렉토리로 이동
Enter	포커스된 디렉토리를 workspace_path로 선택
Space	포커스된 디렉토리 펼침/접기 토글
Home	트리의 첫 번째 항목으로 이동
End	트리의 마지막 가시 항목으로 이동
Esc	파일 브라우저 다이얼로그 닫기

파일(type: "file")은 포커스는 가능하나 Enter로 선택할 수 없다 (MUST). 디렉토리만 workspace_path로 선택 가능하다.

7.6. 작업 디렉토리 선택

트리에서 선택: 디렉토리를 클릭(싱글 클릭)하면 해당 항목을 선택 상태로 표시하고, "선택" 버튼 클릭 또는 Enter 키로 확정한다 (MUST). 확정 시 선택된 디렉토리의 path를 세션 생성 폼의 workspace_path에 반영하고 다이얼로그를 닫는다.

수동 입력: 트리 뷰 하단 또는 상단에 텍스트 입력 필드를 제공해야 한다 (MUST). 사용자가 절대 경로를 직접 입력하여 workspace_path를 지정할 수 있다.

• 입력 필드에 경로를 입력하면, 클라이언트는 해당 경로가 에이전트의 allowed_directories 범위 내인지 클라이언트 측에서 사전 검증해야 한다 (MUST).
• 범위 밖 경로 입력 시 인라인 경고("허용된 디렉토리 범위 밖입니다")를 표시하고 선택 버튼을 비활성화한다 (MUST).
• 유효한 경로 입력 시 트리 뷰를 해당 경로로 자동 이동하여 시각적 확인을 제공한다 (SHOULD).

7.7. 빈 상태 처리

에이전트의 allowed_directories가 빈 배열이거나 모든 경로에 접근 권한이 없는 경우, 트리 뷰 영역에 다음을 표시해야 한다 (MUST):

• "탐색 가능한 디렉토리가 없습니다" 안내 메시지
• 수동 입력 필드로의 안내 텍스트

allowed_directories가 미설정(제한 없음)인 경우에는 OS 루트부터 정상적으로 트리를 표시한다.