Repository navigation
CLI Architecture
CLI 는 앱 실행 파일 안의 한 모드다 (Overview 가 무엇을 왜 그렇게 정했는지 요약한다). 이 페이지는 그 모양(층과 경계)과, 경로 인자나 출력 한 주제에 속하지 않는 불변식을 다룬다 — 왜 그렇게 정했는지는 Decisions and history 가 답한다.
argv
│
▼
cli::mode_for GUI 와 CLI 를 가른다. main() 이 Tauri 를 시작하기 전에 부른다
│ Mode::Cli
▼
cli::run 인자를 해석하고, 런타임을 만들어 명령 하나를 돌린다
│
▼
vault::resolve vault 하나를 고른다. 못 찾으면 실패한다
│ Vault root 는 정규화한 절대 경로 하나
▼
paths 경로 인자를 그 vault 안의 경로로 바꾸고, 앱이 보지 않는 자리를 거른다
│ PathBuf
▼
ops · ops_notes · 명령 함수. 조회 결과를 봉투에 담아 돌려준다
ops_search · ops_links
│ Envelope { vault, truncated, items }
▼
run · execute 결과를 stdout 에, 실패를 stderr 에 쓰고 종료 코드를 돌려준다
경로 인자는 흐름에서 명령 함수 앞에 서지만, 그 판정은 명령 함수가 조회 전에 paths 의 함수를 불러
한다. backlinks 는 그 위에 검사를 직접 한다 — paths::locate 다음, 인덱스를 짓기 전에 폴더를
거절하고, 시스템이 적힌 대로 받지 못하는 경로(예: NUL 이 든 경로, 너무 긴 이름)도 거절한다
(paths::refused_as_written). 각 층의 계약은 src-tauri/src/cli/ 의 모듈 헤더와 문서 주석에 있다.
baram mcp 는 cli::run 이 stdout 을 잡기 전에 이 흐름에서 갈라져 cli::mcp 로 간다 — 명령 하나를 돌리는
대신 stdin 이 닫힐 때까지 서버로 돌고, stdout 은 프로토콜만 싣는다. vault 는 vault::resolve 대신
서버가 호출마다 자기 허용 집합 안에서 고르고, 그 아래의 paths 와 명령 함수는 CLI 와 공유한다. 서버만의 결정과
불변식은 MCP server 에 있다.
| 층 | 하는 일 | 하지 않는 일 |
|---|---|---|
| 모드 분기 | argv 만 보고 GUI 와 CLI 를 가른다 (cli::mode_for) |
둘째 인자 이후 읽기, 경로의 존재 확인 |
| vault 해석 |
--vault 의 경로 · 이름, 또는 현재 디렉터리로 vault 하나를 고른다. 못 찾으면 실패한다 |
앱의 활성 vault 로 대체, 승인 저장소와 대조 |
| 경로 인자 | 노트 · 폴더 경로를 그 vault 안의 경로로 바꾸고, 앱이 보지 않는 자리를 거른다. MCP 에서는 이 판정이 도구의 파일 경계다 | CLI 에서의 보안 경계 — 거기서 vault 밖의 거절은 범위 규칙이다 |
| 명령 | 조회 결과를 봉투에 담아 돌려준다. 직접 출력하지 않는다 | stdout 에 쓰기 |
| 출력 | 탭 구분 텍스트(read 는 파일 내용 그대로), 또는 한 줄짜리 JSON 봉투. 실패는 오류 코드와 종료 코드로 알린다 |
vault 조회 — output 의 함수는 받은 봉투 · 오류 · 경고를 쓸 뿐이다 |
main() 이 Tauri 를 시작하기 전에 argv 로 모드를 정한다. CLI 면 Tauri 를 시작하지 않고 tokio
런타임을 직접 만들어 명령 하나를 돌린 뒤 종료 코드로 끝난다(mcp 는 명령이 아니라 서버를 돌린다). 앱이 떠 있어도
CLI 는 별도 프로세스이고, 둘은 통신하지 않는다.
판정은 GUI 로 보낼 argv 를 열거하고 나머지를 전부 CLI 로 보낸다. GUI 쪽은 인자가 없을 때와, 첫
인자가 macOS 가 앱 번들을 띄우며 붙이는 -psn_ · -NS · -Apple 로 시작하거나, 절대 경로이거나,
scheme:// 꼴의 URL 일 때다 — 둘째 인자부터는 보지 않는다.
-
거꾸로(아는 하위 명령만 CLI 로) 하지 않는다. 그러면
baram --json search x와 오타가 창을 띄운다. 에이전트의 셸은 그 창이 끝날 때까지 멈추고, single-instance 가 없어 두 번째 앱이 뜬다. - 절대 경로는 존재를 묻지 않는다. 지워진 파일, 끊긴 드라이브, 권한 없는 파일에서 존재 검사는 거짓이 되고, 업데이트 재시작은 원래 argv 를 다시 넘긴다. 그런 실행이 CLI 사용법 오류로 떨어지면 Windows 의 GUI 서브시스템 실행 파일은 창도 메시지도 없이 끝난다.
‼️ -플래그로 앱을 다시 띄우는 플러그인(자동 시작 · single-instance)을 더하면 그 플래그를 GUI 쪽 목록에 넣어야 한다. 넣지 않으면 그 실행이 사용법 오류로 끝난다. 시험은 이것을 막아 주지 않는다 — 경고는mode_for의 주석에 있다.
vault 를 조회하는 로직은 원래 Tauri 타입이 없는 Rust 함수였다 — 파일 목록 · 읽기 · 검색 · 태그 ·
태스크 · 링크 인덱스. vault 를 읽는 명령은 이 함수들을 그대로 부른다. 앱과 같은 답을 내는 것이 목표이기 때문이다.
links 를 위해 링크 인덱스에 접근자 하나(outgoing_resolved)를 더했고, 그 안의 해석은 그래프 뷰의
해석기다. 그 결과로 따라오는 성질은 이렇다.
- 디스크를 읽는다. 저장하지 않은 편집은 보이지 않는다.
- 링크 인덱스를 부를 때마다 짓는다. 앱은 인덱스를 메모리에 쥐고 갱신하지만, CLI 프로세스는 명령 하나로 끝난다. 그 비용은 재어 받아들였다 — 측정값과 조건은 사용자 문서에 있다.
-
앱의 등록 목록과 설정은 앱 데이터 폴더의
config.json에서 읽는다. 그 키들의 값을 만드는 쪽은 Rust 가 아니라 프런트엔드의 zustand persist 다 — Rust 의set_config는 받은 문자열을 그 키에 그대로 둔다. 스토어 형식이 바뀌면 CLI 가 빈 목록을 읽게 되므로 형식을 계약 시험으로 묶었다 — 프런트 시험이 실제 persist 출력에 CLI 가 읽는 경로와 타입이 있는지 보고, Rust 시험이 같은 픽스처에서 뽑은 값을 단언하고, Rust 가 직렬화한 컨텍스트를 CLI 리더가 되읽는다.
같은 함수를 부르고도 답이 어디서 같고 어디서 일부러 다른지는 Links and app parity 가 다룬다.
명령 함수는 쓰지 않는다 — 봉투를 돌려줄 뿐, stdout 에 쓰는 것은 cli 모듈의 진입부다. CLI 에서는
run · execute 이고, MCP 에서는 cli::mcp 의 서버다. 이 서버가 명령 함수의 다른 앞단이다 — 도구는 같은
명령 함수를 불러 받은 결과로 답한다. read_note 는 read 대신 노트만 받는 짝(ops::read_note)을 부르고,
list_vaults 는 vaults 의 행 — --vault 를 주었으면 그 폴더들의 등록만 — 에, 앱이 등록하지 않았거나 폴더가
사라진 --vault 의 행(unregistered)을 직접 더한다(Scope::rows).
명령 함수는 --json 을 받지 않는다 — 텍스트로 쓸지 JSON 으로 쓸지는 진입부가 정한다. read 를 뺀
명령은 진입부가 그 플래그를 output::write_envelope 에 넘기고, read 는 execute 가 직접 가른다. 그
형식의 계약은 Output contract 에 있다.
경로 인자나 출력 한 주제에 속하지 않는 불변식이다. 경로 인자의 불변식은 Paths and vault boundary, 출력의 불변식은 Output contract 에 있다.
| 불변식 | 왜 · 무엇이 지키나 |
|---|---|
읽기 전용 — vault, 앱의 config.json, 앱 로그 파일에 쓰지 않는다 |
종단 시험이 시험의 명령 목록을 텍스트와 --json 으로 모두 돌린 전후로 vault · HOME · XDG_DATA_HOME 의 스냅샷을 비교하고, 짝으로 시험이 직접 한 쓰기를 그 스냅샷이 잡는지도 본다. 그 명령 목록은 다른 시험이 --help 에 보이는 명령과 같음을 단언한다 — 보이는 명령을 더하면 거기서 깨지고, 숨긴 명령(hide = true)은 --help 에 나오지 않아 잡히지 않는다 |
조용한 대체가 없다 — vault 를 못 찾으면 VAULT_NOT_FOUND 로 끝나고, 앱에서 마지막으로 연 vault 로 대신하지 않는다 |
대체하면 코드 저장소에서 부른 에이전트가 엉뚱한 vault 를 읽고도 모른다 |
| 루트 표기는 하나다 — 한 실행의 vault 루트는 정규화한 절대 경로 하나이고, 인덱스 build · 조회 · 태스크 제외 판정 · 출력 상대화가 모두 그 표기를 쓴다 | 링크 인덱스는 노트의 나가는 링크를 build 가 받은 경로 문자열 그대로의 키 아래 담고, 태스크 제외 판정은 접두사 제거가 실패하면 조용히 제외하지 않는다 — 표기가 갈리면 오류 없이 답이 틀린다 |
이 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