@wonseok-han/confluence-sync 1.0.0 → 1.2.0

package/dist/pull.js

@@ -2,16 +2,27 @@
  * `confluence-sync pull <pageId|url> [--out <dir>] [--children]`
  * Confluence 페이지를 읽어 Markdown(.md) 으로 생성한다(역방향).
  * 자식이 있는 페이지는 push 관례를 역으로 적용해 <slug>/README.md 폴더로 펼친다.
- * 첨부는 .md 옆에 내려받고 이미지 링크를 로컬 파일명으로 재작성한다.
+ * 첨부는 attachments/<문서명>/ 하위에 내려받고 이미지 링크를 그 경로로 재작성한다.
+ *
+ * 함께 받은 페이지끼리의 내부 링크는 마지막에 상대 .md 경로로 이어 붙인다(Obsidian 그래프·백링크가 살아난다).
+ * 각 문서 머리에 pageId 를 담은 frontmatter 를 남겨, 매핑 파일 없이도 push 가 원본 페이지를 다시 찾아간다.
  */
-import { mkdirSync, writeFileSync } from 'node:fs';
-import { resolve, join, dirname, basename } from 'node:path';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { resolve, join, dirname, basename, relative } from 'node:path';
 import { readEnv, requireEnv } from './config.js';
 import { createClient } from './confluence.js';
 import { htmlToMarkdown, codeLanguagesFromStorage } from './html2md.js';
+import { buildFrontmatter, splitFrontmatter } from './obsidian.js';
+import { collectHeadings, matchConfluenceAnchor } from './anchors.js';
 import { cyan, dim, green, red, yellow } from './colors.js';
 // 첨부 이미지는 항상 <md위치>/attachments/<문서명>/ 하위에 저장한다.
 const ASSETS_DIR = 'attachments';
