@wonseok-han/confluence-sync 1.6.1 → 1.8.0

package/README.md

@@ -24,6 +24,35 @@ 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
@@ -170,6 +199,7 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 - `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** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
 
@@ -221,7 +251,7 @@ pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니
 
 ### 변경 감지와 매핑
 
-- 문서의 `제목 + 본문 + 참조 이미지 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
+- 문서의 `제목 + 본문 + 참조 첨부 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
 - 매핑은 **`<base>/.confluence-sync.json`** 에 저장됩니다. **문서셋과 함께 커밋하세요** — 지우면 다음 실행에서 페이지가 중복 생성됩니다. (`--mapping <path>` 로 위치 변경 가능)
 - **pull 도 같은 매핑에 기록합니다** — 그래서 pull 직후 push 하면 `= 변경없음` 입니다. [Pull → 매핑 기록](#매핑-기록) 참고.
 - Confluence 에서 페이지가 삭제됐다면 자동으로 **재생성**하고, 그 페이지를 가리키던 문서들도 **링크를 다시 연결**합니다. 내용이 그대로라 스킵되는 경우까지 잡으려면 `--verify` 를 씁니다.

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', '--exclude', '--to', '--out', '--port']);
+    const values = new Set(['--base', '--reference-root', '--mapping', '--from-mapping', '--exclude', '--to', '--out', '--port']);
     const result = [];
     for (let i = 0; i < argv.length; i++) {
         if (values.has(argv[i])) {

package/dist/cli/help.js

@@ -27,6 +27,15 @@ ${h('사용법:')}
   ${o('confluence-sync convert --to <형식>')}   이미 받은 .md 의 링크 표기를 바꾸기(로컬 전용)
   ${o('confluence-sync --help | --version')}
 
+${h('remap 옵션(로컬 매핑만 갱신, Confluence 호출 없음):')}
+  ${o('csync remap --base <dir>')}  pageId로 경로를 재연결하고 이동 대기 기록
+  ${o('--from-mapping <path>')}  원본 매핑에서 기존 ID·해시 가져오기(원본 유지)
+  ${o('--mapping <path>')}       저장할 매핑(기본: <base>/.confluence-sync.json)
+  ${o('--exclude <glob>')}       제외 패턴(반복 가능), .confluence-syncignore도 적용
+  ${o('--dry-run')}              변경 내역만 출력, 파일 저장 없음
+  이후 ${o('csync sync --base <dir> --dry-run')}으로 확인하고, 명시적으로 sync할 때 이동 반영.
+  기존 해시가 없으면 sync에서 본문도 갱신합니다. 폴더 ID의 경로 변경은 자동 추론하지 않습니다.
+
 ${h('web 옵션:')}
   ${o('--base <dir>')}      처음 열 폴더(기본: 홈 폴더). 화면에서 기준 폴더를 바꿀 수 있음
   ${o('--port <number>')}   웹 포트(기본: 4318)

package/dist/cli/main.js

@@ -5,6 +5,7 @@ import { printHelp, readPkgVersion } from './help.js';
 import { runInit } from './init.js';
 import { runConvert } from '../conversion/convert.js';
 import { runPull } from '../sync/pull.js';
+import { runRemap } from '../sync/remap.js';
 import { runPush } from '../sync/push.js';
 const argv = process.argv.slice(2);
 try {
@@ -20,6 +21,15 @@ try {
             case 'convert':
                 await runConvert(argv);
                 break;
+            case 'remap':
+                await runRemap(argv);
+                break;
+            case 'sync': {
+                const args = [...argv];
+                args.splice(args.indexOf('sync'), 1);
+                await runPush(args);
+                break;
+            }
             case 'pull':
                 await runPull(argv);
                 break;

package/dist/confluence/client.js

@@ -5,6 +5,15 @@
 import { readFileSync, existsSync } from 'node:fs';
 import { relative } from 'node:path';
 import { red, yellow, dim } from '../shared/colors.js';
+class ConfluenceApiError extends Error {
+    status;
+    responseBody;
+    constructor(status, path, responseBody, statusText) {
+        super(`Confluence API ${status} ${statusText}\n${path}\n${responseBody}`);
+        this.status = status;
+        this.responseBody = responseBody;
+    }
+}
 export function createClient(cfg, opts) {
     const authHeader = () => 'Basic ' + Buffer.from(`${cfg.email}:${cfg.token}`).toString('base64');
     async function api(path, init) {
@@ -18,7 +27,7 @@ export function createClient(cfg, opts) {
             },
         });
         if (!res.ok) {
-            throw new Error(`Confluence API ${res.status} ${res.statusText}\n${path}\n${await res.text()}`);
+            throw new ConfluenceApiError(res.status, path, await res.text(), res.statusText);
         }
         return res.status === 204 ? null : res.json();
     }
@@ -61,66 +70,104 @@ export function createClient(cfg, opts) {
     }
     /** 페이지의 기존 첨부 중 같은 파일명의 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;
-        }
+        const data = await api(`/rest/api/content/${pageId}/child/attachment?filename=${encodeURIComponent(filename)}`);
+        return data?.results?.[0]?.id ?? null;
     }
     /**
-     * 로컬 이미지를 페이지 첨부로 업로드(v1, multipart).
+     * 로컬 파일을 페이지 첨부로 업로드(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()}`);
+        // 롤백 오류에만 재시도한다. 매번 첨부를 재조회해 생성/갱신 경로를 다시 결정한다.
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const attId = await findAttachmentId(pageId, filename);
+            const path = attId
+                ? `/rest/api/content/${pageId}/child/attachment/${attId}/data`
+                : `/rest/api/content/${pageId}/child/attachment`;
+            const form = new FormData();
+            form.append('file', new Blob([buf]), filename);
+            form.append('minorEdit', 'true');
+            const res = await fetch(`${cfg.baseUrl}${path}`, {
+                method: 'POST',
+                headers: { Authorization: authHeader(), 'X-Atlassian-Token': 'nocheck' },
+                body: form,
+            });
+            if (res.ok)
+                return;
+            const detail = await res.text();
+            if (res.status === 500 && /UnexpectedRollbackException|rollback-only/i.test(detail) && attempt < 2) {
+                console.error(yellow(`    ↻ 첨부 트랜잭션 롤백, 재시도 ${attempt + 1}/2: ${filename}`));
+                await new Promise(resolve => setTimeout(resolve, 1000 * 2 ** attempt));
+                continue;
+            }
+            const traceId = res.headers.get('atl-traceid') ?? res.headers.get('x-arequestid');
+            throw new Error(`attachment ${res.status} ${res.statusText}\nPOST ${path}${traceId ? `\ntraceId: ${traceId}` : ''}\n${detail}`);
+        }
     }
