@wonseok-han/confluence-sync 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wonseok-han
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,209 @@
+# confluence-sync
+
+**Confluence Cloud ↔ Markdown 양방향 동기화 CLI**
+
+- **push** — 로컬 `.md` 디렉토리를 Confluence 페이지 트리로 발행. 폴더 구조가 그대로 페이지 계층이 됩니다.
+- **pull** — Confluence 페이지·폴더·**스페이스 전체**를 읽어 `.md` 로 가져옵니다.
+
+문서를 git으로 관리하면서(docs-as-code) Confluence를 미러로 두거나, 반대로 Confluence에 쌓인 문서를 마크다운으로 내려받아 쓸 수 있습니다. 내려받은 마크다운은 Obsidian·VS Code 등 어디서든 그대로 열립니다.
+
+---
+
+## 설치
+
+```bash
+npm i -g @wonseok-han/confluence-sync
+
+confluence-sync --version
+confluence-sync --help
+```
+
+공개 npm 패키지라 **토큰이나 `.npmrc` 설정이 필요 없습니다.** (Node 20+)
+
+## 빠른 시작
+
+```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 로
+```
+
+---
+
+## 설정
+
+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
+
+```bash
+confluence-sync --list                 # 인식된 문서·제목·계층만 출력 (호출·인증 없음)
+confluence-sync --dry-run              # 대상·상태(신규/변경/동일) 미리보기
+confluence-sync                        # 변경된 문서만 갱신 (+ 신규 생성)
+
+confluence-sync --base /abs/path/docs  # 동기화 루트 지정 (env 미설정 시 필수)
+confluence-sync guide/                 # 지정 폴더만 (부모 README 자동 포함)
+confluence-sync guide/setup.md         # 단일 문서만
+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-` … 로 순서 제어)으로 정렬되어 부모가 자식보다 먼저 생성됩니다.
+
+```
+docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
+├── README.md              → 루트 페이지
+├── 10-guide/
+│   ├── README.md          → "10-guide" 대표 페이지
+│   └── 01-setup.md        → 그 자식 페이지
+└── 20-notes/              → README 없음 → Confluence 폴더
+    └── memo.md            → 폴더 안 페이지
+```
+
+### 변환 규칙
+
+- 각 문서의 **첫 `# 제목`** 이 페이지 제목이 되고, 본문은 storage format 으로 변환됩니다.
+- 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
+- **내부 `.md` 링크** → Confluence 페이지 링크로 자동 변환.
+- **로컬 이미지** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
+
+### 변경 감지와 매핑
+
+- 문서의 `제목 + 본문 + 참조 이미지 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
+- 매핑은 **`<base>/.confluence-sync.json`** 에 저장됩니다. **문서셋과 함께 커밋하세요** — 지우면 다음 실행에서 페이지가 중복 생성됩니다. (`--mapping <path>` 로 위치 변경 가능)
+- 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          # 스페이스 전체 (홈페이지부터 전부)
+```
+
+- 대상은 **숫자 ID** 또는 **URL** (`.../pages/<ID>/...` 페이지, `.../folder/<ID>` 폴더) 둘 다 됩니다.
+- **`--children`** — 하위를 재귀 복원합니다. 자식이 있는 페이지는 `<제목>/README.md` 폴더로 펼쳐져 **push 계층 관례와 맞물립니다**.
+- **`--space`** — 대상 없이 스페이스 전체를 가져옵니다. 페이지가 많으면 시간이 걸립니다.
+- **이미지/첨부** 는 문서별로 `attachments/<문서명>/` 아래에 내려받고 링크를 그 경로로 씁니다 (문서 폴더가 이미지로 지저분해지지 않음). 다운로드에는 `read:attachment` 스코프가 필요합니다.
+- 본문은 `export_view`(HTML)를 [turndown](https://github.com/mixmark-io/turndown) 으로 변환합니다 — 코드블록(언어 포함, 미지정은 `plaintext`), GFM 표, 리스트 등.
+
+> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다. 내부 페이지 링크는 절대 URL로 유지됩니다.
+
+---
+
+## 개발
+
+```bash
+git clone https://github.com/wonseok-han/confluence-sync.git
+cd confluence-sync
+npm install
+npm run build
+```
+
+소스에서 바로 실행할 때는 `npm run` 스크립트를 쓰고, 인자는 **`--` 뒤에** 둡니다.
+
+| 글로벌 | 로컬 |
+| --- | --- |
+| `confluence-sync` | `npm run sync` |
+| `confluence-sync --dry-run` | `npm run sync:dry` |
+| `confluence-sync --list` | `npm run list -- --base ./docs` |
+
+## 릴리스
+
+`v*` 태그를 푸시하면 GitHub Actions 가 빌드 → npm 배포 → GitHub Release 까지 자동 처리합니다.
+
+```bash
+npm version patch     # 또는 minor / major
+git push && git push --tags
+```
+
+워크플로는 `package.json` 버전과 태그가 일치하는지 검증한 뒤 배포합니다. 변경 이력은 [CHANGELOG.md](CHANGELOG.md) 를 참고하세요.
+
+> 사전 설정: npm Automation 토큰을 저장소 **Settings → Secrets and variables → Actions** 에 `NPM_TOKEN` 으로 등록해야 합니다.
+
+## 라이선스
+
+[MIT](LICENSE)

package/dist/colors.js

@@ -0,0 +1,20 @@
+/**
+ * 의존성 없는 ANSI 컬러 헬퍼.
+ * 비활성 조건: NO_COLOR / TERM=dumb / --no-color / 출력이 TTY 가 아님(파이프·리다이렉트).
+ * FORCE_COLOR 가 있으면 강제 활성.
+ */
+const enabled = !process.env.NO_COLOR &&
+    process.env.TERM !== 'dumb' &&
+    !process.argv.includes('--no-color') &&
+    (process.env.FORCE_COLOR ? true : process.stdout.isTTY === true);
+const wrap = (open, close) => (s) => enabled ? `\x1b[${open}m${s}\x1b[${close}m` : String(s);
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const magenta = wrap(35, 39);
+export const cyan = wrap(36, 39);
+export const gray = wrap(90, 39);
+export const colorEnabled = () => enabled;

package/dist/config.js

@@ -0,0 +1,28 @@
+/**
+ * 환경변수(.env / 셸) 로딩과 필수값 검증.
+ * dotenv 로딩은 진입점(sync.ts)에서 `import 'dotenv/config'` 로 먼저 수행된다.
+ */
+import { red, cyan } from './colors.js';
+export function readEnv() {
+    return {
+        baseUrl: process.env.CONFLUENCE_BASE_URL,
+        email: process.env.CONFLUENCE_EMAIL,
+        token: process.env.CONFLUENCE_API_TOKEN,
+        spaceKey: process.env.CONFLUENCE_SPACE_KEY,
+        // 신규 이름 우선, 없으면 구 이름(CONFLUENCE_PARENT_PAGE_ID) 하위호환
+        parentId: process.env.CONFLUENCE_PARENT_ID ?? process.env.CONFLUENCE_PARENT_PAGE_ID,
+    };
+}
+/** 동기화(생성/갱신)에 필요한 필수 환경변수 검증. 누락 시 종료. */
+export function requireEnv(env) {
+    const missing = [
+        ['CONFLUENCE_BASE_URL', env.baseUrl],
+        ['CONFLUENCE_EMAIL', env.email],
+        ['CONFLUENCE_API_TOKEN', env.token],
+        ['CONFLUENCE_SPACE_KEY', env.spaceKey],
+    ].filter(([, v]) => !v).map(([k]) => k);
+    if (missing.length) {
+        console.error(red(`환경변수 누락: ${missing.join(', ')}`) + `\n${cyan('confluence-sync init')} 으로 .env 를 만들 수 있습니다.`);
+        process.exit(1);
+    }
+}

package/dist/confluence.js

@@ -0,0 +1,242 @@
+/**
+ * Confluence Cloud API 클라이언트. createClient(config, opts) 로 생성하면
+ * baseUrl·인증·force/verify 옵션을 클로저로 묶은 메서드 집합을 돌려준다.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { relative } from 'node:path';
+import { red, yellow, dim } from './colors.js';
+export function createClient(cfg, opts) {
+    const authHeader = () => 'Basic ' + Buffer.from(`${cfg.email}:${cfg.token}`).toString('base64');
+    async function api(path, init) {
+        const res = await fetch(`${cfg.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: authHeader(),
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...(init?.headers ?? {}),
+            },
+        });
+        if (!res.ok) {
+            throw new Error(`Confluence API ${res.status} ${res.statusText}\n${path}\n${await res.text()}`);
+        }
+        return res.status === 204 ? null : res.json();
+    }
+    /** 페이지 조회. 삭제(휴지통)·부재면 404 → null 반환(그 외 오류는 throw) */
+    async function getPageOrNull(pageId) {
+        const res = await fetch(`${cfg.baseUrl}/api/v2/pages/${pageId}`, {
+            headers: { Authorization: authHeader(), Accept: 'application/json' },
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Confluence API ${res.status} ${res.statusText}\n/api/v2/pages/${pageId}\n${await res.text()}`);
+        return res.json();
+    }
+    async function getSpaceId(key) {
+        return (await getSpaceInfo(key)).id;
+    }
+    /** 스페이스 id + 홈페이지 id(=콘텐츠 트리 루트). */
+    async function getSpaceInfo(key) {
+        const data = await api(`/api/v2/spaces?keys=${encodeURIComponent(key)}`);
+        const space = data.results?.[0];
+        if (!space)
+            throw new Error(`Space key '${key}' 를 찾을 수 없습니다.`);
+        return { id: space.id, homepageId: space.homepageId };
+    }
+    /** 매핑에 기록된 페이지를 모두 삭제(휴지통). 매핑 파일 영속화는 호출자 책임. */
+    async function deleteAll(mapping) {
+        // 페이지(자식) 먼저, 폴더(컨테이너) 나중에 삭제
+        const entries = Object.entries(mapping).sort(([, a], [, b]) => (a.type === 'folder' ? 1 : 0) - (b.type === 'folder' ? 1 : 0));
+        console.log(yellow(`--rebuild: 기존 ${entries.length}건 삭제`));
+        for (const [key, { pageId, type }] of entries) {
+            try {
+                await api(type === 'folder' ? `/api/v2/folders/${pageId}` : `/api/v2/pages/${pageId}`, { method: 'DELETE' });
+                console.log(`  ${yellow('🗑  삭제')} ${key} ${dim(`(#${pageId})`)}`);
+            }
+            catch (e) {
+                console.error(red(`  ✗ 삭제 실패 ${key}`) + `\n${e.message}`);
+            }
+        }
+    }
+    /** 페이지의 기존 첨부 중 같은 파일명의 attachmentId 를 찾는다(없으면 null). */
+    async function findAttachmentId(pageId, filename) {
+        try {
+            const data = await api(`/rest/api/content/${pageId}/child/attachment?filename=${encodeURIComponent(filename)}`);
+            return data?.results?.[0]?.id ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 로컬 이미지를 페이지 첨부로 업로드(v1, multipart).
+     * 같은 파일명 첨부가 이미 있으면 데이터만 새 버전으로 갱신(중복 생성 400 방지),
+     * 없으면 신규 생성한다.
+     */
+    async function uploadAttachment(pageId, filename, abs) {
+        const buf = readFileSync(abs);
+        const form = new FormData();
+        form.append('file', new Blob([buf]), filename);
+        form.append('minorEdit', 'true');
+        const attId = await findAttachmentId(pageId, filename);
+        const path = attId
+            ? `/rest/api/content/${pageId}/child/attachment/${attId}/data` // 기존 첨부 데이터 갱신
+            : `/rest/api/content/${pageId}/child/attachment`; // 신규 첨부 생성
+        const res = await fetch(`${cfg.baseUrl}${path}`, {
+            method: 'POST',
+            headers: { Authorization: authHeader(), 'X-Atlassian-Token': 'nocheck' },
+            body: form,
+        });
+        if (!res.ok)
+            throw new Error(`attachment ${res.status} ${res.statusText}\n${await res.text()}`);
+    }
+    /** 페이지의 로컬 이미지들을 업로드. 성공 개수 반환. baseDir 은 로그 표시용. */
+    async function uploadImages(pageId, images, baseDir) {
+        let ok = 0;
+        for (const img of images) {
+            if (!existsSync(img.abs)) {
+                console.error(yellow(`    ⚠ 이미지 없음: ${relative(baseDir, img.abs)}`));
+                continue;
+            }
+            try {
+                await uploadAttachment(pageId, img.filename, img.abs);
+                ok++;
+            }
+            catch (e) {
+                console.error(red(`    ✗ 이미지 업로드 실패 ${img.filename}`) + `\n${e.message}`);
+            }
+        }
+        return ok;
+    }
+    /** 페이지 생성/갱신. 삭제 감지 시 재생성. 변경 없으면(opts.verify 아니면) 호출 없이 skip. */
+    async function upsertPage(mapping, spaceId, key, title, storage, hash, parentId, forceUpdate = false) {
+        const existing = mapping[key];
+        if (existing?.pageId) {
+            const changed = existing.hash !== hash || opts.force || forceUpdate;
+            // 변경 없고 검증(--verify)도 안 하면 호출 없이 스킵
+            if (!changed && !opts.verify)
+                return 'skipped';
+            const cur = await getPageOrNull(existing.pageId);
+            if (cur) {
+                if (!changed)
+                    return 'skipped'; // 페이지 존재 확인됨, 내용도 동일
+                const nextVersion = (cur.version?.number ?? 1) + 1;
+                await api(`/api/v2/pages/${existing.pageId}`, {
+                    method: 'PUT',
+                    body: JSON.stringify({
+                        id: existing.pageId,
+                        status: 'current',
+                        title,
+                        body: { representation: 'storage', value: storage },
+                        version: { number: nextVersion, message: `sync from git: ${key}` },
+                    }),
+                });
+                mapping[key] = { pageId: existing.pageId, title, hash };
+                return 'updated';
+            }
+            // cur === null: Confluence 에서 삭제됨 → 아래에서 신규 생성으로 복구
+        }
+        const body = {
+            spaceId, status: 'current', title,
+            body: { representation: 'storage', value: storage },
+        };
+        if (parentId)
+            body.parentId = parentId;
+        const created = await api(`/api/v2/pages`, { method: 'POST', body: JSON.stringify(body) });
+        mapping[key] = { pageId: created.id, title, hash };
+        return existing?.pageId ? 'recreated' : 'created';
+    }
+    // ---- pull(역방향) 전용 ----
+    /** v1 GET. api() 와 달리 /rest/api 계열 + 임의 expand 응답을 그대로 돌려준다. */
+    async function getV1(path) {
+        const res = await fetch(`${cfg.baseUrl}${path}`, {
+            headers: { Authorization: authHeader(), Accept: 'application/json' },
+        });
+        if (!res.ok)
+            throw new Error(`Confluence API ${res.status} ${res.statusText}\n${path}\n${await res.text()}`);
+        return res.json();
+    }
+    /**
+     * 콘텐츠 노드 조회. type + 제목 + export_view(HTML) + storage(원본 XHTML).
+     * storage 는 코드블록의 "진짜" 언어를 얻는 데 쓴다(export_view 는 언어 미지정 시 brush:java 기본값이 붙어 신뢰 불가).
+     */
+    async function getNode(id) {
+        const data = await getV1(`/rest/api/content/${id}?expand=body.export_view,body.storage`);
+        return {
+            id: data.id,
+            type: data.type ?? 'page',
+            title: data.title ?? id,
+            html: data.body?.export_view?.value ?? '',
+            storage: data.body?.storage?.value ?? '',
+        };
+    }
+    /** 자식 노드 목록(kind = page|folder, 전체 페이지네이션). */
+    async function listChildren(id, kind) {
+        const out = [];
+        let path = `/rest/api/content/${id}/child/${kind}?limit=100`;
+        while (path) {
+            const data = await getV1(path);
+            for (const c of data.results ?? [])
+                out.push({ id: c.id, title: c.title });
+            const next = data._links?.next;
+            path = next ? (next.startsWith('/') ? next : `/${next}`) : null;
+        }
+        return out;
+    }
+    const getChildPages = (id) => listChildren(id, 'page');
+    const getChildFolders = (id) => listChildren(id, 'folder');
+    /** 페이지 첨부 목록(파일명 + 다운로드 경로). */
+    async function listAttachments(pageId) {
+        const out = [];
+        let path = `/rest/api/content/${pageId}/child/attachment?limit=100`;
+        while (path) {
+            const data = await getV1(path);
+            for (const a of data.results ?? []) {
+                const downloadPath = a._links?.download;
+                if (downloadPath)
+                    out.push({ filename: a.title, downloadPath });
+            }
+            const next = data._links?.next;
+            path = next ? (next.startsWith('/') ? next : `/${next}`) : null;
+        }
+        return out;
+    }
+    /** 첨부 바이너리 다운로드. */
+    async function downloadAttachment(downloadPath) {
+        const url = downloadPath.startsWith('http') ? downloadPath : `${cfg.baseUrl}${downloadPath}`;
+        const res = await fetch(url, { headers: { Authorization: authHeader() } });
+        if (!res.ok)
+            throw new Error(`download ${res.status} ${res.statusText}\n${downloadPath}`);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    // ---- 폴더(README 없는 디렉토리 컨테이너) ----
+    /** 콘텐츠(페이지/폴더) 존재 확인. 404 → null (v1, 폴더 read 스코프 없이도 동작). */
+    async function getContentOrNull(id) {
+        const res = await fetch(`${cfg.baseUrl}/rest/api/content/${id}`, {
+            headers: { Authorization: authHeader(), Accept: 'application/json' },
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Confluence API ${res.status} ${res.statusText}\n/rest/api/content/${id}\n${await res.text()}`);
+        return res.json();
+    }
+    /** 폴더 생성(write:folder 필요). parentId 없으면 공간 최상위. 생성된 folder id 반환. */
+    async function createFolder(spaceId, title, parentId) {
+        const body = { spaceId, title };
+        if (parentId)
+            body.parentId = parentId;
+        const created = await api(`/api/v2/folders`, { method: 'POST', body: JSON.stringify(body) });
+        return created.id;
+    }
+    /** 폴더 삭제(--rebuild). */
+    async function deleteFolder(id) {
+        await api(`/api/v2/folders/${id}`, { method: 'DELETE' });
+    }
+    return {
+        api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, upsertPage,
+        getNode, getChildPages, getChildFolders, listAttachments, downloadAttachment,
+        getContentOrNull, createFolder, deleteFolder,
+    };
+}

package/dist/docs.js

@@ -0,0 +1,120 @@
+/**
+ * 문서 수집과 폴더=계층 구조 계산. 모든 키는 baseDir 기준 상대경로다.
+ * 폴더의 README.md 가 대표 페이지가 되고 같은 폴더의 다른 문서는 그 자식이 된다.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+import { splitTitleAndBody } from './markdown.js';
+/** dir 이하의 모든 .md 절대경로를 재귀 수집 */
+export function collectMarkdown(dir) {
+    const out = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...collectMarkdown(full));
+        else if (entry.isFile() && entry.name.endsWith('.md'))
+            out.push(full);
+    }
+    return out;
+}
+/** base 상대 경로 → 문서 제목(첫 H1) 인덱스 */
+export function buildTitleIndex(rels, baseDir) {
+    const idx = {};
+    for (const rel of rels) {
+        const { title } = splitTitleAndBody(readFileSync(resolve(baseDir, rel), 'utf8'), rel);
+        idx[rel] = title;
+    }
+    return idx;
+}
+const isReadme = (base) => /README\.md$/.test(base);
+/** 폴더 경로 → 그 폴더의 대표 README(base 상대) 인덱스 */
+export function buildFolderIndex(rels) {
+    const idx = {};
+    for (const p of rels) {
+        const parts = p.split('/');
+        if (isReadme(parts[parts.length - 1]))
+            idx[parts.slice(0, -1).join('/')] = p;
+    }
+    return idx;
+}
+const parentDirOf = (dir) => (dir.includes('/') ? dir.slice(0, dir.lastIndexOf('/')) : '');
+/**
+ * dir 의 직계 자식을 담는 "컨테이너"의 mapping 키.
+ * - 루트('') → null (CONFLUENCE_PARENT_ID)
+ * - README 가 있는 폴더 → 그 README 페이지 키
+ * - README 가 없는 폴더 → 폴더 노드 키(`<dir>/`, 끝에 슬래시로 구분)
+ */
+export function containerKeyOf(dir, folderIndex) {
+    if (dir === '')
+        return null;
+    return folderIndex[dir] ?? `${dir}/`;
+}
+/**
+ * 부모 결정(base 상대): 컨테이너 모델.
+ * - 일반 파일 → 자신이 속한 dir 의 컨테이너
+ * - 폴더 대표 README → 그 폴더의 "부모 dir" 컨테이너(README 는 자기 폴더를 대표하므로)
+ */
+export function parentKeyOf(rel, folderIndex) {
+    const parts = rel.split('/');
+    const dir = parts.slice(0, -1).join('/');
+    return isReadme(parts[parts.length - 1])
+        ? containerKeyOf(parentDirOf(dir), folderIndex)
+        : containerKeyOf(dir, folderIndex);
+}
+/** README 가 없어 Confluence 폴더로 만들어야 하는 dir 들(파일들의 모든 상위 dir 중 folderIndex 에 없는 것). */
+export function neededFolderDirs(rels, folderIndex) {
+    const set = new Set();
+    for (const rel of rels) {
+        let dir = parentDirOf(rel);
+        while (dir !== '') {
+            if (!folderIndex[dir])
+                set.add(dir);
+            dir = parentDirOf(dir);
+        }
+    }
+    return [...set];
+}
+/** README(폴더 대표)를 폴더 맨 앞에, 나머지는 파일명순 → 부모가 자식보다 먼저 */
+function sortKey(rel) {
+    const parts = rel.split('/');
+    const base = parts[parts.length - 1];
+    const dir = parts.slice(0, -1).join('/');
+    const leaf = isReadme(base) ? '' : base;
+    return dir === '' ? leaf : dir + '/' + leaf;
+}
+export function sortForSync(rels) {
+    return [...rels].sort((a, b) => {
+        const ka = sortKey(a), kb = sortKey(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+}
+/** 선택 경로(positionals)를 base 상대 키 집합으로 확장(디렉토리는 하위 .md 전부) */
+export function resolveSelection(rels, positionals, baseDir) {
+    const set = new Set();
+    for (const p of positionals) {
+        const abs = resolve(baseDir, p);
+        const relToBase = relative(baseDir, abs);
+        if (relToBase.startsWith('..')) {
+            console.error(`  ⚠ base 밖 경로 무시: ${p}`);
+            continue;
+        }
+        const matched = rels.filter((r) => r === relToBase || r.startsWith(relToBase + '/'));
+        if (matched.length === 0)
+            console.error(`  ⚠ 매칭되는 문서 없음: ${p}`);
+        matched.forEach((m) => set.add(m));
+    }
+    return [...set];
+}
+/** 선택된 문서의 상위 폴더 대표 README 들을 포함(부모 pageId 확보용). 폴더 노드는 neededFolderDirs 로 따로 생성. */
+export function withParents(selected, folderIndex) {
+    const out = new Set(selected);
+    for (const rel of selected) {
+        let dir = parentDirOf(rel);
+        while (dir !== '') {
+            if (folderIndex[dir])
+                out.add(folderIndex[dir]);
+            dir = parentDirOf(dir);
+        }
+    }
+    return [...out];
+}