@wonseok-han/confluence-sync 1.8.0 → 2.0.0

package/README.md

@@ -1,439 +1,73 @@
 # confluence-sync
 
-**Confluence Cloud ↔ Markdown 양방향 동기화 CLI**
+**Confluence Cloud와 로컬 Markdown을 CLI·웹으로 가져오고 업로드합니다.**
 
-- **push** — 로컬 `.md` 디렉토리를 Confluence 페이지 트리로 발행. 폴더 구조가 그대로 페이지 계층이 됩니다.
-- **pull** — Confluence 페이지·폴더·**스페이스 전체**를 읽어 `.md` 로 가져옵니다.
+- **Fetch**: 원격 문서의 신규·버전·위치 변경을 확인합니다.
+- **Pull**: 받을 원격 문서를 로컬 폴더에 반영합니다.
+- **Push**: 직접 선택한 로컬 문서만 Confluence에 업로드합니다.
 
-문서를 git으로 관리하면서(docs-as-code) Confluence를 미러로 두거나, 반대로 Confluence에 쌓인 문서를 마크다운으로 내려받아 쓸 수 있습니다.
+Obsidian의 위키링크·콜아웃·각주와 이미지·PDF 첨부도 지원합니다.
 
-**[Obsidian](#obsidian) vault 와 그대로 맞물립니다** — pull 한 문서는 내부 링크가 이어져 그래프 뷰가 동작하고, vault 에서 쓴 `[[wikilink]]`·`![[embed]]`·frontmatter 를 push 가 그대로 이해합니다.
+## 웹으로 시작하기
 
----
+**[웹 열기](https://confluence-sync-six.vercel.app/)** · CLI 설치 없이 데스크톱 Chrome·Edge에서 사용합니다.
 
-## 설치
+1. **문서 폴더 열기**로 로컬 문서 폴더를 선택하고 읽기·쓰기 권한을 허용합니다.
+2. **Confluence → .env 연결 설정**에서 설정 파일을 선택합니다. 샘플 다운로드와 API 토큰 발급 가이드를 제공하며, 처음 사용하는 폴더는 **스페이스 연결**을 누릅니다.
+3. **Fetch → Pull**로 원격 문서를 확인하고 가져옵니다.
+4. 보낼 문서만 체크한 뒤 **업로드 미리보기 → Confluence에 업로드**를 누릅니다.
 
-```bash
-npm i -g @wonseok-han/confluence-sync
-
-confluence-sync --version
-confluence-sync --help
-```
-
-Node.js 22.13 이상이 필요합니다.
-
-> 짧은 이름 **`csync`** 도 같이 설치됩니다 — 아래 예시의 `confluence-sync` 는 전부 `csync` 로 바꿔 쓸 수 있습니다.
-
-## 파일 이동 후 매핑 정리
-
-`remap`은 로컬 문서의 `pageId`를 기준으로 `.confluence-sync.json`의 경로만 갱신합니다. 인증이나 네트워크 호출 없이 실행되며 문서 파일과 Confluence는 변경하지 않습니다.
-
-```bash
-# 매핑 변경 미리보기 → 매핑만 저장
-csync remap --base ./정리본 --dry-run
-csync remap --base ./정리본
-
-# 원본과 정리본이 다른 디렉토리라면 기존 해시도 가져오기
-csync remap --base ./정리본 --from-mapping ./원본/.confluence-sync.json
-
-# 업로드 없이 sync 예정 내역 확인
-csync sync --base ./정리본 --dry-run
-```
-
-확인 후 사용자가 `csync sync --base ./정리본`을 실행하면 원격에 반영됩니다. `sync`는 기존 기본 명령(`csync --base ...`)의 별칭입니다.
-
-- 기존 ID·제목·해시는 보존하고, 현재 경로에 따른 부모를 `pendingMove.parentKey`에 기록합니다. sync 시 실제 부모와 비교해 이동하고 성공 후 대기 기록을 제거합니다.
-- 경로만 달라지고 렌더링 결과 해시가 같으면 본문·첨부 업로드 없이 이동합니다. 제목·본문·링크 변환 결과가 달라졌거나 기존 해시가 없으면 기존 sync 규칙대로 본문도 갱신합니다. `remap`은 새 해시를 만들어 변경을 숨기지 않습니다.
-- 매핑에 없는 상위 폴더는 같은 스페이스·부모·제목의 원격 폴더를 먼저 찾아 연결하고, 없을 때만 sync 시 생성합니다. 부모 ID 미설정 시 홈페이지 바로 아래의 폴더도 화면상의 루트 폴더로 재사용합니다. 그 외 이름만 같고 부모가 다른 폴더는 재사용하지 않고 위치 충돌을 표시합니다. 폴더 검색과 메타데이터 조회 권한이 필요합니다. 생성 중 동명 충돌(400) 또는 충돌(409)이 나면 한 번 재조회해 같은 위치의 폴더를 재사용합니다. 매핑의 기존 폴더도 스페이스·제목·부모를 검증하며, 권한 오류나 위치 충돌은 자동 생성·이동으로 우회하지 않습니다. README가 있는 디렉토리는 해당 README 페이지가 부모입니다. 루트 문서는 `CONFLUENCE_PARENT_ID` 아래로 이동하며, 미설정 시 스페이스 최상위로 이동합니다. 최상위 이동은 부모 없는 홈페이지를 기준으로 검증하며, 기준을 확인할 수 없으면 실패합니다.
-- 동일 ID를 가진 여러 문서나 매핑, 경로의 ID 충돌, 손상된 JSON은 저장 전에 거부합니다. 이동 대상 페이지 조회 실패 시 자동 재생성하지 않으며, 이동 실패 시 대기 기록을 유지합니다.
-- `--mapping`은 출력 매핑 위치, `--from-mapping`은 읽기 전용 원본 매핑입니다. `.confluence-syncignore`와 반복 `--exclude`를 지원합니다. 원본과 정리본을 함께 스캔하지 말고 정리본만 `--base`로 지정하세요.
-- ID가 없는 문서는 remap에서 미연결로 표시합니다. **이후 sync에서는 기존 규칙대로 새 페이지가 생성될 수 있으므로**, 관리용 문서는 ignore로 제외하세요.
-- 대상에 없는 기존 매핑은 유지합니다. 폴더 자체에는 frontmatter ID가 없으므로 폴더 ID의 경로 변경은 추론하지 않으며, 새 위치에는 새 폴더가 생성될 수 있습니다. 원격의 빈 폴더를 자동 삭제하지 않습니다.
-- 부모 페이지 이동은 원격 하위 페이지에도 영향을 줄 수 있습니다. `--dry-run`은 로컬 계획이며 원격 상태를 조회하지 않습니다. remap 이후 구조를 바꿨다면 다시 remap하세요.
-
-이동은 [Confluence의 페이지 이동 API](https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content---children-and-descendants/#api-wiki-rest-api-content-pageid-move-position-targetid-put)를 사용합니다.
-
-## 빠른 시작
-
-```bash
-cd /path/to/docs          # 동기화할 .md 들이 있는 폴더
-
-confluence-sync init      # 대화형으로 .env 생성 (토큰 입력은 가려짐)
-confluence-sync --dry-run # 무엇이 올라갈지 미리보기
-confluence-sync           # 실제 발행
-```
-
-반대로 Confluence에서 가져오려면:
-
-```bash
-confluence-sync pull --space --out ./docs   # 스페이스 전체를 .md 로
-```
-
----
-
-## 웹에서 변환·동기화하기
-
-화면 상단의 **사용 도움말**에서 변환·동기화 순서, 참조 링크, 덮어쓰기와 로그 설명을 확인할 수 있습니다.
-
-```bash
-csync web                         # 홈 폴더에서 시작, 브라우저 자동 열기
-csync web --base ~/Documents       # 원하는 폴더에서 시작
-```
-
-1. **변환 폴더 선택…**으로 시스템 폴더 다이얼로그를 열어 Vault나 문서 묶음의 기준 폴더를 지정합니다. 경로를 붙여 넣고 **열기**를 눌러도 됩니다.
-2. 파일 이름을 검색하면 기준 폴더의 모든 하위 폴더에서 `.md` 문서를 찾고 상대 경로를 함께 표시합니다. 검색어를 지우면 현재 폴더 목록으로 돌아갑니다. 문서 트리에서 폴더 옆 화살표는 하위 항목을 펼치거나 접고, 폴더·파일 이름은 변환 대상을 선택합니다. 폴더 이름을 선택하면 하위 Markdown 전체, 파일 이름을 선택하면 그 문서 하나가 대상입니다. 펼침·접기는 선택한 대상을 바꾸지 않습니다.
-3. **출력 폴더 선택…**으로 저장 위치를 지정합니다. 새 폴더 경로를 입력할 수도 있으며, 비워두면 기준 폴더 옆에 `폴더명-converted-XXXXXX`를 만듭니다.
-4. **미리보기**를 누르면 본문 비교 화면에 삭제·추가된 부분이 색상으로 표시됩니다. 나란히/인라인 비교와 이전·다음 변경 이동을 지원합니다.
-5. **변환 후 저장**을 누르고 **결과 폴더 열기**로 확인합니다.
-
-웹에서 파일 하나를 선택하면 출력 폴더 바로 아래에 저장합니다. 폴더 전체를 선택하면 모든 하위 Markdown을 변환하고, 선택한 폴더 내부의 상대 경로만 출력 폴더 아래에 유지합니다. 링크 해석 기준은 단일 파일의 부모 폴더 또는 선택한 폴더입니다. CLI의 `--base` 동작은 그대로입니다. 원본과 겹치는 출력 경로는 거부하며, 기존 출력 파일과 내용이 같으면 재사용하므로 같은 폴더에 연속 저장할 수 있습니다. 이름은 같지만 내용이 다르면 대상 파일 목록을 보여주고 덮어쓸지 확인합니다. 취소하면 저장하지 않으며, 확인한 기존 파일이 변경되면 다시 확인합니다. **다른 문서 선택**을 누르면 기준 폴더와 변환 설정을 유지한 채 다음 문서를 고를 수 있습니다. 선택한 대상의 문서와 참조 첨부를 내보냅니다. 단일 파일 모드에서는 링크로 참조된 다른 문서를 함께 복사하지 않습니다. 폴더 변환의 본문 비교는 최대 20개 문서(문서당 200KB 이하)를 선택해서 확인하며, 실제 저장은 전체 문서에 적용됩니다.
-
-변환 미리보기는 원본 파일을 변경하지 않습니다. 폴더 선택창을 사용할 수 없는 환경에서는 경로를 직접 입력할 수 있습니다. Linux에서 폴더 선택창을 사용하려면 `zenity`가 필요합니다.
-
-웹은 `http://localhost:4318` 또는 `http://127.0.0.1:4318`에서 열 수 있습니다. 두 주소의 브라우저 저장소는 별개이므로 기존 경로 설정을 유지하려면 같은 주소로 접속하세요. 변환과 동기화 미리보기는 Confluence 인증 없이 사용할 수 있습니다. 내 컴퓨터의 파일을 탐색하므로 개인용 로컬 실행을 전제로 합니다. `--port 4320`으로 포트를 바꾸거나 `--no-open`으로 자동 열기를 끌 수 있습니다. 종료는 터미널에서 `Ctrl+C`입니다.
-
-변환 탭과 동기화 탭은 기준 폴더·탐색 위치·선택 문서를 각각 기억합니다. 예를 들어 변환은 Obsidian Vault를 기준으로 하고, 동기화는 변환 결과 폴더를 기준으로 지정할 수 있습니다. 각 탭의 경로와 출력 경로·설정 파일 경로·작업 옵션은 같은 브라우저의 로컬 저장소에 보관되어 탭 전환과 새로고침 후에도 유지됩니다. 삭제되거나 열 수 없는 경로는 안내 후 선택을 해제하거나 시작 폴더로 돌아갑니다. 인증 토큰과 동기화 실행 승인은 저장하지 않습니다.
-
-### Confluence 동기화 탭
+문서 미리보기·표 서식 정리·변환도 웹에서 할 수 있습니다. [화면과 자세한 웹 사용법](docs/user/WEB.md)
 
-1. 왼쪽에서 기준 폴더를 열고 **Confluence 동기화** 탭을 선택합니다.
-2. **선택 문서 / 현재 폴더 / 기준 폴더 전체** 중 업로드 범위를 고릅니다.
-3. **설정 확인**으로 서버·계정·스페이스·상위 페이지를 확인합니다. 기준 폴더의 `.env`를 자동으로 사용하며, 다른 `.env` 파일 경로를 직접 지정할 수도 있습니다. 기준 폴더에 `.env`가 없으면 웹 서버 실행 환경을 사용합니다. 지정한 파일은 다른 환경과 섞지 않으며, 토큰 값은 화면에 표시하지 않습니다.
-4. **동기화 미리보기**로 기존 CLI의 `--dry-run` 결과(신규·변경·동일·계층)를 확인합니다. 이 단계는 외부 API를 호출하지 않으므로 서버 연결·권한을 확인하는 기능은 아닙니다.
-5. **Confluence에 동기화**를 누르면 기존 CLI와 동일하게 신규 페이지를 만들고 변경된 페이지·첨부를 업로드합니다. `.confluence-syncignore`와 기준 폴더의 `.confluence-sync.json`을 사용합니다.
+<details>
+<summary>웹 화면 보기</summary>
 
-진행 내역은 화면에 표시되며, 같은 서버가 실행 중이면 새로고침 후에도 마지막 작업 상태를 확인할 수 있습니다. 대상·옵션·문서·설정이 바뀌면 다시 미리보기해야 합니다. 실패 시 일부 문서는 이미 반영됐을 수 있으므로 로그와 미리보기를 확인한 뒤 재실행하세요. 웹에서는 `--rebuild`(전체 삭제 후 재생성), 강제 갱신 및 pull을 제공하지 않습니다.
+예시 문서와 Confluence 데이터를 사용한 화면입니다.
 
-참조 폴더를 여러 개 지정하는 방법과 링크 검색 규칙은 [다른 동기화 폴더의 문서 링크](#다른-동기화-폴더의-문서-링크)를 참고하세요.
+![원격 변경 확인과 업로드할 문서 선택](docs/user/images/web/sync-workspace.png)
 
----
+</details>
 
-## 설정
+## CLI로 시작하기
 
-Confluence 접속 정보를 담은 `.env` 가 **실행 위치(cwd)** 에 있어야 합니다(셸 환경변수도 가능).
-
-**대화형 생성 (권장)**
-
-```bash
-confluence-sync init      # 항목별 안내에 따라 입력 → cwd 에 .env 생성
-```
-
-**직접 작성**
-
-| 변수 | 설명 |
-| --- | --- |
-| `CONFLUENCE_BASE_URL` | `https://api.atlassian.com/ex/confluence/<CLOUD_ID>/wiki` |
-| `CONFLUENCE_EMAIL` | Atlassian 계정 이메일 |
-| `CONFLUENCE_API_TOKEN` | Scoped API 토큰 (아래 참고) |
-| `CONFLUENCE_SPACE_KEY` | URL `.../wiki/spaces/<KEY>/...` 의 KEY |
-| `CONFLUENCE_PARENT_ID` | (선택) 루트 앵커 — 부모 **페이지 또는 폴더** ID. 비우면 공간 최상위 |
-| `CONFLUENCE_SYNC_BASE` | push 할 루트 디렉토리 (`--base` 로도 지정 가능) |
-
-### API 토큰 발급
-
-1. https://id.atlassian.com/manage-profile/security/api-tokens → **Create API token with scopes**
-2. 앱 **Confluence** 선택
-3. 쓰려는 기능에 맞춰 스코프 선택:
-
-   | 기능 | 필요 스코프 |
-   | --- | --- |
-   | **push 기본** (조회·생성·갱신) | `read:space` · `read:page` · `write:page` |
-   | 이미지/첨부 업로드 | `read:content-details` + `write:attachment` (둘 다) |
-   | README 없는 폴더를 Confluence 폴더로 생성 | `write:folder` |
-   | `--rebuild` (삭제 후 재생성) | `delete:page` (+ 폴더 있으면 `delete:folder`) |
-   | **pull** (읽기) | `read:page` + `read:content-details` |
-   | pull 시 첨부 이미지 다운로드 | `read:attachment` |
-
-   > 모두 `:confluence` 접미사가 붙습니다 (예: `read:page:confluence`).
-
-4. 토큰 계정은 대상 Space에 해당 권한이 있어야 합니다.
-
-### cloudId 확인
-
-`BASE_URL` 의 `<CLOUD_ID>` 는 아래에서 확인합니다.
-
-```
-https://<your-domain>.atlassian.net/_edge/tenant_info
-```
-
----
-
-## Push — Markdown → Confluence
+Node.js 22.13 이상인 22.x 또는 24.x가 필요합니다.
 
 ```bash
-confluence-sync --list                 # 인식된 문서·제목·계층만 출력 (호출·인증 없음)
-confluence-sync --dry-run              # 대상·상태(신규/변경/동일) 미리보기
-confluence-sync                        # 변경된 문서만 갱신 (+ 신규 생성)
-
-confluence-sync --base /abs/path/docs  # 동기화 루트 지정 (env 미설정 시 필수)
-confluence-sync guide/                 # 지정 폴더만
-confluence-sync guide/setup.md         # 단일 문서만 (상위 README 는 발행되지 않음)
-confluence-sync --force                # 변경 감지 무시, 전체 강제 갱신
-confluence-sync --verify               # 변경 없는 문서도 페이지 존재 확인
-confluence-sync --rebuild              # 매핑된 페이지 전부 삭제 후 재생성
-confluence-sync --exclude '*-draft.md' # 제외 패턴 (반복 가능)
-```
-
-### 폴더 = 페이지 계층
-
-- 폴더의 **`README.md`** 가 그 폴더의 **대표 페이지**가 되고, 같은 폴더의 다른 문서는 그 자식이 됩니다.
-- README 가 **없는** 폴더는 **Confluence 폴더**로 생성되고 그 아래로 문서가 들어갑니다 (`write:folder` 스코프 필요).
-- `README.md` 는 폴더 맨 앞, 나머지는 파일명순(숫자 prefix `01-`, `10-` … 로 순서 제어)으로 정렬되어 부모가 자식보다 먼저 생성됩니다.
-
-> **경로를 지정해 동기화할 때**는 상위 `README.md` 가 **발행 대상이 아닙니다.** 자식을 붙일 부모 pageId 를 얻는 데만 쓰이고, 내용이 바뀌어 있어도 갱신하지 않습니다(`· 상위` 로 표시). 아직 페이지가 없으면 자식을 붙일 곳이 없으므로 그때는 생성합니다. 상위 문서도 갱신하려면 함께 지정하세요.
-
-```
-docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
-├── README.md              → 루트 페이지
-├── 10-guide/
-│   ├── README.md          → "10-guide" 대표 페이지
-│   └── 01-setup.md        → 그 자식 페이지
-└── 20-notes/              → README 없음 → Confluence 폴더
-    └── memo.md            → 폴더 안 페이지
-```
-
-### 변환 규칙
-
-- 페이지 제목은 **frontmatter `title` → 첫 `# 제목` → 파일명** 순으로 정해지고, 본문은 storage format 으로 변환됩니다.
-- 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
-- `mermaid` 코드블록 뒤에는 **Mermaid diagram** 매크로를 자동 삽입합니다. Confluence에 [Atlassian Labs Mermaid Diagrams Viewer](https://marketplace.atlassian.com/apps/1232887/mermaid-diagrams-viewer)가 설치되어 있어야 하며, 원본 코드도 함께 표시됩니다. 자동 연결은 등장 순서를 사용하므로 페이지의 모든 Mermaid 코드는 `mermaid` 코드블록으로 작성하세요.
-- **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
-- **섹션 링크** `[§1 개요](#1-개요)` · `[§6](./04-구현체.md#6-zkp)` · `[[문서#헤딩 텍스트]]` → Confluence 앵커 링크. [아래 참조](#섹션-링크-앵커)
-- **일반 파일 링크** `[자료](<attachments/자료.pdf>)` → PDF·TXT·MMD·JSON 등 실제 로컬 파일을 페이지 첨부로 업로드하고 다운로드 링크로 변환합니다. 경로는 Markdown 문서 위치 기준이며, 한글·공백 경로와 반복 링크를 지원합니다. 문서 링크(`.md`)·외부 URL·없는 파일은 기존 링크를 유지합니다. 같은 페이지에서 서로 다른 파일의 파일명이 같으면 업로드 이름에 경로 기반 접미사를 붙여 구분합니다.
-- **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
-- **YAML frontmatter** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
-
-### 다른 동기화 폴더의 문서 링크
-
-`--reference-root`를 반복해서 지정하면 다른 동기화 폴더에 이미 게시된 문서로 연결할 수 있습니다.
-
-```bash
-csync --base ./confluence-docs/project \
-  --reference-root ./confluence-docs/DBP \
-  --reference-root ./confluence-docs/shared \
-  ./confluence-docs/project/guide.md --dry-run
-```
-
-위키링크 `[[원본/긴/경로/문서명|표시 이름]]`와 Markdown 링크 `[표시 이름](../이전/문서명.md)` 모두 지원합니다. 현재 루트의 정확한 경로를 먼저 찾고, 참조 루트의 정확한 경로, 전체 후보의 파일명 순으로 검색합니다. 파일명 검색 결과가 하나일 때만 연결하며 별칭은 유지합니다. 현재 루트의 문서는 페이지 제목으로, 참조 문서는 `<참조 루트>/.confluence-sync.json`의 페이지 ID를 사용한 URL로 연결합니다.
-
-참조 폴더는 같은 Confluence 서버의 문서여야 합니다. 참조 폴더의 `.env`에 서버 주소가 있으면 현재 서버와 일치하는지 검사합니다. `.env`가 없으면 현재 서버의 매핑으로 간주합니다. 참조 문서와 매핑은 읽기만 하며 함께 업로드하지 않습니다. 제외 규칙도 적용합니다. 페이지 ID의 실제 서버 존재 여부는 미리보기에서 검사하지 않습니다.
-
-중복 파일명, 대상 문서 누락, 게시 매핑 누락은 CLI 출력과 웹 동기화 미리보기에 경고로 표시하고 링크 원문은 유지합니다. 경고는 업로드를 차단하지 않으므로 실행 전에 확인하세요. 다른 루트의 섹션 링크는 기존 앵커를 사용하며 참조 페이지에 앵커를 새로 만들지 않습니다.
-
-웹에서는 **Confluence 동기화 → 참조 문서 폴더**에 한 줄씩 입력하거나 **참조 폴더 추가…**로 선택합니다. 설정은 새로고침 후에도 유지됩니다. 참조 폴더의 문서·매핑·설정이 변경되면 다시 미리보기해야 합니다. `convert`에는 이 옵션이 필요하지 않습니다.
-
-### 섹션 링크 (앵커)
-
-문서는 표준 마크다운 그대로 두면 됩니다. 이 도구가 Confluence 쪽 앵커를 만들어 맞춰 줍니다.
-
-**Confluence 가 헤딩에 자동으로 붙이는 id 에는 기대지 않습니다.** 그 규칙은 Cloud 와 Data Center 가 다르고(Cloud 는 공백만 하이픈으로 바꾸고, DC 는 `페이지제목-헤딩` 형태) 예고 없이 바뀌기 때문입니다. 대신 **링크 대상이 되는 헤딩 앞에 [Anchor 매크로](https://confluence.atlassian.com/doc/anchors-139442.html)로 이름(= 마크다운 슬러그)을 직접 심고** 링크가 그 이름을 가리키게 합니다 — 양쪽 다 이 도구가 정한 값이라 어느 배포판에서도 맞습니다. 실제로 가리켜지는 헤딩에만 심으므로 페이지가 지저분해지지 않습니다.
-
-| 쓰는 것 | Confluence 에서 |
-| --- | --- |
-| `[§1 개요](#1-개요)` | 같은 페이지의 그 헤딩으로 이동 |
-| `[[#1. 개요]]` · `[[#1. 개요\|§1]]` | 위와 동일 (Obsidian 표기) |
-| `[§6 ZKP](./04-구현체.md#6-zkp)` | 그 페이지의 그 헤딩으로 이동 |
-| `[[04-구현체#6. ZKP]]` | 위와 동일 (Obsidian 표기) |
-
-- 슬러그 규칙은 **GitHub 과 동일**합니다 — 소문자화 → 문자·숫자 아닌 것 제거 → 공백 하나당 하이픈 하나. 공백을 접지 않으므로 `제목  ·  블록` 의 `--` 도 그대로 맞습니다. 겹치는 헤딩에는 `-1`·`-2` 가 붙습니다.
-- 문서의 첫 `# H1` 을 가리키는 링크는 **페이지 최상단**이 됩니다 (H1 은 Confluence 페이지 제목이 되므로).
-- **대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 경고합니다.** 엉뚱한 섹션으로 보내는 대신 알려주는 쪽을 택했습니다 — 대개 오타나 깨진 상대경로입니다.
-
-```
-$ confluence-sync --base ./docs --dry-run
-  [변경] guide/usage.md  →  "사용 안내"  (…, 내부링크: 36, 섹션링크: 30, 앵커: 15, 이미지: 0)
-  ⚠ 대응 헤딩 없는 앵커  guide/reference.md  #없는-헤딩
-```
-
-`섹션링크` 는 이 문서가 **가리키는** 링크 수, `앵커` 는 이 문서에 **심긴** 앵커 수입니다(다른 문서가 가리키는 것 포함).
-
-pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니다(`--obsidian` 이면 `[[문서#헤딩 텍스트]]`).
-
-### 변경 감지와 매핑
-
-- 문서의 `제목 + 본문 + 참조 첨부 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
-- 매핑은 **`<base>/.confluence-sync.json`** 에 저장됩니다. **문서셋과 함께 커밋하세요** — 지우면 다음 실행에서 페이지가 중복 생성됩니다. (`--mapping <path>` 로 위치 변경 가능)
-- **pull 도 같은 매핑에 기록합니다** — 그래서 pull 직후 push 하면 `= 변경없음` 입니다. [Pull → 매핑 기록](#매핑-기록) 참고.
-- Confluence 에서 페이지가 삭제됐다면 자동으로 **재생성**하고, 그 페이지를 가리키던 문서들도 **링크를 다시 연결**합니다. 내용이 그대로라 스킵되는 경우까지 잡으려면 `--verify` 를 씁니다.
-
-### 동기화 제외 (로컬 전용 문서 유지)
-
-같은 폴더에 올릴 문서와 로컬에만 둘 문서가 섞여 있을 때 제외할 수 있습니다.
-
-- **`<base>/.confluence-syncignore`** — `.gitignore` 방식 패턴 파일 (문서셋과 함께 커밋)
-
-  ```gitignore
-  *-draft.md            # 초안 전부 제외
-  notes/local-only.md   # 특정 파일만 (notes/ 의 나머지는 동기화)
-  secret/               # 폴더 통째로
-  ```
-
-- **`--exclude <glob>`** — 일회성 제외 (반복 가능)
-
-제외된 문서는 list·dry-run·sync 모든 모드에서 빠지고, 그 문서만 있던 폴더는 생성되지 않습니다. 부정(`!`), `**` 등 `.gitignore` 규칙을 그대로 따릅니다.
-
-### `--rebuild`
-
-부모 관계는 **생성 시점에만** 지정되어 사후 이동이 어렵습니다. 계층을 갈아엎으려면 `--rebuild` 로 매핑된 페이지·폴더를 모두 삭제(휴지통) 후 재생성합니다. 매핑에 기록된 것만 지우므로 수동으로 만든 페이지는 건드리지 않습니다.
-
----
-
-## Pull — Confluence → Markdown
-
-```bash
-confluence-sync pull <pageId|url>                  # 한 페이지를 현재 폴더에 .md 로
-confluence-sync pull <url> --out ./docs            # 출력 디렉토리 지정
-confluence-sync pull <url> --out ./docs --children # 하위 페이지·폴더까지 트리로 복원
-confluence-sync pull --space --out ./docs          # 스페이스 전체 (홈페이지부터 전부)
-confluence-sync pull --space --obsidian --out ~/MyVault   # 내부 링크를 [[wikilink]] 로
-```
-
-- 대상은 **숫자 ID** 또는 **URL** (`.../pages/<ID>/...` 페이지, `.../folder/<ID>` 폴더) 둘 다 됩니다.
-- **`--children`** — 하위를 재귀 복원합니다. 자식이 있는 페이지는 `<제목>/README.md` 폴더로 펼쳐져 **push 계층 관례와 맞물립니다**.
-- **`--space`** — 대상 없이 스페이스 전체를 가져옵니다. 페이지가 많으면 시간이 걸립니다.
-- **이미지/첨부** 는 문서별로 `attachments/<문서명>/` 아래에 내려받고 링크를 그 경로로 씁니다 (문서 폴더가 이미지로 지저분해지지 않음). 다운로드에는 `read:attachment` 스코프가 필요합니다.
-- **내부 링크** 는 같은 실행에서 함께 받은 페이지끼리 **상대 `.md` 링크로 이어집니다.** 받지 않은 페이지는 절대 URL 로 남습니다(깨진 링크를 만들지 않음).
-- **섹션 링크** 는 Confluence 앵커(`#페이지제목헤딩텍스트`)를 그 문서의 **마크다운 슬러그로 되돌립니다** — 그대로 두면 Obsidian·GitHub 어디서도 걸리지 않기 때문입니다. `--obsidian` 이면 `[[문서#헤딩 텍스트]]` 로 씁니다.
-- 각 문서 머리에 **frontmatter** 가 붙습니다 — `title` · `pageId` · `spaceKey` · `source` · `updated`. `pageId` 가 다시 push 할 때의 앵커입니다.
-- 제목은 frontmatter 의 `title` 로만 들어가고 **본문에 `# 제목` 을 따로 넣지 않습니다** — 제목을 별도로 표시하는 뷰어(Obsidian 등)에서 두 번 보이기 때문입니다. push 는 `title` 을 먼저 읽으므로 왕복에 문제가 없습니다.
-- 본문은 `export_view`(HTML)를 [turndown](https://github.com/mixmark-io/turndown) 으로 변환합니다 — 코드블록(언어 포함, 미지정은 `plaintext`), GFM 표, 리스트 등.
-
-> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다.
-
-### 매핑 기록
-
-pull 은 받아온 문서를 **매핑 파일에 함께 기록합니다** — 페이지 id 와, push 가 계산하는 것과 **같은 방식의 변경 해시**를 남깁니다. 그래서 **pull 직후 push 하면 `= 변경없음`** 입니다. 이게 없으면 매핑에 해시가 없어 방금 받아온 내용을 그대로 되올려 보내게 됩니다.
-
-```bash
-$ confluence-sync pull --space --out ./docs
-  …
-완료  페이지 42개, 폴더 3개 생성  내부링크 88개 연결  매핑 45건
-  매핑: /repo/docs/.confluence-sync.json  (base: /repo/docs)
-
-$ confluence-sync --base ./docs --dry-run
-  [동일] …          # 되올려 보낼 것이 없다
-```
-
-- **base 는 `--out` 에서 위로 올라가며 `.confluence-sync.json` 을 찾아 정합니다.** 매핑 키는 base 기준 상대경로여야 이어지는 push 가 같은 문서를 알아보기 때문입니다. 하위 폴더로 받아도(`--out <base>/일부`) 루트의 매핑에 제대로 들어갑니다.
-- 못 찾으면 `--out` 자체가 base 가 됩니다(그 디렉토리가 곧 동기화 루트가 됩니다).
-- **`--base <dir>`** · **`--mapping <path>`** 로 직접 지정할 수 있고, **`--no-mapping`** 이면 아무것도 쓰지 않습니다.
-- 같은 페이지가 다른 키에 남아 있으면(문서를 옮겼으면) 옛 키를 걷어내 중복 항목을 만들지 않습니다.
-
----
-
-## Obsidian
-
-pull 이 만드는 마크다운은 **vault 에 그대로 열립니다.** 별도 플러그인이 필요 없습니다.
-
-```bash
-cd ~/MyVault
-confluence-sync pull --space --out .              # 스페이스 전체를 vault 로
-confluence-sync pull --space --out . --obsidian   # 내부 링크를 [[wikilink]] 로
-```
-
-- 내부 링크가 이어져 있어 **그래프 뷰·백링크가 그대로 동작**합니다. 기본값인 상대 `.md` 링크도 Obsidian 에서 정상 동작하며 GitHub·VS Code 에서도 열립니다. vault 안에서만 쓸 거라면 `--obsidian` 으로 `[[wikilink]]` 를 받으세요.
-- frontmatter 는 Obsidian 속성 패널에 표시되고, `source` 로 원본 페이지를 바로 열 수 있습니다.
-
----
-
-## `convert` — 이미 받아둔 문서 손보기
-
-**다시 pull 하지 않고** 로컬 `.md` 트리를 제자리에서 고칩니다. Confluence 를 호출하지 않으니 인증도 필요 없습니다.
-
-```bash
-confluence-sync convert --to obsidian ./docs            # 상대 .md 링크 → [[wikilink]]
-confluence-sync convert --to markdown ./docs            # 되돌리기
-confluence-sync convert --fix ./docs                    # 옛 pull 결과 보정
-confluence-sync convert --to obsidian --fix ./docs      # 둘 다
-confluence-sync convert --fix ./docs --dry-run          # 바뀔 파일만 미리보기
-```
-
-### 대상 지정
-
-파일·폴더를 **여러 개** 줄 수 있고, 안 주면 base 전체가 대상입니다.
-
-```bash
-confluence-sync convert --fix ./docs/가이드/설치.md          # 파일 하나만
-confluence-sync convert --fix ./docs/a.md ./docs/나머지/     # 파일 + 폴더 혼합
-```
-
-`--base` 는 **링크를 해석하는 범위**입니다. 파일 하나만 고칠 때도 주변 문서를 알아야 이름이 유일한지, 링크 대상이 실재하는지 판정할 수 있기 때문입니다. 지정하지 않으면 준 경로들의 공통 상위 폴더가 되며, `--to` 로 링크를 바꿀 때는 **문서 트리 루트를 `--base` 로 알려주는 편이 정확합니다.**
-
-```bash
-confluence-sync convert --to obsidian ./docs/가이드/설치.md --base ./docs
+npm i -g @wonseok-han/confluence-sync
+mkdir my-docs
+cd my-docs
+csync init                  # 안내에 따라 .env에 연결 정보 입력
+csync pull                  # 스페이스 문서를 현재 폴더로 가져오기
 ```
 
-### 다른 곳에 내보내기 — `--out`
+API 토큰과 스페이스 키 준비는 [연결 설정 가이드](docs/user/CONFIGURATION.md#api-토큰-발급)를 참고하세요. 기존 문서 폴더를 먼저 연결하려면 `csync init --connect --base <폴더>`를 사용합니다.
 
-`--out` 없이 실행하면 **원본을 덮어씁니다.** 원본을 그대로 두고 결과만 따로 받으려면:
+평소에는 원격을 확인하고, 편집한 문서만 선택해 업로드합니다.
 
 ```bash
-confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
+csync fetch
+csync status
+csync pull
+# 로컬 문서 편집 후
+csync diff "가이드.md"
+csync add "가이드.md"
+csync push --dry-run --verify
+csync push
 ```
 
-- base 기준 상대 경로를 그대로 재현하고, **본문이 참조하는 첨부(이미지)도 같이 복사**합니다 — 안 그러면 링크가 깨집니다.
-- 안 바뀐 문서도 함께 내보내 **온전한 트리**가 나옵니다.
-- `--out` 이 base 안이면 원본을 오염시키므로 거부합니다.
-
-### 링크 표기 (`--to`)
-
-두 방향은 서로의 역변환이라 **왕복해도 내용이 보존됩니다.** 안전하게 바꿀 수 있는 링크만 건드립니다.
-
-- 외부 URL·이미지·깨진 링크(대상 파일 없음)는 **그대로 둡니다.**
-- 파일명이 트리 안에서 겹치면(`README.md` 여러 개 등) `[[wikilink]]` 로 바꾸지 않고 상대 링크를 유지합니다 — 이름만으로는 어느 노트인지 확정할 수 없기 때문입니다.
-- 코드블록·인라인 코드 안의 링크는 손대지 않습니다.
-- **섹션 링크는 표기가 다릅니다** — 표준 마크다운은 슬러그(`문서.md#6-zkp`), Obsidian 은 헤딩 텍스트(`[[문서#6. ZKP]]`)를 씁니다. 대상 문서의 헤딩을 찾아 옮기고, 못 찾으면 섹션 없이 문서 링크로 둡니다. Obsidian 블록 참조(`#^id`)는 마크다운에 대응물이 없어 같은 방식으로 처리합니다.
-- **같은 문서 섹션**도 마찬가지입니다 — `[§4](#4-버전)` ↔ `[[#4. 버전|§4]]`. 표 안에서 `\|` 로 이스케이프된 별칭도 인식합니다.
-
-### 각주와 첨부
-
-`--to markdown`은 각주를 위첨자 링크와 작은 제목으로 변환하고, 각주에 연결된 PDF의
-`#page=N` 페이지를 이미지로 표시합니다. 첨부파일은 `attachments/`에 모아 연결합니다.
-PDF 이미지 추출은 패키지에 포함된 PDF.js로 처리하므로 별도 도구 설치가 필요 없습니다.
-
-`--to obsidian`은 변환 정보와 원본 PDF가 남아 있는 로컬 변환본에서 각주와 PDF 참조를 복원합니다.
-Confluence에서 다시 내려받은 문서의 복원은 보장하지 않습니다.
+**Push는 add한 문서만 업로드합니다.** 기본 Pull은 로컬 수정·양쪽 변경을 보존하며, 로컬에서 파일을 삭제해도 원격 페이지를 삭제하지 않습니다. 연결과 매핑·선택 정보는 문서 폴더의 `.env`와 `.csync/`에 보관합니다.
 
-### 보정 (`--fix`)
+로컬 웹을 쓰려면 `csync web --base .`를 실행하세요. `csync`는 도움말만 표시하며, 명령별 옵션은 `csync <명령> --help`로 확인합니다.
 
-변환기가 개선되기 전에 pull 한 문서에는 옛 결함의 흔적이 남아 있습니다. 스페이스를 통째로 다시 받지 않고 그 흔적만 되돌립니다.
+## 필요한 설명 찾기
 
-| 증상 | 보정 |
+| 궁금한 내용 | 문서 |
 | --- | --- |
-| frontmatter `title` 과 본문 `# 제목` 이 중복 | 겹치는 H1 제거 (Obsidian 에서 제목이 두 번 보임) |
-| 모든 코드블록이 ` ```java ` | 실제 Java 가 아니면 `plaintext` 로 (Confluence 가 언어 미지정 시 `brush: java` 를 붙이는 탓) |
-| 제목에 `[data-colorid=…]{color:#…}` | 본문에 새어 나온 CSS 제거 |
-| `:11\_eleven\_blue:` · `\[선택 가능\]` · `**7️⃣**\-**1️⃣**` | 불필요한 `\` 이스케이프 해제 |
-| 리스트 항목마다 빈 줄 | 같은 종류 항목끼리 붙임 (번호↔글머리 경계는 유지) |
-| 코드블록 안 줄 끝 공백 | 정리 |
-
-**멱등적입니다** — 두 번 돌려도 더 바뀌지 않고, 최신 pull 결과에는 아무것도 하지 않습니다. 애매하면 손대지 않는 쪽을 택하므로 진짜 Java 코드블록은 그대로 남습니다. 파일을 덮어쓰니 `--dry-run` 으로 먼저 확인하세요.
-
-반대로 **vault 를 그대로 push** 할 수 있습니다. Obsidian 문법을 그대로 이해합니다.
-
-| vault 에서 쓴 것 | Confluence 에 올라가는 것 |
-| --- | --- |
-| `[[설계]]` · `[[구조/설계\|설계 문서]]` | 페이지 링크 (짧은 이름·경로 모두 인식) |
-| `[[설계#3. 구성]]` | 그 페이지의 그 섹션 |
-| `[[#3. 구성]]` · `[[#3. 구성\|§3]]` | **같은 페이지**의 그 섹션 |
-| `![[diagram.png]]` | 첨부 이미지 |
-| frontmatter `title:` | 페이지 제목 |
-| frontmatter `pageId:` | **그 페이지를 갱신** (새로 만들지 않음) |
-
-- 코드블록·인라인 코드 안의 `[[...]]` 는 건드리지 않고, **대상을 못 찾은 링크는 원문 그대로** 둡니다(조용히 사라지지 않습니다).
-- `.obsidian/` `.trash/` 등 숨김 폴더는 동기화 대상에서 제외됩니다.
-- `pageId` 덕분에 매핑 파일(`.confluence-sync.json`)을 잃어버려도 **중복 페이지가 생기지 않습니다** — 원본을 찾아가 갱신합니다(`[연결]` 로 표시).
-
-> pull → 편집 → push 왕복이 목적이라면 frontmatter 를 지우지 마세요. `pageId` 가 원본 페이지를 가리키는 유일한 단서입니다.
-
----
-
-## 기여 및 변경 이력
-
-- 버그 신고와 기능 제안: [GitHub Issues](https://github.com/wonseok-han/confluence-sync/issues)
-- 개발 환경과 테스트: [기여 안내](CONTRIBUTING.md)
-- 버전별 변경 사항: [CHANGELOG](CHANGELOG.md)
+| 명령별 옵션, 문서 선택·복구·이동, 제외 규칙 | [CLI 사용 안내](docs/user/CLI.md) |
+| 웹 화면, .env 가져오기, 문서 미리보기·표 편집 | [웹 사용 안내](docs/user/WEB.md) |
+| API 토큰, 작업공간 구조, v1에서 이전 | [설정과 작업공간](docs/user/CONFIGURATION.md) |
+| 위키링크·콜아웃·각주·PDF, convert 사용법 | [Obsidian과 문서 변환](docs/user/OBSIDIAN.md) |
 
-## 라이선스
+버그 신고는 [GitHub Issues](https://github.com/wonseok-han/confluence-sync/issues), 개발·테스트는 [기여 안내](CONTRIBUTING.md), 버전별 변경은 [CHANGELOG](CHANGELOG.md)를 참고하세요.
 
-[MIT](LICENSE)
+[MIT License](LICENSE)

package/dist/cli/args.js

@@ -1,6 +1,6 @@
 /** Positional arguments shared by command dispatch and push selection. */
 export function positionalArgs(argv) {
-    const values = new Set(['--base', '--reference-root', '--mapping', '--from-mapping', '--exclude', '--to', '--out', '--port']);
+    const values = new Set(['--base', '--reference-root', '--mapping', '--from-mapping', '--exclude', '--to', '--out', '--port', '--scope', '--confirm-scope']);
     const result = [];
     for (let i = 0; i < argv.length; i++) {
         if (values.has(argv[i])) {