-    /** 페이지의 로컬 이미지들을 업로드. 성공 개수 반환. baseDir 은 로그 표시용. */
-    async function uploadImages(pageId, images, baseDir) {
+    /** 페이지의 로컬 첨부를 업로드. 성공 개수 반환. */
+    async function uploadAttachments(pageId, attachments, baseDir) {
         let ok = 0;
-        for (const img of images) {
-            if (!existsSync(img.abs)) {
-                console.error(yellow(`    ⚠ 이미지 없음: ${relative(baseDir, img.abs)}`));
+        for (const file of attachments) {
+            if (!existsSync(file.abs)) {
+                console.error(yellow(`    ⚠ 첨부 없음: ${relative(baseDir, file.abs)}`));
                 continue;
             }
             try {
-                await uploadAttachment(pageId, img.filename, img.abs);
+                await uploadAttachment(pageId, file.filename, file.abs);
                 ok++;
             }
             catch (e) {
-                console.error(red(`    ✗ 이미지 업로드 실패 ${img.filename}`) + `\n${e.message}`);
+                console.error(red(`    ✗ 첨부 업로드 실패 ${file.filename}`) + `\n${e.message}`);
             }
         }
         return ok;
     }
+    const uploadImages = uploadAttachments;
     /** 페이지 생성/갱신. 삭제 감지 시 재생성. 변경 없으면(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)
+            if (!changed && !opts.verify && !existing.pendingMove)
                 return 'skipped';
-            const cur = await getPageOrNull(existing.pageId);
+            let cur = await getPageOrNull(existing.pageId);
+            if (!cur && existing.pendingMove)
+                throw new Error(`이동 대상 페이지 #${existing.pageId}가 없습니다. 자동 재생성하지 않습니다.`);
             if (cur) {
-                if (!changed)
-                    return 'skipped'; // 페이지 존재 확인됨, 내용도 동일
+                let moved = false;
+                if (existing.pendingMove) {
+                    if (String(cur.spaceId) !== spaceId)
+                        throw new Error('이동 대상 페이지의 스페이스가 설정과 다릅니다.');
+                    if ((cur.parentId ?? undefined) !== parentId) {
+                        let targetId = parentId;
+                        let position = 'append';
+                        if (!targetId) {
+                            // A sibling of the top-level homepage is also top-level.
+                            const space = await api(`/api/v2/spaces/${spaceId}`);
+                            targetId = space.homepageId;
+                            if (!targetId)
+                                throw new Error('최상위 이동 기준 홈페이지가 없습니다. CONFLUENCE_PARENT_ID를 지정하세요.');
+                            const target = await getPageOrNull(targetId);
+                            if (!target || target.parentId || String(target.spaceId) !== spaceId)
+                                throw new Error('최상위 이동 기준 홈페이지를 확인할 수 없습니다.');
+                            position = 'after';
+                        }
+                        if (targetId === existing.pageId)
+                            throw new Error('페이지를 자기 자신 아래로 이동할 수 없습니다.');
+                        await api(`/rest/api/content/${existing.pageId}/move/${position}/${targetId}`, { method: 'PUT' });
+                        cur = await getPageOrNull(existing.pageId);
+                        if (!cur || (cur.parentId ?? undefined) !== parentId)
+                            throw new Error('이동 후 부모 위치 검증에 실패했습니다. 다시 sync하세요.');
+                        moved = true;
+                    }
+                }
+                if (!changed) {
+                    delete existing.pendingMove;
+                    return moved ? 'moved' : 'skipped';
+                }
                 const nextVersion = (cur.version?.number ?? 1) + 1;
                 await api(`/api/v2/pages/${existing.pageId}`, {
                     method: 'PUT',
@@ -154,7 +201,7 @@ export function createClient(cfg, opts) {
             headers: { Authorization: authHeader(), Accept: 'application/json' },
         });
         if (!res.ok)
-            throw new Error(`Confluence API ${res.status} ${res.statusText}\n${path}\n${await res.text()}`);
+            throw new ConfluenceApiError(res.status, path, await res.text(), res.statusText);
         return res.json();
     }
     /**
@@ -227,6 +274,47 @@ export function createClient(cfg, opts) {
             throw new Error(`Confluence API ${res.status} ${res.statusText}\n/rest/api/content/${id}\n${await res.text()}`);
         return res.json();
     }
+    /** 같은 스페이스·부모·제목의 폴더만 재사용한다. 검색 결과는 현재 메타로 재검증. */
+    async function findFolder(spaceId, spaceKey, title, parentId) {
+        const cql = `type = folder AND space = ${JSON.stringify(spaceKey)} AND title = ${JSON.stringify(title)}`;
+        let path = `/rest/api/content/search?cql=${encodeURIComponent(cql)}&limit=100`;
+        const matches = new Set();
+        const otherParents = new Set();
+        let homepageId;
+        while (path) {
+            const data = await getV1(path);
+            for (const candidate of data.results ?? []) {
+                if (candidate.type !== 'folder' || candidate.title !== title)
+                    continue;
+                const folder = await getV1(`/rest/api/content/${encodeURIComponent(candidate.id)}?expand=ancestors,space`);
+                if (!Array.isArray(folder.ancestors) || !folder.space?.id) {
+                    throw new Error(`폴더 위치 메타데이터를 확인할 수 없습니다: ${candidate.id}`);
+                }
+                if (folder.type !== 'folder' || String(folder.space.id) !== spaceId || folder.title !== title)
+                    continue;
+                const actualParent = folder.ancestors.at(-1)?.id;
+                // The visible space root can be the homepage's children, not parentless content.
+                if (!parentId && actualParent && homepageId === undefined) {
+                    homepageId = String((await api(`/api/v2/spaces/${spaceId}`)).homepageId ?? '');
+                }
+                if (actualParent === parentId || (!parentId && actualParent === homepageId)) {
+                    matches.add(String(folder.id));
+                }
+                else {
+                    otherParents.add(actualParent ?? 'ROOT');
+                }
+            }
+            const next = data._links?.next;
+            // Keep pagination on this configured API base (including gateway cloud IDs).
+            path = next ? new URL(next, 'https://pagination.invalid').pathname.replace(/^\/wiki(?=\/rest\/)/, '') + new URL(next, 'https://pagination.invalid').search : null;
+        }
+        if (matches.size > 1)
+            throw new Error(`같은 위치에 동명 폴더가 여러 개 있습니다: ${title}`);
+        if (!matches.size && otherParents.size) {
+            throw new Error(`동명 폴더 '${title}'가 다른 위치에 있습니다 (현재 부모: ${[...otherParents].join(', ')}, 요청 부모: ${parentId ?? 'ROOT/홈페이지'}). 부모 설정 또는 폴더 구조를 확인하세요.`);
+        }
+        return [...matches][0] ?? null;
+    }
     /** 폴더 생성(write:folder 필요). parentId 없으면 공간 최상위. 생성된 folder id 반환. */
     async function createFolder(spaceId, title, parentId) {
         const body = { spaceId, title };
@@ -235,13 +323,54 @@ export function createClient(cfg, opts) {
         const created = await api(`/api/v2/folders`, { method: 'POST', body: JSON.stringify(body) });
         return created.id;
     }
+    /** 조회→재사용→생성. 동시 생성/검색 지연으로 충돌하면 한 번 재조회한다. */
+    async function upsertFolder(spaceId, spaceKey, title, parentId, mappedId) {
+        parentId = parentId?.trim() || undefined;
+        if (mappedId) {
+            let folder;
+            try {
+                folder = await api(`/rest/api/content/${encodeURIComponent(mappedId)}?expand=ancestors,space`);
+            }
+            catch (error) {
+                if (!(error instanceof ConfluenceApiError) || error.status !== 404)
+                    throw error;
+            }
+            if (folder) {
+                if (!Array.isArray(folder.ancestors) || !folder.space?.id)
+                    throw new Error(`폴더 위치 메타데이터를 확인할 수 없습니다: ${mappedId}`);
+                const actualParent = folder.ancestors.at(-1)?.id;
+                const homepageId = !parentId && actualParent ? String((await api(`/api/v2/spaces/${spaceId}`)).homepageId ?? '') : undefined;
+                if (folder.type !== 'folder' || String(folder.space.id) !== spaceId || folder.title !== title ||
+                    !(actualParent === parentId || (!parentId && actualParent === homepageId))) {
+                    throw new Error(`매핑 폴더 #${mappedId}의 스페이스·제목·부모가 '${title}'의 요청 위치와 다릅니다.`);
+                }
+                return { id: mappedId, created: false };
+            }
+        }
+        const found = await findFolder(spaceId, spaceKey, title, parentId);
+        if (found)
+            return { id: found, created: false };
+        try {
+            return { id: await createFolder(spaceId, title, parentId), created: true };
+        }
+        catch (error) {
+            const conflict = error instanceof ConfluenceApiError &&
+                (error.status === 409 || (error.status === 400 && /folder exists with the same title/i.test(error.responseBody)));
+            if (!conflict)
+                throw error;
+            const raced = await findFolder(spaceId, spaceKey, title, parentId);
+            if (raced)
+                return { id: raced, created: false };
+            throw error;
+        }
+    }
     /** 폴더 삭제(--rebuild). */
     async function deleteFolder(id) {
         await api(`/api/v2/folders/${id}`, { method: 'DELETE' });
     }
     return {
-        api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, upsertPage,
+        api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, uploadAttachments, upsertPage,
         getNode, getChildPages, getChildFolders, listAttachments, downloadAttachment,
-        getContentOrNull, createFolder, deleteFolder,
+        getContentOrNull, findFolder, createFolder, upsertFolder, deleteFolder,
     };
 }

package/dist/confluence/config.js

@@ -10,7 +10,7 @@ export function readEnv() {
         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,
+        parentId: (process.env.CONFLUENCE_PARENT_ID ?? process.env.CONFLUENCE_PARENT_PAGE_ID)?.trim() || undefined,
     };
 }
 /** 동기화(생성/갱신)에 필요한 필수 환경변수 검증. 누락 시 종료. */

package/dist/documents/markdown.js

@@ -5,8 +5,8 @@
  * - 로컬 이미지 → 첨부 참조(ri:attachment), 외부 URL 이미지는 그대로
  * 모든 경로는 baseDir 기준 상대경로로 해석한다.
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve, relative, dirname, basename } from 'node:path';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, relative, dirname, basename, extname } from 'node:path';
 import { createHash } from 'node:crypto';
 import MarkdownIt from 'markdown-it';
 import { resolveWikilinks } from './obsidian.js';
