bholmesdev/hubble.md 딥다이브
— 폴더 하나가 곧 API가 되는 로컬 우선 노트 앱

1한 줄 정체

Hubble은 "내 폴더에 쌓이는 마크다운 파일을, 사람도 AI 에이전트도 함께 편집하는 노트 앱"이다. Notion 같은 블록 에디터(/ 명령, 마크다운 단축키, 프론트매터 속성)를 쓰지만 저장 형식은 평범한 .md 텍스트다. 그래서 에이전트를 그 폴더에 붙이면 곧바로 협업이 되고, 에이전트가 노트를 고치면 Hubble이 즉시 화면을 갱신한다. 여기에 "HTML 앱"이라는 확장 개념으로, 노트 폴더를 표·책장·지도 같은 맞춤 뷰로 바꿀 수 있다.

2왜 주목받는가 — 에이전트 시대의 노트장

Hubble이 떠오른 배경엔 "코딩 에이전트가 파일을 직접 다루는" 흐름이 있다. Claude Code·Codex·Cursor는 결국 폴더 안 파일을 읽고 쓰는 도구다. 그렇다면 노트 앱이 파일을 독점 DB에 가둘 게 아니라 그냥 폴더에 풀어 두면, 에이전트가 곧바로 1급 협업자가 된다는 게 Hubble의 통찰이다. README의 핵심 문구: "Point your agent at your notes folder to start collaborating. Hubble will live-reload as your agent edits."

두 번째 무기는 확장 방식이다. 보통 앱은 플러그인 SDK(자바스크립트 API)를 배워야 기능을 늘린다. Hubble은 "에이전트에게 HTML 앱을 짜 달라"로 대체한다. 파일시스템 자체가 확장 표면이 되는 셈이다.

비슷한 것들과의 비교

"그냥 마크다운 폴더 열면 되잖아?"에 대한 답

맞다, 텍스트 에디터로도 .md는 연다. 어려운 건 (1) Notion급 편집 경험을 주면서도 원본을 평문으로 유지, (2) 외부(에이전트) 편집을 안전하게 실시간 반영, (3) 에이전트가 짠 임의의 HTML을 시스템을 망치지 않게 실행하는 것이다. Hubble은 마크다운↔리치텍스트 왕복 변환 엔진, chokidar 파일 감시 라이브리로드, 그리고 불투명 출처(opaque origin) 샌드박스 iframe + 토큰 인증 브로커로 이 셋을 각각 정공법으로 풀었다.

3기술 스택 전체 지도

