MYBOX Sync

Sync a mapped folder in your Obsidian vault with NAVER MYBOX cloud storage. File creations, edits, renames, moves and deletions inside the mapped folder are pushed automatically; remote changes are pulled on demand. Built on the MYBOX Open API, following the "event trigger + batch" model of obsidian-git.

MVP scope: one-way automatic push (local → remote) plus a manual pull, a single mapped folder, and delete-as-trash. Two-way sync with conflict resolution, scheduled polling, multiple folder mappings, OAuth and shared folders are planned for later versions.

Disclosures

이 플러그인은 아래 항목에 해당하므로, Obsidian 개발자 정책에 따라 명시합니다.

An account is required. You need a NAVER account with MYBOX enabled, and a Personal Access Token (PAT) issued from the MYBOX web settings. Without a PAT the plugin cannot sync anything. The plugin itself is free; MYBOX storage quota follows your own NAVER account plan.

Network use. The plugin sends requests to exactly one remote service: the MYBOX Open API, whose base URL is set in the plugin settings. It is contacted only to list, upload, download, rename, move and trash files inside the folder you mapped — that is the entire purpose of the plugin. No other host is contacted.

No telemetry, no ads. The plugin collects no analytics and displays no advertisements. Diagnostic logging is entirely local: it is on by default and writes only to .obsidian/plugins/mybox-sync/mybox-sync.log inside your vault, trimmed to the last 2000 lines. You can turn it off in the plugin settings.

Files outside the vault are never accessed. All local reads and writes go through the Obsidian vault API and stay within your vault.

⚠️ Security note: your PAT is stored in plain text in the plugin's data file, as Obsidian provides no credential store. Anyone with access to your vault files can read it. Treat the token like a password and revoke it from MYBOX web if your vault is ever exposed.

동작

• 자동 (로컬 → 원격, FR-08~15): 매핑 폴더 내 파일 생성/수정/삭제/이름변경·이동을 감지해 디바운스(기본 5초) 후 MYBOX에 업로드/재업로드/휴지통 이동/rename·move로 반영합니다.
• 수동 (원격 → 로컬, FR-16~18): 명령 팔레트의 "원격 변경 가져오기 (pull)" 또는 리본 아이콘으로 원격의 신규/변경 파일을 내려받습니다. pull은 로컬 파일을 삭제하지 않으며, 양쪽이 모두 변경된 파일은 덮어쓰지 않고 건너뜁니다(충돌 회피).

파일을 지우면 원격에서도 휴지통으로 이동할 뿐 영구 삭제하지 않습니다(FR-25).

설정

1. MYBOX 웹(설정 > 계정 및 개인 액세스 토큰 관리)에서 PAT 발급.
2. 플러그인 설정에서 PAT와 동기화 로컬 폴더를 지정. API 베이스 URL은 기본값 그대로 두면 됩니다.
3. MYBOX 원격 폴더의 폴더 찾아보기 버튼으로 올릴 위치를 고르거나 새로 만듭니다.
4. 연결 확인 버튼으로 매핑 검증.

개발

npm install
npm run test        # 단위 테스트 (vitest run)
npm run typecheck   # 타입체크
npm run build       # 프로덕션 번들(main.js)
npm run dev         # 워치 빌드

빌드 산출물을 로컬 볼트에 바로 넣어보려면:

scripts/deploy-to-vault.sh "/절대경로/내Vault"

통합 테스트 (opt-in, 실호출)

실제 MYBOX 서버를 호출하므로 기본 테스트에서는 제외되어 있습니다. MYBOX_PAT과 MYBOX_BASE를 모두 지정해야 실행되며, 하나라도 없으면 조용히 건너뜁니다.

MYBOX_PAT=mbx_pat_xxx MYBOX_BASE=https://open-api.mybox.naver.com \
  npx vitest run --config vitest.integration.config.ts

구조

src/
├─ main.ts                 엔트리(라이프사이클·이벤트·명령 조립)
├─ pluginPaths.ts          플러그인 데이터 파일 경로 계산(순수)
├─ settings/               설정 스키마·UI
├─ sync/
│  ├─ VaultWatcher.ts      디바운스 버퍼
│  ├─ coalesce.ts          이벤트 병합(순수)
│  ├─ diff.ts              push/pull 결정 로직(순수, 핵심)
│  ├─ SyncEngine.ts        오케스트레이션
│  ├─ SyncStateStore.ts    매핑·baseline 영속화
│  ├─ pathMap.ts           경로 매핑(순수)
│  └─ ObsidianLocalGateway.ts  Vault 파일 IO
├─ api/
│  ├─ MyboxApiClient.ts    Open API 클라이언트
│  ├─ ObsidianHttpClient.ts requestUrl 래퍼
│  ├─ RateLimiter.ts       스로틀러·백오프·일일 카운터(순수)
│  └─ HttpClient.ts        HTTP 경계 인터페이스
└─ ui/
   ├─ StatusBar.ts         상태 표시·알림
   ├─ RemoteFolderModal.ts 원격 폴더 선택 모달
   └─ folderNav.ts         모달 탐색 상태(순수)

스펙: docs/specs/obsidian-mybox-plugin-spec.md · 플랜: docs/plans/obsidian-mybox-plugin-mvp.md

수동 회귀 체크리스트 (스펙 ID)

• PAT 저장/마스킹/경고 노출 (FR-01,02)
• 잘못된 PAT → 토큰 필요 알림, 동기화 중단 (FR-04)
• 매핑 폴더 파일 생성 → 원격 업로드 + 상태바 갱신 (FR-08,10,21)
• 파일 수정 → isOverwrite 재업로드 (FR-11)
• 폴더 생성 → 원격 폴더 생성 (FR-12)
• 파일 삭제 → 원격 휴지통 이동(영구삭제 아님) (FR-13,25)
• 이름변경/이동 → 원격 rename/move(재업로드 아님) (FR-14)
• 수동 pull → 원격 신규/변경 다운로드, 로컬 미삭제, 충돌 skip (FR-16~18)
• 앱 재시작 → 매핑/baseline 복원 (FR-19,20)
• 대량 변경 시 스로틀·백오프로 429 회피 (FR-22)
• 다운로드 일일 한도 근접 경고 (FR-23)

License

MIT