@@ -27,7 +27,7 @@ const md = new MarkdownIt({ html: true, linkify: true, breaks: false });
 const emptyCtx = () => ({
     fileDir: '', titleIndex: {}, anchorIndex: {}, selfRel: '', selfTitle: '',
     anchorNames: new Set(), bodySlugs: [], headingSeq: 0, mermaidSeq: 0, anchorsPlaced: 0,
-    images: [], internalLinks: 0, anchorLinks: 0, deadAnchors: [], linkStack: [], linkedTitles: new Set(),
+    images: [], attachments: [], internalLinks: 0, anchorLinks: 0, deadAnchors: [], linkStack: [], linkedTitles: new Set(),
 });
 // 렌더 규칙은 md 인스턴스에 한 번만 등록되므로, 현재 변환 컨텍스트를 모듈 변수로 공유한다.
 let ctx = emptyCtx();
@@ -91,6 +91,23 @@ md.renderer.rules.fence = (tokens, idx) => {
     const code = `<ac:structured-macro ac:name="code">${langParam}<ac:plain-text-body><![CDATA[${safe}]]></ac:plain-text-body></ac:structured-macro>\n`;
     return code + (lang === 'mermaid' ? mermaidMacro(ctx.selfRel, ctx.mermaidSeq++) : '');
 };