+/** 마크다운 링크 중 Confluence 페이지를 가리키는 것: [text](https://.../pages/<id>/...) */
+const PAGE_LINK = /\[([^\]]*)\]\(<?(https?:\/\/[^\s)<>]*?\/pages\/(\d+)[^\s)<>]*?)>?\)/g;
+/** 같은 문서 안의 앵커: [text](#앵커) */
+const SELF_ANCHOR = /\[([^\]]*)\]\(#([^)\s]+)\)/g;
+/** 다른 페이지의 섹션: [text](https://.../pages/<id>/제목#앵커) — 앵커만 따로 잡는다 */
+const PAGE_ANCHOR = /(\[[^\]]*\]\(<?https?:\/\/[^\s)<>]*?\/pages\/(\d+)[^\s)<>#]*)#([^\s)<>]+?)(>?\))/g;
 function optVal(argv, name) {
     const i = argv.indexOf(name);
     return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
@@ -28,8 +39,11 @@ function parseContentId(input) {
 function slug(title) {
     return title.replace(/[\/\\:*?"<>|]/g, '-').replace(/\s+/g, ' ').trim() || 'untitled';
 }
+/** 공백이 있으면 <...> 로 감싼 마크다운 링크 목적지 */
+const dest = (p) => (/\s/.test(p) ? `<${p}>` : p);
 /** 페이지 1건을 .md 로 생성(자식 페이지/폴더가 있으면 <slug>/README.md 폴더로). */
-async function pullPage(client, node, destDir, withChildren) {
+async function pullPage(ctx, node, destDir) {
+    const { client, withChildren } = ctx;
     const { id, title, html, storage } = node;
     // 페이지도 하위 페이지 + 하위 폴더를 모두 가질 수 있다(폴더가 페이지 밑에 올 수 있음).
     const childFolders = withChildren ? await client.getChildFolders(id) : [];
@@ -66,19 +80,33 @@ async function pullPage(client, node, destDir, withChildren) {
             }
         }
     }
-    writeFileSync(filePath, `# ${title}\n\n${body}`);
+    // frontmatter 의 pageId 는 push 왕복의 앵커다(매핑 파일이 없어도 원본 페이지를 찾아간다).
+    // 취향 옵션이 아니라 중복 페이지 생성을 막는 장치이므로 항상 쓴다. Obsidian 은 이를 속성으로 보여준다.
+    const fm = buildFrontmatter({
+        title,
+        pageId: id,
+        spaceKey: ctx.spaceKey,
+        source: node.url ?? '',
+        updated: node.updated ?? '',
+    });
+    // 제목은 frontmatter 의 title 하나로 충분하다. 본문에 `# 제목` 을 또 넣으면
+    // 제목을 따로 표시하는 뷰어(Obsidian 등)에서 두 번 보인다. push 도 title 속성을 먼저 읽는다.
+    writeFileSync(filePath, fm ? `${fm}${body}` : `# ${title}\n\n${body}`);
+    ctx.written.push(filePath);
+    ctx.pathById.set(id, filePath);
     const imgNote = referenced.size ? `, 이미지 ${referenced.size}` : '';
     console.log(`  ${green('＋ 생성')}  ${filePath}  ${dim(`(#${id}${imgNote})`)}`);
     const counts = { pages: 1, folders: 0 };
     for (const f of childFolders)
-        add(counts, await pullNode(client, f.id, folder, withChildren));
+        add(counts, await pullNode(ctx, f.id, folder));
     for (const c of childPages)
-        add(counts, await pullNode(client, c.id, folder, withChildren));
+        add(counts, await pullNode(ctx, c.id, folder));
     return counts;
 }
 function add(acc, c) { acc.pages += c.pages; acc.folders += c.folders; }
 /** 노드(페이지/폴더)를 재귀적으로 가져온다. 폴더는 디렉토리(본문 없음)로 만든다. 노드 하나 실패는 스킵. */
-async function pullNode(client, id, destDir, withChildren) {
+async function pullNode(ctx, id, destDir) {
+    const { client, withChildren } = ctx;
     try {
         const node = await client.getNode(id);
         if (node.type === 'folder') {
@@ -88,9 +116,9 @@ async function pullNode(client, id, destDir, withChildren) {
             const counts = { pages: 0, folders: 1 };
             if (withChildren) {
                 for (const f of await client.getChildFolders(id))
-                    add(counts, await pullNode(client, f.id, dir, true));
+                    add(counts, await pullNode(ctx, f.id, dir));
                 for (const p of await client.getChildPages(id))
-                    add(counts, await pullNode(client, p.id, dir, true));
+                    add(counts, await pullNode(ctx, p.id, dir));
             }
             else {
                 console.log(dim('     (하위 내용은 --children 으로 가져옵니다)'));
@@ -98,13 +126,104 @@ async function pullNode(client, id, destDir, withChildren) {
             return counts;
         }
         // page: getNode 결과(html + storage) 그대로 사용
-        return await pullPage(client, node, destDir, withChildren);
+        return await pullPage(ctx, node, destDir);
     }
     catch (e) {
         console.error(red(`  ✗ 실패  #${id}`) + `\n${e.message}`);
         return { pages: 0, folders: 0 };
     }
 }
+function readDocInfo(file) {
+    const { data, body } = splitFrontmatter(readFileSync(file, 'utf8'));
+    const headings = collectHeadings(body);
+    return {
+        title: data.title ?? '',
+        headings,
+        textBySlug: new Map(headings.map((h) => [h.slug, h.text])),
+    };
+}
+/**
+ * Confluence 가 만든 헤딩 앵커를 마크다운 슬러그로 바꾼다.
+ *
+ * Confluence 의 앵커 id 는 `<페이지제목><헤딩텍스트>`(공백 제거) 라서 Obsidian·GitHub 에서는
+ * 아무 데도 가리키지 못한다. 실제 헤딩을 찾아 그 문서의 슬러그로 바꿔 줘야 링크가 산다.
+ * relinkPass 보다 **먼저** 돈다 — 아직 링크가 절대 URL 이라 어느 페이지인지 id 로 알 수 있기 때문이다.
+ */
+export function anchorPass(written, pathById) {
+    const info = new Map();
+    for (const f of written)
+        info.set(f, readDocInfo(f));
+    let count = 0;
+    for (const file of written) {
+        const self = info.get(file);
+        const before = readFileSync(file, 'utf8');
+        // 우리가 올린 페이지는 Anchor 매크로 이름이 이미 마크다운 슬러그라 그대로 두면 된다.
+        // Confluence 에서 직접 쓴 페이지만 헤딩을 찾아 맞춘다.
+        const toSlug = (frag, d) => {
+            if (d.textBySlug.has(frag))
+                return null; // 이미 올바른 슬러그
+            return matchConfluenceAnchor(frag, d.headings, d.title)?.slug ?? null;
+        };
+        let after = before.replace(SELF_ANCHOR, (whole, label, frag) => {
+            const slug = toSlug(frag, self);
+            if (!slug)
+                return whole; // 이미 맞거나 못 찾음 → 손대지 않는다(엉뚱한 곳으로 보내지 않기 위해)
+            count++;
+            return `[${label}](#${slug})`;
+        });
+        after = after.replace(PAGE_ANCHOR, (whole, head, id, frag, tail) => {
+            const target = pathById.get(id);
+            const ti = target && info.get(target);
+            if (!ti)
+                return whole; // 이번에 안 받은 페이지 → 원본 URL 이 살아 있어야 한다
+            const slug = toSlug(frag, ti);
+            if (!slug)
+                return whole;
+            count++;
+            return `${head}#${slug}${tail}`;
+        });
+        if (after !== before)
+            writeFileSync(file, after);
+    }
+    return { count, info };
+}
+/**
+ * 함께 받은 페이지를 가리키는 절대 Confluence URL 을 상대 .md 링크(또는 [[wikilink]])로 바꾼다.
+ * 이번에 받지 않은 페이지의 링크는 절대 URL 그대로 둔다(깨진 링크를 만들지 않는다).
+ * 반환값은 재작성한 링크 수.
+ */
+export function relinkPass(written, pathById, wikilinks, info) {
+    const noExt = (p) => basename(p).replace(/\.md$/i, '');
+    // wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 유일할 때만 안전하게 쓸 수 있다.
+    const nameCount = new Map();
+    for (const p of pathById.values())
+        nameCount.set(noExt(p), (nameCount.get(noExt(p)) ?? 0) + 1);
+    let count = 0;
+    for (const file of written) {
+        const before = readFileSync(file, 'utf8');
+        const after = before.replace(PAGE_LINK, (whole, text, url, id) => {
+            const target = pathById.get(id);
+            if (!target || target === file)
+                return whole; // 못 받은 페이지·자기 자신 → 원본 URL 유지
+            count++;
+            const name = noExt(target);
+            const label = (text || name).trim();
+            const slug = url.includes('#') ? url.split('#').slice(1).join('#') : '';
+            if (wikilinks && nameCount.get(name) === 1) {
+                // Obsidian 은 슬러그가 아니라 헤딩 텍스트로 섹션을 가리킨다: [[문서#헤딩 텍스트]]
+                const heading = slug ? info?.get(target)?.textBySlug.get(slug) : undefined;
+                if (!heading)
+                    return label === name ? `[[${name}]]` : `[[${name}|${label}]]`;
+                return `[[${name}#${heading}|${label}]]`;
+            }
+            const rel = relative(dirname(file), target).split('\\').join('/');
+            return `[${label}](${dest(rel + (slug ? `#${slug}` : ''))})`;
+        });
+        if (after !== before)
+            writeFileSync(file, after);
+    }
+    return count;
+}
 export async function runPull(argv) {
     const withChildren = argv.includes('--children');
     const wholeSpace = argv.includes('--space');
@@ -112,6 +231,22 @@ export async function runPull(argv) {
     const env = readEnv();
     requireEnv(env);
     const client = createClient({ baseUrl: env.baseUrl, email: env.email, token: env.token }, { force: false, verify: false });
+    const ctx = {
+        client,
+        withChildren,
+        obsidian: argv.includes('--obsidian'),
+        spaceKey: env.spaceKey,
+        written: [],
+        pathById: new Map(),
+    };
+    const done = (c) => {
+        // 앵커를 먼저 슬러그로 바꾼 뒤 링크를 상대경로로 옮긴다(순서가 바뀌면 어느 페이지의 헤딩인지 알 수 없다).
+        const { count: anchors, info } = anchorPass(ctx.written, ctx.pathById);
+        const relinked = relinkPass(ctx.written, ctx.pathById, ctx.obsidian, info);
+        console.log(`\n${green('완료')}  페이지 ${c.pages}개${c.folders ? `, 폴더 ${c.folders}개` : ''} 생성` +
+            (relinked ? `  ${cyan(`내부링크 ${relinked}개 연결`)}` : '') +
+            (anchors ? `  ${cyan(`섹션링크 ${anchors}개 복원`)}` : ''));
+    };
     // --space: 스페이스 홈페이지(콘텐츠 트리 루트)부터 전체를 재귀적으로 가져옴
     if (wholeSpace) {
         const { homepageId } = await client.getSpaceInfo(env.spaceKey);
@@ -120,8 +255,8 @@ export async function runPull(argv) {
             process.exit(1);
         }
         console.log(`${dim('pull:')} space ${cyan(env.spaceKey)} ${dim('→')} ${cyan(outDir)} ${dim('(전체)')}`);
-        const { pages, folders } = await pullNode(client, homepageId, outDir, true);
-        console.log(`\n${green('완료')}  페이지 ${pages}개${folders ? `, 폴더 ${folders}개` : ''} 생성`);
+        ctx.withChildren = true;
+        done(await pullNode(ctx, homepageId, outDir));
         return;
     }
     // 위치 인자: ['pull', <pageId|url>, ...]
@@ -146,6 +281,5 @@ export async function runPull(argv) {
         process.exit(1);
     }
     console.log(`${dim('pull:')} #${contentId} ${dim('→')} ${cyan(outDir)}${withChildren ? dim(' (+children)') : ''}`);
-    const { pages, folders } = await pullNode(client, contentId, outDir, withChildren);
-    console.log(`\n${green('완료')}  페이지 ${pages}개${folders ? `, 폴더 ${folders}개` : ''} 생성`);
+    done(await pullNode(ctx, contentId, outDir));
 }

package/dist/repair.js

@@ -0,0 +1,145 @@
+/**
+ * 이미 내려받아 둔 .md 를 고친다(사후 보정).
+ *
+ * html2md 가 개선되기 전에 pull 한 문서에는 변환기 결함의 흔적이 남아 있다.
+ * 스페이스를 통째로 다시 받지 않고도 같은 결과를 얻도록, 그 흔적들만 골라 되돌린다.
+ * 파일을 덮어쓰므로 **확실한 것만** 고치고, 애매하면 손대지 않는다.
+ */
+import { relaxEscapes } from './html2md.js';
+import { splitFrontmatter } from './obsidian.js';
+const emptyStats = () => ({ cssJunk: 0, codeLang: 0, trailingWs: 0, escapes: 0, tightList: 0, dupTitle: 0 });
+export const totalFixes = (s) => Object.values(s).reduce((a, b) => a + b, 0);
+const FENCE = /^\s*(?:```|~~~)/;
+/** 리스트 항목이면 종류('ul'|'ol'), 아니면 null. 종류가 다르면 별개의 리스트다. */
+function listKind(line) {
+    if (/^[ \t]*[-*+]\s/.test(line))
+        return 'ul';
+    if (/^[ \t]*\d+[.)]\s/.test(line))
+        return 'ol';
+    return null;
+}
+/**
+ * Confluence export_view 는 색상 텍스트용 인라인 <style> 을 본문에(제목 안까지) 끼워 넣는데,
+ * 예전 변환기는 그 CSS 텍스트를 그대로 뱉었다. `[data-colorid=xxx]{color:#fff;}` 같은 잔해다.
+ * (turndown 이 이스케이프해 `\[data-colorid=...\]` 형태로 남아 있기도 하다.)
+ */
+function stripCssJunk(line) {
+    return line
+        .replace(/\\?\[data-colorid=[^\]]*\\?\]\s*\{[^}]*\}/g, '') // 선택자 + 규칙 블록
+        .replace(/\\?\[data-colorid=[^\]]*\\?\]/g, '') // 선택자만 남은 것
+        .replace(/\{\s*color\s*:\s*[^}]*\}/g, ''); // 규칙만 남은 것
+}
+/**
+ * 실제 Java 코드로 보이는가?
+ * Confluence 는 언어를 지정하지 않은 code 매크로를 export 할 때 `brush: java` 를 기본으로 붙인다.
+ * 그래서 예전 변환기는 거의 모든 코드블록을 ```java 로 찍었다. 진짜 Java 만 남기고 plaintext 로 되돌린다.
+ */
+function looksLikeJava(code) {
+    return (/^\s*(package|import)\s+(java|javax|com|org)\b/m.test(code) ||
+        /\b(public|private|protected)\s+(static\s+)?(final\s+)?(class|interface|enum|void)\b/.test(code) ||
+        /\bSystem\.(out|err)\.print/.test(code) ||
+        /@Override\b/.test(code));
+}
+/**
+ * 리스트 항목 사이의 빈 줄을 없앤다(Confluence 의 <li><p> 때문에 생긴 loose list).
+ * 앞뒤가 **같은 종류**의 항목일 때만 붙인다 — 번호 목록과 글머리 목록이 잇달아 나오는 경우
+ * 그 사이의 빈 줄은 두 리스트를 갈라놓는 구분자라 지우면 하나로 합쳐져 버린다.
+ */
+function tightenLists(lines, stats) {
+    const out = [];
+    let inFence = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (FENCE.test(line))
+            inFence = !inFence;
+        if (!inFence && line.trim() === '' && out.length) {
+            const prev = listKind(out[out.length - 1]);
+            const next = listKind(lines[i + 1] ?? '');
+            if (prev && prev === next) {
+                stats.tightList++;
+                continue;
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * frontmatter 에 title 이 있는데 본문 첫 헤딩이 같은 제목이면 그 H1 을 지운다.
+ * 제목을 따로 표시하는 뷰어(Obsidian 등)에서 제목이 두 번 보이기 때문이다.
+ * 제목이 다르면(본문이 실제로 다른 이야기로 시작하면) 손대지 않는다.
+ */
+function dropDuplicateTitle(src, stats) {
+    const { data, body } = splitFrontmatter(src);
+    if (!data.title)
+        return src;
+    const lines = body.split('\n');
+    const i = lines.findIndex((l) => l.trim() !== '');
+    if (i === -1)
+        return src;
+    const h1 = lines[i].match(/^#\s+(.*)$/);
+    if (!h1 || h1[1].trim() !== data.title.trim())
+        return src;
+    lines.splice(i, 1);
+    while (lines[i]?.trim() === '')
+        lines.splice(i, 1); // H1 뒤에 붙어 있던 빈 줄까지
+    stats.dupTitle++;
+    const fmBlock = src.slice(0, src.length - body.length);
+    return fmBlock + lines.join('\n');
+}
+/** 문서 하나를 보정한다. 반환된 text 가 원본과 같으면 고칠 것이 없었다는 뜻. */
+export function repairMarkdown(input) {
+    const stats = emptyStats();
+    const src = dropDuplicateTitle(input, stats);
+    const lines = src.split('\n');
+    const out = [];
+    let inFence = false;
+    let fenceStart = -1; // out 기준, 현재 코드블록 여는 줄의 인덱스
+    for (const raw of lines) {
+        if (FENCE.test(raw)) {
+            if (!inFence) {
+                inFence = true;
+                fenceStart = out.length;
+                out.push(raw);
+            }
+            else {
+                // 코드블록 종료 — 모아둔 내용으로 언어를 판정한다
+                inFence = false;
+                const opener = out[fenceStart];
+                if (/^\s*(?:```|~~~)java\s*$/.test(opener)) {
+                    const code = out.slice(fenceStart + 1).join('\n');
+                    if (!looksLikeJava(code)) {
+                        out[fenceStart] = opener.replace(/java\s*$/, 'plaintext');
+                        stats.codeLang++;
+                    }
+                }
+                out.push(raw);
+            }
+            continue;
+        }
+        if (inFence) {
+            // 코드 안에서는 줄 끝 공백만 정리한다(코드 의미는 불변). 이스케이프·CSS 는 손대지 않는다.
+            const trimmed = raw.replace(/[ \t]+$/, '');
+            if (trimmed !== raw)
+                stats.trailingWs++;
+            out.push(trimmed);
+            continue;
+        }
+        let line = raw;
+        const noCss = stripCssJunk(raw);
+        if (noCss !== raw) {
+            stats.cssJunk++;
+            // 잔해를 걷어낸 자리에 공백이 남는다: "#  {제거됨} 제목" → "# 제목"
+            line = noCss.replace(/[ \t]{2,}/g, ' ').replace(/[ \t]+$/, '');
+        }
+        out.push(line);
+    }
+    // 이스케이프 완화는 코드블록을 알아서 건너뛴다(html2md 와 같은 규칙을 재사용)
+    let text = relaxEscapes(tightenLists(out, stats).join('\n'));
+    // relaxEscapes 가 어디를 바꿨는지 역추적하긴 어려우니, 사라진 백슬래시 개수로 센다
+    const backslashes = (s) => (s.match(/\\/g) || []).length;
+    stats.escapes = Math.max(0, backslashes(src) - backslashes(text));
+    // CSS 잔해를 걷어내면 빈 껍데기 제목(`#` 만 남은 줄)이 생길 수 있다
+    text = text.replace(/^#{1,6}[ \t]*$/gm, '');
+    return { text, stats };
+}

package/dist/sync.js

@@ -14,15 +14,16 @@
  * 세부 로직은 ./markdown ./docs ./mapping ./confluence ./config ./init ./help 모듈에 있다.
  */
 import 'dotenv/config';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { readEnv, requireEnv } from './config.js';
-import { toStorage, splitTitleAndBody, docHash } from './markdown.js';
-import { collectMarkdown, buildTitleIndex, buildFolderIndex, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
+import { toStorage, docHash } from './markdown.js';
+import { collectMarkdown, collectAssets, buildDocIndex, resolveAnchorTargets, buildFolderIndex, buildVault, vaultResolver, readDoc, parentKeyOf, containerKeyOf, sortForSync, resolveSelection, withParents, } from './docs.js';
 import { loadMapping, saveMapping } from './mapping.js';
 import { createClient } from './confluence.js';
 import { runInit } from './init.js';
 import { runPull } from './pull.js';
+import { runConvert } from './convert.js';
 import { buildIgnorer } from './ignore.js';
 import { printHelp, readPkgVersion } from './help.js';
 import { bold, dim, red, green, yellow, magenta, cyan, gray } from './colors.js';
@@ -51,7 +52,8 @@ const EXCLUDES = optVals('--exclude');
 // 위치 인자(선택 경로/서브커맨드): 플래그·옵션값 제외
 const positionals = [];
 for (let i = 0; i < argv.length; i++) {
-    if (argv[i] === '--base' || argv[i] === '--mapping' || argv[i] === '--exclude') {
+    if (argv[i] === '--base' || argv[i] === '--mapping' || argv[i] === '--exclude'
+        || argv[i] === '--to' || argv[i] === '--out') {
         i++;
         continue;
     }
@@ -76,6 +78,10 @@ if (positionals[0] === 'pull') {
     await runPull(argv);
     process.exit(0);
 }
+if (positionals[0] === 'convert') {
+    await runConvert(argv);
+    process.exit(0);
+}
 const baseInput = optVal('--base') ?? process.env.CONFLUENCE_SYNC_BASE;
 if (!baseInput) {
     console.error(red('✗ 동기화 루트가 지정되지 않았습니다.') + '\n' +
@@ -102,7 +108,20 @@ async function main() {
     const allRel = collected.filter((r) => !ignorer.ignores(r)); // 제외된 문서는 모든 단계에서 빠짐
     const ignoredCount = collected.length - allRel.length;
     const folderIndex = buildFolderIndex(allRel);
-    const titleIndex = buildTitleIndex(allRel, BASE_DIR); // 링크 변환은 항상 전체 기준
+    // 링크·섹션 링크 변환은 항상 전체 기준(선택 동기화여도 대상 문서의 제목·헤딩을 알아야 한다)
+    const { titles: titleIndex, anchors: anchorIndex, docs } = buildDocIndex(allRel, BASE_DIR);
+    // Obsidian [[wikilink]] 해석용 이름 인덱스. 제외된 문서는 링크 대상에서도 빠진다.
+    const vault = buildVault(allRel, collectAssets(BASE_DIR).map((f) => relative(BASE_DIR, f)));
+    // 누가 어느 헤딩을 가리키는지 먼저 모은다 — 그 헤딩에만 Anchor 매크로를 심는다.
+    // 선택 동기화여도 트리 전체를 봐야 한다(다른 문서가 이 문서의 섹션을 가리킬 수 있으므로).
+    const anchorTargets = resolveAnchorTargets(docs, vault);
+    const render = (rel, body, title) => toStorage(body, rel, titleIndex, BASE_DIR, {
+        resolveLink: vaultResolver(rel, vault),
+        anchorIndex,
+        title,
+        anchorNames: anchorTargets[rel],
+        bodySlugs: docs[rel]?.bodySlugs,
+    });
     const selected = positionals.length
         ? withParents(resolveSelection(allRel, positionals, BASE_DIR), folderIndex)
         : allRel;
@@ -148,13 +167,21 @@ async function main() {
                     const fex = mapping[`${d}/`];
                     console.log(`  [${fex?.pageId ? gray('폴더') : green('폴더+')}] 📁 ${d}/`);
                 }
-            const { title, body } = splitTitleAndBody(readFileSync(resolve(BASE_DIR, rel), 'utf8'), rel);
-            const r = toStorage(body, rel, titleIndex, BASE_DIR);
+            const { title, body, fm } = readDoc(BASE_DIR, rel);
+            const r = render(rel, body, title);
             const hash = docHash(title, r);
             const ex = mapping[rel];
-            const status = !ex?.pageId ? green('신규') : ex.hash === hash ? gray('동일') : yellow('변경');
+            // 매핑엔 없지만 frontmatter 에 pageId 가 있으면 신규 생성이 아니라 기존 페이지에 연결된다
+            const status = !ex?.pageId
+                ? (fm.pageId ? cyan('연결') : green('신규'))
+                : ex.hash === hash ? gray('동일') : yellow('변경');
             const pk = parentKeyOf(rel, folderIndex);
-            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}, 이미지: ${r.images.length})`)}`);
+            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})`)}`);
+            if (r.deadAnchors.length) {
+                console.error(yellow(`    ⚠ 대응 헤딩 없는 앵커 ${r.deadAnchors.length}개: `) + dim(r.deadAnchors.slice(0, 3).join(' ')));
+            }
         }
         console.log('\n' + dim('--dry-run: 실제 호출 없음.'));
         return;
@@ -166,7 +193,7 @@ async function main() {
         saveMapping(MAPPING_PATH, {});
     }
     const work = REBUILD ? {} : mapping;
-    let created = 0, updated = 0, skipped = 0, recreated = 0, relinked = 0, foldersMade = 0;
+    let created = 0, updated = 0, skipped = 0, recreated = 0, relinked = 0, foldersMade = 0, linked = 0;
     const rendered = new Map();
     const recreatedTitles = new Set(); // 이번에 재생성된 문서의 제목
     const touched = new Set(); // 이번에 발행(생성/갱신/재생성)된 문서
@@ -216,16 +243,37 @@ async function main() {
             console.error(yellow(`  ✗ 건너뜀  ${rel}  (상위 폴더 미생성)`));
             continue;
         }
-        const { title, body } = splitTitleAndBody(readFileSync(resolve(BASE_DIR, rel), 'utf8'), rel);
-        const r = toStorage(body, rel, titleIndex, BASE_DIR);
+        const { title, body, fm } = readDoc(BASE_DIR, rel);
+        const r = render(rel, body, title);
         const hash = docHash(title, r);
         const pk = parentKeyOf(rel, folderIndex);
+        if (r.deadAnchors.length) {
+            console.error(yellow(`  ⚠ 대응 헤딩 없는 앵커  ${rel}`) + dim(`  ${r.deadAnchors.slice(0, 3).join(' ')}${r.deadAnchors.length > 3 ? ` 외 ${r.deadAnchors.length - 3}` : ''}`));
+        }
         const parentId = pk ? work[pk]?.pageId : env.parentId;
         rendered.set(rel, { ...r, title, hash, parentId });
         if (pk && !parentId) {
             console.error(yellow(`  ✗ 건너뜀  ${rel}  (부모 '${pk}' 가 아직 없음)`));
             continue;
         }
+        // pull 로 받은 문서(frontmatter 에 pageId)는 매핑이 없어도 원본 페이지에 다시 연결한다.
+        // 매핑 파일을 잃었거나 vault 를 다른 곳에 복제한 경우 중복 생성을 막아준다.
+        if (!work[rel]?.pageId && fm.pageId) {
+            try {
+                if (await client.getContentOrNull(fm.pageId)) {
+                    work[rel] = { pageId: fm.pageId, title };
+                    saveMapping(MAPPING_PATH, work);
+                    console.log(`  ${cyan('🔗 연결')}  ${rel}  ${dim(`→ 기존 페이지 #${fm.pageId}`)}`);
+                    linked++;
+                }
+                else {
+                    console.error(yellow(`  ⚠ frontmatter 의 pageId #${fm.pageId} 를 찾을 수 없습니다 → 새로 생성  (${rel})`));
+                }
+            }
+            catch (e) {
+                console.error(yellow(`  ⚠ pageId 확인 실패 #${fm.pageId}: ${e.message}`));
+            }
+        }
         try {
             const result = await client.upsertPage(work, spaceId, rel, title, r.storage, hash, parentId);
             saveMapping(MAPPING_PATH, work);
@@ -282,6 +330,7 @@ async function main() {
         `  ${magenta(`재생성 ${recreated}`)}` +
         `  ${cyan(`링크재연결 ${relinked}`)}` +
         `  ${gray(`변경없음 ${skipped}`)}` +
+        (linked ? `  ${cyan(`연결 ${linked}`)}` : '') +
         (foldersMade ? `  ${cyan(`폴더 ${foldersMade}`)}` : '') +
         `  ${dim(`대상 ${files.length}`)}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Confluence Cloud ↔ Markdown 양방향 동기화 CLI — 마크다운을 Confluence 페이지로 발행(push)하고, Confluence 페이지·폴더·스페이스를 마크다운으로 가져옵니다(pull).",
   "keywords": [
@@ -26,7 +26,8 @@
     "node": ">=20"
   },
   "bin": {
-    "confluence-sync": "dist/sync.js"
+    "confluence-sync": "dist/sync.js",
+    "csync": "dist/sync.js"
   },
   "files": [
     "dist",