Repository navigation
CLI Output contract
CLI 가 stdout · stderr 에 쓰는 것의 계약이다. 형식 자체(이스케이프 · 봉투의 키 · 오류 코드 · 종료 코드)는 사용자 문서 의 "출력" · "오류와 종료 코드" 가 canonical 이다. 명령마다의 항목 필드는 그 문서가 다 적지 않는다 — CLI 전용 구조체가 정하고, 종단 시험이 명령마다 기대 JSON 으로 고정한다. 여기는 그 형식을 지키는 불변식과 함정을 적는다. 출력을 명령 함수에서 떼어 둔 구조는 Architecture 의 경계 3, 개요는 Overview 에 있다.
명령의 결과는 탭 구분 텍스트(read 는 파일 내용 그대로), 또는 한 줄짜리 JSON 봉투다. 실패는 오류
코드와 종료 코드로 알린다 — 인자 해석기가 읽지 못한 명령줄과 --help · --version 은 해석기가 일반
텍스트로 쓴다(--json 을 읽기 전이다).
read 를 뺀 명령은 두 형식이 output::write_envelope 에서 갈린다. read 는 진입부의 execute 가
직접 가르고, 텍스트 모드에서 봉투 대신 파일 내용을 그대로 쓴다 — read 의 명령 함수도 다른 명령처럼
봉투를 돌려준다. 명령이 알리는 오류도 --json 이면 JSON, 아니면 텍스트로 stderr 에 쓴다
(output::write_error).
텍스트 모드에서 명령이 알리는 오류의 메시지 줄과 경고는 한 줄이다 — 메시지를 필드와 같은
output::escape 로 쓴다(오류에 후보가 있으면 후보마다 들여 쓴 줄이 뒤따르고, 인자 해석기가 쓰는
사용법 오류는 이 형식 밖이다). 메시지는 남의 글을 되풀이한다: 정규식 crate 의 여러 줄 문구, 손으로
고친 config.json 의 값, MCP 에서는 모델이 고른 경로(NUL 이 들 수 있다). MCP 서버의 도구 오류도 이
텍스트 형식이라 같은 함수를 지난다.
JSON 은 공개 계약이다 — IPC 구조체를 그대로 직렬화하지 않고 CLI 전용 구조체로 옮겨 담는다.
IPC 구조체는 프런트엔드의 필요로 바뀐다. 옮겨 담는 자리에서 정렬 · 1 기준 줄 번호 · 경로 표기를 맞춘다. 종단 시험이 Architecture 의 읽기 전용 시험과 같은 명령 목록마다 봉투 전체를 기대 JSON 과 비교한다 — 키가 빠지거나 더해지면 실패한다.
분기는 code 로 한다 — 메시지의 문구는 계약이 아니다.
오류 코드를 가르는 match 에는 _ 갈래가 없어, 새 코드는 이름을 얻기 전에 컴파일되지 않는다.
CLI 가 만드는 문구는 영어이고, 메시지가 인용하는 경로 · 이름과 IO 의 OS 실패 설명은 그대로 싣는다.
왜 영어인지는 Decisions and history 가 답한다.
-
println!은 끊긴 파이프에서 panic 하고, 릴리스 프로필은panic = "abort"다. 출력은 오류를 돌려받는 쓰기로 하고, 받는 쪽이 먼저 닫은 파이프(| head)는 종료0으로 끝낸다. 이것을 시험하는 출력은 파이프 버퍼보다 커야 한다 — 작으면 읽는 쪽이 닫기 전에 쓰기가 끝나println!구현도 통과한다. 텍스트와--json은 다른 쓰기 길을 지나므로 둘 다 돌린다. -
내부 오류 타입의
Display에는 한국어가 섞여 있다(FsError·ConfigError·IndexError). 그대로 내보내지 않고 코드별 영어 문구로 옮긴다. -
read_dir순서는 시험이 고를 수 없다.files의 정렬 호출을 지워도 종단 시험이 초록이었다 — 그 픽스처에서 APFS 의read_dir이 마침 정렬된 순서를 냈다. 정렬은 행을 만드는 순수 함수에 뒤집은 입력을 먹이는 단위 시험으로 지킨다. 같은 줄 안의 링크 순서처럼 안정 정렬이 계약인 곳은 긴 입력으로 시험한다 — 짧은 입력의 시험은sort_unstable_by_key로 바꿔도 통과했다.
이 wiki 는 baram 리포의 wiki/ 에서
생성됩니다. 여기서 편집하지 마세요 — 다음 게시가 덮어씁니다. 고칠 것은 리포에 PR 로 보내 주세요.
링크 없는 항목은 아직 쓰지 않았다. 그 주제의 현재 출처는 해당 모듈의 헤더 주석이고, 어느 파일인지는 Code map 이, 구현 현황은 #298 · #372 가 답한다.
- Overview
- Architecture
- Core state machine — 미작성
- Adapters — 미작성
- Hangul and IME — 미작성
- Input islands and block entry
- Search — 미작성
- Source mode and code block CM
- Lifecycle and settings — 미작성
- WebKit selection churn
- PM machinery in non-editable views — 미작성
- Performance — 미작성
- Resource and security boundaries — 미작성
- Internal contracts — 미작성
- Command reference — 미작성
- Testing methodology — 미작성
- Code map
- Decisions and history
링크 없는 항목은 아직 쓰지 않았다. 쓰는 법은 사용자 문서 가,
구현 현황과 다음 단계는 추적 이슈 가, 계약은
src-tauri/src/cli/ 의 모듈 헤더와 함수 · 타입의 문서 주석이 답한다.
- Overview
- Architecture
- Vault resolution and app config — 미작성
- Paths and vault boundary
- Output contract
- Links and app parity
- MCP server
- Testing methodology — 미작성
- Code map — 미작성
- Decisions and history