+/** 페이지 첨부 이름은 유일해야 한다. 동일 경로는 한 번만 업로드한다. */
+function addAttachment(abs) {
+    const existing = ctx.attachments.find(a => a.abs === abs);
+    if (existing)
+        return existing.filename;
+    let filename = basename(abs);
+    if (ctx.attachments.some(a => a.filename === filename)) {
+        const ext = extname(filename), stem = basename(filename, ext);
+        const suffix = hashOf(relative(baseDir, abs).split('\\').join('/')).slice(0, 12);
+        filename = `${stem}-${suffix}${ext}`;
+        let n = 1;
+        while (ctx.attachments.some(a => a.filename === filename))
+            filename = `${stem}-${suffix}-${n++}${ext}`;
+    }
+    ctx.attachments.push({ filename, abs });
+    return filename;
+}
 md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
     const originalHref = tokens[idx].attrGet('href') || '';
     const href = ctx.rewriteHref?.(originalHref) ?? originalHref;
@@ -109,6 +126,17 @@ md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
         const page = t.title ? `<ri:page ri:content-title="${escapeXml(t.title)}" />` : '';
         return `<ac:link${anchor}>${page}<ac:link-body>`;
     }
+    // 일반 로컬 파일 링크도 첨부로 전환한다. 문서·외부 URL·없는 대상은 유지한다.
+    const path = href.split('#')[0];
+    if (path && !/^[a-z][a-z\d+.-]*:|^\/\//i.test(path) && !/\.md$/i.test(decodePath(path))) {
+        const abs = resolve(baseDir, ctx.fileDir, decodePath(path));
+        if (existsSync(abs) && statSync(abs).isFile()) {
+            const filename = addAttachment(abs);
+            ctx.linkStack.push(true);
+            const fragment = href.includes('#') ? ` ac:anchor="${escapeXml(decodePath(href.slice(href.indexOf('#') + 1)))}"` : '';
+            return `<ac:link${fragment}><ri:attachment ri:filename="${escapeXml(filename)}" /><ac:link-body>`;
+        }
+    }
     ctx.linkStack.push(false);
     return self.renderToken(tokens, idx, opts);
 };
