@wonseok-han/confluence-sync 1.6.0 → 1.7.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

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();
     }
@@ -115,12 +124,43 @@ export function createClient(cfg, opts) {
         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 +194,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 +267,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,6 +316,47 @@ 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' });
@@ -242,6 +364,6 @@ export function createClient(cfg, opts) {
     return {
         api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, 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/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,7 +140,8 @@ 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}` : '';
@@ -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,6 +258,11 @@ export async function runPush(argv) {
                 skipped++;
                 continue;
             }
+            if (result === 'moved') {
+                console.log(`  ${cyan('→ 이동')}  ${rel}  (부모: ${pk ?? 'ROOT'})`);
+                moved++;
+                continue;
+            }
             const imgOk = await client.uploadImages(work[rel].pageId, r.images, BASE_DIR);
             const imgNote = r.images.length ? `, 이미지 ${imgOk}/${r.images.length}` : '';
             const label = result === 'created' ? green('＋ 생성')
@@ -292,6 +308,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/references.js

@@ -87,7 +87,10 @@ export function buildReferenceLookup(base, rels, roots, baseUrl) {
                 return null;
             }
             linked(`${target} → pageId ${hit.pageId} (${join(hit.root, hit.rel)})`);
-            return `${server}/pages/viewpage.action?pageId=${encodeURIComponent(hit.pageId)}`;
+            // The API gateway has no browser UI. References are already restricted to
+            // the same server, so Cloud links can use the viewing site's /wiki root.
+            const pageBase = new URL(server).hostname === 'api.atlassian.com' ? '/wiki' : server;
+            return `${pageBase}/pages/viewpage.action?pageId=${encodeURIComponent(hit.pageId)}`;
         },
     };
 }

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/package.json

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