Hubble은 pnpm 워크스페이스 모노레포다(전부 TypeScript ~5.8, 린트·포맷은 ESLint+Prettier가 아니라 Biome 2.4, React Compiler까지 켜져 있음). 크게 apps/*(실행되는 3개 앱)와 packages/*(공유 코어)로 나뉜다.

① apps/desktop — 메인 Hubble 앱 (Electron)

• Electron 42.3 + electron-vite 5 + electron-builder 26 + electron-updater 6.8(자동 업데이트, 현재 macOS 한정).
• React 19.1 렌더러.
• Tiptap 3(@tiptap/core·react·pm·starter-kit + image/list 확장) — ProseMirror 기반 블록 에디터.
• 상태 관리는 Redux/Zustand가 아니라 저자가 만든 @simplestack/store 0.7(시그널 유사).
• UI: @base-ui/react, shadcn 4, class-variance-authority·clsx·tailwind-merge, sonner(토스트), @iconify-json/mingcute.
• 스타일: Tailwind CSS v4(@tailwindcss/vite, HTML 앱엔 @tailwindcss/browser 주입).
• 터미널: @xterm/xterm 6 + node-pty 1.1 — 앱 안에서 에이전트 CLI를 돌리는 내장 터미널.
• 기타: chokidar 4(파일 감시), Zod 4(검증), ignore 7(.gitignore 파싱), alpinejs 3.15(HTML 앱에 주입).

② apps/web — 마케팅 랜딩(hubble.md)

• Astro 6 + astro-icon·gsap·canvas-confetti, Node 22 필요.

③ apps/www — 브라우저판 Hubble (개발 중, HEAVILY WIP)

• Vite + React 19 + react-router 7 + Convex 1.34(백엔드). 로컬 FS가 없으니 워크스페이스는 항상 클라우드 동기화형.

④ packages/* — 공유 코어

• editor — 프레임워크 독립 마크다운 엔진. unified·remark-parse·remark-gfm·mdast·yaml로 파싱, ProseMirror로 변환. Hubble의 심장.
• ui — editor 위의 React UI. Tiptap 테이블, highlight.js/lowlight(코드 하이라이트), cmdk(커맨드 팔레트), @dnd-kit(드래그).
• runtime — 빌드 없이 두 파일(global.js, html-app-theme.css)만. HTML 앱에 주입되는 에이전트 브리지.
• sync(WIP) — 파일시스템↔Convex 동기화 엔진(콘텐츠 해시 충돌 감지). convex-client / sync-backend가 클라우드 동기화 담당.
• cli — 터미널에서 폴더를 동기화하는 hubble 바이너리.

4아키텍처 심화 — Electron 3분할과 HTML 앱 샌드박스

Hubble의 도메인 모델은 CONTEXT.md의 용어집이 곧 설계도다. 핵심 개념: Workspace(.hubble/config.json이 있는 논리적 노트 묶음. 클라우드가 아니라 설정 파일의 존재로 정의됨), HTML App(폴더 안의 .html 파일을 Hubble이 실행하는 미니 UI), Embed(마크다운 안에 인라인으로 박은 HTML 앱), Workspace Snapshot(원자적으로 조립된 로딩 완료 상태 — 이게 완성돼야 화면을 그린다).

① Electron 3분할 — 권한을 좁게 나누기

흥미로운 사실: 이 팀은 원래 Tauri에서 Electron으로 옮겼다(ADR-0002). 이유는 렌더러를 Chrome DevTools Protocol로 노출해 에이전트가 UI를 테스트할 수 있게 하려던 것. Main 프로세스만 파일시스템을 만지고, Preload는 contextBridge로 타입 안전한 window.desktopApi 하나만 노출하며(contextIsolation:true, nodeIntegration:false), Renderer는 결론만 받는다. 특히 렌더러는 사용자가 허용한 경로(grantedFiles/grantedRoots)만 만질 수 있는 권한 그랜트 모델을 쓴다 — 앰비언트 파일 접근이 없다.

② 마크다운 ⇄ 리치텍스트 왕복 변환

Hubble의 "평문을 유지하면서 예쁜 편집"을 가능케 하는 엔진(packages/editor). .md 텍스트는 먼저 프론트매터(YAML)를 본문과 분리(ADR-0003)한 뒤, remark AST를 거쳐 Tiptap/ProseMirror 문서로 바뀐다. 편집 후엔 다시 마크다운으로 직렬화해 디스크에 쓴다. 이 왕복 신뢰성(round-trip fidelity)은 MarkdownRoundtrip.test.ts 등으로 집요하게 테스트된다 — "화면에서 고치고 저장했더니 원문이 미묘하게 망가지는" 사고를 막는 계약이다.

③ HTML 앱 샌드박스 — 에이전트가 짠 코드를 안전하게 실행

가장 배울 게 많은 부분(ADR-0004/0005). 에이전트가 써넣은 임의의 HTML을 어떻게 안전하게 실행할까? Hubble은 불투명 출처(opaque origin) 샌드박스 iframe에 그 HTML을 넣는다: sandbox="allow-scripts allow-forms"(same-origin 없음), name={token}으로 고유 토큰 부여. iframe은 파일시스템에 직접 못 닿고, 오직 주입된 window.hubble.files.* API를 postMessage로 호출한다. 호스트 쪽 브로커(IframeView.tsx)가 토큰을 확인하고 Zod 스키마 검증 + 워크스페이스 경로 확인(assertPathInWorkspace)을 거친 뒤에만 실제 파일 작업을 대행한다.

④ HTML 앱 런타임 — 왜 "그냥 HTML"이 동작하나

에이전트는 Tailwind 클래스와 Alpine x-data만 쓴 평범한 .html을 써넣으면 된다. 비결은 Main 프로세스가 hubble-asset:// 프로토콜로 그 파일을 서빙하기 전에 테마 CSS·Hubble 런타임·Tailwind 브라우저 빌드·Alpine.js를 자동 주입하기 때문이다. 주입되는 packages/runtime/global.js가 window.hubble을 만든다:

// packages/runtime/global.js — HTML 앱이 파일을 다루는 유일한 통로
window.hubble = {
  files: {
    list:   (glob = "**/*") => requestHubble("files.list", { glob }),
    read:   (path)          => requestHubble("files.read", { path }),
    create: (input)         => requestHubble("files.create", { input }),
    update: (path, patch)   => requestHubble("files.update", { path, patch }),
    remove: (path)          => requestHubble("files.remove", { path }),
    open:   (path)          => requestHubble("files.open", { path }),
    // safeList/safeRead/... = 던지지 않고 { ok, value } 반환하는 변형
  },
};

