@wonseok-han/confluence-sync 1.0.0

package/dist/help.js

@@ -0,0 +1,57 @@
+/** --help / --version 출력. */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { bold, cyan, dim } from './colors.js';
+/** 설치된 패키지(package.json)의 버전을 읽는다(dist·src 어느 쪽에서 실행해도 ../package.json). */
+export function readPkgVersion() {
+    try {
+        const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+        return JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+export function printHelp() {
+    const h = (s) => bold(s); // 섹션 제목
+    const o = (s) => cyan(s); // 옵션/명령
+    console.log(`${bold(cyan(`confluence-sync v${readPkgVersion()}`))}
+${dim('Markdown 디렉토리를 Confluence Cloud 페이지로 단방향 동기화합니다.')}
+
+${h('사용법:')}
+  ${o('confluence-sync')} [옵션] [경로...]      문서를 동기화(md → Confluence)
+  ${o('confluence-sync init')}                  대화형으로 .env 설정 파일 생성
+  ${o('confluence-sync pull <pageId|url>')}     Confluence 페이지/폴더를 .md 로 가져오기(역방향)
+  ${o('confluence-sync --help | --version')}
+
+${h('동기화 옵션:')}
+  ${o('--base <dir>')}      동기화 루트 (또는 env CONFLUENCE_SYNC_BASE). 미지정 시 중단
+  ${o('--mapping <path>')}  매핑 파일 위치 (기본: <base>/.confluence-sync.json)
+  ${o('--exclude <glob>')}  동기화 제외 패턴(반복 가능). <base>/.confluence-syncignore(.gitignore 방식)도 사용
+  ${o('--dry-run')}         호출 없이 대상·상태(신규/변경/동일)·링크·이미지 출력
+  ${o('--list')}            인식된 문서·제목·계층만 출력 (Confluence 호출·인증 없음)
+  ${o('--force')}           변경 감지 무시, 전체 강제 갱신
+  ${o('--verify')}          변경 없는 문서도 페이지 존재 확인(삭제됐으면 재생성)
+  ${o('--rebuild')}         매핑된 페이지 전부 삭제 후 재생성
+  ${o('--no-color')}        컬러 출력 끄기
+  ${o('-h, --help')}        이 도움말
+  ${o('-v, --version')}     버전 출력
+
+${h('경로 인자:')}
+  파일/폴더를 주면 그 문서만 동기화합니다(부모 README 자동 포함).
+  예)  ${o('confluence-sync 20-design')}        ${o('confluence-sync 90-glossary.md')}
+
+${h('pull(역방향) 옵션:')}
+  ${o('--out <dir>')}       .md 를 생성할 디렉토리(기본: 현재 폴더)
+  ${o('--children')}        하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
+  ${o('--space')}          대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
+  (이미지는 항상 attachments/<문서명>/ 하위에 저장됨)
+  예)  ${o('confluence-sync pull https://.../pages/12345/Title --out ./docs --children')}
+       ${o('confluence-sync pull --space --out ./docs')}
+
+${h('설정(.env):')}
+  실행 위치(cwd)의 .env 또는 셸 환경변수를 읽습니다.
+  필수: CONFLUENCE_BASE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY
+  선택: CONFLUENCE_PARENT_ID(페이지/폴더 id), CONFLUENCE_SYNC_BASE
+  ${o("'confluence-sync init'")} 으로 대화형 생성 가능.`);
+}

package/dist/html2md.js

@@ -0,0 +1,137 @@
+/**
+ * Confluence export_view(HTML) → Markdown 변환.
+ * turndown(HTML→MD) + Confluence 특화 규칙(code 매크로·첨부 이미지·표).
+ * storage/export_view 는 무손실 역변환이 아니므로 근사 결과다.
+ */
+import TurndownService from 'turndown';
+/** storage(XHTML)의 code 매크로들에서 language 파라미터를 문서 순서대로 추출(미지정은 ''). */
+export function codeLanguagesFromStorage(storage) {
+    const out = [];
+    const macro = /<ac:structured-macro[^>]*ac:name="code"[\s\S]*?<\/ac:structured-macro>/g;
+    let m;
+    while ((m = macro.exec(storage)) !== null) {
+        const lang = m[0].match(/ac:name="language"[^>]*>([^<]*)</);
+        out.push(lang ? lang[1].trim() : '');
+    }
+    return out;
+}
+/** 공백이 있으면 <...> 로 감싼 마크다운 링크 목적지(공백 있는 경로도 안전하게 파싱되도록) */
+const linkDest = (p) => (/\s/.test(p) ? `<${p}>` : p);
+/**
+ * turndown 은 텍스트 노드 단위로 이스케이프해서, 줄 중간인데도 마커로 오인해 \- \+ \. 을 남긴다.
+ * (예: `**7️⃣**\-**1️⃣**` — 두 굵은 글씨 사이 텍스트 노드가 "-" 하나라 노드 시작으로 취급)
+ * 줄 맨 앞의 진짜 마커 이스케이프는 보존하고, 그 뒤(줄 중간)의 것만 되돌린다. 코드블록은 건드리지 않는다.
+ */
+function relaxEscapes(md) {
+    let inFence = false;
+    return md
+        .split('\n')
+        .map((line) => {
+        if (/^\s*```/.test(line)) {
+            inFence = !inFence;
+            return line;
+        }
+        if (inFence)
+            return line;
+        // 들여쓰기 + (줄 맨 앞의 이스케이프된 마커) 까지는 그대로 두고 이후만 완화
+        const head = line.match(/^\s*(?:\\[-+>#]|\d+\\\.)?/)?.[0] ?? '';
+        const rest = line
+            .slice(head.length)
+            // 줄 중간의 - + . > 는 마커가 아니므로 이스케이프 불필요
+            .replace(/\\([-+.>])/g, '$1')
+            // 링크가 아닌 대괄호 쌍(뒤에 ( 나 [ 가 오지 않음)은 이스케이프 불필요
+            .replace(/\\\[([^[\]\n]*)\\\](?!\s*[([])/g, '[$1]');
+        return head + rest;
+    })
+        .join('\n');
+}
+export function htmlToMarkdown(html, opts = {}) {
+    const td = new TurndownService({
+        headingStyle: 'atx',
+        codeBlockStyle: 'fenced',
+        bulletListMarker: '-',
+        hr: '---',
+        emDelimiter: '_',
+    });
+    // Confluence export_view 는 색상 텍스트용 인라인 <style> 을 본문(제목 안까지) 끼워 넣는다.
+    // turndown 은 기본적으로 이런 요소의 텍스트를 그대로 뱉으므로 통째로 제거한다.
+    td.remove(['style', 'script', 'noscript', 'head', 'meta', 'link']);
+    // turndown 은 _ 를 강조로 오인할까봐 전부 \_ 로 이스케이프한다.
+    // 그러나 단어 내부 밑줄은 CommonMark 에서 강조가 아니므로(:11_eleven_square_blue: 같은 이모지 코드)
+    // 양쪽이 단어 문자인 경우만 이스케이프를 되돌린다.
+    const baseEscape = td.escape.bind(td);
+    td.escape = (s) => baseEscape(s).replace(/(\w)\\_(?=\w)/g, '$1_');
+    // Confluence 는 리스트 항목 내용을 <li><p>…</p></li> 로 감싼다.
+    // 기본 규칙대로면 문단으로 취급돼 항목마다 빈 줄이 생기므로(loose list),
+    // li 안의 첫 문단은 빈 줄 없이 붙인다(두 번째 이후 문단은 기존대로 분리).
+    td.addRule('liParagraph', {
+        filter: (node) => node.nodeName === 'P' && node.parentNode?.nodeName === 'LI',
+        replacement: (content, node) => {
+            const el = node;
+            return el.previousElementSibling ? `\n\n${content}` : content;
+        },
+    });
+    // 코드블록: Confluence code 매크로는 export_view 에서 <pre ...syntaxhighlighter...> 로 렌더된다.
+    // 언어는 storage 기반 codeLangs 를 우선 사용(개수가 맞을 때). 없으면 brush 로 폴백.
+    const preCount = (html.match(/<pre[\s>]/gi) || []).length;
+    const langs = opts.codeLangs && opts.codeLangs.length === preCount ? opts.codeLangs : undefined;
+    let preIdx = 0;
+    td.addRule('confCode', {
+        filter: (node) => node.nodeName === 'PRE',
+        replacement: (_content, node) => {
+            const el = node;
+            const i = preIdx++;
+            let lang;
+            if (langs) {
+                lang = langs[i] ?? '';
+            }
+            else {
+                const params = el.getAttribute('data-syntaxhighlighter-params') || '';
+                const m = params.match(/brush:\s*([^;]+)/i);
+                lang = m ? m[1].trim() : '';
+            }
+            // 원본에 줄 끝 공백이 잔뜩 붙어 있는 경우가 많아 트림(코드 의미는 불변)
+            const code = (el.textContent || '').replace(/[ \t]+$/gm, '').replace(/\n+$/, '');
+            return `\n\n\`\`\`${lang || 'plaintext'}\n${code}\n\`\`\`\n\n`;
+        },
+    });
+    // 이미지: 첨부 → 로컬 파일명으로, 외부 URL 이미지 → 절대 URL 유지.
+    td.addRule('confImage', {
+        filter: 'img',
+        replacement: (_content, node) => {
+            const el = node;
+            const src = el.getAttribute('src') || '';
+            const alt = el.getAttribute('alt') || '';
+            const isAttachment = el.getAttribute('data-linked-resource-type') === 'attachment' ||
+                /\/download\/(attachments|thumbnails)\//.test(src);
+            if (!isAttachment && /^https?:\/\//i.test(src)) {
+                return `![${alt}](${linkDest(src)})`;
+            }
+            const alias = el.getAttribute('data-linked-resource-default-alias') || '';
+            const name = alias || decodeURIComponent((src.split('?')[0].split('/').pop() || '').trim());
+            if (name)
+                opts.onImage?.(name);
+            const dest = opts.assetPrefix ? `${opts.assetPrefix}/${name}` : name;
+            return `![${alt || name}](${linkDest(dest)})`;
+        },
+    });
+    // 표 → GFM 마크다운 표(turndown 기본은 표 미지원).
+    td.addRule('confTable', {
+        filter: 'table',
+        replacement: (_content, node) => {
+            const cell = (c) => td.turndown(c.innerHTML || '').replace(/\n+/g, ' ').replace(/\|/g, '\\|').trim();
+            const trs = Array.from(node.querySelectorAll('tr'));
+            const matrix = trs.map((r) => Array.from(r.children).filter((c) => c.nodeName === 'TD' || c.nodeName === 'TH').map(cell));
+            const rows = matrix.filter((r) => r.length);
+            if (!rows.length)
+                return '';
+            const header = rows[0];
+            const sep = header.map(() => '---');
+            let out = `\n\n| ${header.join(' | ')} |\n| ${sep.join(' | ')} |\n`;
+            for (const r of rows.slice(1))
+                out += `| ${r.join(' | ')} |\n`;
+            return `${out}\n`;
+        },
+    });
+    return relaxEscapes(td.turndown(html)).trim() + '\n';
+}

package/dist/ignore.js

@@ -0,0 +1,25 @@
+/**
+ * 동기화 제외 규칙. base 루트의 .confluence-syncignore(.gitignore 방식) + --exclude 옵션.
+ * 매칭은 npm `ignore`(gitignore 스펙) 사용. 경로는 base 기준 상대(POSIX).
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import ignore from 'ignore';
+export const IGNORE_FILE = '.confluence-syncignore';
+export function buildIgnorer(baseDir, excludes) {
+    const ig = ignore();
+    let active = false;
+    const file = join(baseDir, IGNORE_FILE);
+    if (existsSync(file)) {
+        ig.add(readFileSync(file, 'utf8'));
+        active = true;
+    }
+    if (excludes.length) {
+        ig.add(excludes);
+        active = true;
+    }
+    return {
+        ignores: (rel) => active && ig.ignores(rel),
+        active,
+    };
+}

package/dist/init.js

@@ -0,0 +1,120 @@
+/**
+ * `confluence-sync init` — 대화형으로 cwd 에 .env 를 생성한다.
+ * TTY 가 아니면(파이프/CI) 값 없는 빈 템플릿을 쓴다. 토큰 입력은 *로 가린다.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { bold, cyan, dim, green, red, yellow } from './colors.js';
+/** 일반 한 줄 입력(에코 표시). 매 질문마다 readline 을 새로 열고 닫아 stdin 경쟁을 피한다. */
+async function promptLine(query) {
+    const rl = createInterface({ input, output });
+    try {
+        return (await rl.question(query)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** 비밀 입력: raw 모드로 직접 읽어 *로 가린다(readline 미사용 → 에코 충돌 없음). */
+function promptSecret(query) {
+    return new Promise((resolve) => {
+        output.write(query);
+        const wasRaw = input.isRaw ?? false;
+        input.setRawMode?.(true);
+        input.resume();
+        let val = '';
+        const cleanup = () => {
+            input.removeListener('data', onData);
+            input.setRawMode?.(wasRaw);
+            input.pause();
+        };
+        const onData = (buf) => {
+            for (const ch of buf.toString('utf8')) {
+                if (ch === '\r' || ch === '\n' || ch === '\u0004') { // Enter / Ctrl+D
+                    cleanup();
+                    output.write('\n');
+                    resolve(val.trim());
+                    return;
+                }
+                if (ch === '\u0003') { // Ctrl+C
+                    cleanup();
+                    output.write('\n');
+                    process.exit(1);
+                }
+                if (ch === '\u007f' || ch === '\b') { // Backspace
+                    if (val.length) {
+                        val = val.slice(0, -1);
+                        output.write('\b \b');
+                    }
+                    continue;
+                }
+                if (ch >= ' ') {
+                    val += ch;
+                    output.write('*');
+                }
+            }
+        };
+        input.on('data', onData);
+    });
+}
+export async function runInit(argv) {
+    const target = resolve(process.cwd(), '.env');
+    const force = argv.includes('--force');
+    const fields = [
+        { key: 'CONFLUENCE_BASE_URL', hint: 'https://api.atlassian.com/ex/confluence/<CLOUD_ID>/wiki 형식 (CLOUD_ID: <도메인>.atlassian.net/_edge/tenant_info 에서 확인)' },
+        { key: 'CONFLUENCE_EMAIL', hint: 'Atlassian 계정 이메일' },
+        { key: 'CONFLUENCE_API_TOKEN', hint: 'Scoped API 토큰 (id.atlassian.com → Create API token with scopes). 입력은 가려집니다', secret: true },
+        { key: 'CONFLUENCE_SPACE_KEY', hint: 'URL .../wiki/spaces/<KEY>/... 의 KEY' },
+        { key: 'CONFLUENCE_PARENT_ID', hint: '루트 앵커(페이지 또는 폴더 id). 비우면 공간 최상위', optional: true },
+        { key: 'CONFLUENCE_SYNC_BASE', hint: `동기화 루트 디렉토리 (기본: ${process.cwd()})`, optional: true, def: process.cwd() },
+    ];
+    const renderEnv = (vals) => '# confluence-sync 설정 (confluence-sync init 으로 생성)\n\n' +
+        fields.map((f) => `# ${f.hint}\n${f.key}=${vals[f.key] ?? ''}`).join('\n\n') +
+        '\n';
+    // 덮어쓰기 가드
+    if (existsSync(target) && !force) {
+        if (!input.isTTY) {
+            console.error(red(`✗ .env 가 이미 있습니다: ${target}`) + `\n  덮어쓰려면:  ${cyan('confluence-sync init --force')}`);
+            process.exit(1);
+        }
+        const rlConfirm = createInterface({ input, output });
+        const ans = await rlConfirm.question(`.env 가 이미 존재합니다 (${target}). 덮어쓸까요? [y/N] `);
+        rlConfirm.close();
+        if (!/^y(es)?$/i.test(ans.trim())) {
+            console.log('취소했습니다.');
+            return;
+        }
+    }
+    // 비대화형(파이프/CI): 값 없이 빈 템플릿만 생성
+    if (!input.isTTY) {
+        writeFileSync(target, renderEnv({}));
+        console.log(`템플릿 .env 를 생성했습니다: ${target}\n각 값을 채워 넣으세요.`);
+        return;
+    }
+    // 대화형 마법사
+    console.log(bold('confluence-sync .env 설정 마법사'));
+    console.log(dim('각 항목을 입력하세요. (Enter 로 비우면 빈 값 또는 기본값)\n'));
+    const values = {};
+    try {
+        for (const f of fields) {
+            const label = `${cyan(f.key)}${f.optional ? dim(' (선택)') : ''}\n  ${dim(f.hint)}\n  ${cyan('>')} `;
+            let v = f.secret ? await promptSecret(label) : await promptLine(label);
+            if (!v && f.def)
+                v = f.def;
+            values[f.key] = v;
+        }
+    }
+    catch (e) {
+        // 일반 입력에서 Ctrl+D(EOF) → AbortError. 깔끔히 취소
+        if (e?.name === 'AbortError') {
+            output.write(yellow('\n취소했습니다. (.env 미생성)\n'));
+            return;
+        }
+        throw e;
+    }
+    writeFileSync(target, renderEnv(values));
+    console.log(green(`\n✓ .env 생성 완료: ${target}`));
+    console.log(`  다음으로:  ${cyan('confluence-sync --dry-run')}  ${dim('(대상·상태 미리보기)')}`);
+}

package/dist/mapping.js

@@ -0,0 +1,16 @@
+/**
+ * 매핑(파일 경로 ↔ pageId ↔ hash) 영속화.
+ * 기본 위치는 <base>/.confluence-sync.json 이며 문서셋과 함께 버전관리된다.
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+export function loadMapping(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function saveMapping(path, m) {
+    writeFileSync(path, JSON.stringify(m, null, 2) + '\n');
+}

package/dist/markdown.js

@@ -0,0 +1,112 @@
+/**
+ * Markdown → Confluence storage format 변환.
+ * - 코드블록 → code 매크로
+ * - 내부 .md 링크 → 페이지 링크(ri:page, 대상 제목 기반)
+ * - 로컬 이미지 → 첨부 참조(ri:attachment), 외부 URL 이미지는 그대로
+ * 모든 경로는 baseDir 기준 상대경로로 해석한다.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, relative, dirname, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+import MarkdownIt from 'markdown-it';
+export const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+export const hashOf = (s) => createHash('sha256').update(s).digest('hex');
+/** markdown-it 이 퍼센트 인코딩한 링크/이미지 경로를 실제 경로로 디코드(실패 시 원본). */
+const decodePath = (s) => {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+};
+const md = new MarkdownIt({ html: true, linkify: true, breaks: false });
+// 렌더 규칙은 md 인스턴스에 한 번만 등록되므로, 현재 변환 컨텍스트를 모듈 변수로 공유한다.
+let ctx = { fileDir: '', titleIndex: {}, images: [], internalLinks: 0, linkStack: [], linkedTitles: new Set() };
+let baseDir = '';
+/** 링크 href 가 base 내부 .md 면 그 페이지 제목 반환 */
+function resolveInternalLink(href) {
+    if (!href || /^(https?:|mailto:|#)/i.test(href))
+        return null;
+    const pathPart = href.split('#')[0];
+    if (!pathPart || !/\.md$/i.test(pathPart))
+        return null;
+    const rel = relative(baseDir, resolve(baseDir, ctx.fileDir, decodePath(pathPart)));
+    return ctx.titleIndex[rel] ?? null;
+}
+md.renderer.rules.fence = (tokens, idx) => {
+    const t = tokens[idx];
+    const lang = (t.info || '').trim().split(/\s+/)[0];
+    const safe = t.content.split(']]>').join(']]]]><![CDATA[>');
+    const langParam = lang ? `<ac:parameter ac:name="language">${lang}</ac:parameter>` : '';
+    return `<ac:structured-macro ac:name="code">${langParam}<ac:plain-text-body><![CDATA[${safe}]]></ac:plain-text-body></ac:structured-macro>\n`;
+};
+md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
+    const href = tokens[idx].attrGet('href') || '';
+    const targetTitle = resolveInternalLink(href);
+    if (targetTitle) {
+        ctx.linkStack.push(true);
+        ctx.internalLinks++;
+        ctx.linkedTitles.add(targetTitle);
+        return `<ac:link><ri:page ri:content-title="${escapeXml(targetTitle)}" /><ac:link-body>`;
+    }
+    ctx.linkStack.push(false);
+    return self.renderToken(tokens, idx, opts);
+};
+md.renderer.rules.link_close = (tokens, idx, opts, _env, self) => ctx.linkStack.pop() ? '</ac:link-body></ac:link>' : self.renderToken(tokens, idx, opts);
+// 이미지 기본 최대 표시 폭(px). Confluence 본문 폭을 넘는 큰 원본이 영역을 벗어나는 것을 막는다.
+// 개별 이미지는 markdown title 로 덮어쓴다: ![alt](src "width=900")
+const DEFAULT_IMAGE_WIDTH = 760;
+md.renderer.rules.image = (tokens, idx) => {
+    const token = tokens[idx];
+    const src = token.attrGet('src') || '';
+    const title = token.attrGet('title') || '';
+    const m = title.match(/width\s*=\s*(\d+)/i);
+    const width = m ? m[1] : String(DEFAULT_IMAGE_WIDTH);
+    const widthAttr = width ? ` ac:width="${escapeXml(width)}"` : '';
+    if (/^https?:\/\//i.test(src)) {
+        return `<ac:image${widthAttr}><ri:url ri:value="${escapeXml(src)}" /></ac:image>`;
+    }
+    // markdown-it 이 링크 경로를 퍼센트 인코딩하므로 디코드해서 실제 파일명/경로로 복원(한글·공백 대응)
+    const abs = resolve(baseDir, ctx.fileDir, decodePath(src.split('#')[0]));
+    const filename = basename(abs);
+    ctx.images.push({ filename, abs });
+    return `<ac:image${widthAttr}><ri:attachment ri:filename="${escapeXml(filename)}" /></ac:image>`;
+};
+/** 첫 H1(`# 제목`)을 제목으로 추출하고 본문에서 제거 */
+export function splitTitleAndBody(markdown, fallback) {
+    const lines = markdown.split('\n');
+    const i = lines.findIndex((l) => /^#\s+/.test(l));
+    if (i === -1)
+        return { title: fallback, body: markdown };
+    const title = lines[i].replace(/^#\s+/, '').trim();
+    lines.splice(i, 1);
+    return { title, body: lines.join('\n') };
+}
+/** 본문 markdown 을 storage format 으로 변환(base 기준 상대경로로 링크·이미지 해석). */
+export function toStorage(markdown, rel, titleIndex, base) {
+    baseDir = base;
+    ctx = { fileDir: dirname(rel) === '.' ? '' : dirname(rel), titleIndex, images: [], internalLinks: 0, linkStack: [], linkedTitles: new Set() };
+    const storage = md.render(markdown);
+    return { storage, images: ctx.images, internalLinks: ctx.internalLinks, linkedTitles: [...ctx.linkedTitles] };
+}
+/**
+ * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 이미지의 내용 해시.
+ * 이미지 내용을 포함하므로, 같은 파일명으로 이미지만 교체해도 해시가 바뀌어 재동기화 대상이 된다.
+ * 이미지가 없으면 hashOf(title + '\0' + storage) 와 동일(이미지 없는 문서는 기존 해시 유지).
+ */
+export function docHash(title, r) {
+    const parts = [title, r.storage];
+    for (const img of r.images) {
+        let digest = 'missing';
+        try {
+            if (existsSync(img.abs))
+                digest = createHash('sha256').update(readFileSync(img.abs)).digest('hex');
+        }
+        catch {
+            /* 읽기 실패 시 'missing' 으로 둔다 */
+        }
+        parts.push(`${img.filename}:${digest}`);
+    }
+    return hashOf(parts.join('\0'));
+}

package/dist/pull.js

@@ -0,0 +1,151 @@
+/**
+ * `confluence-sync pull <pageId|url> [--out <dir>] [--children]`
+ * Confluence 페이지를 읽어 Markdown(.md) 으로 생성한다(역방향).
+ * 자식이 있는 페이지는 push 관례를 역으로 적용해 <slug>/README.md 폴더로 펼친다.
+ * 첨부는 .md 옆에 내려받고 이미지 링크를 로컬 파일명으로 재작성한다.
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve, join, dirname, basename } from 'node:path';
+import { readEnv, requireEnv } from './config.js';
+import { createClient } from './confluence.js';
+import { htmlToMarkdown, codeLanguagesFromStorage } from './html2md.js';
+import { cyan, dim, green, red, yellow } from './colors.js';
+// 첨부 이미지는 항상 <md위치>/attachments/<문서명>/ 하위에 저장한다.
+const ASSETS_DIR = 'attachments';
+function optVal(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+/** URL/숫자/쿼리에서 콘텐츠 ID 추출(page·folder URL 모두) */
+function parseContentId(input) {
+    if (/^\d+$/.test(input))
+        return input;
+    return (input.match(/\/(?:pages|folder)\/(\d+)/)?.[1] ??
+        input.match(/[?&]pageId=(\d+)/)?.[1] ??
+        null);
+}
+/** 제목 → 파일/폴더명(파일시스템 금지문자 치환, 한글 유지) */
+function slug(title) {
+    return title.replace(/[\/\\:*?"<>|]/g, '-').replace(/\s+/g, ' ').trim() || 'untitled';
+}
+/** 페이지 1건을 .md 로 생성(자식 페이지/폴더가 있으면 <slug>/README.md 폴더로). */
+async function pullPage(client, node, destDir, withChildren) {
+    const { id, title, html, storage } = node;
+    // 페이지도 하위 페이지 + 하위 폴더를 모두 가질 수 있다(폴더가 페이지 밑에 올 수 있음).
+    const childFolders = withChildren ? await client.getChildFolders(id) : [];
+    const childPages = withChildren ? await client.getChildPages(id) : [];
+    const hasChildren = childFolders.length + childPages.length > 0;
+    const folder = hasChildren ? join(destDir, slug(title)) : destDir;
+    const filePath = hasChildren ? join(folder, 'README.md') : join(destDir, `${slug(title)}.md`);
+    mkdirSync(dirname(filePath), { recursive: true });
+    // 첨부는 항상 <md위치>/attachments/<문서명>/이미지 에 저장
+    const mdBase = basename(filePath).replace(/\.md$/, '');
+    const assetPrefix = `${ASSETS_DIR}/${mdBase}`;
+    const referenced = new Set();
+    const body = htmlToMarkdown(html, {
+        onImage: (f) => referenced.add(f),
+        assetPrefix,
+        codeLangs: codeLanguagesFromStorage(storage), // 코드블록 언어는 storage 가 진짜
+    });
+    if (referenced.size) {
+        const attachments = await client.listAttachments(id);
+        const byName = new Map(attachments.map((a) => [a.filename, a.downloadPath]));
+        const saveDir = join(dirname(filePath), assetPrefix);
+        for (const name of referenced) {
+            const dp = byName.get(name);
+            if (!dp) {
+                console.error(yellow(`    ⚠ 첨부 없음: ${name}`));
+                continue;
+            }
+            try {
+                mkdirSync(saveDir, { recursive: true });
+                writeFileSync(join(saveDir, name), await client.downloadAttachment(dp));
+            }
+            catch (e) {
+                console.error(red(`    ✗ 첨부 다운로드 실패 ${name}`) + `\n${e.message}`);
+            }
+        }
+    }
+    writeFileSync(filePath, `# ${title}\n\n${body}`);
+    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));
+    for (const c of childPages)
+        add(counts, await pullNode(client, c.id, folder, withChildren));
+    return counts;
+}
+function add(acc, c) { acc.pages += c.pages; acc.folders += c.folders; }
+/** 노드(페이지/폴더)를 재귀적으로 가져온다. 폴더는 디렉토리(본문 없음)로 만든다. 노드 하나 실패는 스킵. */
+async function pullNode(client, id, destDir, withChildren) {
+    try {
+        const node = await client.getNode(id);
+        if (node.type === 'folder') {
+            const dir = join(destDir, slug(node.title));
+            mkdirSync(dir, { recursive: true });
+            console.log(`  ${cyan('📁 폴더')}  ${dir}  ${dim(`(#${id})`)}`);
+            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));
+                for (const p of await client.getChildPages(id))
+                    add(counts, await pullNode(client, p.id, dir, true));
+            }
+            else {
+                console.log(dim('     (하위 내용은 --children 으로 가져옵니다)'));
+            }
+            return counts;
+        }
+        // page: getNode 결과(html + storage) 그대로 사용
+        return await pullPage(client, node, destDir, withChildren);
+    }
+    catch (e) {
+        console.error(red(`  ✗ 실패  #${id}`) + `\n${e.message}`);
+        return { pages: 0, folders: 0 };
+    }
+}
+export async function runPull(argv) {
+    const withChildren = argv.includes('--children');
+    const wholeSpace = argv.includes('--space');
+    const outDir = resolve(optVal(argv, '--out') ?? process.cwd());
+    const env = readEnv();
+    requireEnv(env);
+    const client = createClient({ baseUrl: env.baseUrl, email: env.email, token: env.token }, { force: false, verify: false });
+    // --space: 스페이스 홈페이지(콘텐츠 트리 루트)부터 전체를 재귀적으로 가져옴
+    if (wholeSpace) {
+        const { homepageId } = await client.getSpaceInfo(env.spaceKey);
+        if (!homepageId) {
+            console.error(red(`✗ 스페이스 '${env.spaceKey}' 의 홈페이지를 찾을 수 없습니다.`));
+            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}개` : ''} 생성`);
+        return;
+    }
+    // 위치 인자: ['pull', <pageId|url>, ...]
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--out') {
+            i++;
+            continue;
+        }
+        if (argv[i].startsWith('-'))
+            continue;
+        positionals.push(argv[i]);
+    }
+    const target = positionals[1];
+    if (!target) {
+        console.error(red('✗ 가져올 페이지/폴더를 지정하세요.') + `\n  예) ${cyan('confluence-sync pull <pageId|url> [--out <dir>] [--children]')}\n  스페이스 전체: ${cyan('confluence-sync pull --space')}`);
+        process.exit(1);
+    }
+    const contentId = parseContentId(target);
+    if (!contentId) {
+        console.error(red(`✗ 콘텐츠 ID 를 인식할 수 없습니다: ${target}`) + '\n  숫자 ID 또는 .../pages/<ID>/... · .../folder/<ID> URL 을 주세요.');
+        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}개` : ''} 생성`);
+}