@wonseok-han/confluence-sync 1.8.0 → 2.0.1

package/dist/sync/remap.js

@@ -4,7 +4,9 @@ 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';
+import { resolveSyncBase, loadWorkspace, inScope, inNestedWorkspace, requireScope } from './workspace.js';
+import { mappingPath } from './metadata.js';
+import { saveMapping } from './mapping.js';
 function readMapping(path) {
     if (!existsSync(path))
         return {};
@@ -39,11 +41,13 @@ export async function runRemap(argv) {
     }
     if (positionalArgs(argv).length !== 1)
         throw new Error('remap은 --base 전체를 대상으로 실행합니다.');
-    const baseInput = opts['--base']?.[0] ?? process.env.CONFLUENCE_SYNC_BASE;
+    const baseInput = resolveSyncBase(opts['--base']?.[0]);
     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 workspace = loadWorkspace(base);
+    const scope = requireScope(workspace);
+    const output = resolve(opts['--mapping']?.[0] ?? mappingPath(base));
     const source = opts['--from-mapping']?.[0];
     if (source && !existsSync(resolve(source)))
         throw new Error(`원본 매핑이 없습니다: ${source}`);
@@ -57,7 +61,7 @@ export async function runRemap(argv) {
             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 files = collectMarkdown(base).map(f => relative(base, f).split('\\').join('/')).filter(f => !ignorer.ignores(f) && inScope(f, workspace) && !inNestedWorkspace(base, f)).sort();
     const folders = buildFolderIndex(files);
     const byId = new Map();
     for (const [key, entry] of Object.entries(mapping)) {
@@ -83,11 +87,19 @@ export async function runRemap(argv) {
         const prior = byId.get(id);
         if (prior?.[1].type === 'folder')
             throw new Error(`폴더 ID를 문서에 사용할 수 없습니다: ${key}`);
+        if (id === scope.id && (scope.type !== 'page' || key !== 'README.md'))
+            throw new Error('스코프 루트의 매핑 경로는 README.md로 유지해야 합니다.');
+        if (scope.type === 'page' && key === 'README.md') {
+            if (id !== scope.id)
+                throw new Error('루트 README.md의 pageId가 선택한 스코프와 다릅니다.');
+            console.log('스코프 루트 유지: README.md');
+            continue;
+        }
         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 시 본문 갱신 대상'}`);
+        console.log(`${prior?.[0] ?? `#${id}`} → ${key} (부모: ${entry.pendingMove.parentKey ?? 'ROOT'})${entry.hash ? '' : ' — 기존 해시 없음: push 시 본문 갱신 대상'}`);
     }
     for (const [key, entry] of updates)
         next[key] = entry;

package/dist/sync/remote-folder-moves.js

@@ -0,0 +1,66 @@
+/** Filesystem part of a remote folder move. Pull owns commit/rollback and baselines. */
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve, relative, dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { within } from './workspace.js';
+export function folderMoves(folders = []) {
+    const all = folders.filter(f => f.previousPath && f.previousPath !== f.path).map(f => ({ from: f.previousPath, to: f.path, pageId: f.pageId })).sort((a, b) => a.from.length - b.from.length);
+    return all.filter(move => !all.some(parent => parent !== move && move.from.startsWith(parent.from) && move.to === parent.to + move.from.slice(parent.from.length)));
+}
+export function relocated(path, moves) {
+    const move = moves.find(m => path.startsWith(m.from));
+    return move ? move.to + path.slice(move.from.length) : path;
+}
+export function folderStamp(base, rel) {
+    const root = resolve(base, rel), entries = [];
+    const walk = (path) => {
+        const info = lstatSync(path);
+        if (info.isSymbolicLink())
+            throw Error(`폴더 이동 중 심볼릭 링크는 지원하지 않습니다: ${rel}`);
+        if (info.isDirectory()) {
+            entries.push([relative(root, path), 'directory']);
+            for (const entry of readdirSync(path).sort()) {
+                if (['.csync', '.git', '.confluence-workspace.json', '.confluence-sync.json'].includes(entry))
+                    throw Error(`별도 작업공간이 있는 폴더는 자동 이동하지 않습니다: ${rel}`);
+                walk(join(path, entry));
+            }
+        }
+        else if (info.isFile())
+            entries.push([relative(root, path), createHash('sha256').update(readFileSync(path)).digest('hex')]);
+        else
+            throw Error(`일반 파일이 아닌 항목이 있어 폴더를 이동할 수 없습니다: ${rel}`);
+    };
+    walk(root);
+    return createHash('sha256').update(JSON.stringify(entries)).digest('hex');
+}
+export function checkFolderDestination(base, move) {
+    const from = resolve(base, move.from), to = resolve(base, move.to);
+    if (!within(base, from) || !within(base, to) || from === resolve(base) || to === resolve(base) || within(from, to) || within(to, from))
+        throw Error(`안전하지 않은 폴더 이동: ${move.from} → ${move.to}`);
+    if (!existsSync(from) || !lstatSync(from).isDirectory() || lstatSync(from).isSymbolicLink())
+        throw Error(`이동할 로컬 폴더를 확인하세요: ${move.from}`);
+    if (existsSync(to))
+        throw Error(`폴더 이동 대상 경로가 이미 존재합니다: ${move.to}`);
+    for (let path = dirname(to); within(base, path); path = dirname(path)) {
+        if (existsSync(path) && (!lstatSync(path).isDirectory() || lstatSync(path).isSymbolicLink()))
+            throw Error(`폴더 이동 대상의 상위 경로를 확인하세요: ${move.to}`);
+        if (path === resolve(base))
+            break;
+    }
+}
+export async function verifyRemoteFolderMoves(client, moves, folders) {
+    for (let offset = 0; offset < moves.length; offset += 100) {
+        const batch = moves.slice(offset, offset + 100), expected = new Map(batch.map(move => [move.pageId, folders.find(folder => folder.pageId === move.pageId)]));
+        const query = new URLSearchParams({ cql: `id in (${batch.map(move => move.pageId).join(',')})`, expand: 'ancestors,space', limit: '100' });
+        const response = await client.api('/rest/api/content/search?' + query);
+        if (!Array.isArray(response?.results) || response.results.length !== expected.size)
+            throw Error('이동할 원격 폴더를 다시 확인할 수 없습니다. 로컬 폴더는 유지합니다.');
+        const seen = new Set();
+        for (const folder of response.results) {
+            const id = String(folder?.id), parent = folder?.ancestors?.at(-1)?.id;
+            if (!expected.has(id) || seen.has(id) || folder.type !== 'folder' || parent == null || String(parent) !== expected.get(id)?.parentId || folder.title !== expected.get(id)?.title)
+                throw Error('가져오기 도중 원격 폴더 위치가 바뀌었거나 이름이 변경되었습니다. Fetch 후 다시 확인하세요.');
+            seen.add(id);
+        }
+    }
+}

package/dist/sync/render.js

@@ -16,14 +16,15 @@ export function buildTreeRenderer(baseDir, rels, options) {
     // Obsidian [[wikilink]] 해석용 이름 인덱스
     const vault = buildVault(rels, collectAssets(baseDir).map((f) => relative(baseDir, f)));
     // 누가 어느 헤딩을 가리키는지 먼저 모은다 — 그 헤딩에만 Anchor 매크로를 심는다.
-    const lookup = options ? buildReferenceLookup(baseDir, rels, options.referenceRoots, options.baseUrl) : null;
+    const lookup = options ? buildReferenceLookup(options.referenceBase ?? baseDir, rels, options.referenceRoots, options.baseUrl) : null;
     const anchorTargets = resolveAnchorTargets(docs, vault, lookup?.localTarget);
-    const render = (rel, body, title) => {
+    const render = (rel, body, title, legacyCallouts = false) => {
         const warnings = new Set(), references = new Set();
         const linked = (message) => references.add(message);
         const warn = (message) => warnings.add(message);
         const ordinary = vaultResolver(rel, vault);
         const result = toStorage(body, rel, titles, baseDir, {
+            legacyCallouts,
             resolveLink: (target, embed) => {
                 if (!lookup || embed || !!vault.assets[target.toLowerCase()])
                     return ordinary(target, embed);

package/dist/sync/restore.js

@@ -0,0 +1,28 @@
+/** Recover selected local documents from Confluence; never deletes or writes remote content. */
+import { positionalArgs } from '../cli/args.js';
+import { resolveSyncBase } from './workspace.js';
+import { runPull, validateRestorePaths } from './pull.js';
+import { loadIndex, completeStaged } from './staging.js';
+export async function runRestore(argv) {
+    let explicitBase;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--base') {
+            const value = argv[++i];
+            if (!value || value.startsWith('-'))
+                throw new Error('--base 뒤에 작업공간 폴더를 지정하세요.');
+            explicitBase = value;
+        }
+        else if (argv[i].startsWith('-') && !['--no-color', '--obsidian', '--overwrite'].includes(argv[i]))
+            throw new Error(`지원하지 않는 restore 옵션: ${argv[i]}. csync restore --help를 확인하세요.`);
+    }
+    const base = resolveSyncBase(explicitBase);
+    if (!base)
+        throw new Error('작업공간을 지정하세요: csync restore README.md --base <폴더>');
+    const overwrite = argv.includes('--overwrite');
+    const paths = validateRestorePaths(base, positionalArgs(argv).slice(1), overwrite);
+    const staged = loadIndex(base).entries;
+    await runPull(['pull', '--base', base, ...(argv.includes('--obsidian') ? ['--obsidian'] : [])], { restorePaths: paths, restoreOverwrite: overwrite });
+    for (const path of paths)
+        completeStaged(base, path, staged[path]);
+    console.log('복구한 문서는 업로드 대상으로 추가하지 않습니다. 업로드하려면 직접 csync add로 선택하세요.');
+}

package/dist/sync/scope.js

@@ -0,0 +1,47 @@
+import { loadMapping } from './mapping.js';
+import { mappingPath } from './metadata.js';
+/** Stable space-root connection shared by the CLI and Web. */
+import { existsSync, statSync } from 'node:fs';
+import { createClient } from '../confluence/client.js';
+import { loadWorkspace, saveWorkspace, assertWorkspaceConnection, requireScope } from './workspace.js';
+export function scopeClient(env) {
+    if (!env.baseUrl || !env.email || !env.token || !env.spaceKey)
+        throw new Error('사이트·계정·API 토큰·스페이스 설정이 필요합니다.');
+    const url = new URL(env.baseUrl);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
+        throw new Error('Confluence BASE_URL은 인증정보·쿼리가 없는 HTTPS 주소여야 합니다.');
+    return createClient({ baseUrl: env.baseUrl, email: env.email, token: env.token }, { force: false, verify: false, requestTimeoutMs: 20_000 });
+}
+/** Bind a workspace to a space homepage without changing its documents or mapping. */
+export async function connectWorkspace(base, env) {
+    if (!existsSync(base) || !statSync(base).isDirectory())
+        throw new Error('기준 폴더는 존재하는 폴더여야 합니다.');
+    const prior = loadWorkspace(base);
+    if (prior.connection)
+        assertWorkspaceConnection(prior, env);
+    if (prior.version === 2 && prior.connection?.spaceId && prior.connection.homepageId && prior.remoteRoot) {
+        // Preserve the existing remote binding. Reconnecting never moves local or remote documents.
+        const workspace = { version: 2, connection: prior.connection, remoteRoot: prior.remoteRoot };
+        saveWorkspace(base, workspace);
+        return workspace;
+    }
+    const client = scopeClient(env), space = await client.getSpaceInfo(env.spaceKey);
+    if (!space.homepageId)
+        throw new Error('스페이스 홈페이지를 찾을 수 없습니다.');
+    const rootEntry = loadMapping(mappingPath(base))['README.md'];
+    if (rootEntry && rootEntry.pageId !== space.homepageId)
+        throw new Error('루트 README가 다른 원격 페이지에 연결되어 있습니다. 스페이스 전체를 위한 별도 기준 폴더를 사용하세요.');
+    const workspace = { version: 2, connection: { baseUrl: env.baseUrl, spaceKey: env.spaceKey, spaceId: space.id, homepageId: space.homepageId }, remoteRoot: { id: space.homepageId, type: 'page', path: '/' } };
+    saveWorkspace(base, workspace);
+    return workspace;
+}
+export async function verifyScope(client, workspace) {
+    const root = requireScope(workspace), connection = workspace.connection;
+    const space = await client.getSpaceInfo(connection.spaceKey);
+    if (space.id !== connection.spaceId || space.homepageId !== connection.homepageId)
+        throw new Error('스페이스 연결 기준이 변경되었습니다. 다시 설정하세요.');
+    const info = await client.getContentInfo(root.id);
+    if (info.spaceId !== space.id || info.type !== root.type)
+        throw new Error('스페이스 루트 연결이 변경되었습니다.');
+    return space.id;
+}

package/dist/sync/staging.js

@@ -0,0 +1,193 @@
+import { green, cyan } from '../shared/colors.js';
+import { reconcilePages } from './reconcile.js';
+import { localStateHash } from './local-state.js';
+import { buildTreeRenderer } from './render.js';
+/** Document-level upload selection. Source files are never copied into the index. */
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, mkdirSync, writeFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
+import { dirname, resolve, relative, join } from 'node:path';
+import { collectMarkdown } from '../documents/catalog.js';
+import { docHash } from '../documents/markdown.js';
+import { buildIgnorer } from './ignore.js';
+import { preparePushTree } from './prepare.js';
+import { loadMapping } from './mapping.js';
+import { mappingPath, workspacePath } from './metadata.js';
+import { loadWorkspace, requireScope, inScope, inNestedWorkspace, resolveSyncBase } from './workspace.js';
+import { readEnv } from '../confluence/config.js';
+import { positionalArgs } from '../cli/args.js';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+export const sourceHash = (base, rel) => digest(readFileSync(resolve(base, rel)));
+function location(base) {
+    workspacePath(base); // Shared metadata-directory validation, including symlinks.
+    const path = join(base, '.csync/index.json');
+    try {
+        if (!lstatSync(path).isFile())
+            throw new Error('업로드 대상 파일은 일반 파일이어야 합니다.');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return path;
+}
+function binding(base) {
+    const workspace = loadWorkspace(base);
+    requireScope(workspace);
+    const identity = [workspace.connection?.baseUrl, workspace.connection?.spaceKey, workspace.connection?.spaceId, workspace.remoteRoot?.id, workspace.remoteRoot?.type];
+    return { portable: digest(JSON.stringify(identity)), legacy: digest(JSON.stringify([realpathSync(base), ...identity])) };
+}
+function validPath(rel) { return !!rel && !rel.startsWith('/') && !rel.includes('\\') && rel.split('/').every(p => p && p !== '.' && p !== '..') && /\.md$/i.test(rel); }
+export function loadIndex(base) {
+    const path = location(base), expected = binding(base);
+    if (!existsSync(path))
+        return { version: 2, binding: expected.portable, entries: {} };
+    const index = JSON.parse(readFileSync(path, 'utf8'));
+    if (![1, 2].includes(index?.version) || typeof index.binding !== 'string' || !/^[a-f0-9]{64}$/.test(index.binding) || !index.entries || Array.isArray(index.entries) || typeof index.entries !== 'object'
+        || Object.entries(index.entries).some(([rel, entry]) => !validPath(rel) || !entry || !/^[a-f0-9]{64}$/.test(entry.source) || !/^[a-f0-9]{64}$/.test(entry.hash) || entry.reviewRequired !== undefined && typeof entry.reviewRequired !== 'boolean'))
+        throw new Error('.csync/index.json이 손상되었습니다. 업로드 선택 정보를 확인하세요.');
+    const verified = index.binding === (index.version === 1 ? expected.legacy : expected.portable);
+    // Reading never rewrites the index. An unverifiable old selection remains
+    // visible, but requires an explicit add before it can authorize any upload.
+    const entries = Object.fromEntries(Object.entries(index.entries).map(([rel, entry]) => [rel, verified ? entry : { ...entry, reviewRequired: true }]));
+    return { version: 2, binding: expected.portable, entries };
+}
+function saveIndex(base, index) {
+    const path = location(base);
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temp, JSON.stringify(index, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            unlinkSync(temp);
+    }
+}
+export function stagedPaths(base) {
+    const index = loadIndex(base), workspace = loadWorkspace(base);
+    const paths = Object.keys(index.entries);
+    if (!paths.length)
+        throw new Error('업로드 대상이 없습니다. csync add <파일·폴더>로 문서를 추가하세요.');
+    if (paths.some(path => index.entries[path].reviewRequired))
+        throw new Error('작업공간 연결 또는 이전 업로드 선택을 다시 확인해야 합니다. csync add로 문서를 다시 추가하세요.');
+    for (const rel of paths)
+        if (!inScope(rel, workspace))
+            throw new Error(`업로드 대상이 작업공간 밖입니다: ${rel}. unstage로 해제하고 기준 폴더를 확인하세요.`);
+    return paths;
+}
+export function assertStaged(base, rel, hash, entry) {
+    if (entry.reviewRequired)
+        throw new Error(`업로드 선택을 다시 확인해야 합니다: ${rel}. csync add로 다시 추가하세요.`);
+    if (sourceHash(base, rel) !== entry.source || hash !== entry.hash)
+        throw new Error(`추가 후 문서·첨부·링크가 변경되었습니다: ${rel}. csync add로 다시 추가하세요.`);
+}
+export function completeStaged(base, rel, expected) {
+    if (!expected)
+        return;
+    const index = loadIndex(base);
+    if (JSON.stringify(index.entries[rel]) !== JSON.stringify(expected))
+        return;
+    delete index.entries[rel];
+    saveIndex(base, index);
+}
+export async function inspectStaging(base, options = {}, only) {
+    const workspace = loadWorkspace(base);
+    requireScope(workspace);
+    const index = loadIndex(base), ignorer = buildIgnorer(base, []);
+    const all = collectMarkdown(base).map(p => relative(base, p).split('\\').join('/')).filter(p => !ignorer.ignores(p) && !inNestedWorkspace(base, p));
+    const selected = all.filter(p => inScope(p, workspace) && (!only || only.some(key => !key || p === key || p.startsWith(key + '/'))));
+    const sources = Object.fromEntries(selected.map(rel => [rel, sourceHash(base, rel)]));
+    const prepared = await preparePushTree(base, all, selected, { referenceRoots: options.referenceRoots ?? [], baseUrl: options.baseUrl });
+    try {
+        const originalMapping = loadMapping(mappingPath(base));
+        const mapping = reconcilePages(base, originalMapping, all, selected, requireScope(workspace));
+        const legacy = buildTreeRenderer(base, all);
+        const rows = selected.map(path => {
+            const doc = prepared.docs[path], rendered = prepared.render(path, doc.body, doc.title), hash = docHash(doc.title, rendered);
+            if (sourceHash(base, path) !== sources[path])
+                throw new Error('조회 중 문서가 변경되었습니다. 다시 시도하세요.');
+            const oldPath = doc.fm.pageId && Object.keys(originalMapping).find(key => originalMapping[key].pageId === doc.fm.pageId && !key.endsWith('/'));
+            const prior = originalMapping[path] ?? (oldPath ? originalMapping[oldPath] : undefined);
+            const reconciled = mapping[path];
+            const clean = prior?.localHash ? prior.localHash === localStateHash(base, path, rendered) : !!prior?.hash && (prior.hash === hash || prior.hash === docHash(legacy.docs[path].title, legacy.render(path, legacy.docs[path].body, legacy.docs[path].title))
+                || prior.hash === docHash(doc.title, prepared.render(path, doc.body, doc.title, 'panels'))
+                || prior.hash === docHash(doc.title, prepared.render(path, doc.body, doc.title, true))
+                || prior.hash === docHash(legacy.docs[path].title, legacy.render(path, legacy.docs[path].body, legacy.docs[path].title, 'panels'))
+                || prior.hash === docHash(legacy.docs[path].title, legacy.render(path, legacy.docs[path].body, legacy.docs[path].title, true)));
+            const renamed = !!prior?.pageId && !reconciled?.pendingMove && !!oldPath && oldPath !== path;
+            const status = !prior?.pageId ? 'new' : reconciled?.pendingMove ? 'moved' : renamed || !clean ? 'changed' : 'same';
+            const entry = { source: sources[path], hash };
+            const unmapped = !prior?.pageId && !!doc.fm.pageId;
+            const staged = !!index.entries[path], stale = staged && (unmapped || !!index.entries[path].reviewRequired || JSON.stringify(index.entries[path]) !== JSON.stringify(entry));
+            return { path, status, staged, stale, entry, ...(renamed && clean ? { renamed: true } : {}), pageId: prior?.pageId ?? doc.fm.pageId, ...(!prior?.pageId && doc.fm.pageId ? { unmapped: true, recoverable: doc.fm.spaceKey === workspace.connection?.spaceKey } : {}) };
+        });
+        for (const path of Object.keys(index.entries))
+            if (!rows.some(row => row.path === path))
+                rows.push({ path, status: 'unavailable', staged: true, stale: true, entry: index.entries[path], pageId: mapping[path]?.pageId });
+        return rows;
+    }
+    finally {
+        prepared.dispose();
+    }
+}
+export async function changeStaging(base, paths, action, options = {}) {
+    if (!paths.length)
+        throw new Error('파일 또는 폴더를 지정하세요. 전체 범위는 . 으로 지정하세요.');
+    const index = loadIndex(base);
+    const keys = paths.map(path => {
+        const key = relative(base, resolve(base, path)).split('\\').join('/');
+        if (key === '..' || key.startsWith('../'))
+            throw new Error('기준 폴더 밖의 경로는 추가할 수 없습니다.');
+        return key;
+    });
+    const rows = action === 'add' ? await inspectStaging(base, options, keys) : Object.keys(index.entries).map(path => ({ path, status: '', entry: index.entries[path] }));
+    const touched = [];
+    for (const key of keys) {
+        const matches = rows.filter(row => (!key || row.path === key || row.path.startsWith(key + '/')) && (action !== 'add' || row.status !== 'unavailable'));
+        if (!matches.length)
+            throw new Error(`작업공간에서 선택할 문서가 없습니다: ${key || '.'}`);
+        touched.push(...matches);
+        for (const row of matches)
+            if (action === 'add')
+                index.entries[row.path] = row.entry;
+            else
+                delete index.entries[row.path];
+    }
+    // Do not overwrite selections changed by another process while conversion was running.
+    const current = loadIndex(base);
+    for (const path of new Set([...Object.keys(current.entries), ...Object.keys(index.entries)])) {
+        if (keys.some(key => !key || path === key || path.startsWith(key + '/'))) {
+            if (index.entries[path])
+                current.entries[path] = index.entries[path];
+            else
+                delete current.entries[path];
+        }
+    }
+    saveIndex(base, current);
+    return touched;
+}
+export async function runStaging(argv) {
+    const command = positionalArgs(argv)[0];
+    if (command !== 'add' && command !== 'unstage')
+        throw new Error('문서 선택 명령은 add 또는 unstage를 사용하세요.');
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--base' || argv[i] === '--reference-root') {
+            const option = argv[i], value = argv[++i];
+            if (!value || value.startsWith('-'))
+                throw new Error(`${option} 뒤에 폴더를 지정하세요.`);
+        }
+        else if (argv[i].startsWith('-') && argv[i] !== '--no-color')
+            throw new Error(`지원하지 않는 ${command} 옵션: ${argv[i]}. csync ${command} --help를 확인하세요.`);
+    }
+    const at = argv.indexOf('--base'), base = resolveSyncBase(at < 0 ? undefined : argv[at + 1]);
+    if (!base)
+        throw new Error('작업공간을 지정하세요: --base <dir>');
+    const refs = [];
+    for (let i = 0; i < argv.length; i++)
+        if (argv[i] === '--reference-root')
+            refs.push(argv[++i]);
+    const options = { referenceRoots: refs, baseUrl: readEnv(base).baseUrl };
+    await changeStaging(base, positionalArgs(argv).slice(1), command === 'add' ? 'add' : 'remove', options);
+    console.log((command === 'add' ? green : cyan)(`업로드 대상 ${Object.keys(loadIndex(base).entries).length}개 저장됨`));
+}

package/dist/sync/workspace.js

@@ -0,0 +1,100 @@
+/** Shared workspace identity and persistent sync boundaries. No network access. */
+import { existsSync, readFileSync, writeFileSync, realpathSync, mkdirSync } from 'node:fs';
+import { dirname, join, relative, resolve, isAbsolute } from 'node:path';
+import { parse } from 'dotenv';
+import { workspacePath, hasMetadata } from './metadata.js';
+export { WORKSPACE_FILE } from './metadata.js';
+export function within(base, path) {
+    const rel = relative(base, path);
+    return !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`);
+}
+export function findSyncBase(from) {
+    for (let dir = resolve(from);; dir = dirname(dir)) {
+        if (hasMetadata(dir))
+            return dir;
+        if (dirname(dir) === dir)
+            return undefined;
+    }
+}
+export function resolveSyncBase(explicit) {
+    if (explicit)
+        return resolve(explicit);
+    if (process.env.CONFLUENCE_SYNC_BASE)
+        return resolve(process.env.CONFLUENCE_SYNC_BASE);
+    const found = findSyncBase(process.cwd());
+    if (found)
+        return found;
+    const envPath = join(process.cwd(), '.env');
+    const value = existsSync(envPath) ? parse(readFileSync(envPath)).CONFLUENCE_SYNC_BASE : undefined;
+    return value ? resolve(value) : undefined;
+}
+export function loadWorkspace(base) {
+    const path = workspacePath(base);
+    if (!existsSync(path))
+        return { version: 1 };
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    if (!value || ![1, 2].includes(value.version) ||
+        (value.syncPaths !== undefined && (!Array.isArray(value.syncPaths) || !value.syncPaths.length || value.syncPaths.some((p) => typeof p !== 'string' || !p))) ||
+        (value.root !== undefined && (!value.root || typeof value.root.id !== 'string' || !value.root.id || !['page', 'folder'].includes(value.root.type) || typeof value.root.baseUrl !== 'string' || typeof value.root.spaceKey !== 'string'))) {
+        throw new Error(`잘못된 작업공간 설정: ${path}`);
+    }
+    // Read the old remote-scope shape without treating it as a selected local range.
+    if (value.scope?.id) {
+        value.remoteRoot = value.scope;
+        delete value.scope;
+    }
+    for (const path of value.syncPaths ?? [])
+        if (scopePath(base, path) !== path)
+            throw new Error(`관리 범위는 정규화된 상대 경로여야 합니다: ${path}`);
+    if (value.scopeCheckRequired !== undefined && typeof value.scopeCheckRequired !== 'boolean')
+        throw new Error('잘못된 스코프 검증 설정입니다.');
+    if (value.connection && (typeof value.connection.baseUrl !== 'string' || typeof value.connection.spaceKey !== 'string'))
+        throw new Error('잘못된 연결 설정입니다.');
+    if (value.scope && (!['file', 'folder'].includes(value.scope.type) || typeof value.scope.path !== 'string' || scopePath(base, value.scope.path) !== value.scope.path))
+        throw new Error('로컬 스코프가 올바르지 않습니다. 기준 폴더 안의 파일·폴더를 지정하세요.');
+    if (value.version === 2 && (!value.remoteRoot || typeof value.remoteRoot.id !== 'string' || !value.remoteRoot.id || !['page', 'folder'].includes(value.remoteRoot.type) || typeof value.remoteRoot.path !== 'string' || !value.remoteRoot.path.startsWith('/') ||
+        !value.connection?.baseUrl || !value.connection.spaceKey || !value.connection.spaceId || !value.connection.homepageId))
+        throw new Error('스페이스 연결이 올바르지 않습니다. csync init --connect로 다시 연결하세요.');
+    delete value.scope;
+    delete value.syncPaths;
+    return value;
+}
+export function saveWorkspace(base, value) {
+    const path = workspacePath(base);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
+}
+export function scopePath(base, path) {
+    const abs = resolve(base, path);
+    if (!within(base, abs))
+        throw new Error(`관리 범위가 작업공간 밖입니다: ${path}`);
+    let ancestor = abs;
+    while (!existsSync(ancestor) && dirname(ancestor) !== ancestor)
+        ancestor = dirname(ancestor);
+    if (existsSync(base) && !within(realpathSync(base), realpathSync(ancestor)))
+        throw new Error(`관리 범위가 작업공간 밖입니다: ${path}`);
+    return relative(base, abs).split('\\').join('/') || '.';
+}
+/** The workspace root is the whole managed space; individual Push selection is separate. */
+export function inScope(_rel, workspace) {
+    return workspace.version === 2 && !!workspace.remoteRoot && !!workspace.connection;
+}
+export function requireScope(workspace) {
+    if (workspace.version !== 2 || !workspace.remoteRoot || !workspace.connection)
+        throw new Error('스페이스 연결이 없습니다. csync init --connect로 기준 폴더를 연결하거나 최초 Pull을 실행하세요.');
+    return workspace.remoteRoot;
+}
+export function assertWorkspaceConnection(workspace, env) {
+    const connection = workspace.connection;
+    if (connection && (connection.baseUrl.replace(/\/$/, '') !== env.baseUrl?.replace(/\/$/, '') || connection.spaceKey !== env.spaceKey)) {
+        throw new Error('작업공간의 Confluence 사이트·스페이스가 현재 설정과 다릅니다.');
+    }
+}
+/** Nested workspaces are independent; never traverse them from an outer sync. */
+export function inNestedWorkspace(base, rel) {
+    for (let dir = dirname(resolve(base, rel)); dir !== base && within(base, dir); dir = dirname(dir)) {
+        if (hasMetadata(dir))
+            return true;
+    }
+    return false;
+}