@wonseok-han/confluence-sync 1.8.0 → 2.0.0

package/dist/sync/fetch.js

@@ -0,0 +1,287 @@
+import { progressStep } from '../shared/progress.js';
+/** Read-only, batched remote observation. Never advances the synchronization baseline. */
+import { bold, cyan, green, yellow, red, dim } from '../shared/colors.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { readEnv } from '../confluence/config.js';
+import { buildFolderIndex, parentKeyOf } from '../documents/catalog.js';
+import { buildIgnorer } from './ignore.js';
+import { loadMapping } from './mapping.js';
+import { mappingPath, METADATA_DIR } from './metadata.js';
+import { scopeClient } from './scope.js';
+import { assertWorkspaceConnection, inNestedWorkspace, inScope, loadWorkspace, requireScope, resolveSyncBase, within } from './workspace.js';
+export const FETCH_TTL_MS = 120_000;
+const BATCH_SIZE = 100, MAX_REQUESTS = 20;
+const states = new Set(['unchanged', 'changed', 'unavailable', 'unknown', 'new']);
+const digest = (value) => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function cachePath(base) {
+    mappingPath(base); // Validates the metadata directory, including symlinks.
+    const path = join(base, METADATA_DIR, 'remote.json');
+    if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()))
+        throw new Error('원격 조회 캐시는 일반 파일이어야 합니다.');
+    return path;
+}
+function fetchContext(baseInput, env, options = {}) {
+    const base = realpathSync.native?.(baseInput) ?? realpathSync(baseInput), workspace = loadWorkspace(base), root = requireScope(workspace);
+    assertWorkspaceConnection(workspace, env);
+    const mapping = loadMapping(options.mappingFile ?? mappingPath(base)), ignore = buildIgnorer(base, []);
+    const scoped = Object.entries(mapping).filter(([path]) => inScope(path.replace(/\/$/, ''), workspace) && !ignore.ignores(path) && !inNestedWorkspace(base, path));
+    const pages = scoped.filter(([path, entry]) => entry.type !== 'folder' && /\.md$/i.test(path)).sort(([a], [b]) => a.localeCompare(b));
+    if (pages.some(([, entry]) => !/^\d+$/.test(entry.pageId)))
+        throw new Error('매핑의 페이지 ID가 숫자가 아닙니다. 매핑을 확인하세요.');
+    const folderIndex = buildFolderIndex(Object.keys(mapping).filter(path => /\.md$/i.test(path)));
+    const expectedParents = new Map(pages.map(([path]) => { const parent = parentKeyOf(path, folderIndex); return [path, path === 'README.md' && mapping[path].pageId === root.id ? undefined : mapping[path].remoteParentId ?? (parent ? mapping[parent]?.pageId : root.id)]; }));
+    const key = digest(['discovery-v2', base, workspace, env.baseUrl, env.spaceKey, digest([env.email, env.token]), pages, [...expectedParents], scoped.filter(([, e]) => e.type === 'folder')]);
+    const binding = digest([base, workspace, env.baseUrl, env.spaceKey, digest([env.email, env.token])]);
+    const path = cachePath(base), now = Date.now();
+    return { base, workspace, root, mapping, pages, scoped, expectedParents, key, path, now, binding };
+}
+function cachedSnapshot(context, allowExpired = false) {
+    try {
+        const value = JSON.parse(readFileSync(context.path, 'utf8'));
+        const age = context.now - Date.parse(value?.checkedAt);
+        if (value?.version !== 1 || value.key !== context.key || age < 0 || !Number.isFinite(age) || !allowExpired && age >= FETCH_TTL_MS || !Array.isArray(value.items))
+            return null;
+        if (value.folders !== undefined && (!Array.isArray(value.folders) || value.folders.some(folder => !folder || typeof folder.path !== 'string' || !folder.path.endsWith('/') || !/^\d+$/.test(folder.pageId) || typeof folder.title !== 'string' || !within(context.base, resolve(context.base, folder.path)))))
+            return null;
+        const ids = new Set();
+        for (const item of value.items) {
+            if (!item || typeof item.path !== 'string' || !within(context.base, resolve(context.base, item.path)) || !/\.md$/i.test(item.path) || !/^\d+$/.test(item.pageId) || ids.has(item.pageId) || !states.has(item.state) || !Array.isArray(item.reasons) || item.reasons.some(r => typeof r !== 'string'))
+                return null;
+            ids.add(item.pageId);
+        }
+        if (context.pages.some(([, entry]) => !ids.has(entry.pageId)))
+            return null;
+        return value;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+/** Reclassify saved metadata against current baselines without API calls. */
+export function readFetchSnapshot(base, env) {
+    const context = fetchContext(base, env), strict = cachedSnapshot(context, true);
+    if (strict)
+        return strict;
+    let prior;
+    try {
+        prior = JSON.parse(readFileSync(context.path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT' || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+    if (prior?.binding !== context.binding || !cachedSnapshot({ ...context, key: prior.key }, true))
+        return null;
+    const byId = new Map(context.pages.map(([path, entry]) => [entry.pageId, { path, entry }]));
+    return { ...prior, key: context.key, items: prior.items.map(item => {
+            const mapped = byId.get(item.pageId);
+            if (!mapped)
+                return item;
+            const { path, entry } = mapped, reasons = [];
+            if (item.state === 'unavailable')
+                return { ...item, path, baselineVersion: entry.remoteVersion };
+            if (!entry.remoteVersion || !item.remoteVersion || item.remoteVersion < entry.remoteVersion)
+                return { ...item, path, baselineVersion: entry.remoteVersion, state: 'unknown', reasons: ['원격 버전 기준을 확인할 수 없습니다. Fetch로 갱신하세요.'] };
+            if (item.remoteVersion !== entry.remoteVersion)
+                reasons.push(`버전 v${entry.remoteVersion} → v${item.remoteVersion}`);
+            if (entry.title && item.title && entry.title !== item.title)
+                reasons.push('제목 변경');
+            const parent = context.expectedParents.get(path);
+            if (parent && item.parentId && parent !== item.parentId)
+                reasons.push('원격 부모 위치 변경');
+            return { ...item, path, baselineVersion: entry.remoteVersion, state: reasons.length ? 'changed' : 'unchanged', reasons };
+        }) };
+}
+export async function fetchRemote(baseInput, env, options = {}) {
+    const context = fetchContext(baseInput, env, options);
+    const { base, workspace, pages, scoped, key, path, now, expectedParents, binding } = context;
+    const cached = options.refresh ? null : cachedSnapshot(context);
+    if (cached)
+        return { snapshot: cached, cached: true, requests: 0 };
+    const client = scopeClient({ ...env, baseUrl: env.baseUrl?.replace(/\/$/, '') });
+    const remote = new Map();
+    let requests = 0;
+    const query = new URLSearchParams({ 'space-id': workspace.connection.spaceId, status: 'current', limit: String(BATCH_SIZE) });
+    let cursor = '', seen = new Set();
+    do {
+        if (requests >= MAX_REQUESTS)
+            throw new Error('원격 조회가 최대 20회에 도달했습니다. 기존 캐시는 유지합니다.');
+        progressStep(`스페이스 원격 메타데이터 확인 · ${remote.size}개 발견`);
+        const params = new URLSearchParams(query);
+        if (cursor)
+            params.set('cursor', cursor);
+        let link = '';
+        requests++;
+        const data = await client.api('/api/v2/pages?' + params, undefined, headers => { link = headers.get('link') ?? ''; });
+        if (!data || !Array.isArray(data.results))
+            throw new Error('원격 페이지 목록 응답이 올바르지 않습니다.');
+        for (const page of data.results) {
+            if (!page || !/^\d+$/.test(String(page.id)) || page.parentId != null && !/^\d+$/.test(String(page.parentId)) || String(page.spaceId) !== workspace.connection.spaceId || remote.has(String(page.id)))
+                throw new Error('원격 페이지 목록의 ID·스페이스 또는 중복 응답을 확인하세요.');
+            remote.set(String(page.id), page);
+        }
+        const next = data._links?.next || link.split(',').find(part => /rel\s*=\s*"?next"?/i.test(part))?.match(/<([^>]+)>/)?.[1];
+        cursor = '';
+        if (next) {
+            const url = new URL(next, env.baseUrl.replace(/\/$/, '') + '/api/v2/pages');
+            if (url.origin !== new URL(env.baseUrl).origin || !/\/api\/v2\/pages$/.test(url.pathname) || !url.searchParams.get('cursor'))
+                throw new Error('원격 페이지 목록의 다음 페이지 주소가 올바르지 않습니다.');
+            cursor = url.searchParams.get('cursor');
+            if (seen.has(cursor))
+                throw new Error('원격 페이지 목록의 페이지네이션이 반복됩니다.');
+            seen.add(cursor);
+        }
+    } while (cursor);
+    const items = pages.map(([path, entry]) => {
+        const page = remote.get(entry.pageId), item = { path, pageId: entry.pageId, baselineVersion: entry.remoteVersion, state: 'unknown', reasons: [] };
+        if (!page)
+            return { ...item, state: 'unavailable', reasons: ['조회 결과에 없음 — 삭제·권한 변경·보관 여부는 확인되지 않았습니다.'] };
+        if (typeof page.title === 'string')
+            item.title = page.title;
+        if (typeof page.parentId === 'string')
+            item.parentId = page.parentId;
+        if (Number.isInteger(page.version?.number) && page.version.number > 0)
+            item.remoteVersion = page.version.number;
+        if (!entry.remoteVersion || !item.remoteVersion || item.remoteVersion < entry.remoteVersion)
+            item.reasons.push('비교할 기준 버전 또는 원격 버전을 확인할 수 없습니다.');
+        else {
+            item.state = 'unchanged';
+            if (item.remoteVersion !== entry.remoteVersion)
+                item.reasons.push(`버전 v${entry.remoteVersion} → v${item.remoteVersion}`);
+            if (entry.title && item.title && entry.title !== item.title)
+                item.reasons.push('제목 변경');
+            const parent = expectedParents.get(path);
+            if (parent && item.parentId && parent !== item.parentId)
+                item.reasons.push('원격 부모 위치 변경');
+            if (item.reasons.length)
+                item.state = 'changed';
+        }
+        return item;
+    });
+    // Batch only unresolved parents of unmapped pages; expanded ancestry is shared.
+    const mappingById = new Map(Object.entries(context.mapping).map(([path, entry]) => [entry.pageId, { path, entry }]));
+    const folders = new Map();
+    const slug = (title) => { const value = title.replace(/[\/\\:*?"<>|]/g, '-').replace(/\s+/g, ' ').trim(); return !value || /^\.+$/.test(value) ? 'untitled' : value.startsWith('.') || ['attachments', 'node_modules'].includes(value) ? '_' + value : value; };
+    const nodes = new Map(remote);
+    const missingParents = [...new Set([...remote].filter(([id]) => !mappingById.has(id)).map(([, page]) => String(page.parentId ?? '')).filter(id => id && id !== context.root.id && !nodes.has(id) && !mappingById.has(id)))];
+    for (let offset = 0; offset < missingParents.length; offset += BATCH_SIZE) {
+        const ids = missingParents.slice(offset, offset + BATCH_SIZE), remaining = new Set(ids), seenStarts = new Set();
+        let start = '';
+        do {
+            if (requests >= MAX_REQUESTS)
+                throw new Error('원격 조회가 최대 20회에 도달했습니다. 기존 캐시는 유지합니다.');
+            const params = new URLSearchParams({ cql: `id in (${ids.join(',')})`, expand: 'ancestors,space', limit: String(BATCH_SIZE) });
+            if (start)
+                params.set('start', start);
+            requests++;
+            progressStep(`신규 문서의 부모 폴더 메타데이터 조회 · ${offset + 1}–${offset + ids.length}`);
+            const data = await client.api('/rest/api/content/search?' + params);
+            if (!Array.isArray(data?.results))
+                throw new Error('원격 부모 폴더 목록을 확인할 수 없습니다.');
+            for (const info of data.results) {
+                const id = String(info?.id);
+                if (!remaining.has(id) || info.type !== 'folder' || String(info.space?.id) !== workspace.connection.spaceId || !Array.isArray(info.ancestors))
+                    throw new Error('원격 부모 폴더의 ID·스페이스·유형을 확인하세요.');
+                remaining.delete(id);
+                for (let i = 0; i < info.ancestors.length; i++) {
+                    const a = info.ancestors[i];
+                    if (!/^\d+$/.test(String(a.id)) || typeof a.title !== 'string')
+                        throw new Error('원격 상위 폴더 정보를 확인할 수 없습니다.');
+                    if (!nodes.has(String(a.id)))
+                        nodes.set(String(a.id), { id: String(a.id), title: a.title, type: 'folder', parentId: info.ancestors[i - 1]?.id });
+                }
+                nodes.set(id, { id, title: info.title, type: 'folder', parentId: info.ancestors.at(-1)?.id });
+            }
+            start = '';
+            if (data._links?.next) {
+                const url = new URL(data._links.next, env.baseUrl);
+                if (url.origin !== new URL(env.baseUrl).origin || !/\/rest\/api\/content\/search$/.test(url.pathname) || !/^\d+$/.test(url.searchParams.get('start') ?? ''))
+                    throw new Error('부모 폴더 목록의 다음 페이지 주소가 올바르지 않습니다.');
+                start = url.searchParams.get('start');
+                if (seenStarts.has(start))
+                    throw new Error('부모 폴더 페이지네이션이 반복됩니다.');
+                seenStarts.add(start);
+            }
+        } while (start);
+        if (remaining.size)
+            throw new Error('신규 원격 문서의 부모 폴더를 찾을 수 없습니다. 기존 캐시는 유지합니다.');
+    }
+    async function container(id, visiting = new Set()) {
+        if (id === context.root.id)
+            return '';
+        if (visiting.has(id))
+            throw new Error('원격 부모 관계가 순환합니다.');
+        visiting.add(id);
+        const mapped = mappingById.get(id);
+        if (mapped)
+            return mapped.entry.type === 'folder' ? mapped.path.replace(/\/$/, '') : dirname(mapped.path) === '.' ? '' : dirname(mapped.path);
+        const node = nodes.get(id);
+        if (!node)
+            throw new Error(`원격 부모 정보를 확인할 수 없습니다: #${id}`);
+        if (typeof node.title !== 'string' || !node.title.trim())
+            throw new Error(`원격 제목을 확인할 수 없습니다: #${id}`);
+        const parent = node.parentId ? await container(String(node.parentId), visiting) : '';
+        const path = [parent, slug(node.title)].filter(Boolean).join('/');
+        if (!remote.has(id))
+            folders.set(id, { path: path + '/', pageId: id, title: node.title });
+        return path;
+    }
+    const mappedIds = new Set(Object.values(context.mapping).map(entry => entry.pageId));
+    for (const [id, page] of remote)
+        if (!mappedIds.has(id) && page.parentId)
+            await container(String(page.parentId));
+    for (const [id, page] of remote) {
+        if (mappedIds.has(id))
+            continue;
+        if (typeof page.title !== 'string' || !Number.isInteger(page.version?.number) || page.version.number < 1)
+            throw new Error(`신규 원격 문서의 제목·버전을 확인할 수 없습니다: #${id}`);
+        const parent = page.parentId ? await container(String(page.parentId)) : '';
+        const hasChildren = [...nodes.values()].some(node => String(node.parentId) === id);
+        const path = id === context.root.id ? 'README.md' : [parent, slug(page.title) + (hasChildren ? '/README.md' : '.md')].filter(Boolean).join('/');
+        if (!inScope(path, workspace) || buildIgnorer(base, []).ignores(path) || inNestedWorkspace(base, path))
+            continue;
+        items.push({ path, pageId: id, title: page.title, parentId: page.parentId, remoteVersion: page.version.number, state: 'new', reasons: ['아직 로컬에 받지 않은 원격 문서'] });
+    }
+    const snapshot = { version: 1, key, binding, checkedAt: new Date(now).toISOString(), scope: '.', requests, items, folders: [...folders.values()], foldersSkipped: scoped.filter(([, e]) => e.type === 'folder').length };
+    // Publish only a complete observation. Never replace a good cache with partial results.
+    cachePath(base);
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = join(dirname(path), `.remote-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temp, JSON.stringify(snapshot, null, 2) + '\n', { mode: 0o600, flag: 'wx' });
+        renameSync(temp, path);
+    }
+    finally {
+        rmSync(temp, { force: true });
+    }
+    return { snapshot, cached: false, requests };
+}
+export async function runFetch(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--base') {
+            if (!argv[i + 1] || argv[i + 1].startsWith('-'))
+                throw new Error('--base에 기준 폴더를 지정하세요.');
+            i++;
+        }
+        else if (!['fetch', '--no-color', '--refresh'].includes(argv[i]))
+            throw new Error('fetch는 연결된 작업공간을 사용합니다. 옵션은 --base와 --refresh만 지정하세요.');
+    }
+    const i = argv.indexOf('--base'), base = resolveSyncBase(i >= 0 ? argv[i + 1] : undefined);
+    if (!base)
+        throw new Error('작업공간이 없습니다. --base로 기준 폴더를 지정하세요.');
+    const { snapshot, cached, requests } = await fetchRemote(base, readEnv(base), { refresh: argv.includes('--refresh') });
+    const counts = Object.fromEntries([...states].map(state => [state, snapshot.items.filter(item => item.state === state).length]));
+    console.log(`${bold(cyan('원격 변경 확인 · 스페이스 작업공간'))}\n${dim(`조회 시각: ${snapshot.checkedAt}${cached ? ' · 2분 이내 캐시 사용' : ''}`)}\n이번 API 요청: ${cyan(`${requests}회`)} · 대상 ${snapshot.items.length}건`);
+    const tones = { new: cyan, changed: cyan, unavailable: red, unknown: yellow, unchanged: green };
+    for (const item of snapshot.items.filter(item => item.state !== 'unchanged'))
+        console.log(`  ${tones[item.state](`[${({ new: '원격 신규', changed: '원격 변경', unavailable: '조회 불가', unknown: '확인 필요', unchanged: '버전 동일' })[item.state]}]`)} ${item.path} ${dim(`(#${item.pageId})`)} · ${item.reasons.join(', ')}`);
+    console.log(`${green(`버전 동일 ${counts.unchanged}`)} · ${cyan(`원격 신규 ${counts.new}`)} · ${cyan(`원격 변경 ${counts.changed}`)} · ${counts.unavailable ? red(`조회 불가 ${counts.unavailable}`) : dim('조회 불가 0')} · ${counts.unknown ? yellow(`확인 필요 ${counts.unknown}`) : dim('확인 필요 0')}`);
+    if (!snapshot.items.length)
+        console.log(dim('스페이스에서 가져올 문서가 없습니다.'));
+    console.log(dim('문서·동기화 기준은 유지합니다. 스페이스의 새 문서와 버전·위치 변경을 확인했습니다. 가져오기: csync pull'));
+}

package/dist/sync/ignore.js

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

package/dist/sync/local-state.js

@@ -0,0 +1,12 @@
+/** Local edit detection is independent of rendered storage and incoming anchor links. */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+export function localStateHash(base, rel, rendered) {
+    const hash = createHash('sha256').update(readFileSync(resolve(base, rel)));
+    for (const asset of [...rendered.attachments].sort((a, b) => a.filename.localeCompare(b.filename))) {
+        hash.update('\0' + asset.filename + '\0');
+        hash.update(createHash('sha256').update(readFileSync(asset.abs)).digest());
+    }
+    return hash.digest('hex');
+}

package/dist/sync/mapping.js

@@ -1,18 +1,41 @@
 /**
  * 매핑(파일 경로 ↔ pageId ↔ hash) 영속화.
- * 기본 위치는 <base>/.confluence-sync.json 이며 문서셋과 함께 버전관리된다.
+ * 기본 위치는 <base>/.csync/mapping.json 이며 문서셋과 함께 버전관리된다.
  */
-import { readFileSync, writeFileSync } from 'node:fs';
-/** base 루트에 놓이는 매핑 파일 이름. 이 파일이 있는 곳이 곧 동기화 루트다. */
-export const MAPPING_FILE = '.confluence-sync.json';
+import { readFileSync, writeFileSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname } from 'node:path';
+export { MAPPING_FILE } from './metadata.js';
 export function loadMapping(path) {
+    let data;
     try {
-        return JSON.parse(readFileSync(path, 'utf8'));
+        data = JSON.parse(readFileSync(path, 'utf8'));
     }
-    catch {
-        return {};
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw new Error(`매핑 파일을 읽을 수 없습니다: ${path}`);
     }
+    if (!data || typeof data !== 'object' || Array.isArray(data) || Object.values(data).some(entry => !entry || typeof entry.pageId !== 'string' || !entry.pageId ||
+        (entry.sourceObject !== undefined && (typeof entry.sourceObject !== 'string' || !/^[a-f0-9]{64}$/.test(entry.sourceObject))) ||
+        (entry.localHash !== undefined && (typeof entry.localHash !== 'string' || !/^[a-f0-9]{64}$/.test(entry.localHash))) ||
+        (entry.remoteParentId !== undefined && (typeof entry.remoteParentId !== 'string' || !entry.remoteParentId)) ||
+        (entry.remoteVersion !== undefined && (!Number.isInteger(entry.remoteVersion) || entry.remoteVersion < 1)))) {
+        throw new Error(`잘못된 매핑 파일: ${path}`);
+    }
+    const ids = Object.values(data).map(entry => entry.pageId);
+    if (new Set(ids).size !== ids.length)
+        throw new Error(`매핑 pageId 중복: ${path}`);
+    return data;
 }
 export function saveMapping(path, m) {
-    writeFileSync(path, JSON.stringify(m, null, 2) + '\n');
+    mkdirSync(dirname(path), { recursive: true });
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(m, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
 }

package/dist/sync/metadata.js

@@ -0,0 +1,57 @@
+/** Metadata locations shared by CLI, references and the web adapter. */
+import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, lstatSync } from 'node:fs';
+import { join } from 'node:path';
+export const METADATA_DIR = '.csync';
+export const MAPPING_FILE = '.csync/mapping.json';
+export const WORKSPACE_FILE = '.csync/workspace.json';
+export const IGNORE_FILE = '.csync/ignore';
+const files = {
+    mapping: [MAPPING_FILE, '.confluence-sync.json'],
+    workspace: [WORKSPACE_FILE, '.confluence-workspace.json'],
+    ignore: [IGNORE_FILE, '.confluence-syncignore'],
+};
+export function metadataPath(base, kind) {
+    const directory = join(base, METADATA_DIR);
+    if (existsSync(directory) && (!lstatSync(directory).isDirectory() || lstatSync(directory).isSymbolicLink()))
+        throw new Error(`메타데이터 폴더가 올바르지 않습니다: ${directory}`);
+    const [current, legacy] = files[kind].map(name => join(base, name));
+    for (const path of [current, legacy])
+        if (existsSync(path) && (!lstatSync(path).isFile() || lstatSync(path).isSymbolicLink()))
+            throw new Error(`메타데이터 파일이 올바르지 않습니다: ${path}`);
+    if (existsSync(current) && existsSync(legacy) && !readFileSync(current).equals(readFileSync(legacy))) {
+        throw new Error(`기존·새 메타데이터가 충돌합니다: ${legacy}, ${current}. 사용할 기준을 먼저 정리하세요.`);
+    }
+    return existsSync(current) || !existsSync(legacy) ? current : legacy;
+}
+export const mappingPath = (base) => metadataPath(base, 'mapping');
+export const workspacePath = (base) => metadataPath(base, 'workspace');
+export const ignorePath = (base) => metadataPath(base, 'ignore');
+export function hasMetadata(base) {
+    return existsSync(join(base, METADATA_DIR)) || ['mapping', 'workspace'].some(kind => existsSync(join(base, files[kind][1])));
+}
+/** Include absent locations too, so creating a competing legacy file invalidates a plan. */
+export function metadataFiles(base) {
+    return Object.values(files).flatMap(names => names.map(name => join(base, name)));
+}
+/** Explicit, offline migration. Copy and verify every destination before removing any source. */
+export function migrateMetadata(base, dryRun = false) {
+    const plan = Object.keys(files).map(kind => {
+        metadataPath(base, kind); // Validate every pair before any mutation.
+        const [next, prior] = files[kind];
+        return { source: join(base, prior), target: join(base, next) };
+    }).filter(item => existsSync(item.source)).map(item => ({ ...item, bytes: readFileSync(item.source) }));
+    for (const item of plan)
+        console.log(`${item.source} → ${item.target}`);
+    if (!dryRun && plan.length) {
+        mkdirSync(join(base, METADATA_DIR), { recursive: true });
+        for (const item of plan)
+            if (!existsSync(item.target))
+                writeFileSync(item.target, item.bytes, { flag: 'wx' });
+        for (const item of plan)
+            if (!readFileSync(item.target).equals(item.bytes) || !readFileSync(item.source).equals(item.bytes))
+                throw new Error('이전 중 메타데이터가 변경되었습니다. 원본은 제거하지 않았습니다.');
+        for (const item of plan)
+            unlinkSync(item.source);
+    }
+    return plan.length;
+}

package/dist/sync/prepare.js

@@ -0,0 +1,52 @@
+/** Prepare publication content without writing to the source workspace. */
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { buildVault, collectAssets } from '../documents/catalog.js';
+import { prepareMarkdown } from '../conversion/markdown.js';
+import { within } from './workspace.js';
+import { buildTreeRenderer } from './render.js';
+export async function preparePushTree(base, rels, selected, options) {
+    const stage = mkdtempSync(join(tmpdir(), 'csync-push-'));
+    const dispose = () => rmSync(stage, { recursive: true, force: true });
+    try {
+        const chosen = new Set(selected);
+        const sourceRenderer = buildTreeRenderer(base, rels);
+        const vault = buildVault(rels, collectAssets(base).map(file => relative(base, file).split('\\').join('/')));
+        for (const rel of rels) {
+            const original = resolve(base, rel), destination = resolve(stage, rel);
+            let text = readFileSync(original, 'utf8');
+            if (chosen.has(rel)) {
+                // Preview renders actual temporary PNGs too, so attachment hashes match Push.
+                const converted = await prepareMarkdown(text, original, base, vault, stage, false, undefined, false);
+                text = converted.text;
+                for (const [asset, source] of converted.copies) {
+                    const target = resolve(stage, asset);
+                    mkdirSync(dirname(target), { recursive: true });
+                    copyFileSync(source, target);
+                }
+            }
+            // Use the publication renderer as the final asset authority: conversion may
+            // miss balanced parentheses in Markdown paths or assets inside raw HTML.
+            if (chosen.has(rel)) {
+                const doc = sourceRenderer.docs[rel];
+                for (const asset of sourceRenderer.render(rel, doc.body, doc.title).attachments) {
+                    if (!within(base, asset.abs) || !existsSync(asset.abs))
+                        continue;
+                    const target = resolve(stage, relative(base, asset.abs));
+                    if (existsSync(target))
+                        continue;
+                    mkdirSync(dirname(target), { recursive: true });
+                    copyFileSync(asset.abs, target);
+                }
+            }
+            mkdirSync(dirname(destination), { recursive: true });
+            writeFileSync(destination, text);
+        }
+        return { ...buildTreeRenderer(stage, rels, options ? { ...options, referenceBase: base } : undefined), dispose };
+    }
+    catch (error) {
+        dispose();
+        throw error;
+    }
+}