Repository navigation
Home
Tauri 2.0 + Tiptap/ProseMirror + React 로 만든 경량 WYSIWYG 마크다운 에디터.
| 하려는 일 | 먼저 읽을 것 |
|---|---|
| 앱을 쓴다 | 시작하기 — 사용자 문서 전체는 baram.ing/ko/docs |
| 지금 무엇이 되고 무엇이 안 되는지 본다 | 이슈 |
| 코드에 기여한다 |
CLAUDE.md 의 기술 스택 · 로컬 실행 · 테스트 · Git 절. PR 을 열기 전에 돌릴 npm run verify:ci 는 CONTRIBUTING.md 에 있다 |
| 코드가 지켜야 하는 계약을 찾는다 | 리포의 CLAUDE.md 와 각 모듈 헤더 주석 |
| 플러그인을 만든다 | 빠르게 시작하기 |
| 테마를 만든다 | 테마 만들기 |
| 보안 문제를 알린다 |
SECURITY.md — 공개 이슈가 아니라 비공개 신고로 |
| 왜 이렇게 만들었는지 안다 | 여기 — 아래 원칙과 섹션 |
이 wiki 는 리포의 wiki/ 에서 생성된다. 합성·색인 레이어이므로 거의 변하지 않는 것만
직접 싣고 — 아키텍처 불변식, 결정과 그 근거, 두 번 밟지 말아야 할 함정 — 자주 변하는 것은
위 표의 canonical 한 집을 가리킨다.
웹뷰의 React 프런트엔드와 Rust 백엔드가 Tauri IPC 로 이야기하고, 노트는 디스크의 마크다운 파일이다. 같은 실행 파일이 명령줄 도구로도 돌고, sandboxed 플러그인은 따로 떨어진 웹뷰에서 돈다.
앱 웹뷰 — React
│ 에디터 Tiptap / ProseMirror
│ 상태 Zustand
│ 파이프라인 markdown → mdast → ProseMirror, 되돌릴 때는 그 역순 (remark)
│ trusted 플러그인 — 앱 코드와 같은 JS realm 에서 돈다
│
│ ▼ IPC 커맨드 (invoke) ▲ 이벤트 (llm:token · file:changed …)
│
│ 플러그인 웹뷰 plugin-<id> — sandboxed 플러그인, 플러그인마다 숨은 창 하나
│ │ ACL 이 허락하는 커맨드: 브로커 plugin_call, 전송 plugin_sandbox_connect ·
│ │ plugin_sandbox_report. 앱 웹뷰의 호스트와 주고받는 메시지도 Rust 를 거친다
│ │
│ │ CLI 모드 — 같은 실행 파일, argv 로 갈린다 (cli::mode_for)
│ │ │ Tauri 를 띄우지 않고 vault 를 조회하는 함수(파일 · 링크 인덱스 ·
│ │ │ 검색 · 태그 · 태스크)를 직접 부른다. 읽기만 한다
▼ ▼ ▼
Rust 백엔드 — 웹뷰의 호출은 IPC 커맨드를 거쳐, CLI 의 호출은 곧장 모듈로
│ 파일 · 파일 감시 · 링크 인덱스 · 검색 · 태그 인덱스 · 태스크 인덱스
│ 플러그인 브로커 · vault 승인 저장소 · export · git · 스냅샷 …
│ LLM 스트리밍 ──▶ AI 프로바이더 (HTTP)
▼
디스크의 마크다운 파일 (vault)
에디터 위의 vim 은 Vim, CLI 모드는 CLI 섹션이 잇는다. 파이프라인은 아래 원칙 1 이, trusted · sandboxed 티어는 원칙 3 과 사용자 문서 신뢰 모델, 보안, 오류 가 잇는다. 링크 인덱스 · vault 승인 저장소 · export 는 wiki 섹션이 없다 — 출처는 아래 표에 있다.
원칙마다 그것을 지키는 관문과, 그 관문이 보지 못하는 것을 함께 적는다.
-
원칙 — WYSIWYG 에서의 저장은 문서 전체를 다시 직렬화하고 표기를 한 가지로 맞춘다: 목록 기호
-, 굵게**, 기울임*, 구분선---,#제목, 코드 블록은 백틱 펜스. 그래서 다른 표기(*·+목록,__굵게__, Setext 제목, 들여쓴 코드, 문단 줄 끝의 공백 같은)로 쓴 파일은 첫 저장에서 그 줄들이 바뀐다. 그 표기로 쓴 원문은 왕복에서 바이트가 바뀌지 않아야 한다. source mode 에서의 저장은 버퍼의 글을 그대로 쓴다. -
왜 — 저장은 매번 문서 전체를 쓴다. 왕복이 무언가를 잃으면 사용자가 손대지 않은 곳에서 잃는다 — 굵게가 든
하이라이트(
==**b**==)를 읽으며 하이라이트를 버리고 다음 저장에\==**b**==를 쓰던 결함(#646 · #647)이 그랬다. 그 수정은 하이라이트를 지키되<mark>**b**</mark>로 쓴다 — 이것도 첫 저장에서 바뀌는 표기다. 표기를 맞추는 것은 잃는 것이 아니지만 diff 를 만든다 — 표 셀을 열 폭까지 채우던 정규화는 그래서 걷어 냈다(#645). -
무엇이 지키나 · 보지 못하는 것 — 라운드트립 시험(
Roundtrip: Headings·Roundtrip: Lists같은 vitest 묶음)이 제 입력의 바이트 일치를 단언하고, 확장마다 그 시험을 두는 것이CLAUDE.md의 규약이다. 시험한 입력뿐이다 — 모든 문법을 훑는 관문은 없다. 표기가 바뀌는 자리 가운데 표 구분 행의 대시 수(mdast 가 기록하지 않는다)와 후행 공백이 붙은 빈 체크박스는 시험이 정규화로 적어 둔다.
-
원칙 — 웹뷰가 넘긴 경로에 asset scope 를 열기 전에, Rust 가 소유한 승인 기록(
approved-roots.json)이 그 경로를 덮는지 본다. 덮지 않으면approval_cmd::ensure_approved는 사용자에게 묻고(경로를 풀지 못하면 거부), 플러그인 dev 폴더의 부여(admit_folder)는 묻지 않고 거부한다. -
왜 — 웹뷰는
config.json에 임의 키를 쓸 수 있어, 승인을 거기 두면 인가받아야 할 쪽이 자기 인가를 쓴다. -
무엇이 지키나 · 보지 못하는 것 —
no_new_asset_scope_grant_outside_the_allowlist가 크레이트 소스에서.allow_directory(·.allow_file(이 든 줄을 훑어 (파일, 줄 텍스트) 허용 목록과 개수로 고정한다. 새 자리가 승인 게이트를 먼저 지나는지는 목록에 올리는 사람이 보고, 목록에는 웹뷰 경로가 아닌 부여도 이유와 함께 있다.no_new_scope_forbid_call_anywhere_in_the_crate는.forbid_directory(·.forbid_file(이 든 줄을 허용 목록에 오른 줄 말고는 막는다 — forbid 는 allow 보다 우선하고 해제 API 가 없어, 회수가 그 세션의 재승인까지 죽인다. 이쪽은 개수를 세지 않아, 허용된 줄과 같은 텍스트를 같은 파일에 하나 더 두면 지나간다. 두 시험이 보는 것은 이 크레이트에 메서드 호출 꼴로 쓴 줄이다 —Scope::allow_directory(&scope, …)처럼 달리 쓴 호출과 의존성 안의 부여는 보지 못한다. 대화상자 플러그인의open·save는 사용자가 고른 경로를 asset scope 에 더하고, 앱 창은 그 권한(dialog:default)을 가진다.
-
원칙 —
sandboxed플러그인은 플러그인마다 숨은plugin-<id>웹뷰에서 돈다. 파일 · 네트워크 · 저장소는 Rust 브로커plugin_call이 창 라벨과 승인한 capability 로, 에디터 · AI · 설정 · UI 는 앱 쪽 호스트가 대조한다.trusted플러그인은 앱 코드와 같은 JS realm 에서 돌고, 거기서 capability 검사는 API 관문일 뿐이다. -
왜 — 같은 realm 의 코드는
invoke를 직접 import 해 앱 창이 허락받은 커맨드(앱 커맨드 가운데서는 sandbox 전용 커맨드를 뺀 전부)를 부를 수 있고, Rust 는 그 호출이 앱의 것인지 플러그인의 것인지 가를 수 없다. -
무엇이 지키나 · 보지 못하는 것 — Rust 통합 시험
acl_lockdown의sandbox_tier_grants_exactly_its_allowlist가plugin-*창에 닿는 capability 를 모두 합친 권한이 정확히plugin_call·plugin_sandbox_connect·plugin_sandbox_report의 allow 권한인지 보고, 브로커가 op 마다 요구하는 capability 는required_capability_mapping_is_exhaustive_and_not_cross_wired가 고정한다. 그 시험이 보는 것은 허락된 권한이다 — Tauri 가 ACL 을 거치지 않게 둔 채널 데이터 fetch 는 어느 웹뷰나 부를 수 있고,acl_lockdown의 주석이 그 한계를 적어 둔다.
-
원칙 — 링크가 가리키는 노트 이름 · 링크 대상 · 링크 앞의 vault alias 는 NFC → 소문자 → NFC 로 접어
비교하고, 프런트의
foldName과 Rust 의fold_name이 같은 접기다. 경로가 root 아래인지 묻는 판정은 이 접기를 쓰지 않는다. - 왜 — 키보드로 친 이름은 완성형(NFC)이고 macOS 의 일부 도구는 파일 이름을 분해형(NFD)으로 저장해, 한 이름이 두 문자열이 된다.
-
무엇이 지키나 · 보지 못하는 것 — 두 언어의 시험(
fold_name_agrees_with_the_shared_fixture, vitest 의foldName and the fixture the backend reads)이 같은 픽스처 파일을 읽는다. Rust 링크 인덱스 모듈 안에서fold_name을 건너뛰는 대소문자 접기는no_name_comparison_in_the_index_folds_case_past_fold_name이(이유와 함께 허용 목록에 오른 것 말고), ESLint 규칙이 지정한 프런트 파일의 맨toLowerCase·toLocaleLowerCase는no-restricted-properties가 막는다(eslint-disable-next-line을 단 줄 말고). 두 스캔은 정해 둔 꼴의 접기만 찾는다 — 접기 없는 바이트 비교(===·starts_with같은)는 보지 못한다. 그리고 스캔 범위 밖에서 이름을 비교하는 코드가 있다 — 프런트는 ESLint 규칙의 파일 범위 밖, Rust 는 링크 인덱스 모듈 밖이다(링크 대상을 맨 소문자로 파일 이름과 대조하는resolve_cross_vault_link처럼).
- Vim — WYSIWYG · source mode · 코드블록에서 켜지는 vim 모달 편집. 평문 표면은 기성 어댑터를, WYSIWYG 는 자체 엔진을 쓴다 — 그 선이 왜 거기인지와 한국어 입력을 어느 층에서 받는지가 내용이다. Overview → Architecture → Decisions and history. 파일 위치는 Code map.
-
CLI — 앱 실행 파일이 겸하는 읽기 전용 명령줄 도구. Tauri 를 띄우지 않고 앱과 같은
Rust 함수로 디스크의 vault 를 읽는다 — 모드 분기, 앱과 같은 답과 일부러 다른 답, 그 모양을 지키는 불변식이
내용이다. Overview → Architecture → Decisions and history.
같은 명령 함수를 MCP 도구로 내는
baram mcp는 MCP server.
| 영역 | 출처 |
|---|---|
| 링크 인덱스와 파일 rename (#678 · #619) |
CLAUDE.md Rust 절의 링크 index · 파일 rename 항목, index::filing 의 모듈 doc, 사용자 문서 위키링크와 태그
|
| 플러그인 실행 모델 (§260) | 사용자 문서 신뢰 모델, 보안, 오류, Rust 통합 시험 acl_lockdown 의 모듈 doc, createExtensionContext 위의 주석 |
| 테마와 외관 (§355~§371) | 사용자 문서 테마 · 테마 만들기 · 설정과 외관, installTheme 이 사는 모듈의 헤더 주석 |
| export 정책 (#527 · #545) |
CLAUDE.md TypeScript 절의 "export 경로는 둘이다" 항목, 사용자 문서 내보내기
|
| vault 경계 인가 (§329–§336) |
CLAUDE.md Rust 절의 "vault 경계는 자기를 인가할 수 없다" 항목, approval 모듈의 헤더 주석, 사용자 문서 볼트와 폴더 접근
|
리포의 wiki/ 를 고쳐 PR 로 보낸다. PR 의 CI lint 잡이 npm run lint 안에서 wiki 게이트 npm run lint:wiki
와 prettier 검사를 돌리고, wiki/ 의 변경이 main 에 들어오면 게시 워크플로가 wiki 게이트를 다시 돌린 뒤(prettier
검사는 다시 돌리지 않는다) GitHub wiki 로 게시한다. GitHub wiki 에서 직접 고친 것은 다음 게시가 알림 없이 덮는다.
- 합성 · 색인 레이어다. 거의 변하지 않는 것만 직접 싣고, 쓰는 법은 사용자 문서로, 구현 현황은 이슈로 보낸다.
- 낡는 숫자(줄 수 · 개수)와 "예정 · 대기 · 진행 중" 을 쓰지 않는다. § 번호와 이슈 · PR 번호는 식별자라 쓴다.
-
페이지 이름이 곧 계층이고, 바꾸지 않는다.
Vim Architecture는Vim-Architecture.md다 — GitHub wiki 에는 폴더가 없고 이름이 전역 유일해야 하며, 리다이렉트가 없어 이름을 바꾸면 밖에 남은 링크가 깨진다. 이름이 틀렸으면 새 페이지를 만들고 옛 페이지를 한 줄 포인터로 남긴다 — 게이트는 그 포인터 페이지에도 길이와 사이드바 등재를 요구하므로,scripts/check-wiki.mjs의SIZE_EXCEPTIONS에 이유와 함께 올리고 사이드바에 링크한다. -
페이지는 40~200줄이다 (Home · 사이드바 · 푸터는 게이트가 재지 않고, 정당한 예외는
SIZE_EXCEPTIONS에 이유와 함께 적는다). 새 페이지는 사이드바에 링크해야 게이트를 지난다. -
내부 링크는 확장자 없이
[Architecture](Vim-Architecture)꼴로 쓴다. 게이트가 대상 페이지가 있는지 보고,baram.ing링크는 사용자 문서 소스에 그 페이지가 있는지 본다. 이중 대괄호 문법은 코드 안이어도 게이트가 거부한다.
규칙의 출처는 CLAUDE.md 의 "개발자용 wiki 편집" 항목이고, wiki 게이트가 거는 검사는 scripts/check-wiki.mjs
에 있다 — 심볼릭 링크와 하위 디렉터리 금지처럼 이 페이지와 그 항목에 없는 것도 있다. 문장 하나하나에 걸리는
규칙은 같은 파일의 "주석·문서의 주장" 절에 있다.
이 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