호스트 쪽 브로커는 각 메서드를 Zod로 검증하고 경로를 워크스페이스 안으로 가둔다. update는 패치형이라 생략한 본문·속성 키는 보존되고, 속성 삭제는 명시적으로만 된다:

// apps/desktop/src/editor/IframeView.tsx (요지)
if (request.method === "files.update") {
  const path = await resolveFilePath(parseInput(markdownPathSchema, params.path), true);
  const patch = parseInput(filePatchSchema, params.patch);          // Zod 검증
  const absolutePath = await resolveWorkspaceFile(workspacePath, path, { exists: true });
  const markdown = await applyMarkdownPatch(absolutePath, patch);   // 실제 파일 수정
  await refreshFiles(workspacePath);
  return { ok: true, value: parseMarkdownFile(path, markdown) };
}

5디렉토리 구조 해부

구조에서 읽히는 의도는 "코어와 껍데기의 분리"다. 마크다운 엔진(editor)은 React를 모르는 순수 로직으로 떼어 두고, React UI(ui)가 그 위에 얹힌다. 그래서 데스크톱(Electron)·브라우저(Convex)·CLI가 같은 코어를 공유한다. 그리고 레포 자체가 에이전트로 운영된다 — .agents/.claude/.codex 설정과 docs/adr(설계 결정 기록)이 그 증거다.

6학습 포인트 — 기술별 배울 것

1) Electron 보안을 제대로 하는 법

contextIsolation:true, nodeIntegration:false, 타입 안전한 단일 contextBridge API, 그리고 권한 그랜트 모델(렌더러는 사용자가 허용한 경로만 접근). "권한은 기본 없음, 필요한 것만 명시"의 실전판. electron/main.ts와 preload.ts가 교과서.

2) 신뢰할 수 없는 코드를 iframe으로 격리하기 (가장 희귀)

불투명 출처 샌드박스 iframe + postMessage 비동기 RPC 브로커 + 토큰 인증 + Zod 검증 + 경로 제한. 임의의 사용자/에이전트 작성 HTML을 안전하게 실행하는 보안 아키텍처 사례 연구. ADR-0004/0005를 함께 읽자.

3) 마크다운 ⇄ 리치텍스트 양방향 변환

remark(unified) 파싱 + 커스텀 ProseMirror 직렬화기, 그리고 왕복 테스트를 정확성 계약으로 삼는 법. 평문을 진실의 출처로 유지하는 WYSIWYG 에디터를 만드는 진지한 수업.

4) 프론트매터를 타입 있는 속성 저장소로

YAML 1.2 의미론, 타입 추론(true/false→체크박스, YYYY-MM-DD→날짜), 패치 시 알 수 없는 키 보존(ADR-0003). "구조화 데이터를 평문에 얹는" 실전 패턴.

5) 모노레포 엔지니어링

pnpm 워크스페이스(workspace:* 의존), 프레임워크 독립 코어(editor)와 React UI(ui) 분리, ESLint+Prettier 대신 Biome, React Compiler + 감사(audit) 게이트. 여러 앱이 코어를 공유하는 대형 구조의 정석.

6) 로컬 우선 동기화 설계

디스크를 진실의 출처로 두고 Convex에 콘텐츠 해시 기반 충돌 감지로 조정하는 packages/sync/src/sync.ts. pushed/pulled/deleted/conflicts를 반환하는 재조정(reconciliation) 로직.

7시스템 / 실행 요구사항

8직접 해볼 수 있는 실습 과제

9관련 기술 심화 로드맵 (주차별)

10핵심 키워드 사전

11참고 링크

• GitHub 저장소: github.com/bholmesdev/hubble.md
• 공식 사이트: hubble.md
• 에이전트 스킬: bholmesdev/hubble-skills (npx skills add bholmesdev/hubble-skills)
• 내부 문서: 저장소 CONTEXT.md · AGENTS.md · docs/adr/* — 이 딥다이브의 1차 소스
• ProseMirror: prosemirror.net · Tiptap: tiptap.dev
• unified / remark: unifiedjs.com
• Electron 보안: 보안 체크리스트
• 참고 개념: local-first software, iframe sandbox, Convex, Biome, pnpm workspaces