@wonseok-han/confluence-sync 1.7.0 → 1.8.0

package/README.md

@@ -199,6 +199,7 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 - `mermaid` 코드블록 뒤에는 **Mermaid diagram** 매크로를 자동 삽입합니다. Confluence에 [Atlassian Labs Mermaid Diagrams Viewer](https://marketplace.atlassian.com/apps/1232887/mermaid-diagrams-viewer)가 설치되어 있어야 하며, 원본 코드도 함께 표시됩니다. 자동 연결은 등장 순서를 사용하므로 페이지의 모든 Mermaid 코드는 `mermaid` 코드블록으로 작성하세요.
 - **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
 - **섹션 링크** `[§1 개요](#1-개요)` · `[§6](./04-구현체.md#6-zkp)` · `[[문서#헤딩 텍스트]]` → Confluence 앵커 링크. [아래 참조](#섹션-링크-앵커)
+- **일반 파일 링크** `[자료](<attachments/자료.pdf>)` → PDF·TXT·MMD·JSON 등 실제 로컬 파일을 페이지 첨부로 업로드하고 다운로드 링크로 변환합니다. 경로는 Markdown 문서 위치 기준이며, 한글·공백 경로와 반복 링크를 지원합니다. 문서 링크(`.md`)·외부 URL·없는 파일은 기존 링크를 유지합니다. 같은 페이지에서 서로 다른 파일의 파일명이 같으면 업로드 이름에 경로 기반 접미사를 붙여 구분합니다.
 - **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
 - **YAML frontmatter** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
 
@@ -250,7 +251,7 @@ pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니
 
 ### 변경 감지와 매핑
 
-- 문서의 `제목 + 본문 + 참조 이미지 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
+- 문서의 `제목 + 본문 + 참조 첨부 내용` 해시를 저장해두고, **바뀐 문서만** 새 버전으로 올립니다(`= 변경없음` 은 API 호출조차 하지 않음). `--force` 로 무시할 수 있습니다.
 - 매핑은 **`<base>/.confluence-sync.json`** 에 저장됩니다. **문서셋과 함께 커밋하세요** — 지우면 다음 실행에서 페이지가 중복 생성됩니다. (`--mapping <path>` 로 위치 변경 가능)
 - **pull 도 같은 매핑에 기록합니다** — 그래서 pull 직후 push 하면 `= 변경없음` 입니다. [Pull → 매핑 기록](#매핑-기록) 참고.
 - Confluence 에서 페이지가 삭제됐다면 자동으로 **재생성**하고, 그 페이지를 가리키던 문서들도 **링크를 다시 연결**합니다. 내용이 그대로라 스킵되는 경우까지 잡으려면 `--verify` 를 씁니다.

package/dist/confluence/client.js

@@ -70,54 +70,61 @@ export function createClient(cfg, opts) {
     }
     /** 페이지의 기존 첨부 중 같은 파일명의 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);
+            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;
     }
+    const uploadImages = uploadAttachments;
     /** 페이지 생성/갱신. 삭제 감지 시 재생성. 변경 없으면(opts.verify 아니면) 호출 없이 skip. */
     async function upsertPage(mapping, spaceId, key, title, storage, hash, parentId, forceUpdate = false) {
         const existing = mapping[key];
@@ -362,7 +369,7 @@ export function createClient(cfg, opts) {
         await api(`/api/v2/folders/${id}`, { method: 'DELETE' });
     }
     return {
-        api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, upsertPage,
+        api, getPageOrNull, getSpaceId, getSpaceInfo, deleteAll, uploadImages, uploadAttachments, upsertPage,
         getNode, getChildPages, getChildFolders, listAttachments, downloadAttachment,
         getContentOrNull, findFolder, createFolder, upsertFolder, deleteFolder,
     };

package/dist/documents/markdown.js

@@ -5,8 +5,8 @@
  * - 로컬 이미지 → 첨부 참조(ri:attachment), 외부 URL 이미지는 그대로
  * 모든 경로는 baseDir 기준 상대경로로 해석한다.
  */
-import { readFileSync, existsSync } from 'node:fs';
-import { resolve, relative, dirname, basename } from 'node:path';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, relative, dirname, basename, extname } from 'node:path';
 import { createHash } from 'node:crypto';
 import MarkdownIt from 'markdown-it';
 import { resolveWikilinks } from './obsidian.js';
@@ -27,7 +27,7 @@ const md = new MarkdownIt({ html: true, linkify: true, breaks: false });
 const emptyCtx = () => ({
     fileDir: '', titleIndex: {}, anchorIndex: {}, selfRel: '', selfTitle: '',
     anchorNames: new Set(), bodySlugs: [], headingSeq: 0, mermaidSeq: 0, anchorsPlaced: 0,
-    images: [], internalLinks: 0, anchorLinks: 0, deadAnchors: [], linkStack: [], linkedTitles: new Set(),
+    images: [], attachments: [], internalLinks: 0, anchorLinks: 0, deadAnchors: [], linkStack: [], linkedTitles: new Set(),
 });
 // 렌더 규칙은 md 인스턴스에 한 번만 등록되므로, 현재 변환 컨텍스트를 모듈 변수로 공유한다.
 let ctx = emptyCtx();
@@ -91,6 +91,23 @@ md.renderer.rules.fence = (tokens, idx) => {
     const code = `<ac:structured-macro ac:name="code">${langParam}<ac:plain-text-body><![CDATA[${safe}]]></ac:plain-text-body></ac:structured-macro>\n`;
     return code + (lang === 'mermaid' ? mermaidMacro(ctx.selfRel, ctx.mermaidSeq++) : '');
 };
+/** 페이지 첨부 이름은 유일해야 한다. 동일 경로는 한 번만 업로드한다. */
+function addAttachment(abs) {
+    const existing = ctx.attachments.find(a => a.abs === abs);
+    if (existing)
+        return existing.filename;
+    let filename = basename(abs);
+    if (ctx.attachments.some(a => a.filename === filename)) {
+        const ext = extname(filename), stem = basename(filename, ext);
+        const suffix = hashOf(relative(baseDir, abs).split('\\').join('/')).slice(0, 12);
+        filename = `${stem}-${suffix}${ext}`;
+        let n = 1;
+        while (ctx.attachments.some(a => a.filename === filename))
+            filename = `${stem}-${suffix}-${n++}${ext}`;
+    }
+    ctx.attachments.push({ filename, abs });
+    return filename;
+}
 md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
     const originalHref = tokens[idx].attrGet('href') || '';
     const href = ctx.rewriteHref?.(originalHref) ?? originalHref;
@@ -109,6 +126,17 @@ md.renderer.rules.link_open = (tokens, idx, opts, _env, self) => {
         const page = t.title ? `<ri:page ri:content-title="${escapeXml(t.title)}" />` : '';
         return `<ac:link${anchor}>${page}<ac:link-body>`;
     }
+    // 일반 로컬 파일 링크도 첨부로 전환한다. 문서·외부 URL·없는 대상은 유지한다.
+    const path = href.split('#')[0];
+    if (path && !/^[a-z][a-z\d+.-]*:|^\/\//i.test(path) && !/\.md$/i.test(decodePath(path))) {
+        const abs = resolve(baseDir, ctx.fileDir, decodePath(path));
+        if (existsSync(abs) && statSync(abs).isFile()) {
+            const filename = addAttachment(abs);
+            ctx.linkStack.push(true);
+            const fragment = href.includes('#') ? ` ac:anchor="${escapeXml(decodePath(href.slice(href.indexOf('#') + 1)))}"` : '';
+            return `<ac:link${fragment}><ri:attachment ri:filename="${escapeXml(filename)}" /><ac:link-body>`;
+        }
+    }
     ctx.linkStack.push(false);
     return self.renderToken(tokens, idx, opts);
 };
@@ -128,7 +156,7 @@ md.renderer.rules.image = (tokens, idx) => {
     }
     // markdown-it 이 링크 경로를 퍼센트 인코딩하므로 디코드해서 실제 파일명/경로로 복원(한글·공백 대응)
     const abs = resolve(baseDir, ctx.fileDir, decodePath(src.split('#')[0]));
-    const filename = basename(abs);
+    const filename = addAttachment(abs);
     ctx.images.push({ filename, abs });
     return `<ac:image${widthAttr}><ri:attachment ri:filename="${escapeXml(filename)}" /></ac:image>`;
 };
@@ -163,6 +191,7 @@ export function toStorage(markdown, rel, titleIndex, base, opts = {}) {
     return {
         storage,
         images: ctx.images,
+        attachments: ctx.attachments,
         internalLinks: ctx.internalLinks,
         anchorLinks: ctx.anchorLinks,
         anchorsPlaced: ctx.anchorsPlaced,
@@ -171,13 +200,13 @@ export function toStorage(markdown, rel, titleIndex, base, opts = {}) {
     };
 }
 /**
- * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 이미지의 내용 해시.
- * 이미지 내용을 포함하므로, 같은 파일명으로 이미지만 교체해도 해시가 바뀌어 재동기화 대상이 된다.
- * 이미지가 없으면 hashOf(title + '\0' + storage) 와 동일(이미지 없는 문서는 기존 해시 유지).
+ * 변경 감지용 문서 해시: 제목 + storage + 참조 로컬 첨부의 내용 해시.
+ * 첨부 내용을 포함하므로, 같은 파일명으로 파일만 교체해도 해시가 바뀌어 재동기화 대상이 된다.
+ * 첨부가 없으면 hashOf(title + '\0' + storage) 와 동일(첨부 없는 문서는 기존 해시 유지).
  */
 export function docHash(title, r) {
     const parts = [title, r.storage];
-    for (const img of r.images) {
+    for (const img of r.attachments) {
         let digest = 'missing';
         try {
             if (existsSync(img.abs))

package/dist/sync/push.js

@@ -145,7 +145,7 @@ export async function runPush(argv) {
             const pk = parentKeyOf(rel, folderIndex);
             const anchorNote = r.anchorLinks || r.anchorsPlaced
                 ? `, 섹션링크: ${r.anchorLinks}, 앵커: ${r.anchorsPlaced}` : '';
-            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}${anchorNote}, 이미지: ${r.images.length})`)}`);
+            console.log(`  [${status}] ${rel}  ${dim('→')}  ${cyan(`"${title}"`)}  ${dim(`(부모: ${pk ?? 'ROOT'}, 내부링크: ${r.internalLinks}${anchorNote}, 이미지: ${r.images.length}, 첨부: ${r.attachments.length})`)}`);
             if (r.deadAnchors.length) {
                 console.error(yellow(`    ⚠ 대응 헤딩 없는 앵커 ${r.deadAnchors.length}개: `) + dim(r.deadAnchors.slice(0, 3).join(' ')));
             }
@@ -263,8 +263,12 @@ export async function runPush(argv) {
                 moved++;
                 continue;
             }
-            const imgOk = await client.uploadImages(work[rel].pageId, r.images, BASE_DIR);
-            const imgNote = r.images.length ? `, 이미지 ${imgOk}/${r.images.length}` : '';
+            const imgOk = await client.uploadAttachments(work[rel].pageId, r.attachments, BASE_DIR);
+            const imgNote = r.attachments.length ? `, 첨부 ${imgOk}/${r.attachments.length}` : '';
+            if (imgOk !== r.attachments.length) {
+                delete work[rel].hash; // 부분 실패는 다음 동기화에서 재시도한다.
+                saveMapping(MAPPING_PATH, work);
+            }
             const label = result === 'created' ? green('＋ 생성')
                 : result === 'recreated' ? magenta('♻ 재생성(삭제 복구)')
                     : yellow('↻ 갱신');
@@ -296,7 +300,11 @@ export async function runPush(argv) {
             try {
                 await client.upsertPage(work, spaceId, rel, r.title, r.storage, r.hash, r.parentId, true);
                 saveMapping(MAPPING_PATH, work);
-                await client.uploadImages(work[rel].pageId, r.images, BASE_DIR);
+                const uploaded = await client.uploadAttachments(work[rel].pageId, r.attachments, BASE_DIR);
+                if (uploaded !== r.attachments.length) {
+                    delete work[rel].hash;
+                    saveMapping(MAPPING_PATH, work);
+                }
                 console.log(`  ${cyan('🔗 링크 재연결')}  ${rel}  ${dim('→')}  ${cyan(`"${r.title}"`)}`);
                 relinked++;
             }

package/dist/web/sync.js

@@ -148,7 +148,7 @@ export function createWebSync(runner = runSyncCLI) {
         let reportedFailure = false;
         const secrets = [prepared.env.CONFLUENCE_API_TOKEN, Buffer.from(`${prepared.env.CONFLUENCE_EMAIL}:${prepared.env.CONFLUENCE_API_TOKEN}`).toString('base64')].filter(Boolean);
         const log = (text) => {
-            if (text.includes('✗') || text.includes('⚠ 이미지 없음'))
+            if (text.includes('✗') || text.includes('⚠ 이미지 없음') || text.includes('⚠ 첨부 없음'))
                 reportedFailure = true; // CLI reports per-document / attachment failures without exiting.
             for (const secret of secrets)
                 text = text.split(secret).join('[비공개]');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wonseok-han/confluence-sync",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "description": "Confluence Cloud ↔ Markdown 양방향 동기화 CLI — 마크다운을 Confluence 페이지로 발행(push)하고, Confluence 페이지·폴더·스페이스를 마크다운으로 가져옵니다(pull).",
   "keywords": [