Skip to content

CLI Output contract

github-actions[bot] edited this page Oct 17, 2026 · 2 revisions

CLI Output contract

CLI 가 stdout · stderr 에 쓰는 것의 계약이다. 형식 자체(이스케이프 · 봉투의 키 · 오류 코드 · 종료 코드)는 사용자 문서 의 "출력" · "오류와 종료 코드" 가 canonical 이다. 명령마다의 항목 필드는 그 문서가 다 적지 않는다 — CLI 전용 구조체가 정하고, 종단 시험이 명령마다 기대 JSON 으로 고정한다. 여기는 그 형식을 지키는 불변식과 함정을 적는다. 출력을 명령 함수에서 떼어 둔 구조는 Architecture 의 경계 3, 개요는 Overview 에 있다.

텍스트와 JSON 봉투

명령의 결과는 탭 구분 텍스트(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 은 공개 계약이다

JSON 은 공개 계약이다 — IPC 구조체를 그대로 직렬화하지 않고 CLI 전용 구조체로 옮겨 담는다.

IPC 구조체는 프런트엔드의 필요로 바뀐다. 옮겨 담는 자리에서 정렬 · 1 기준 줄 번호 · 경로 표기를 맞춘다. 종단 시험이 Architecture 의 읽기 전용 시험과 같은 명령 목록마다 봉투 전체를 기대 JSON 과 비교한다 — 키가 빠지거나 더해지면 실패한다.

분기는 code 로, 문구는 영어로

분기는 code 로 한다 — 메시지의 문구는 계약이 아니다.

오류 코드를 가르는 match 에는 _ 갈래가 없어, 새 코드는 이름을 얻기 전에 컴파일되지 않는다.

CLI 가 만드는 문구는 영어이고, 메시지가 인용하는 경로 · 이름과 IO 의 OS 실패 설명은 그대로 싣는다. 왜 영어인지는 Decisions and history 가 답한다.

두 번 밟지 말 것

  1. println! 은 끊긴 파이프에서 panic 하고, 릴리스 프로필은 panic = "abort" 다. 출력은 오류를 돌려받는 쓰기로 하고, 받는 쪽이 먼저 닫은 파이프(| head)는 종료 0 으로 끝낸다. 이것을 시험하는 출력은 파이프 버퍼보다 커야 한다 — 작으면 읽는 쪽이 닫기 전에 쓰기가 끝나 println! 구현도 통과한다. 텍스트와 --json 은 다른 쓰기 길을 지나므로 둘 다 돌린다.
  2. 내부 오류 타입의 Display 에는 한국어가 섞여 있다(FsError · ConfigError · IndexError). 그대로 내보내지 않고 코드별 영어 문구로 옮긴다.
  3. read_dir 순서는 시험이 고를 수 없다. files 의 정렬 호출을 지워도 종단 시험이 초록이었다 — 그 픽스처에서 APFS 의 read_dir 이 마침 정렬된 순서를 냈다. 정렬은 행을 만드는 순수 함수에 뒤집은 입력을 먹이는 단위 시험으로 지킨다. 같은 줄 안의 링크 순서처럼 안정 정렬이 계약인 곳은 긴 입력으로 시험한다 — 짧은 입력의 시험은 sort_unstable_by_key 로 바꿔도 통과했다.

baram

Vim

링크 없는 항목은 아직 쓰지 않았다. 그 주제의 현재 출처는 해당 모듈의 헤더 주석이고, 어느 파일인지는 Code map 이, 구현 현황은 #298 · #372 가 답한다.

CLI

링크 없는 항목은 아직 쓰지 않았다. 쓰는 법은 사용자 문서 가, 구현 현황과 다음 단계는 추적 이슈 가, 계약은 src-tauri/src/cli/ 의 모듈 헤더와 함수 · 타입의 문서 주석이 답한다.

Clone this wiki locally