@wonseok-han/confluence-sync 1.0.0 → 1.2.0

package/README.md

@@ -5,7 +5,9 @@
 - **push** — 로컬 `.md` 디렉토리를 Confluence 페이지 트리로 발행. 폴더 구조가 그대로 페이지 계층이 됩니다.
 - **pull** — Confluence 페이지·폴더·**스페이스 전체**를 읽어 `.md` 로 가져옵니다.
 
-문서를 git으로 관리하면서(docs-as-code) Confluence를 미러로 두거나, 반대로 Confluence에 쌓인 문서를 마크다운으로 내려받아 쓸 수 있습니다. 내려받은 마크다운은 Obsidian·VS Code 등 어디서든 그대로 열립니다.
+문서를 git으로 관리하면서(docs-as-code) Confluence를 미러로 두거나, 반대로 Confluence에 쌓인 문서를 마크다운으로 내려받아 쓸 수 있습니다.
+
+**[Obsidian](#obsidian) vault 와 그대로 맞물립니다** — pull 한 문서는 내부 링크가 이어져 그래프 뷰가 동작하고, vault 에서 쓴 `[[wikilink]]`·`![[embed]]`·frontmatter 를 push 가 그대로 이해합니다.
 
 ---
 
@@ -20,6 +22,8 @@ confluence-sync --help
 
 공개 npm 패키지라 **토큰이나 `.npmrc` 설정이 필요 없습니다.** (Node 20+)
 
+> 짧은 이름 **`csync`** 도 같이 설치됩니다 — 아래 예시의 `confluence-sync` 는 전부 `csync` 로 바꿔 쓸 수 있습니다.
+
 ## 빠른 시작
 
 ```bash
@@ -122,10 +126,38 @@ docs/                      → [CONFLUENCE_PARENT_ID 또는 공간 최상위]
 
 ### 변환 규칙
 
-- 각 문서의 **첫 `# 제목`** 이 페이지 제목이 되고, 본문은 storage format 으로 변환됩니다.
+- 페이지 제목은 **frontmatter `title` → 첫 `# 제목` → 파일명** 순으로 정해지고, 본문은 storage format 으로 변환됩니다.
 - 코드블록 → **code 매크로**, 표·리스트·헤딩은 그대로.
-- **내부 `.md` 링크** → Confluence 페이지 링크로 자동 변환.
-- **로컬 이미지** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
+- **내부 `.md` 링크**와 **`[[wikilink]]`** → Confluence 페이지 링크로 자동 변환.
+- **섹션 링크** `[§1 개요](#1-개요)` · `[§6](./04-구현체.md#6-zkp)` · `[[문서#헤딩 텍스트]]` → Confluence 앵커 링크. [아래 참조](#섹션-링크-앵커)
+- **로컬 이미지**와 **`![[embed]]`** → 페이지 첨부로 업로드 후 참조 (같은 파일명은 새 버전으로 갱신). 외부 URL 이미지는 그대로.
+- **YAML frontmatter** 는 메타데이터로만 쓰이고 본문에 새지 않습니다.
+
+### 섹션 링크 (앵커)
+
+문서는 표준 마크다운 그대로 두면 됩니다. 이 도구가 Confluence 쪽 앵커를 만들어 맞춰 줍니다.
+
+**Confluence 가 헤딩에 자동으로 붙이는 id 에는 기대지 않습니다.** 그 규칙은 Cloud 와 Data Center 가 다르고(Cloud 는 공백만 하이픈으로 바꾸고, DC 는 `페이지제목-헤딩` 형태) 예고 없이 바뀌기 때문입니다. 대신 **링크 대상이 되는 헤딩 앞에 [Anchor 매크로](https://confluence.atlassian.com/doc/anchors-139442.html)로 이름(= 마크다운 슬러그)을 직접 심고** 링크가 그 이름을 가리키게 합니다 — 양쪽 다 이 도구가 정한 값이라 어느 배포판에서도 맞습니다. 실제로 가리켜지는 헤딩에만 심으므로 페이지가 지저분해지지 않습니다.
+
+| 쓰는 것 | Confluence 에서 |
+| --- | --- |
+| `[§1 개요](#1-개요)` | 같은 페이지의 그 헤딩으로 이동 |
+| `[§6 ZKP](./04-구현체.md#6-zkp)` | 그 페이지의 그 헤딩으로 이동 |
+| `[[04-구현체#6. ZKP]]` | 위와 동일 (Obsidian 표기) |
+
+- 슬러그 규칙은 **GitHub 과 동일**합니다 — 소문자화 → 문자·숫자 아닌 것 제거 → 공백 하나당 하이픈 하나. 공백을 접지 않으므로 `제목  ·  블록` 의 `--` 도 그대로 맞습니다. 겹치는 헤딩에는 `-1`·`-2` 가 붙습니다.
+- 문서의 첫 `# H1` 을 가리키는 링크는 **페이지 최상단**이 됩니다 (H1 은 Confluence 페이지 제목이 되므로).
+- **대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 경고합니다.** 엉뚱한 섹션으로 보내는 대신 알려주는 쪽을 택했습니다 — 대개 오타나 깨진 상대경로입니다.
+
+```
+$ confluence-sync --base ./docs --dry-run
+  [변경] core-tech/03-standards.md  →  "표준 참조"  (…, 내부링크: 36, 섹션링크: 30, 앵커: 15, 이미지: 0)
+  ⚠ 대응 헤딩 없는 앵커  poc/02-zkp/legacy/README.md  #부록-a-개념-다리
+```
+
+`섹션링크` 는 이 문서가 **가리키는** 링크 수, `앵커` 는 이 문서에 **심긴** 앵커 수입니다(다른 문서가 가리키는 것 포함).
+
+pull 은 반대로 Confluence 앵커를 마크다운 슬러그로 되돌립니다(`--obsidian` 이면 `[[문서#헤딩 텍스트]]`).
 
 ### 변경 감지와 매핑
 
@@ -162,15 +194,115 @@ confluence-sync pull <pageId|url>                  # 한 페이지를 현재 폴
 confluence-sync pull <url> --out ./docs            # 출력 디렉토리 지정
 confluence-sync pull <url> --out ./docs --children # 하위 페이지·폴더까지 트리로 복원
 confluence-sync pull --space --out ./docs          # 스페이스 전체 (홈페이지부터 전부)
+confluence-sync pull --space --obsidian --out ~/MyVault   # 내부 링크를 [[wikilink]] 로
 ```
 
 - 대상은 **숫자 ID** 또는 **URL** (`.../pages/<ID>/...` 페이지, `.../folder/<ID>` 폴더) 둘 다 됩니다.
 - **`--children`** — 하위를 재귀 복원합니다. 자식이 있는 페이지는 `<제목>/README.md` 폴더로 펼쳐져 **push 계층 관례와 맞물립니다**.
 - **`--space`** — 대상 없이 스페이스 전체를 가져옵니다. 페이지가 많으면 시간이 걸립니다.
 - **이미지/첨부** 는 문서별로 `attachments/<문서명>/` 아래에 내려받고 링크를 그 경로로 씁니다 (문서 폴더가 이미지로 지저분해지지 않음). 다운로드에는 `read:attachment` 스코프가 필요합니다.
+- **내부 링크** 는 같은 실행에서 함께 받은 페이지끼리 **상대 `.md` 링크로 이어집니다.** 받지 않은 페이지는 절대 URL 로 남습니다(깨진 링크를 만들지 않음).
+- **섹션 링크** 는 Confluence 앵커(`#페이지제목헤딩텍스트`)를 그 문서의 **마크다운 슬러그로 되돌립니다** — 그대로 두면 Obsidian·GitHub 어디서도 걸리지 않기 때문입니다. `--obsidian` 이면 `[[문서#헤딩 텍스트]]` 로 씁니다.
+- 각 문서 머리에 **frontmatter** 가 붙습니다 — `title` · `pageId` · `spaceKey` · `source` · `updated`. `pageId` 가 다시 push 할 때의 앵커입니다.
+- 제목은 frontmatter 의 `title` 로만 들어가고 **본문에 `# 제목` 을 따로 넣지 않습니다** — 제목을 별도로 표시하는 뷰어(Obsidian 등)에서 두 번 보이기 때문입니다. push 는 `title` 을 먼저 읽으므로 왕복에 문제가 없습니다.
 - 본문은 `export_view`(HTML)를 [turndown](https://github.com/mixmark-io/turndown) 으로 변환합니다 — 코드블록(언어 포함, 미지정은 `plaintext`), GFM 표, 리스트 등.
 
-> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다. 내부 페이지 링크는 절대 URL로 유지됩니다.
+> **무손실 왕복은 아닙니다.** Confluence storage → Markdown 은 근사 변환이라 일부 매크로·레이아웃은 단순화됩니다.
+
+---
+
+## Obsidian
+
+pull 이 만드는 마크다운은 **vault 에 그대로 열립니다.** 별도 플러그인이 필요 없습니다.
+
+```bash
+cd ~/MyVault
+confluence-sync pull --space --out .              # 스페이스 전체를 vault 로
+confluence-sync pull --space --out . --obsidian   # 내부 링크를 [[wikilink]] 로
+```
+
+- 내부 링크가 이어져 있어 **그래프 뷰·백링크가 그대로 동작**합니다. 기본값인 상대 `.md` 링크도 Obsidian 에서 정상 동작하며 GitHub·VS Code 에서도 열립니다. vault 안에서만 쓸 거라면 `--obsidian` 으로 `[[wikilink]]` 를 받으세요.
+- frontmatter 는 Obsidian 속성 패널에 표시되고, `source` 로 원본 페이지를 바로 열 수 있습니다.
+
+---
+
+## `convert` — 이미 받아둔 문서 손보기
+
+**다시 pull 하지 않고** 로컬 `.md` 트리를 제자리에서 고칩니다. Confluence 를 호출하지 않으니 인증도 필요 없습니다.
+
+```bash
+confluence-sync convert --to obsidian ./docs            # 상대 .md 링크 → [[wikilink]]
+confluence-sync convert --to markdown ./docs            # 되돌리기
+confluence-sync convert --fix ./docs                    # 옛 pull 결과 보정
+confluence-sync convert --to obsidian --fix ./docs      # 둘 다
+confluence-sync convert --fix ./docs --dry-run          # 바뀔 파일만 미리보기
+```
+
+### 대상 지정
+
+파일·폴더를 **여러 개** 줄 수 있고, 안 주면 base 전체가 대상입니다.
+
+```bash
+confluence-sync convert --fix ./docs/가이드/설치.md          # 파일 하나만
+confluence-sync convert --fix ./docs/a.md ./docs/나머지/     # 파일 + 폴더 혼합
+```
+
+`--base` 는 **링크를 해석하는 범위**입니다. 파일 하나만 고칠 때도 주변 문서를 알아야 이름이 유일한지, 링크 대상이 실재하는지 판정할 수 있기 때문입니다. 지정하지 않으면 준 경로들의 공통 상위 폴더가 되며, `--to` 로 링크를 바꿀 때는 **문서 트리 루트를 `--base` 로 알려주는 편이 정확합니다.**
+
+```bash
+confluence-sync convert --to obsidian ./docs/가이드/설치.md --base ./docs
+```
+
+### 다른 곳에 내보내기 — `--out`
+
+`--out` 없이 실행하면 **원본을 덮어씁니다.** 원본을 그대로 두고 결과만 따로 받으려면:
+
+```bash
+confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault
+```
+
+- base 기준 상대 경로를 그대로 재현하고, **본문이 참조하는 첨부(이미지)도 같이 복사**합니다 — 안 그러면 링크가 깨집니다.
+- 안 바뀐 문서도 함께 내보내 **온전한 트리**가 나옵니다.
+- `--out` 이 base 안이면 원본을 오염시키므로 거부합니다.
+
+### 링크 표기 (`--to`)
+
+두 방향은 서로의 역변환이라 **왕복해도 내용이 보존됩니다.** 안전하게 바꿀 수 있는 링크만 건드립니다.
+
+- 외부 URL·이미지·깨진 링크(대상 파일 없음)는 **그대로 둡니다.**
+- 파일명이 트리 안에서 겹치면(`README.md` 여러 개 등) `[[wikilink]]` 로 바꾸지 않고 상대 링크를 유지합니다 — 이름만으로는 어느 노트인지 확정할 수 없기 때문입니다.
+- 코드블록·인라인 코드 안의 링크는 손대지 않습니다.
+- **섹션 링크는 표기가 다릅니다** — 표준 마크다운은 슬러그(`문서.md#6-zkp`), Obsidian 은 헤딩 텍스트(`[[문서#6. ZKP]]`)를 씁니다. 대상 문서의 헤딩을 찾아 옮기고, 못 찾으면 섹션 없이 문서 링크로 둡니다. Obsidian 블록 참조(`#^id`)는 마크다운에 대응물이 없어 같은 방식으로 처리합니다.
+
+### 보정 (`--fix`)
+
+변환기가 개선되기 전에 pull 한 문서에는 옛 결함의 흔적이 남아 있습니다. 스페이스를 통째로 다시 받지 않고 그 흔적만 되돌립니다.
+
+| 증상 | 보정 |
+| --- | --- |
+| frontmatter `title` 과 본문 `# 제목` 이 중복 | 겹치는 H1 제거 (Obsidian 에서 제목이 두 번 보임) |
+| 모든 코드블록이 ` ```java ` | 실제 Java 가 아니면 `plaintext` 로 (Confluence 가 언어 미지정 시 `brush: java` 를 붙이는 탓) |
+| 제목에 `[data-colorid=…]{color:#…}` | 본문에 새어 나온 CSS 제거 |
+| `:11\_eleven\_blue:` · `\[선택 가능\]` · `**7️⃣**\-**1️⃣**` | 불필요한 `\` 이스케이프 해제 |
+| 리스트 항목마다 빈 줄 | 같은 종류 항목끼리 붙임 (번호↔글머리 경계는 유지) |
+| 코드블록 안 줄 끝 공백 | 정리 |
+
+**멱등적입니다** — 두 번 돌려도 더 바뀌지 않고, 최신 pull 결과에는 아무것도 하지 않습니다. 애매하면 손대지 않는 쪽을 택하므로 진짜 Java 코드블록은 그대로 남습니다. 파일을 덮어쓰니 `--dry-run` 으로 먼저 확인하세요.
+
+반대로 **vault 를 그대로 push** 할 수 있습니다. Obsidian 문법을 그대로 이해합니다.
+
+| vault 에서 쓴 것 | Confluence 에 올라가는 것 |
+| --- | --- |
+| `[[설계]]` · `[[구조/설계\|설계 문서]]` | 페이지 링크 (짧은 이름·경로 모두 인식) |
+| `![[diagram.png]]` | 첨부 이미지 |
+| frontmatter `title:` | 페이지 제목 |
+| frontmatter `pageId:` | **그 페이지를 갱신** (새로 만들지 않음) |
+
+- 코드블록·인라인 코드 안의 `[[...]]` 는 건드리지 않고, **대상을 못 찾은 링크는 원문 그대로** 둡니다(조용히 사라지지 않습니다).
+- `.obsidian/` `.trash/` 등 숨김 폴더는 동기화 대상에서 제외됩니다.
+- `pageId` 덕분에 매핑 파일(`.confluence-sync.json`)을 잃어버려도 **중복 페이지가 생기지 않습니다** — 원본을 찾아가 갱신합니다(`[연결]` 로 표시).
+
+> pull → 편집 → push 왕복이 목적이라면 frontmatter 를 지우지 마세요. `pageId` 가 원본 페이지를 가리키는 유일한 단서입니다.
 
 ---
 
@@ -202,7 +334,7 @@ git push && git push --tags
 
 워크플로는 `package.json` 버전과 태그가 일치하는지 검증한 뒤 배포합니다. 변경 이력은 [CHANGELOG.md](CHANGELOG.md) 를 참고하세요.
 
-> 사전 설정: npm Automation 토큰을 저장소 **Settings → Secrets and variables → Actions** 에 `NPM_TOKEN` 으로 등록해야 합니다.
+> npm 발행은 **Trusted Publishing(OIDC)** 을 씁니다 — 장기 토큰 없이 GitHub Actions 가 단기 자격증명으로 배포합니다.
 
 ## 라이선스
 

package/dist/anchors.js

@@ -0,0 +1,157 @@
+/**
+ * 헤딩 앵커 — 마크다운과 Confluence 의 서로 다른 "섹션 가리키기" 표기를 잇는다.
+ *
+ *   마크다운(GitHub·Obsidian·VS Code)   [§1](#1-신뢰--trust-registry----블록-01)   ← 슬러그
+ *   Obsidian wikilink                   [[문서#1. 신뢰 — Trust Registry  ·  블록 01]]  ← 헤딩 텍스트
+ *
+ * **Confluence 가 헤딩에 자동으로 붙이는 id 에는 기대지 않는다.** 그 규칙은 Cloud 와 Data Center 가
+ * 서로 다르고(‑ Cloud 는 공백만 하이픈으로 바꾸고, DC 는 `페이지제목-헤딩` 형태다) 예고 없이 바뀐다.
+ * 대신 링크 대상이 되는 헤딩 앞에 **Anchor 매크로로 이름을 직접 심고**, 링크는 그 이름을 가리킨다.
+ * 이름은 마크다운 슬러그를 그대로 쓰므로 왕복도 정확해진다 — 양쪽 다 우리가 정한 값이다.
+ */
+const FENCE = /^\s*(?:```|~~~)/;
+/** 인라인 마크다운 표기를 벗긴다 — 슬러그는 렌더된 텍스트 기준이다. */
+function plainText(s) {
+    return s
+        .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // [label](url) → label
+        .replace(/\[\[([^\]|#]+)(?:#[^\]|]+)?(?:\|([^\]]+))?\]\]/g, (_m, t, a) => a ?? t)
+        .replace(/`+/g, '')
+        .replace(/\*\*|~~|\*/g, '') // _ 는 남긴다: 슬러그가 밑줄을 보존하므로(foo_bar → foo_bar)
+        .trim();
+}
+/**
+ * GitHub 호환 헤딩 슬러그: 소문자 → 문자·숫자·공백·하이픈·밑줄 외 제거 → 공백 하나당 하이픈 하나.
+ * 공백을 **접지 않는** 것이 핵심이다 — `제목  ·  블록` 처럼 구두점이 빠지면 하이픈이 여러 개 남는다.
+ */
+export function slugifyHeading(text) {
+    return plainText(text)
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+/** 본문의 ATX 헤딩 목록(코드블록 안은 제외). 슬러그가 겹치면 GitHub 처럼 -1·-2 를 붙인다. */
+export function collectHeadings(md) {
+    const out = [];
+    const used = new Map();
+    let inFence = false;
+    for (const line of md.split('\n')) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        // 닫는 # 는 앞에 공백이 있을 때만 장식이다(`## C#` 의 # 를 지우지 않도록)
+        const m = line.match(/^(#{1,6})\s+(.*?)(?:\s+#+)?\s*$/);
+        if (!m)
+            continue;
+        const text = m[2].trim();
+        if (!text)
+            continue;
+        const base = slugifyHeading(text);
+        const n = used.get(base) ?? 0;
+        used.set(base, n + 1);
+        out.push({ text, slug: n ? `${base}-${n}` : base, level: m[1].length });
+    }
+    return out;
+}
+/** 슬러그 → 헤딩 텍스트. 먼저 나온 헤딩이 이긴다. */
+export function buildAnchorIndex(md) {
+    const idx = new Map();
+    for (const h of collectHeadings(md))
+        if (!idx.has(h.slug))
+            idx.set(h.slug, h.text);
+    return idx;
+}
+/** 퍼센트 인코딩된 앵커를 되돌린다(실패하면 원문). */
+export const decodeAnchor = (s) => {
+    try {
+        return decodeURIComponent(s);
+    }
+    catch {
+        return s;
+    }
+};
+/**
+ * Confluence 앵커 비교용 키 — 공백·구두점을 모두 지운 소문자.
+ * Confluence 는 헤딩 앵커 id 를 만들 때 공백을 지우고 구두점 처리도 버전마다 달라서,
+ * 남는 글자(문자·숫자)만으로 맞춰야 안정적이다.
+ */
+export const anchorKey = (s) => s.normalize('NFC').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
+/**
+ * Confluence 가 만든 앵커 fragment 를 이 문서의 헤딩에 맞춘다.
+ * id 는 보통 `<페이지제목><헤딩텍스트>`(공백 제거) 형태라 제목 접두사를 허용하고,
+ * 그래도 안 맞으면 "헤딩으로 끝나는가"로 한 번 더 시도한다(가장 긴 헤딩이 이긴다).
+ */
+export function matchConfluenceAnchor(fragment, headings, pageTitle) {
+    const frag = anchorKey(decodeAnchor(fragment));
+    if (!frag)
+        return null;
+    const titleKey = anchorKey(pageTitle);
+    let loose = null;
+    let looseLen = 0;
+    for (const h of headings) {
+        const hk = anchorKey(h.text);
+        if (!hk)
+            continue;
+        if (frag === hk || frag === titleKey + hk)
+            return h; // 정확히 맞으면 바로
+        if (frag.endsWith(hk) && hk.length > looseLen) {
+            loose = h;
+            looseLen = hk.length;
+        }
+    }
+    return loose;
+}
+/**
+ * Obsidian wikilink 의 앵커(`[[문서#헤딩 텍스트]]`)를 마크다운 슬러그로.
+ * 중첩 헤딩(`#상위#하위`)은 마지막 것이 실제 목적지고, 블록 참조(`#^id`)는 마크다운에 대응물이 없다.
+ */
+export function wikilinkAnchorToSlug(anchor) {
+    const last = anchor.split('#').filter(Boolean).pop();
+    if (!last || last.startsWith('^'))
+        return null;
+    return slugifyHeading(last) || null;
+}
+const MD_LINK = /\[([^\]]*)\]\((<[^>]+>|[^()\s]+)\)/g;
+const WIKILINK = /(!?)\[\[([^\]|#]+)(#[^\]|]+)?(?:\|([^\]]+))?\]\]/g;
+/**
+ * 본문에서 **앵커가 붙은 링크만** 훑는다 — 어느 문서의 어느 헤딩에 앵커를 심어야 하는지 알아내기 위해서다.
+ * 전체 렌더보다 훨씬 싸고, 코드블록·인라인 코드·이미지는 제외한다.
+ */
+export function collectLinkAnchors(md) {
+    const out = [];
+    let inFence = false;
+    for (const line of md.split('\n')) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        // 홀수 인덱스 = 인라인 코드 → 링크로 치지 않는다
+        const prose = line.split(/(`+[^`]*`+)/).filter((_, i) => i % 2 === 0).join('');
+        for (const m of prose.matchAll(MD_LINK)) {
+            if (prose[m.index - 1] === '!')
+                continue; // 이미지
+            const d = decodeAnchor(m[2].replace(/^<(.*)>$/, '$1'));
+            const i = d.indexOf('#');
+            if (i < 0 || i === d.length - 1)
+                continue;
+            if (/^(https?:|mailto:)/i.test(d))
+                continue;
+            out.push({ dest: d.slice(0, i), fragment: d.slice(i + 1), wiki: false });
+        }
+        for (const m of prose.matchAll(WIKILINK)) {
+            if (m[1] === '!' || !m[3])
+                continue; // 임베드·앵커 없는 wikilink
+            out.push({ dest: m[2].trim(), fragment: m[3].slice(1), wiki: true });
+        }
+    }
+    return out;
+}
+/** Anchor 매크로 — 링크 대상 헤딩 바로 앞에 심어 이름을 고정한다. */
+export function anchorMacro(name) {
+    const safe = name.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return `<ac:structured-macro ac:name="anchor"><ac:parameter ac:name="">${safe}</ac:parameter></ac:structured-macro>`;
+}

package/dist/confluence.js

@@ -158,17 +158,22 @@ export function createClient(cfg, opts) {
         return res.json();
     }
     /**
-     * 콘텐츠 노드 조회. type + 제목 + export_view(HTML) + storage(원본 XHTML).
+     * 콘텐츠 노드 조회. type + 제목 + export_view(HTML) + storage(원본 XHTML) + 출처 메타.
      * storage 는 코드블록의 "진짜" 언어를 얻는 데 쓴다(export_view 는 언어 미지정 시 brush:java 기본값이 붙어 신뢰 불가).
+     * url/updated 는 frontmatter 의 출처 정보로 쓰이며, 응답에 없으면 undefined.
      */
     async function getNode(id) {
-        const data = await getV1(`/rest/api/content/${id}?expand=body.export_view,body.storage`);
+        const data = await getV1(`/rest/api/content/${id}?expand=body.export_view,body.storage,version`);
+        const base = data._links?.base;
+        const webui = data._links?.webui;
         return {
             id: data.id,
             type: data.type ?? 'page',
             title: data.title ?? id,
             html: data.body?.export_view?.value ?? '',
             storage: data.body?.storage?.value ?? '',
+            url: base && webui ? `${base}${webui}` : undefined,
+            updated: data.version?.when,
         };
     }
     /** 자식 노드 목록(kind = page|folder, 전체 페이지네이션). */

package/dist/convert.js

@@ -0,0 +1,257 @@
+/**
+ * `confluence-sync convert [--to obsidian|markdown] [--fix] [파일|폴더...] [--base <dir>] [--dry-run]`
+ * 이미 내려받은 .md 를 제자리에서 손본다. Confluence 호출도 인증도 없다.
+ *
+ *   --to obsidian  — 상대 .md 링크 → [[wikilink]]
+ *   --to markdown  — [[wikilink]] · ![[embed]] → 상대 .md 링크 (되돌리기)
+ *   --fix          — 옛 변환기가 남긴 흔적 보정(코드블록 언어·CSS 잔해·이스케이프·빈 줄)
+ *
+ * 스페이스를 통째로 다시 받지 않고도 최신 변환 품질을 얻기 위한 것이다.
+ * 링크는 대상이 트리 안에 실제로 있을 때만 바꾼다(외부 URL·이미지·깨진 링크는 손대지 않는다).
+ */
+import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync, copyFileSync } from 'node:fs';
+import { resolve, relative, dirname, basename, join } from 'node:path';
+import { collectMarkdown, collectAssets, buildVault, vaultResolver } from './docs.js';
+import { linksToWikilinks, resolveWikilinks, splitFrontmatter } from './obsidian.js';
+import { buildAnchorIndex } from './anchors.js';
+import { repairMarkdown, totalFixes } from './repair.js';
+import { bold, cyan, dim, gray, green, red, yellow } from './colors.js';
+function optVal(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+const decode = (s) => { try {
+    return decodeURIComponent(s);
+}
+catch {
+    return s;
+} };
+const posix = (s) => s.split('\\').join('/');
+// ![alt](경로) — 본문이 참조하는 로컬 이미지(--out 으로 복사할 때 같이 옮긴다)
+const IMAGE = /!\[[^\]]*\]\((<[^>]+>|[^()\s]+)\)/g;
+/** md 본문이 참조하는 로컬 첨부의 절대경로들(외부 URL 제외, 실제 존재하는 것만). */
+function referencedAssets(text, fileAbs) {
+    const out = [];
+    for (const m of text.matchAll(IMAGE)) {
+        const dest = decode(m[1].replace(/^<(.*)>$/, '$1')).split('#')[0];
+        if (/^(https?:|data:)/i.test(dest))
+            continue;
+        const abs = resolve(dirname(fileAbs), dest);
+        if (existsSync(abs))
+            out.push(abs);
+    }
+    return out;
+}
+/** 준 경로들을 모두 담는 가장 가까운 폴더(파일은 그 파일이 있는 폴더로 친다). 인자가 없으면 null. */
+function commonAncestor(paths) {
+    if (!paths.length)
+        return null;
+    const dirs = paths.map((p) => {
+        const abs = resolve(p);
+        return statSync(abs).isDirectory() ? abs : dirname(abs);
+    });
+    const split = dirs.map((d) => d.split('/'));
+    const head = split[0];
+    let i = 0;
+    while (i < head.length && split.every((s) => s[i] === head[i]))
+        i++;
+    return split.length === 1 ? dirs[0] : head.slice(0, i).join('/') || '/';
+}
+/**
+ * 상대 .md 링크 → [[wikilink]].
+ * wikilink 는 vault 어디서든 "이름"으로 찾으므로, 파일명이 트리 안에서 유일할 때만 바꾼다
+ * (겹치면 엉뚱한 노트로 이어질 수 있어 상대 링크를 그대로 둔다).
+ */
+function toObsidian(text, fileAbs, baseDir, nameCount, headingOf) {
+    return linksToWikilinks(text, (dest, label) => {
+        if (/^(https?:|mailto:|#)/i.test(dest))
+            return null; // 외부 링크·같은 문서 앵커
+        const [pathPart, ...hash] = decode(dest).split('#');
+        if (!/\.md$/i.test(pathPart))
+            return null;
+        const targetAbs = resolve(dirname(fileAbs), pathPart);
+        if (!existsSync(targetAbs))
+            return null; // 깨진 링크는 손대지 않는다
+        if (relative(baseDir, targetAbs).startsWith('..'))
+            return null; // 트리 밖
+        const name = basename(targetAbs).replace(/\.md$/i, '');
+        if (nameCount.get(name) !== 1)
+            return null; // 이름이 겹치면 상대 링크 유지
+        // Obsidian 의 섹션 링크는 슬러그가 아니라 헤딩 텍스트다. 대상 문서에서 헤딩을 못 찾으면
+        // 슬러그를 그대로 넣어봤자 안 걸리므로, 링크는 살리되 섹션은 떼고 문서 최상단으로 보낸다.
+        const slug = hash.join('#');
+        const heading = slug ? headingOf(targetAbs, slug) : undefined;
+        const anchor = heading ? `#${heading}` : '';
+        const l = label.trim();
+        return l && l !== name ? `[[${name}${anchor}|${l}]]` : anchor ? `[[${name}${anchor}|${name}]]` : `[[${name}]]`;
+    });
+}
+export async function runConvert(argv) {
+    const toRaw = optVal(argv, '--to');
+    const fix = argv.includes('--fix');
+    if (toRaw !== undefined && toRaw !== 'obsidian' && toRaw !== 'markdown') {
+        console.error(red(`✗ 알 수 없는 변환 방향: ${toRaw}`) + '\n  --to obsidian | --to markdown');
+        process.exit(1);
+    }
+    const to = toRaw;
+    if (!to && !fix) {
+        console.error(red('✗ 할 일을 지정하세요: --to <형식> 또는 --fix') +
+            `\n  예) ${cyan('confluence-sync convert --to obsidian ./docs')}` +
+            `\n      ${cyan('confluence-sync convert --fix ./docs')}          ${dim('(옛 pull 결과 보정)')}` +
+            `\n      ${cyan('confluence-sync convert --to obsidian --fix ./docs')}  ${dim('(둘 다)')}`);
+        process.exit(1);
+    }
+    const dryRun = argv.includes('--dry-run');
+    // --out: 원본을 두고 변환 결과를 다른 트리에 쓴다(base 기준 상대 경로를 그대로 재현)
+    const outOpt = optVal(argv, '--out');
+    const outDir = outOpt ? resolve(outOpt) : undefined;
+    // 위치 인자: ['convert', <파일|폴더>...]  (옵션 값은 건너뛴다)
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--to' || argv[i] === '--base' || argv[i] === '--out') {
+            i++;
+            continue;
+        }
+        if (argv[i].startsWith('-'))
+            continue;
+        positionals.push(argv[i]);
+    }
+    const targets = positionals.slice(1); // [0] 은 'convert'
+    for (const t of targets) {
+        if (!existsSync(resolve(t))) {
+            console.error(red(`✗ 없는 경로: ${t}`));
+            process.exit(1);
+        }
+    }
+    /**
+     * baseDir 은 **링크를 해석하는 범위**다. 파일 하나만 고칠 때도 주변 문서를 알아야
+     * (이름이 유일한지·링크 대상이 실재하는지) 판정할 수 있다.
+     * 기본값은 준 경로들의 공통 상위 폴더 — 폴더를 주면 그 폴더, 파일을 주면 그 파일이 있는 폴더다.
+     * 링크 변환(--to)에서 트리 전체를 봐야 한다면 --base 로 루트를 지정한다.
+     */
+    const baseOpt = optVal(argv, '--base');
+    const baseDir = resolve(baseOpt ?? commonAncestor(targets) ?? process.cwd());
+    if (!existsSync(baseDir) || !statSync(baseDir).isDirectory()) {
+        console.error(red(`✗ --base 가 디렉토리가 아닙니다: ${baseDir}`));
+        process.exit(1);
+    }
+    const allMd = collectMarkdown(baseDir); // 링크 해석용(전체)
+    const mdRels = allMd.map((f) => posix(relative(baseDir, f)));
+    const vault = buildVault(mdRels, collectAssets(baseDir).map((f) => posix(relative(baseDir, f))));
+    // obsidian 방향의 이름 중복 검사도 트리 전체 기준이어야 한다
+    const nameCount = new Map();
+    for (const f of allMd) {
+        const n = basename(f).replace(/\.md$/i, '');
+        nameCount.set(n, (nameCount.get(n) ?? 0) + 1);
+    }
+    // 섹션 링크(#슬러그 ↔ #헤딩 텍스트)를 옮기려면 대상 문서의 헤딩을 알아야 한다. 필요할 때만 읽는다.
+    const anchorCache = new Map();
+    const headingOf = (targetAbs, slug) => {
+        let idx = anchorCache.get(targetAbs);
+        if (!idx) {
+            idx = buildAnchorIndex(splitFrontmatter(readFileSync(targetAbs, 'utf8')).body);
+            anchorCache.set(targetAbs, idx);
+        }
+        return idx.get(slug.toLowerCase());
+    };
+    // 실제로 고쳐 쓸 파일(선택). 경로를 안 주면 base 전체.
+    const selected = targets.length
+        ? allMd.filter((f) => targets.some((t) => {
+            const abs = resolve(t);
+            return f === abs || f.startsWith(abs + '/');
+        }))
+        : allMd;
+    // base 밖의 .md 를 직접 지목한 경우(예: 이웃 폴더 파일) 는 위 필터에 안 걸린다
+    const outside = targets
+        .map((t) => resolve(t))
+        .filter((abs) => statSync(abs).isFile() && !allMd.includes(abs));
+    if (outside.length) {
+        console.error(yellow(`⚠ --base(${baseDir}) 밖의 파일은 건너뜁니다:`) + '\n  ' + outside.join('\n  '));
+    }
+    if (!selected.length) {
+        console.error(red('✗ 대상 .md 가 없습니다.') + dim('\n  (파일을 직접 지목했다면 --base 로 문서 트리 루트를 알려주세요)'));
+        process.exit(1);
+    }
+    const mdAbs = selected;
+    const jobs = [
+        to === 'obsidian' ? '상대 .md 링크 → [[wikilink]]' : to === 'markdown' ? '[[wikilink]] → 상대 .md 링크' : '',
+        fix ? '변환 흔적 보정' : '',
+    ].filter(Boolean).join(' + ');
+    const scope = mdAbs.length === allMd.length
+        ? `${mdAbs.length}건`
+        : `선택 ${mdAbs.length}/${allMd.length}건`;
+    if (outDir && (outDir === baseDir || outDir.startsWith(baseDir + '/'))) {
+        console.error(red(`✗ --out 이 base 안에 있습니다: ${outDir}`) + dim('\n  원본 트리를 덮어쓰지 않도록 base 밖의 경로를 쓰세요.'));
+        process.exit(1);
+    }
+    console.log(`${dim('base:')} ${cyan(baseDir)}\n` +
+        `${dim('대상:')} ${scope}  ${dim('—')}  ${jobs}` +
+        (outDir ? `\n${dim('출력:')} ${cyan(outDir)} ${dim('(원본 유지)')}` : '') +
+        (dryRun ? dim('  (dry-run)') : ''));
+    let changed = 0;
+    const copiedAssets = new Set();
+    const total = { cssJunk: 0, codeLang: 0, trailingWs: 0, escapes: 0, tightList: 0, dupTitle: 0 };
+    for (const abs of mdAbs) {
+        const rel = posix(relative(baseDir, abs));
+        const before = readFileSync(abs, 'utf8');
+        let text = before;
+        const notes = [];
+        // 보정을 먼저 한다 — 이스케이프가 풀려야(\[…\] → […]) 링크 인식이 정확해진다
+        if (fix) {
+            const r = repairMarkdown(text);
+            text = r.text;
+            const n = totalFixes(r.stats);
+            if (n) {
+                for (const k of Object.keys(total))
+                    total[k] += r.stats[k];
+                notes.push(dim(`보정 ${n}`));
+            }
+        }
+        if (to === 'obsidian')
+            text = toObsidian(text, abs, baseDir, nameCount, headingOf);
+        else if (to === 'markdown')
+            text = resolveWikilinks(text, vaultResolver(rel, vault));
+        // 제자리 변환이면 바뀐 것만 쓰지만, --out 이면 대상 전부를 내보낸다(온전한 트리가 나와야 하므로)
+        if (!outDir && text === before)
+            continue;
+        if (outDir) {
+            const target = join(outDir, rel);
+            if (!dryRun) {
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, text);
+                // 이미지가 따라가지 않으면 링크가 깨진다 — 참조된 첨부를 같은 상대 위치로 복사
+                for (const asset of referencedAssets(text, abs)) {
+                    const arel = posix(relative(baseDir, asset));
+                    if (arel.startsWith('..') || copiedAssets.has(arel))
+                        continue; // base 밖 첨부는 두고 온다
+                    const dstAsset = join(outDir, arel);
+                    mkdirSync(dirname(dstAsset), { recursive: true });
+                    copyFileSync(asset, dstAsset);
+                    copiedAssets.add(arel);
+                }
+            }
+        }
+        else if (!dryRun) {
+            writeFileSync(abs, text);
+        }
+        // --out 이면 안 바뀐 파일도 그대로 내보내지만, 로그는 실제로 손댄 것만 남긴다
+        if (text !== before) {
+            changed++;
+            console.log(`  ${cyan('↻')}  ${rel}${notes.length ? '  ' + notes.join(' ') : ''}`);
+        }
+    }
+    console.log('\n' + bold('완료') + `  ${changed ? green(`${changed}개 파일 변경`) : gray('고칠 것 없음')}` +
+        (outDir ? `  ${cyan(`${mdAbs.length}개 파일 출력`)}${copiedAssets.size ? dim(`, 첨부 ${copiedAssets.size}`) : ''}` : '') +
+        `  ${dim(`대상 ${mdAbs.length}`)}`);
+    if (fix && totalFixes(total)) {
+        console.log(dim('  보정:') +
+            `  중복 제목 ${total.dupTitle}` +
+            `  코드블록 언어 ${total.codeLang}` +
+            `  CSS 잔해 ${total.cssJunk}` +
+            `  이스케이프 ${total.escapes}` +
+            `  리스트 빈 줄 ${total.tightList}` +
+            `  줄끝 공백 ${total.trailingWs}`);
+    }
+    if (dryRun)
+        console.log(dim('--dry-run: 파일을 쓰지 않았습니다.'));
+}