@wonseok-han/confluence-sync 1.7.0 → 2.0.0

package/dist/confluence/client.js

@@ -4,7 +4,8 @@
  */
 import { readFileSync, existsSync } from 'node:fs';
 import { relative } from 'node:path';
-import { red, yellow, dim } from '../shared/colors.js';
+import { confluenceFetch as fetch } from '../runtime/network.js';
+import { red, yellow } from '../shared/colors.js';
 class ConfluenceApiError extends Error {
     status;
     responseBody;
@@ -14,26 +15,39 @@ class ConfluenceApiError extends Error {
         this.responseBody = responseBody;
     }
 }
+/** Distinguishes missing binary content from authorization and transport failures. */
+export class ConfluenceDownloadError extends Error {
+    status;
+    constructor(status, statusText, path) {
+        super(`download ${status} ${statusText}\n${path}`);
+        this.status = status;
+    }
+}
 export function createClient(cfg, opts) {
     const authHeader = () => 'Basic ' + Buffer.from(`${cfg.email}:${cfg.token}`).toString('base64');
-    async function api(path, init) {
-        const res = await fetch(`${cfg.baseUrl}${path}`, {
-            ...init,
-            headers: {
-                Authorization: authHeader(),
-                'Content-Type': 'application/json',
-                Accept: 'application/json',
-                ...(init?.headers ?? {}),
-            },
-        });
-        if (!res.ok) {
-            throw new ConfluenceApiError(res.status, path, await res.text(), res.statusText);
+    async function api(path, init, onHeaders) {
+        const signal = opts.requestTimeoutMs ? AbortSignal.timeout(opts.requestTimeoutMs) : undefined;
+        try {
+            const res = await fetch(`${cfg.baseUrl}${path}`, {
+                ...init, ...(signal ? { signal } : {}),
+                headers: {
+                    Authorization: authHeader(), 'Content-Type': 'application/json', Accept: 'application/json', ...(init?.headers ?? {}),
+                },
+            });
+            if (!res.ok)
+                throw new ConfluenceApiError(res.status, path, await res.text(), res.statusText);
+            onHeaders?.(res.headers);
+            return res.status === 204 ? null : await res.json();
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw new Error(`Confluence 메타데이터 응답 대기 시간이 초과되었습니다 (${opts.requestTimeoutMs / 1000}초). 잠시 후 다시 시도하세요. 요청: ${path}`);
+            throw error;
         }
-        return res.status === 204 ? null : res.json();
     }
     /** 페이지 조회. 삭제(휴지통)·부재면 404 → null 반환(그 외 오류는 throw) */
-    async function getPageOrNull(pageId) {
-        const res = await fetch(`${cfg.baseUrl}/api/v2/pages/${pageId}`, {
+    async function getPageOrNull(pageId, withBody = false) {
+        const res = await fetch(`${cfg.baseUrl}/api/v2/pages/${pageId}${withBody ? '?body-format=storage' : ''}`, {
             headers: { Authorization: authHeader(), Accept: 'application/json' },
         });
         if (res.status === 404)
@@ -51,84 +65,122 @@ export function createClient(cfg, opts) {
         const space = data.results?.[0];
         if (!space)
             throw new Error(`Space key '${key}' 를 찾을 수 없습니다.`);
-        return { id: space.id, homepageId: space.homepageId };
-    }
-    /** 매핑에 기록된 페이지를 모두 삭제(휴지통). 매핑 파일 영속화는 호출자 책임. */
-    async function deleteAll(mapping) {
-        // 페이지(자식) 먼저, 폴더(컨테이너) 나중에 삭제
-        const entries = Object.entries(mapping).sort(([, a], [, b]) => (a.type === 'folder' ? 1 : 0) - (b.type === 'folder' ? 1 : 0));
-        console.log(yellow(`--rebuild: 기존 ${entries.length}건 삭제`));
-        for (const [key, { pageId, type }] of entries) {
-            try {
-                await api(type === 'folder' ? `/api/v2/folders/${pageId}` : `/api/v2/pages/${pageId}`, { method: 'DELETE' });
-                console.log(`  ${yellow('🗑  삭제')} ${key} ${dim(`(#${pageId})`)}`);
-            }
-            catch (e) {
-                console.error(red(`  ✗ 삭제 실패 ${key}`) + `\n${e.message}`);
-            }
-        }
+        return { id: String(space.id), homepageId: space.homepageId ? String(space.homepageId) : undefined };
     }
     /** 페이지의 기존 첨부 중 같은 파일명의 attachmentId 를 찾는다(없으면 null). */
     async function findAttachmentId(pageId, filename) {
-        try {
-            const data = await api(`/rest/api/content/${pageId}/child/attachment?filename=${encodeURIComponent(filename)}`);
-            return data?.results?.[0]?.id ?? null;
-        }
-        catch {
-            return null;
-        }
+        const data = await api(`/rest/api/content/${pageId}/child/attachment?filename=${encodeURIComponent(filename)}`);
+        return data?.results?.[0]?.id ?? null;
     }
     /**
-     * 로컬 이미지를 페이지 첨부로 업로드(v1, multipart).
+     * 로컬 파일을 페이지 첨부로 업로드(v1, multipart).
      * 같은 파일명 첨부가 이미 있으면 데이터만 새 버전으로 갱신(중복 생성 400 방지),
      * 없으면 신규 생성한다.
      */
     async function uploadAttachment(pageId, filename, abs) {
         const buf = readFileSync(abs);
-        const form = new FormData();
-        form.append('file', new Blob([buf]), filename);
-        form.append('minorEdit', 'true');
-        const attId = await findAttachmentId(pageId, filename);
-        const path = attId
-            ? `/rest/api/content/${pageId}/child/attachment/${attId}/data` // 기존 첨부 데이터 갱신
-            : `/rest/api/content/${pageId}/child/attachment`; // 신규 첨부 생성
-        const res = await fetch(`${cfg.baseUrl}${path}`, {
-            method: 'POST',
-            headers: { Authorization: authHeader(), 'X-Atlassian-Token': 'nocheck' },
-            body: form,
-        });
-        if (!res.ok)
-            throw new Error(`attachment ${res.status} ${res.statusText}\n${await res.text()}`);
+        // 롤백 오류에만 재시도한다. 매번 첨부를 재조회해 생성/갱신 경로를 다시 결정한다.
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const attId = await findAttachmentId(pageId, filename);
+            await assertInScope(pageId);
+            const path = attId
+                ? `/rest/api/content/${pageId}/child/attachment/${attId}/data`
+                : `/rest/api/content/${pageId}/child/attachment`;
+            const form = new FormData();
+            form.append('file', new Blob([buf]), filename);
+            form.append('minorEdit', 'true');
+            const res = await fetch(`${cfg.baseUrl}${path}`, {
+                method: 'POST',
+                headers: { Authorization: authHeader(), 'X-Atlassian-Token': 'nocheck' },
+                body: form,
+            });
+            if (res.ok)
+                return;
+            const detail = await res.text();
+            if (res.status === 500 && /UnexpectedRollbackException|rollback-only/i.test(detail) && attempt < 2) {
+                console.error(yellow(`    ↻ 첨부 트랜잭션 롤백, 재시도 ${attempt + 1}/2: ${filename}`));
+                await new Promise(resolve => setTimeout(resolve, 1000 * 2 ** attempt));
+                continue;
+            }
+            const traceId = res.headers.get('atl-traceid') ?? res.headers.get('x-arequestid');
+            throw new Error(`attachment ${res.status} ${res.statusText}\nPOST ${path}${traceId ? `\ntraceId: ${traceId}` : ''}\n${detail}`);
+        }
     }
-    /** 페이지의 로컬 이미지들을 업로드. 성공 개수 반환. baseDir 은 로그 표시용. */
-    async function uploadImages(pageId, images, baseDir) {
+    /** 페이지의 로컬 첨부를 업로드. 성공 개수 반환. */
+    async function uploadAttachments(pageId, attachments, baseDir) {
         let ok = 0;
-        for (const img of images) {
-            if (!existsSync(img.abs)) {
-                console.error(yellow(`    ⚠ 이미지 없음: ${relative(baseDir, img.abs)}`));
+        for (const file of attachments) {
+            if (!existsSync(file.abs)) {
+                console.error(yellow(`    ⚠ 첨부 없음: ${relative(baseDir, file.abs)}`));
                 continue;
             }
             try {
-                await uploadAttachment(pageId, img.filename, img.abs);
+                await uploadAttachment(pageId, file.filename, file.abs);
                 ok++;
             }
             catch (e) {
-                console.error(red(`    ✗ 이미지 업로드 실패 ${img.filename}`) + `\n${e.message}`);
+                console.error(red(`    ✗ 첨부 업로드 실패 ${file.filename}`) + `\n${e.message}`);
             }
         }
         return ok;
     }
-    /** 페이지 생성/갱신. 삭제 감지 시 재생성. 변경 없으면(opts.verify 아니면) 호출 없이 skip. */
+    const uploadImages = uploadAttachments;
+    /** Expanded metadata only: scope selection never downloads page bodies. */
+    async function getContentInfo(id) {
+        const data = await getV1(`/rest/api/content/${encodeURIComponent(id)}?expand=ancestors,space,version`);
+        if (String(data.id) !== id || !['page', 'folder'].includes(data.type) || !data.space?.id || !Array.isArray(data.ancestors))
+            throw new Error(`콘텐츠 위치를 확인할 수 없습니다: ${id}`);
+        const parentId = data.parentId ?? data.ancestors.at(-1)?.id;
+        return { id: String(data.id), title: data.title, type: data.type, spaceId: String(data.space.id), ...(parentId ? { parentId: String(parentId) } : {}), ancestors: data.ancestors.map((a) => ({ id: String(a.id), title: a.title })) };
+    }
+    async function assertInScope(id) {
+        if (!opts.scope)
+            return;
+        const info = await getContentInfo(id);
+        if (info.spaceId !== opts.scope.spaceId || (!opts.scope.spaceOnly && info.id !== opts.scope.id && !info.ancestors.some(a => a.id === opts.scope.id)))
+            throw new Error(`선택한 원격 스코프 밖입니다: #${id}`);
+        return info;
+    }
+    /** Read-only preflight. An unknown baseline must never authorize overwriting an existing page. */
+    async function checkPage(mapping, spaceId, key, hash, forceUpdate = false) {
+        const entry = mapping[key];
+        if (!entry?.pageId)
+            return;
+        const changed = entry.hash !== hash || opts.force || forceUpdate;
+        if (!changed && !opts.verify && !entry.pendingMove && !opts.scope)
+            return;
+        await assertInScope(entry.pageId);
+        const current = await getPageOrNull(entry.pageId);
+        assertPageBaseline(entry, current, spaceId, key, changed || !!entry.pendingMove);
+    }
+    function assertPageBaseline(entry, current, spaceId, key, writes) {
+        if (!current)
+            throw new Error(`원격 페이지 #${entry.pageId}가 없습니다: ${key}. 자동 재생성하지 않습니다.`);
+        if (current.spaceId !== undefined && String(current.spaceId) !== spaceId)
+            throw new Error(`페이지 스페이스가 다릅니다: ${key}`);
+        if (writes && entry.remoteParentId && typeof current.parentId === 'string' && current.parentId !== entry.remoteParentId)
+            throw new Error(`원격 위치 충돌: ${key} (기준 부모 #${entry.remoteParentId}, 현재 #${current.parentId}) — pull로 원격 위치를 확인하세요.`);
+        if (entry.remoteVersion === undefined) {
+            if (writes)
+                throw new Error(`원격 버전 기준이 없습니다: ${key}. 로컬 변경을 보관한 뒤 pull로 기준을 확보하세요.`);
+            return;
+        }
+        if (current.version?.number !== entry.remoteVersion)
+            throw new Error(`원격 변경 충돌: ${key} (기준 v${entry.remoteVersion}, 현재 v${current.version?.number ?? '?'}) — pull로 원격 내용을 확인하세요.`);
+    }
+    /** Incremental push with remote-version protection; --force does not bypass conflicts. */
     async function upsertPage(mapping, spaceId, key, title, storage, hash, parentId, forceUpdate = false) {
         const existing = mapping[key];
         if (existing?.pageId) {
             const changed = existing.hash !== hash || opts.force || forceUpdate;
             // 변경 없고 검증(--verify)도 안 하면 호출 없이 스킵
-            if (!changed && !opts.verify && !existing.pendingMove)
+            if (!changed && !opts.verify && !existing.pendingMove && !opts.scope)
                 return 'skipped';
-            let cur = await getPageOrNull(existing.pageId);
-            if (!cur && existing.pendingMove)
-                throw new Error(`이동 대상 페이지 #${existing.pageId}가 없습니다. 자동 재생성하지 않습니다.`);
+            await assertInScope(existing.pageId);
+            if (existing.pendingMove && existing.pageId === opts.scope?.id)
+                throw new Error('스코프 루트는 이동할 수 없습니다.');
+            let cur = await getPageOrNull(existing.pageId, !!existing.pendingMove);
+            assertPageBaseline(existing, cur, spaceId, key, changed || !!existing.pendingMove);
             if (cur) {
                 let moved = false;
                 if (existing.pendingMove) {
@@ -142,7 +194,7 @@ export function createClient(cfg, opts) {
                             const space = await api(`/api/v2/spaces/${spaceId}`);
                             targetId = space.homepageId;
                             if (!targetId)
-                                throw new Error('최상위 이동 기준 홈페이지가 없습니다. CONFLUENCE_PARENT_ID를 지정하세요.');
+                                throw new Error('최상위 이동 기준 홈페이지가 없습니다. 원격 스코프를 다시 설정하세요.');
                             const target = await getPageOrNull(targetId);
                             if (!target || target.parentId || String(target.spaceId) !== spaceId)
                                 throw new Error('최상위 이동 기준 홈페이지를 확인할 수 없습니다.');
@@ -150,8 +202,16 @@ export function createClient(cfg, opts) {
                         }
                         if (targetId === existing.pageId)
                             throw new Error('페이지를 자기 자신 아래로 이동할 수 없습니다.');
+                        const priorBody = cur.body?.storage?.value;
+                        const priorTitle = cur.title;
+                        if (typeof priorBody !== 'string')
+                            throw new Error('이동 전 원격 본문을 확인할 수 없습니다.');
+                        if (parentId)
+                            await assertInScope(parentId);
                         await api(`/rest/api/content/${existing.pageId}/move/${position}/${targetId}`, { method: 'PUT' });
-                        cur = await getPageOrNull(existing.pageId);
+                        cur = await getPageOrNull(existing.pageId, true);
+                        if (cur?.body?.storage?.value !== priorBody || cur?.title !== priorTitle)
+                            throw new Error('이동 도중 원격 본문·제목이 변경되었습니다. 본문을 덮어쓰지 않습니다.');
                         if (!cur || (cur.parentId ?? undefined) !== parentId)
                             throw new Error('이동 후 부모 위치 검증에 실패했습니다. 다시 sync하세요.');
                         moved = true;
@@ -159,8 +219,13 @@ export function createClient(cfg, opts) {
                 }
                 if (!changed) {
                     delete existing.pendingMove;
+                    if (typeof cur.parentId === 'string')
+                        existing.remoteParentId = cur.parentId;
+                    if (moved && cur.version?.number)
+                        existing.remoteVersion = cur.version.number;
                     return moved ? 'moved' : 'skipped';
                 }
+                await assertInScope(existing.pageId);
                 const nextVersion = (cur.version?.number ?? 1) + 1;
                 await api(`/api/v2/pages/${existing.pageId}`, {
                     method: 'PUT',
@@ -172,11 +237,15 @@ export function createClient(cfg, opts) {
                         version: { number: nextVersion, message: `sync from git: ${key}` },
                     }),
                 });
-                mapping[key] = { pageId: existing.pageId, title, hash };
+                const remoteParentId = typeof cur.parentId === 'string' ? cur.parentId : existing.remoteParentId;
+                mapping[key] = { pageId: existing.pageId, title, hash, remoteVersion: nextVersion, ...(remoteParentId ? { remoteParentId } : {}) };
                 return 'updated';
             }
-            // cur === null: Confluence 에서 삭제됨 → 아래에서 신규 생성으로 복구
         }
+        if (opts.scope && !parentId)
+            throw new Error('스코프 안의 부모가 필요합니다.');
+        if (parentId)
+            await assertInScope(parentId);
         const body = {
             spaceId, status: 'current', title,
             body: { representation: 'storage', value: storage },
@@ -184,18 +253,13 @@ export function createClient(cfg, opts) {
         if (parentId)
             body.parentId = parentId;
         const created = await api(`/api/v2/pages`, { method: 'POST', body: JSON.stringify(body) });
-        mapping[key] = { pageId: created.id, title, hash };
-        return existing?.pageId ? 'recreated' : 'created';
+        mapping[key] = { pageId: created.id, title, hash, remoteVersion: created.version?.number ?? 1, ...(parentId ? { remoteParentId: parentId } : {}) };
+        return 'created';
     }
     // ---- pull(역방향) 전용 ----
     /** v1 GET. api() 와 달리 /rest/api 계열 + 임의 expand 응답을 그대로 돌려준다. */
     async function getV1(path) {
-        const res = await fetch(`${cfg.baseUrl}${path}`, {
-            headers: { Authorization: authHeader(), Accept: 'application/json' },
-        });
-        if (!res.ok)
-            throw new ConfluenceApiError(res.status, path, await res.text(), res.statusText);
-        return res.json();
+        return api(path);
     }
     /**
      * 콘텐츠 노드 조회. type + 제목 + export_view(HTML) + storage(원본 XHTML) + 출처 메타.
@@ -214,6 +278,7 @@ export function createClient(cfg, opts) {
             storage: data.body?.storage?.value ?? '',
             url: base && webui ? `${base}${webui}` : undefined,
             updated: data.version?.when,
+            ...(data.version?.number !== undefined ? { version: data.version.number } : {}),
         };
     }
     /** 자식 노드 목록(kind = page|folder, 전체 페이지네이션). */
@@ -223,7 +288,7 @@ export function createClient(cfg, opts) {
         while (path) {
             const data = await getV1(path);
             for (const c of data.results ?? [])
-                out.push({ id: c.id, title: c.title });
+                out.push({ id: String(c.id), title: c.title });
             const next = data._links?.next;
             path = next ? (next.startsWith('/') ? next : `/${next}`) : null;
         }
@@ -252,7 +317,7 @@ export function createClient(cfg, opts) {
         const url = downloadPath.startsWith('http') ? downloadPath : `${cfg.baseUrl}${downloadPath}`;
         const res = await fetch(url, { headers: { Authorization: authHeader() } });
         if (!res.ok)
-            throw new Error(`download ${res.status} ${res.statusText}\n${downloadPath}`);
+            throw new ConfluenceDownloadError(res.status, res.statusText, downloadPath);
         return Buffer.from(await res.arrayBuffer());
     }
     // ---- 폴더(README 없는 디렉토리 컨테이너) ----
@@ -310,6 +375,10 @@ export function createClient(cfg, opts) {
     }
     /** 폴더 생성(write:folder 필요). parentId 없으면 공간 최상위. 생성된 folder id 반환. */
     async function createFolder(spaceId, title, parentId) {
+        if (opts.scope && !parentId)
+            throw new Error('스코프 안의 부모가 필요합니다.');
+        if (parentId)
+            await assertInScope(parentId);
         const body = { spaceId, title };
         if (parentId)
             body.parentId = parentId;
@@ -319,6 +388,11 @@ export function createClient(cfg, opts) {
     /** 조회→재사용→생성. 동시 생성/검색 지연으로 충돌하면 한 번 재조회한다. */
     async function upsertFolder(spaceId, spaceKey, title, parentId, mappedId) {
         parentId = parentId?.trim() || undefined;
+        if (parentId)
+            await assertInScope(parentId);
+        if (mappedId) {
+            await assertInScope(mappedId);
+        }
         if (mappedId) {
             let folder;
             try {
@@ -339,6 +413,7 @@ export function createClient(cfg, opts) {
                 }
                 return { id: mappedId, created: false };
             }
+            throw new Error(`매핑 폴더 #${mappedId}가 없습니다. 자동 재생성하지 않습니다.`);
         }
         const found = await findFolder(spaceId, spaceKey, title, parentId);
         if (found)
@@ -357,13 +432,9 @@ export function createClient(cfg, opts) {
             throw error;
         }
     }
-    /** 폴더 삭제(--rebuild). */
-    async function deleteFolder(id) {
-        await api(`/api/v2/folders/${id}`, { method: 'DELETE' });
-    }
     return {
-        api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, upsertPage,
+        api, getContentInfo, assertInScope, getPageOrNull, getSpaceId, getSpaceInfo, uploadImages, uploadAttachments, upsertPage, checkPage,
         getNode, getChildPages, getChildFolders, listAttachments, downloadAttachment,
-        getContentOrNull, findFolder, createFolder, upsertFolder, deleteFolder,
+        getContentOrNull, findFolder, createFolder, upsertFolder,
     };
 }

package/dist/confluence/config.js

@@ -1,16 +1,20 @@
 /**
  * 환경변수(.env / 셸) 로딩과 필수값 검증.
- * dotenv 로딩은 진입점(sync.ts)에서 `import 'dotenv/config'` 로 먼저 수행된다.
+ * 작업공간 .env를 읽고 셸 환경변수를 우선 적용한다.
  */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse } from 'dotenv';
 import { red, cyan } from '../shared/colors.js';
-export function readEnv() {
+export function readEnv(base) {
+    const read = (dir) => existsSync(join(dir, '.env')) ? parse(readFileSync(join(dir, '.env'))) : {};
+    const dir = base && existsSync(join(base, '.env')) ? base : process.cwd();
+    const values = { ...read(dir), ...process.env };
     return {
-        baseUrl: process.env.CONFLUENCE_BASE_URL,
-        email: process.env.CONFLUENCE_EMAIL,
-        token: process.env.CONFLUENCE_API_TOKEN,
-        spaceKey: process.env.CONFLUENCE_SPACE_KEY,
-        // 신규 이름 우선, 없으면 구 이름(CONFLUENCE_PARENT_PAGE_ID) 하위호환
-        parentId: (process.env.CONFLUENCE_PARENT_ID ?? process.env.CONFLUENCE_PARENT_PAGE_ID)?.trim() || undefined,
+        baseUrl: values.CONFLUENCE_BASE_URL,
+        email: values.CONFLUENCE_EMAIL,
+        token: values.CONFLUENCE_API_TOKEN,
+        spaceKey: values.CONFLUENCE_SPACE_KEY,
     };
 }
 /** 동기화(생성/갱신)에 필요한 필수 환경변수 검증. 누락 시 종료. */

package/dist/confluence/env-file.js

@@ -0,0 +1,23 @@
+/** Shared dotenv import/update rules. Only connection keys are imported. */
+import { parse } from 'dotenv';
+export const connectionKeys = ['CONFLUENCE_BASE_URL', 'CONFLUENCE_EMAIL', 'CONFLUENCE_API_TOKEN', 'CONFLUENCE_SPACE_KEY'];
+// Match dotenv assignments, including quoted multiline values, without rewriting unrelated content.
+const assignments = () => /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/mg;
+export function importConnection(text) {
+    if (typeof text !== 'string' || Buffer.byteLength(text) > 12_000 || text.includes('\0'))
+        throw new Error('.env 파일은 12KB 이하 텍스트여야 합니다.');
+    const values = parse(text);
+    if (!connectionKeys.some(key => Object.hasOwn(values, key)))
+        throw new Error('Confluence 연결 환경변수가 없는 파일입니다.');
+    const env = {}, raw = {};
+    for (const match of text.matchAll(assignments()))
+        raw[match[1]] = match[2] ?? '';
+    for (const key of connectionKeys)
+        env[key] = values[key]?.trim() ?? '';
+    const content = connectionKeys.map(key => `${key}=${raw[key] ?? ''}`).join('\n') + '\n';
+    return { env, content };
+}
+export function mergeConnection(existing, content) {
+    const remaining = existing.replace(assignments(), (match, key) => connectionKeys.includes(key) ? '' : match);
+    return `${remaining.trimEnd()}${remaining.trim() ? '\n\n' : ''}${content}`;
+}

package/dist/confluence/links.js

@@ -0,0 +1,18 @@
+/** Navigation links emitted by Confluence exports are web paths, not disk paths. */
+export function isConfluenceWebPath(value) {
+    let path = value.split(/[?#]/)[0];
+    try {
+        for (let i = 0; i < 4; i++) {
+            const decoded = decodeURIComponent(path);
+            if (decoded === path)
+                break;
+            path = decoded;
+        }
+    }
+    catch {
+        return false;
+    }
+    if (/[\\\x00-\x1f\x7f]/.test(path) || path.split('/').some(part => part === '.' || part === '..'))
+        return false;
+    return path === '/wiki' || path.startsWith('/wiki/');
+}

package/dist/conversion/asset-paths.js

@@ -0,0 +1,5 @@
+import { basename, dirname, join, relative } from 'node:path';
+/** Pull and converted documents keep attachments beside their owning Markdown file. */
+export function documentAttachmentDir(file, base) {
+    return join(dirname(relative(base, file)), 'attachments', basename(file).replace(/\.md$/i, '')).split('\\').join('/');
+}

package/dist/conversion/attachments.js

@@ -1,13 +1,16 @@
+import { createDocument } from '@mixmark-io/domino';
 import { createHash } from 'node:crypto';
 import { existsSync, statSync, readFileSync } from 'node:fs';
-import { resolve, relative, dirname, basename, isAbsolute } from 'node:path';
+import { resolve, relative, dirname, basename, extname, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { documentAttachmentDir } from './asset-paths.js';
+import { isConfluenceWebPath } from '../confluence/links.js';
 import { mapMarkdownText } from './pdf-pages.js';
 /** 출력 트리의 경로와 실제 입력 파일을 연결한다. dry-run에서도 파일 복사 없이 사용한다. */
 export function attachmentMapper(file, base) {
     const copies = new Map(); // base 상대 출력 경로 → 입력 절대경로
     function localPath(raw) {
-        if (!raw || raw.startsWith('#') || raw.startsWith('//'))
+        if (!raw || raw.startsWith('#') || raw.startsWith('//') || isConfluenceWebPath(raw))
             return null;
         if (/^file:/i.test(raw))
             return fileURLToPath(raw);
@@ -30,15 +33,33 @@ export function attachmentMapper(file, base) {
         // 일반 외부 URL 및 없는 링크는 그대로 남긴다.
         if (!existsSync(abs) || !statSync(abs).isFile())
             return null;
-        let rel = relative(base, abs).split('\\').join('/');
-        if (!rel.startsWith('attachments/')) {
+        const folder = documentAttachmentDir(file, base), name = basename(abs);
+        let rel = `${folder}/${name}`;
+        const previous = copies.get(rel) ?? resolve(base, rel);
+        if (previous !== abs && existsSync(previous) && statSync(previous).isFile() && !readFileSync(previous).equals(readFileSync(abs))) {
             const hash = createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 24);
-            rel = `attachments/files/${hash}/${basename(abs)}`;
+            const extension = extname(name);
+            rel = `${folder}/${basename(name, extension)}-${hash}${extension}`;
         }
         copies.set(rel, abs);
         const target = wiki ? rel : relative(dirname(file), resolve(base, rel)).split('\\').join('/');
         return target + fragment;
     }
+    function rewriteHtml(part) {
+        return part.replace(/<!--[\s\S]*?-->|<(script|style|pre|code)\b[^>]*>[\s\S]*?<\/\1\s*>|<(img|a)\b(?:[^"'<>]|"[^"]*"|'[^']*')*>/gi, (tag, excluded, type) => {
+            if (!type)
+                return tag;
+            const attribute = type.toLowerCase() === 'img' ? 'src' : 'href';
+            const raw = createDocument(tag).querySelector(type)?.getAttribute(attribute);
+            if (!raw)
+                return tag;
+            const target = relocate(raw);
+            if (target === null)
+                return tag;
+            const value = target.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+            return tag.replace(new RegExp(`(\\s${attribute}\\s*=\\s*)("[^"]*"|'[^']*'|[^\\s>]+)`, 'i'), (_all, prefix) => `${prefix}"${value}"`);
+        });
+    }
     function rewrite(text) {
         return mapMarkdownText(text, part => {
             const md = part.replace(/(?<!!)(!?)\[([^\]\n]*)\]\((<[^>\n]+>|[^()\s]+)\)/g, (all, bang, label, raw, offset) => {
@@ -47,13 +68,14 @@ export function attachmentMapper(file, base) {
                 const dest = relocate(raw.replace(/^<(.*)>$/, '$1'));
                 return dest === null ? all : `${bang}[${label}](<${dest.replace(/</g, '%3C').replace(/>/g, '%3E')}>)`;
             });
-            return md.replace(/(!?)\[\[([^\]|\n]+)(?:\|([^\]\n]*))?\]\]/g, (all, bang, target, label, offset) => {
+            const wiki = md.replace(/(!?)\[\[([^\]|\n]+)(?:\|([^\]\n]*))?\]\]/g, (all, bang, target, label, offset) => {
                 if ((md.slice(0, offset).match(/\\+$/)?.[0].length ?? 0) % 2)
                     return all;
                 const dest = relocate(target, true);
                 return dest === null ? all : `${bang}[[${dest}${label === undefined ? '' : '|' + label}]]`;
             });
-        });
+            return rewriteHtml(wiki);
+        }, rewriteHtml);
     }
     return { copies, rewrite, source: (abs) => copies.get(relative(base, abs).split('\\').join('/')) ?? abs };
 }

package/dist/conversion/convert.js

@@ -9,14 +9,15 @@
  * 스페이스를 통째로 다시 받지 않고도 최신 변환 품질을 얻기 위한 것이다.
  * 링크는 대상이 트리 안에 실제로 있을 때만 바꾼다(외부 URL·이미지·깨진 링크는 손대지 않는다).
  */
+import { prepareMarkdown } from './markdown.js';
 import { attachmentMapper } from './attachments.js';
 import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, copyFileSync, realpathSync } from 'node:fs';
 import { resolve, relative, dirname, basename, join, isAbsolute } from 'node:path';
-import { collectMarkdown, collectAssets, buildVault, vaultResolver } from '../documents/catalog.js';
-import { linksToWikilinks, resolveWikilinks, splitFrontmatter } from '../documents/obsidian.js';
+import { collectMarkdown, collectAssets, buildVault } from '../documents/catalog.js';
+import { linksToWikilinks, splitFrontmatter } from '../documents/obsidian.js';
 import { buildAnchorIndex } from '../documents/anchors.js';
-import { footnotesToLinks, linksToFootnotes } from './footnotes.js';
-import { extractPdfPages, restorePdfReferences, mapMarkdownText } from './pdf-pages.js';
+import { linksToFootnotes } from './footnotes.js';
+import { restorePdfReferences } from './pdf-pages.js';
 import { repairMarkdown, totalFixes } from './repair.js';
 import { bold, cyan, dim, gray, green, red, yellow } from '../shared/colors.js';
 function optVal(argv, name) {
@@ -248,29 +249,16 @@ export async function runConvert(argv) {
             text = toObsidian(text, abs, baseDir, nameCount, headingOf, (s) => selfIdx.get(s.toLowerCase()), attachments.source);
         }
         else if (to === 'markdown') {
-            const lookup = vaultResolver(rel, vault);
-            // 명시된 첨부 경로를 먼저 출력 트리로 옮긴 뒤 wiki 이름을 해석한다.
-            text = attachments.rewrite(text);
-            text = resolveWikilinks(text, (target, embed) => {
-                const imported = resolve(baseDir, target);
-                if (attachments.copies.has(posix(relative(baseDir, imported)))) {
-                    return posix(relative(dirname(abs), imported));
-                }
-                return lookup(target, embed);
-            });
-            text = footnotesToLinks(attachments.rewrite(text));
-            mapMarkdownText(text, part => {
-                if (/\[\[[^\]\n]*\.pdf#page=[^\]\n]*\]\]/i.test(part)) {
-                    throw new Error(`PDF 위키링크를 해석하지 못했습니다 (${rel}). --base에 PDF가 포함되는지 확인하세요.`);
-                }
-                return part;
-            });
-            const pdf = await extractPdfPages(text, abs, baseDir, outDir ?? baseDir, dryRun, attachments.source);
+            const pdf = await prepareMarkdown(text, abs, baseDir, vault, outDir ?? baseDir, dryRun, attachments);
             pdf.assets.forEach(a => sourceAssets.add(a));
             text = pdf.text;
             if (pdf.pages)
                 notes.push(dim(`PDF ${pdf.pages}쪽 이미지`));
         }
+        else if (outDir) {
+            // Repair-only exports use the same attachment layout without changing document link syntax.
+            text = attachments.rewrite(text);
+        }
         // 제자리 변환이면 바뀐 것만 쓰지만, --out 이면 대상 전부를 내보낸다(온전한 트리가 나와야 하므로)
         if (!outDir && text === before)
             continue;