@@ -128,7 +156,7 @@ md.renderer.rules.image = (tokens, idx) => {
     }
     // markdown-it 이 링크 경로를 퍼센트 인코딩하므로 디코드해서 실제 파일명/경로로 복원(한글·공백 대응)
     const abs = resolve(baseDir, ctx.fileDir, decodePath(src.split('#')[0]));
-    const filename = basename(abs);
+    const filename = addAttachment(abs);
     ctx.images.push({ filename, abs });
     return `<ac:image${widthAttr}><ri:attachment ri:filename="${escapeXml(filename)}" /></ac:image>`;
 };
@@ -163,6 +191,7 @@ export function toStorage(markdown, rel, titleIndex, base, opts = {}) {
     return {
         storage,
         images: ctx.images,
+        attachments: ctx.attachments,
         internalLinks: ctx.internalLinks,
         anchorLinks: ctx.anchorLinks,
         anchorsPlaced: ctx.anchorsPlaced,
@@ -171,13 +200,13 @@ export function toStorage(markdown, rel, titleIndex, base, opts = {}) {
     };
 }
 /**
- * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 이미지의 내용 해시.
- * 이미지 내용을 포함하므로, 같은 파일명으로 이미지만 교체해도 해시가 바뀌어 재동기화 대상이 된다.
- * 이미지가 없으면 hashOf(title + '\0' + storage) 와 동일(이미지 없는 문서는 기존 해시 유지).
+ * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 첨부의 내용 해시.
+ * 첨부 내용을 포함하므로, 같은 파일명으로 파일만 교체해도 해시가 바뀌어 재동기화 대상이 된다.
+ * 첨부가 없으면 hashOf(title + '\0' + storage) 와 동일(첨부 없는 문서는 기존 해시 유지).
  */
 export function docHash(title, r) {
     const parts = [title, r.storage];
-    for (const img of r.images) {
+    for (const img of r.attachments) {
         let digest = 'missing';
         try {
             if (existsSync(img.abs))

package/dist/sync/push.js

@@ -101,6 +101,19 @@ export async function runPush(argv) {
         return;
     }
     const mapping = loadMapping(MAPPING_PATH);
+    // A remap plan is valid only for the tree it was prepared against.
+    for (const rel of files) {
+        const entry = mapping[rel];
+        if (entry?.pendingMove && entry.pendingMove.parentKey !== parentKeyOf(rel, folderIndex)) {
+            throw new Error(`구조가 remap 이후 변경되었습니다: ${rel}. remap을 다시 실행하세요.`);
+        }
+        const id = readDoc(BASE_DIR, rel).fm.pageId;
+        if (entry && id && entry.pageId !== id)
+            throw new Error(`pageId 충돌: ${rel}`);
+        if (!entry && id && Object.values(mapping).some(e => e.pageId === id && e.pendingMove)) {
+            throw new Error(`remap 이후 경로가 변경되었습니다: ${rel}. remap을 다시 실행하세요.`);
+        }
+    }
     if (DRY_RUN) {
         const seen = new Set();
         for (const rel of files) {
@@ -127,11 +140,12 @@ export async function runPush(argv) {
             // 매핑엔 없지만 frontmatter 에 pageId 가 있으면 신규 생성이 아니라 기존 페이지에 연결된다
             const status = !ex?.pageId
                 ? (fm.pageId ? cyan('연결') : green('신규'))
-                : ex.hash === hash ? gray('동일') : yellow('변경');
+                : ex.pendingMove ? cyan(ex.hash === hash ? '위치 확인/이동' : '위치 확인/이동 + 변경')
+                    : ex.hash === hash ? gray('동일') : yellow('변경');
             const pk = parentKeyOf(rel, folderIndex);
             const anchorNote = r.anchorLinks || r.anchorsPlaced
                 ? `, 섹션링크: ${r.anchorLinks}, 앵커: ${r.anchorsPlaced}` : '';
-            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}${anchorNote}, 이미지: ${r.images.length})`)}`);
+            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}${anchorNote}, 이미지: ${r.images.length}, 첨부: ${r.attachments.length})`)}`);
             if (r.deadAnchors.length) {
                 console.error(yellow(`    ⚠ 대응 헤딩 없는 앵커 ${r.deadAnchors.length}개: `) + dim(r.deadAnchors.slice(0, 3).join(' ')));
             }
@@ -146,11 +160,12 @@ export async function runPush(argv) {
         saveMapping(MAPPING_PATH, {});
     }
     const work = REBUILD ? {} : mapping;
+    let moved = 0;
     let created = 0, updated = 0, skipped = 0, recreated = 0, relinked = 0, foldersMade = 0, linked = 0, carried = 0;
     const rendered = new Map();
     const recreatedTitles = new Set(); // 이번에 재생성된 문서의 제목
     const touched = new Set(); // 이번에 발행(생성/갱신/재생성)된 문서
-    const handledFolders = new Set(); // 이번 실행에서 처리한 폴더 dir
+    const handledFolders = new Map(); // 이번 실행에서 처리한 폴더 dir
     // README 없는 폴더를 Confluence 폴더로 생성(없으면)하고 work 에 등록. 성공 여부 반환.
     const ensureFolder = async (dir) => {
         const key = `${dir}/`;
@@ -161,20 +176,19 @@ export async function runPush(argv) {
             return false;
         }
         const ex = work[key];
-        if (ex?.pageId && ex.type === 'folder' && (await client.getContentOrNull(ex.pageId))) {
-            return true; // 이미 존재
-        }
         try {
             const title = dir.split('/').pop();
-            const fid = await client.createFolder(spaceId, title, parentId);
+            const result = await client.upsertFolder(spaceId, env.spaceKey, title, parentId, ex?.type === 'folder' ? ex.pageId : undefined);
+            const fid = result.id;
             work[key] = { pageId: fid, title, type: 'folder' };
             saveMapping(MAPPING_PATH, work);
-            console.log(`  ${cyan('📁 폴더')}  ${dir}/  ${dim(`(부모: ${pcKey ?? 'ROOT'})`)}`);
-            foldersMade++;
+            console.log(`  ${cyan(!result.created ? '📁 폴더 연결' : '📁 폴더')}  ${dir}/  ${dim(`(부모: ${pcKey ?? 'ROOT'})`)}`);
+            if (result.created)
+                foldersMade++;
             return true;
         }
         catch (e) {
-            console.error(red(`  ✗ 폴더 생성 실패  ${dir}/`) + `\n${e.message}`);
+            console.error(red(`  ✗ 폴더 준비 실패  ${dir}/`) + `\n${e.message}`);
             return false;
         }
     };
@@ -182,12 +196,9 @@ export async function runPush(argv) {
         // 상위 README-less 폴더들 보장(shallow→deep)
         let folderOk = true;
         for (const d of ancestorFolderDirs(rel)) {
-            if (!handledFolders.has(d)) {
-                handledFolders.add(d);
-                if (!(await ensureFolder(d)))
-                    folderOk = false;
-            }
-            else if (!work[`${d}/`]?.pageId)
+            if (!handledFolders.has(d))
+                handledFolders.set(d, await ensureFolder(d));
+            if (!handledFolders.get(d))
                 folderOk = false;
             if (!folderOk)
                 break;
@@ -247,8 +258,17 @@ export async function runPush(argv) {
                 skipped++;
                 continue;
             }
-            const imgOk = await client.uploadImages(work[rel].pageId, r.images, BASE_DIR);
-            const imgNote = r.images.length ? `, 이미지 ${imgOk}/${r.images.length}` : '';
+            if (result === 'moved') {
+                console.log(`  ${cyan('→ 이동')}  ${rel}  (부모: ${pk ?? 'ROOT'})`);
+                moved++;
+                continue;
+            }
+            const imgOk = await client.uploadAttachments(work[rel].pageId, r.attachments, BASE_DIR);
+            const imgNote = r.attachments.length ? `, 첨부 ${imgOk}/${r.attachments.length}` : '';
+            if (imgOk !== r.attachments.length) {
+                delete work[rel].hash; // 부분 실패는 다음 동기화에서 재시도한다.
+                saveMapping(MAPPING_PATH, work);
+            }
             const label = result === 'created' ? green('＋ 생성')
                 : result === 'recreated' ? magenta('♻ 재생성(삭제 복구)')
                     : yellow('↻ 갱신');
@@ -280,7 +300,11 @@ export async function runPush(argv) {
             try {
                 await client.upsertPage(work, spaceId, rel, r.title, r.storage, r.hash, r.parentId, true);
                 saveMapping(MAPPING_PATH, work);
-                await client.uploadImages(work[rel].pageId, r.images, BASE_DIR);
+                const uploaded = await client.uploadAttachments(work[rel].pageId, r.attachments, BASE_DIR);
+                if (uploaded !== r.attachments.length) {
+                    delete work[rel].hash;
+                    saveMapping(MAPPING_PATH, work);
+                }
                 console.log(`  ${cyan('🔗 링크 재연결')}  ${rel}  ${dim('→')}  ${cyan(`"${r.title}"`)}`);
                 relinked++;
             }
@@ -292,6 +316,7 @@ export async function runPush(argv) {
     console.log('\n' + bold('완료') +
         `  ${green(`생성 ${created}`)}` +
         `  ${yellow(`갱신 ${updated}`)}` +
+        `  ${cyan(`이동 ${moved}`)}` +
         `  ${magenta(`재생성 ${recreated}`)}` +
         `  ${cyan(`링크재연결 ${relinked}`)}` +
         `  ${gray(`변경없음 ${skipped}`)}` +

package/dist/sync/remap.js

@@ -0,0 +1,97 @@
+/** Local-only pageId-based mapping reconciliation. Never contacts Confluence. */
+import { existsSync, readFileSync } from 'node:fs';
+import { relative, resolve } from 'node:path';
+import { positionalArgs } from '../cli/args.js';
+import { collectMarkdown, readDoc, buildFolderIndex, parentKeyOf } from '../documents/catalog.js';
+import { buildIgnorer } from './ignore.js';
+import { MAPPING_FILE, saveMapping } from './mapping.js';
+function readMapping(path) {
+    if (!existsSync(path))
+        return {};
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        throw new Error(`잘못된 매핑: ${path}`);
+    const ids = new Set();
+    for (const [key, value] of Object.entries(data)) {
+        if (!value || typeof value !== 'object' || typeof value.pageId !== 'string') {
+            throw new Error(`잘못된 매핑 항목: ${key}`);
+        }
+        const id = value.pageId;
+        if (ids.has(id))
+            throw new Error(`매핑 pageId 중복: ${id}`);
+        ids.add(id);
+    }
+    return data;
+}
+export async function runRemap(argv) {
+    const values = new Set(['--base', '--mapping', '--from-mapping', '--exclude']);
+    const opts = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (values.has(arg)) {
+            const value = argv[++i];
+            if (!value || value.startsWith('--'))
+                throw new Error(`${arg} 값이 필요합니다.`);
+            (opts[arg] ??= []).push(value);
+        }
+        else if (arg !== 'remap' && arg !== '--dry-run')
+            throw new Error(`remap: 지원하지 않는 인자 ${arg}`);
+    }
+    if (positionalArgs(argv).length !== 1)
+        throw new Error('remap은 --base 전체를 대상으로 실행합니다.');
+    const baseInput = opts['--base']?.[0] ?? process.env.CONFLUENCE_SYNC_BASE;
+    if (!baseInput)
+        throw new Error('remap: --base <dir> 또는 CONFLUENCE_SYNC_BASE가 필요합니다.');
+    const base = resolve(baseInput);
+    const output = resolve(opts['--mapping']?.[0] ?? resolve(base, MAPPING_FILE));
+    const source = opts['--from-mapping']?.[0];
+    if (source && !existsSync(resolve(source)))
+        throw new Error(`원본 매핑이 없습니다: ${source}`);
+    const mapping = readMapping(output);
+    if (source)
+        for (const [key, entry] of Object.entries(readMapping(resolve(source)))) {
+            if (Object.values(mapping).some(e => e.pageId === entry.pageId))
+                continue;
+            if (mapping[key] && mapping[key].pageId !== entry.pageId)
+                throw new Error(`매핑 충돌: ${key}`);
+            mapping[key] ??= entry;
+        }
+    const ignorer = buildIgnorer(base, opts['--exclude'] ?? []);
+    const files = collectMarkdown(base).map(f => relative(base, f).split('\\').join('/')).filter(f => !ignorer.ignores(f)).sort();
+    const folders = buildFolderIndex(files);
+    const byId = new Map();
+    for (const [key, entry] of Object.entries(mapping)) {
+        if (byId.has(entry.pageId))
+            throw new Error(`매핑 pageId 중복: ${entry.pageId}`);
+        byId.set(entry.pageId, [key, entry]);
+    }
+    const docs = files.map(key => ({ key, doc: readDoc(base, key) }));
+    const seen = new Set();
+    const next = structuredClone(mapping);
+    const updates = [];
+    for (const { key, doc } of docs) {
+        const id = doc.fm.pageId ?? mapping[key]?.pageId;
+        if (!id) {
+            console.log(`미연결: ${key} (pageId 없음)`);
+            continue;
+        }
+        if (seen.has(id))
+            throw new Error(`문서 pageId 중복: ${id}`);
+        seen.add(id);
+        if (mapping[key] && mapping[key].pageId !== id)
+            throw new Error(`pageId 충돌: ${key}`);
+        const prior = byId.get(id);
+        if (prior?.[1].type === 'folder')
+            throw new Error(`폴더 ID를 문서에 사용할 수 없습니다: ${key}`);
+        if (prior)
+            delete next[prior[0]];
+        const entry = { ...(prior?.[1] ?? { pageId: id, title: doc.title }), pendingMove: { parentKey: parentKeyOf(key, folders) } };
+        updates.push([key, entry]);
+        console.log(`${prior?.[0] ?? `#${id}`} → ${key} (부모: ${entry.pendingMove.parentKey ?? 'ROOT'})${entry.hash ? '' : ' — 기존 해시 없음: sync 시 본문 갱신 대상'}`);
+    }
+    for (const [key, entry] of updates)
+        next[key] = entry;
+    if (!argv.includes('--dry-run'))
+        saveMapping(output, next);
+    console.log(`${argv.includes('--dry-run') ? '미리보기' : '매핑 저장'}: ${output} (${updates.length}건). Confluence 호출 없음.`);
+}

package/dist/web/sync.js

@@ -148,7 +148,7 @@ export function createWebSync(runner = runSyncCLI) {
         let reportedFailure = false;
         const secrets = [prepared.env.CONFLUENCE_API_TOKEN, Buffer.from(`${prepared.env.CONFLUENCE_EMAIL}:${prepared.env.CONFLUENCE_API_TOKEN}`).toString('base64')].filter(Boolean);
         const log = (text) => {
-            if (text.includes('✗') || text.includes('⚠ 이미지 없음'))
+            if (text.includes('✗') || text.includes('⚠ 이미지 없음') || text.includes('⚠ 첨부 없음'))
                 reportedFailure = true; // CLI reports per-document / attachment failures without exiting.
             for (const secret of secrets)
                 text = text.split(secret).join('[비공개]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.6.1",
+  "version": "1.8.0",
   "type": "module",
   "description": "Confluence Cloud ↔ Markdown 양방향 동기화 CLI — 마크다운을 Confluence 페이지로 발행(push)하고, Confluence 페이지·폴더·스페이스를 마크다운으로 가져옵니다(pull).",
   "keywords": [