@wonseok-han/confluence-sync 1.7.0 → 2.0.0

package/dist/cli/help.js

@@ -1,119 +1,218 @@
-/** --help / --version 출력. */
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
+/** Task-oriented CLI overview and per-command help. */
 import { bold, cyan, dim } from '../shared/colors.js';
-/** 설치된 패키지(package.json)의 버전을 읽는다(dist·src 어느 쪽에서 실행해도 ../../package.json). */
-export function readPkgVersion() {
-    try {
-        const pkgPath = fileURLToPath(new URL('../../package.json', import.meta.url));
-        return JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? 'unknown';
-    }
-    catch {
-        return 'unknown';
+import { readPkgVersion } from '../shared/version.js';
+export { readPkgVersion };
+const workspace = `  --base <폴더>             작업공간 지정(상위 작업공간 자동 탐색)
+  --reference-root <폴더>   다른 작업공간의 게시 매핑으로 링크 연결(반복 가능)`;
+const help = {
+    init: `csync init [--base <폴더>] [--force]
+csync init --connect [--base <폴더>]
+csync init --migrate [--base <폴더>] [--dry-run]
+
+  init             .env 생성. 터미널에서는 값을 입력하고, 비대화형은 빈 템플릿 생성
+  --base <폴더>    .env를 생성하거나 연결할 기존 폴더(기본: 현재 폴더)
+  --force          기존 .env 교체
+  --connect        준비된 .env로 기준 폴더 ↔ 스페이스 연결. 문서 다운로드·업로드 없음
+  --migrate        기존 루트 메타데이터를 .csync/로 이전(.env·문서 유지, API 호출 없음)
+  --dry-run        --migrate 이전 내역만 확인
+
+  기존 스페이스 받기: csync init → .env 값 입력 → csync pull
+  로컬 문서부터 시작: csync init → .env 값 입력 → csync init --connect → csync add 문서.md
+  연결 정보만 있는 폴더에서도 Pull이 스페이스를 확인하고 자동 연결합니다. 별도 스코프 설정은 없습니다.`,
+    status: `csync status [--base <폴더>] [--reference-root <폴더>]
+
+${workspace}
+
+  로컬 문서와 저장된 Fetch 결과를 합쳐 표시합니다. Confluence API 호출·파일 저장 없음.
+  ↓ 받을 변경: 원격에서만 변경 → csync pull
+  ↑ 보낼 변경: 로컬 작업 → csync diff 문서.md → csync add 문서.md
+  ! 양쪽 변경: 양쪽 모두 변경 → csync diff 문서.md --remote로 비교
+  ! 확인 필요: 재추가 필요, 파일 누락, 원격 조회 불가 또는 기준 버전 확인 필요
+  [추가됨]은 다음 Push에 포함, [미선택]은 제외입니다.
+  원격 조회 시각을 확인하세요. 원격 미확인·오래된 결과는 csync fetch로 갱신합니다.
+  로컬 누락 복구: csync restore README.md (기존 파일은 덮어쓰지 않음)
+  원격 누락을 삭제로 확정하거나 로컬 파일 삭제를 원격에 전파하지 않습니다.`,
+    fetch: `csync fetch [--base <폴더>] [--refresh]
+
+  --base <폴더>    원격 변경을 확인할 작업공간
+  --refresh        2분 캐시를 건너뛰고 원격 상태 다시 조회
+
+  스페이스의 페이지 메타데이터를 100개씩 조회해 원격 신규·버전·제목·위치를 확인합니다. 본문·첨부는 받지 않습니다.
+  .csync/remote.json에 저장하고 2분 동안 재사용합니다. 한 실행 최대 20회 요청.
+  문서·매핑의 동기화 기준과 업로드 선택은 유지합니다. 결과는 csync status에서 확인하세요.
+  경로 구성에 필요한 폴더 정보만 추가 조회합니다. 페이지 버전이 그대로인 첨부 단독 변경은 감지하지 않습니다.
+
+  예: csync fetch → csync status → csync pull`,
+    pull: `csync pull [--base <폴더>] [--obsidian]
+
+  --base <폴더>    작업공간 지정
+  --out <폴더>     저장할 작업공간(--base와 같아야 함)
+  --obsidian       내부 링크를 [[wikilink]]로 저장
+  --mapping <파일> 매핑 파일 지정(기본: .csync/mapping.json)
+
+  Fetch 결과에서 아직 받지 않은 원격 문서와 원격에서만 변경된 문서를 받습니다.
+  로컬이 비어 있어도 동일한 동작이며, 최초·전체 가져오기를 구분하지 않습니다.
+  연결 정보만 있는 폴더는 .env로 스페이스 연결을 확인합니다.
+  2분 이내 Fetch 결과를 재사용하며 없거나 만료되면 메타데이터를 조회합니다.
+  로컬 수정·의도적인 삭제·이동 대기·양쪽 변경은 보존하고 원격 삭제를 전파하지 않습니다.
+  원복은 csync restore <파일> --overwrite를 사용하세요.
+
+  예: csync fetch → csync status → csync pull
+      csync pull --out ./docs`,
+    restore: `csync restore <파일.md...> [--overwrite] [--base <폴더>] [--obsidian]
+
+  --base <폴더>    기존 작업공간 지정
+  --obsidian       복구 문서의 내부 링크를 [[wikilink]]로 저장
+  --overwrite      지정 문서의 로컬 수정과 관련 첨부를 버리고 원격 최신으로 교체
+
+  지정한 문서를 매핑의 pageId로 조회해 최신 원격 본문과 첨부로 복구합니다.
+  원격에 쓰거나 삭제하지 않습니다. 하위 페이지·전체 스페이스는 탐색하지 않습니다.
+  기본은 누락 파일만 복구하며 기존 로컬 문서·첨부를 보호합니다.
+  --overwrite는 지정한 문서와 원격에서 참조하는 첨부를 교체합니다. 로컬 수정은 사라집니다.
+  다운로드 중 추가로 변경된 파일은 옵션과 관계없이 보존하고 중단합니다.
+  제외 규칙·독립 작업공간·이동 대기·같은 pageId의 이동한 로컬 문서는 복구하지 않습니다.
+  복구한 문서는 업로드 선택에서 제외합니다. 다시 올리려면 직접 add하세요.
+  일반 pull은 로컬 삭제를 보존합니다. restore는 사용자가 지정한 파일만 복구합니다.
+
+  예: csync restore README.md
+      csync restore "수정한 문서.md" --overwrite
+      csync restore "지식자산/문서.md" --base ./스페이스`,
+    add: `csync add <파일·폴더...> [--base <폴더>] [--reference-root <폴더>]
+
+${workspace}
+
+  다음 Push에 포함할 문서를 .csync/index.json에 저장합니다. 폴더는 하위 문서 전체, .은 전체.
+  Confluence API를 호출하지 않으며 원본 파일은 유지합니다.
+  내용 사본이나 일부 줄을 저장하는 기능은 아닙니다. 추가 후 문서·첨부·링크가 바뀌면 재추가하세요.
+  참조 폴더는 add와 push에 같은 값을 지정하세요.
+
+  예: csync add "지식자산/특허출원/문서.md"
+      csync status
+      csync push --dry-run
+      csync push`,
+    unstage: `csync unstage <파일·폴더...> [--base <폴더>]
+
+  --base <폴더>    작업공간 지정
+
+  저장된 업로드 선택에서만 제외합니다. 문서·첨부·매핑·원격 내용은 유지합니다.
+  파일 변경을 취소하거나 원래 내용으로 복원하는 명령이 아닙니다.
+
+  예: csync unstage 문서.md
+      csync unstage .     # 모두 선택 해제`,
+    push: `csync push [파일·폴더...] [옵션]
+
+${workspace}
+  --dry-run         업로드 계획만 확인(기본은 API 호출 없음)
+  --verify          변경 없는 문서까지 원격 버전·존재 확인(--dry-run과 함께 읽기 전용 조회)
+  --list            인식된 문서·제목·계층만 출력(인증·API 호출 없음)
+  --force           본문 강제 갱신(원격 충돌 검사는 유지)
+  --exclude <패턴>  제외 패턴(반복 가능, .csync/ignore도 적용)
+  --mapping <파일>  매핑 파일 지정(기본: .csync/mapping.json)
+
+  경로 없는 push: add로 선택한 문서만 처리합니다. 선택이 없으면 중단합니다.
+  push 문서.md: 저장된 선택과 별개로 명시한 문서를 직접 처리합니다.
+  추가 후 수정한 문서는 다시 add해야 하며 성공·변경없음 항목은 선택 해제, 실패 항목은 유지합니다.
+  CLI 미리보기는 선택 사항입니다. 웹은 미리보기 완료 후에만 업로드할 수 있습니다.
+  미리보기 여부와 관계없이 원격 버전 충돌 검사는 유지하며 자동 병합하지 않습니다.
+  상위 README는 부모 연결에만 사용합니다. 미연결 상위 README는 함께 추가하거나 Pull로 연결하세요.
+  위키링크·각주·PDF 페이지 참조·Obsidian callout을 전처리하며 원본은 유지합니다.
+
+  권장: csync add 문서.md → csync push --dry-run --verify → csync push
+  직접: csync push 문서.md --dry-run → csync push 문서.md`,
+    diff: `csync diff <파일.md> [--remote] [--base <폴더>]
+
+  --base <폴더>    작업공간 지정
+  --remote         해당 페이지 본문 1회 조회 후 현재 원격 ↔ 로컬 비교
+
+  기본은 마지막 성공한 Pull·Push의 저장된 Markdown 기준본과 비교합니다(API 호출 없음).
+  새 문서는 빈 내용과 비교하며 옛 매핑에 기준본이 없으면 --remote로 현재 원격과 비교하세요.
+  원격 비교는 HTML → Markdown 근사 변환이며 과거 동기화 시점의 내용이 아닙니다.
+  문서·매핑·업로드 선택은 변경하지 않습니다.
+
+  예: csync diff "지식자산/문서.md"
+      csync diff "지식자산/문서.md" --remote`,
+    remap: `csync remap [--base <폴더>] [--dry-run]
+
+  --base <폴더>           작업공간 지정
+  --dry-run              계획만 확인, 저장 없음
+  --from-mapping <파일>   외부 매핑에서 ID·해시 가져오기(원본 유지)
+  --mapping <파일>        대상 매핑(기본: .csync/mapping.json)
+  --exclude <패턴>        제외 패턴(반복 가능)
+
+  로컬 파일의 pageId로 이동한 경로를 재연결합니다. API 호출·원격 이동 없음.
+  보통 파일 이동 후 add와 push로 자동 인식하므로 별도 remap은 필요하지 않습니다.
+  원격 위치 변경은 명시적으로 Push할 때 반영합니다. 폴더 ID의 경로 변경은 자동 추론하지 않습니다.`,
+    convert: `csync convert [파일·폴더...] --to markdown|obsidian [옵션]
+csync convert [파일·폴더...] --fix [옵션]
+
+  --to markdown    위키링크·이미지·각주·PDF 페이지 참조를 Markdown으로 변환
+  --to obsidian    Markdown 링크를 [[wikilink]]로 변환
+  --fix            옛 Confluence 결과의 CSS 잔해·코드블록 언어·불필요한 이스케이프 보정
+  --base <폴더>    링크 해석 기준(기본: 대상의 공통 상위 폴더)
+  --out <폴더>     별도 출력 위치. 생략하면 원본 파일을 변경합니다.
+  --dry-run        변경할 파일만 확인, 저장 없음
+
+  로컬 전용이며 Confluence API·인증은 필요하지 않습니다.
+  첨부는 문서 옆 attachments/<문서명>/에 보관합니다.
+  Push는 필요한 전처리를 내부 수행하므로 먼저 변환본을 만들 필요는 없습니다.
+
+  예: csync convert --to markdown ./vault --out ./markdown`,
+    web: `csync web [--base <폴더>] [--port <번호>] [--no-open] [--ui <배포 웹 URL>] [--hosted]
+
+  --base <폴더>    시작 폴더(기본: 홈 폴더, 화면에서 변경 가능)
+  --port <번호>    웹 포트(기본: 4318)
+  --no-open        브라우저 자동 열기 생략
+  --hosted         브라우저 폴더 접근을 사용하는 배포 서버 실행(기본 포트 8080)
+  --ui <URL>      배포 웹을 이 컴퓨터의 실행기에 연결(HTTPS, 로컬 개발은 HTTP 허용)
+
+  localhost / 127.0.0.1에서 로컬 웹 화면을 실행합니다.
+  문서 변환·표 서식·미리보기와 CLI와 같은 Fetch·Pull·업로드 선택·Push를 제공합니다.
+  접속 설정은 선택한 기준 폴더의 .env 또는 직접 가져온 .env를 사용합니다.
+  --ui는 지정한 웹 출처만 허용하며 연결 키는 csync를 종료하면 만료됩니다.
+  예: csync web --ui https://csync.example.com --base ./vault`,
+};
+export function printHelp(command) {
+    if (command) {
+        if (!help[command])
+            throw new Error(`지원하지 않는 명령입니다: ${command}. csync --help를 확인하세요.`);
+        console.log(`${bold(cyan(`csync ${command}`))}\n\n사용법: ${help[command]}\n\n  -h, --help  이 명령의 도움말\n  --no-color  색상 없이 출력(NO_COLOR 환경변수도 지원)`);
+        return;
     }
-}
-export function printHelp() {
-    const h = (s) => bold(s); // 섹션 제목
-    const o = (s) => cyan(s); // 옵션/명령
     console.log(`${bold(cyan(`confluence-sync v${readPkgVersion()}`))}
-${dim('Confluence Cloud ↔ Markdown 양방향 동기화 CLI.')}
-${dim('짧은 이름')} ${o('csync')} ${dim('로도 실행할 수 있습니다(아래 confluence-sync 를 csync 로 대체 가능).')}
-
-${h('사용법:')}
-  ${o('confluence-sync')} [옵션] [경로...]      문서를 동기화(md → Confluence)
-  ${o('confluence-sync web')}                   문서 변환·Confluence 동기화 웹 화면(로컬 전용)
-  ${o('confluence-sync init')}                  대화형으로 .env 설정 파일 생성
-  ${o('confluence-sync pull <pageId|url>')}     Confluence 페이지/폴더를 .md 로 가져오기(역방향)
-  ${o('confluence-sync convert --to <형식>')}   이미 받은 .md 의 링크 표기를 바꾸기(로컬 전용)
-  ${o('confluence-sync --help | --version')}
-
-${h('remap 옵션(로컬 매핑만 갱신, Confluence 호출 없음):')}
-  ${o('csync remap --base <dir>')}  pageId로 경로를 재연결하고 이동 대기 기록
-  ${o('--from-mapping <path>')}  원본 매핑에서 기존 ID·해시 가져오기(원본 유지)
-  ${o('--mapping <path>')}       저장할 매핑(기본: <base>/.confluence-sync.json)
-  ${o('--exclude <glob>')}       제외 패턴(반복 가능), .confluence-syncignore도 적용
-  ${o('--dry-run')}              변경 내역만 출력, 파일 저장 없음
-  이후 ${o('csync sync --base <dir> --dry-run')}으로 확인하고, 명시적으로 sync할 때 이동 반영.
-  기존 해시가 없으면 sync에서 본문도 갱신합니다. 폴더 ID의 경로 변경은 자동 추론하지 않습니다.
-
-${h('web 옵션:')}
-  ${o('--base <dir>')}      처음 열 폴더(기본: 홈 폴더). 화면에서 기준 폴더를 바꿀 수 있음
-  ${o('--port <number>')}   웹 포트(기본: 4318)
-  ${o('--no-open')}         브라우저를 자동으로 열지 않음
-  localhost / 127.0.0.1 로컬 주소에서 실행. 화면에서 출력 폴더 지정 가능. 원본 유지.
-
-${h('동기화 옵션:')}
-  ${o('--reference-root <dir>')}  동기화 링크 참조 폴더(반복 가능, 참조 문서는 업로드하지 않음)
-  ${o('--base <dir>')}      동기화 루트 (또는 env CONFLUENCE_SYNC_BASE). 미지정 시 중단
-  ${o('--mapping <path>')}  매핑 파일 위치 (기본: <base>/.confluence-sync.json)
-  ${o('--exclude <glob>')}  동기화 제외 패턴(반복 가능). <base>/.confluence-syncignore(.gitignore 방식)도 사용
-  ${o('--dry-run')}         호출 없이 대상·상태(신규/변경/동일)·링크·이미지 출력
-  ${o('--list')}            인식된 문서·제목·계층만 출력 (Confluence 호출·인증 없음)
-  ${o('--force')}           변경 감지 무시, 전체 강제 갱신
-  ${o('--verify')}          변경 없는 문서도 페이지 존재 확인(삭제됐으면 재생성)
-  ${o('--rebuild')}         매핑된 페이지 전부 삭제 후 재생성
-  ${o('--no-color')}        컬러 출력 끄기
-  ${o('-h, --help')}        이 도움말
-  ${o('-v, --version')}     버전 출력
-
-${h('경로 인자:')}
-  파일/폴더를 주면 ${bold('그 문서만')} 발행합니다.
-  상위 ${o('README.md')} 는 자식을 붙일 부모 pageId 를 얻는 데만 쓰이고 내용은 갱신되지 않습니다
-  ${dim('(아직 페이지가 없으면 자식을 붙일 곳이 없으므로 그때는 생성됩니다).')}
-  상위 문서까지 갱신하려면 함께 지정하세요.
-  예)  ${o('confluence-sync 20-design')}        ${o('confluence-sync 90-glossary.md')}
-
-${h('pull(역방향) 옵션:')}
-  ${o('--out <dir>')}         .md 를 생성할 디렉토리(기본: 현재 폴더)
-  ${o('--children')}          하위 페이지까지 재귀적으로 가져와 폴더 트리로 복원
-  ${o('--space')}             대상 없이 스페이스(CONFLUENCE_SPACE_KEY) 홈페이지부터 전체를 가져옴
-  ${o('--obsidian')}          내부 링크를 [[wikilink]] 로 출력(기본: 어디서나 열리는 상대 .md 링크)
-  ${o('--base <dir>')}        매핑 키의 기준(기본: --out 에서 위로 올라가며 .confluence-sync.json 을 찾음)
-  ${o('--mapping <path>')}    매핑 파일 위치 (기본: <base>/.confluence-sync.json)
-  ${o('--no-mapping')}        매핑을 기록하지 않음
-  (이미지는 항상 attachments/<문서명>/ 하위에 저장됨)
-  받아온 문서는 pageId 와 ${dim('변경 해시')}가 매핑에 기록되어, ${bold('pull 직후 push 하면 "변경없음"')} 입니다
-  ${dim('(기록하지 않으면 방금 받아온 내용을 그대로 되올려 보내게 됩니다).')}
-  예)  ${o('confluence-sync pull https://.../pages/12345/Title --out ./docs --children')}
-       ${o('confluence-sync pull --space --out ./docs')}
-
-${h('convert(이미 받아둔 .md 손보기) 옵션:')} ${dim('Confluence 호출·인증 없음')}
-  ${o('--to obsidian')}    상대 .md 링크 → [[wikilink]]
-  ${o('--to markdown')}    [[wikilink]] · ![[embed]] → 상대 .md 링크 (되돌리기)
-                   각주 → 위첨자 링크·제목 앵커, PDF #page=N → 해당 쪽 이미지
-                   --to obsidian은 변환 표식으로 각주·PDF 참조를 복원
-                   절대경로·file://·../ 로컬 첨부는 출력 트리에 복사하고 링크 변경
-  ${o('--fix')}            옛 pull 결과 보정 — 코드블록 언어(java→plaintext)·CSS 잔해·
-                   불필요한 \\ 이스케이프·리스트 사이 빈 줄
-  ${o('--base <dir>')}     링크를 해석할 문서 트리 루트(기본: 준 경로들의 공통 상위 폴더)
-  ${o('--out <dir>')}      원본을 두고 결과를 다른 트리에 쓰기(참조된 첨부도 함께 복사)
-  ${o('--dry-run')}        바뀔 파일만 출력하고 쓰지 않음
-
-  파일·폴더를 여러 개 줄 수 있고, 안 주면 base 전체가 대상입니다.
-  ${o('--out')} 없이 실행하면 ${dim('원본 파일을 덮어씁니다')}.
-  예)  ${o('confluence-sync convert --fix ./docs --dry-run')}
-       ${o('confluence-sync convert --to obsidian --fix ./docs --out ~/MyVault')}
-       ${o('confluence-sync convert --fix ./docs/가이드/설치.md --base ./docs')}  ${dim('(파일 하나만)')}
-
-${h('섹션 링크(앵커):')}
-  ${o('[§1 개요](#1-개요)')} 처럼 헤딩을 가리키는 링크가 Confluence 에서도 동작합니다.
-  같은 문서(${o('#슬러그')} · ${o('[[#헤딩]]')})·다른 문서(${o('문서.md#슬러그')} · ${o('[[문서#헤딩]]')}) 모두 지원합니다.
-  Confluence 의 자동 헤딩 id 는 배포판마다 달라서, 가리켜지는 헤딩 앞에 ${dim('Anchor 매크로')}로
-  이름을 직접 심고 그 이름을 가리킵니다. pull 은 반대로 슬러그를 되돌립니다.
-  대응하는 헤딩을 못 찾으면 링크를 바꾸지 않고 ${dim('⚠ 대응 헤딩 없는 앵커')} 로 알려 줍니다
-  ${dim('(대개 문서 쪽 오타나 깨진 상대경로입니다)')}.
-
-${h('Obsidian:')}
-  pull 결과는 vault 에서 바로 열립니다. 함께 받은 페이지끼리의 내부 링크가 이어져 그래프·백링크가
-  동작하고, 각 문서의 frontmatter 에 pageId 가 남아 원본 페이지를 가리킵니다.
-  [[wikilink]] 표기를 원하면 ${o('pull --obsidian')}, 이미 받아둔 문서라면 ${o('convert --to obsidian')}.
-
-  push 는 vault 문법을 그대로 이해합니다: ${o('[[wikilink]]')} · ${o('![[embed]]')} · ${o('[[문서#헤딩]]')} · YAML frontmatter
-  (frontmatter 의 ${o('title')} 이 페이지 제목이 되고, ${o('pageId')} 가 있으면 매핑이 없어도 그 페이지를 갱신합니다).
-
-${h('설정(.env):')}
-  실행 위치(cwd)의 .env 또는 셸 환경변수를 읽습니다.
-  필수: CONFLUENCE_BASE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN, CONFLUENCE_SPACE_KEY
-  선택: CONFLUENCE_PARENT_ID(페이지/폴더 id), CONFLUENCE_SYNC_BASE
-  ${o("'confluence-sync init'")} 으로 대화형 생성 가능.`);
+${dim('Confluence Cloud ↔ Markdown · 기준 폴더 하나가 스페이스 작업공간입니다.')}
+
+${bold('사용법:')} csync <명령> [옵션]
+  init       .env 준비 / --connect로 기존 문서 폴더 연결
+  status     로컬 변경 + 마지막 Fetch 결과 + 업로드 선택 확인(API 호출 없음)
+  fetch      연결된 페이지의 원격 변경 확인(본문·첨부 유지, 2분 캐시)
+  pull       아직 받지 않은 문서와 원격에서만 바뀐 문서 받기
+  restore    선택한 문서를 원격 최신으로 복구(--overwrite로 로컬 수정 원복)
+  diff       문서 내용 비교(--remote는 원격 본문 1회 조회)
+  add        다음 Push에 포함할 문서 선택
+  unstage    업로드 선택 해제(원본 유지)
+  push       선택한 문서 업로드(명시한 경로는 직접 처리)
+  web        로컬 웹 화면 실행
+  convert    로컬 문서 형식 변환
+  remap      고급: 이동한 로컬 파일의 매핑 정리
+
+${bold('시작:')}
+  csync init → .env 값 입력 → csync pull
+  Pull 없이 로컬 문서부터: csync init → .env 값 입력 → csync init --connect
+
+${bold('반복 작업:')}
+  csync fetch → csync status → csync pull
+  문서 편집 → csync diff 문서.md → csync add 문서.md
+  csync push --dry-run → csync push
+
+  Push는 선택한 문서만 처리하고, 기본 Pull은 로컬 수정·양쪽 변경을 보존합니다.
+  새 원격 문서는 Fetch로 발견하고 Pull로 받습니다. 자동 병합하지 않습니다.
+  add 후 문서·첨부·링크를 수정했다면 다시 add하세요.
+  CLI --dry-run은 선택 사항이며 원격 충돌 검사는 항상 적용합니다.
+
+${bold('도움말:')}
+  csync <명령> --help    해당 명령의 옵션과 예제
+  csync --version       버전 확인
+  --no-color            색상 없이 출력(NO_COLOR 환경변수도 지원)
+  csync                 도움말만 표시(업로드하지 않음)
+  confluence-sync도 같은 명령으로 사용할 수 있습니다.`);
 }

package/dist/cli/init.js

@@ -6,6 +6,11 @@ import { existsSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
+import { loadWorkspace, resolveSyncBase } from '../sync/workspace.js';
+import { migrateMetadata, mappingPath } from '../sync/metadata.js';
+import { loadMapping } from '../sync/mapping.js';
+import { connectWorkspace } from '../sync/scope.js';
+import { readEnv } from '../confluence/config.js';
 import { bold, cyan, dim, green, red, yellow } from '../shared/colors.js';
 /** 일반 한 줄 입력(에코 표시). 매 질문마다 readline 을 새로 열고 닫아 stdin 경쟁을 피한다. */
 async function promptLine(query) {
@@ -60,15 +65,49 @@ function promptSecret(query) {
     });
 }
 export async function runInit(argv) {
-    const target = resolve(process.cwd(), '.env');
+    if (argv.includes('--scope') || argv.includes('--confirm-scope'))
+        throw new Error('--scope 설정은 제거되었습니다. 기준 폴더가 스페이스 전체 작업공간입니다. 연결은 init --connect를 사용하세요.');
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--base') {
+            if (!argv[++i] || argv[i].startsWith('-'))
+                throw new Error('--base 뒤에 기준 폴더를 지정하세요.');
+        }
+        else if (!['init', '--connect', '--migrate', '--dry-run', '--force', '--no-color'].includes(argv[i]))
+            throw new Error(`지원하지 않는 init 인자: ${argv[i]}. csync init --help를 확인하세요.`);
+    }
+    if (argv.includes('--dry-run') && !argv.includes('--migrate'))
+        throw new Error('init --dry-run은 --migrate와 함께 사용하세요. .env 생성이나 연결은 실행하지 않았습니다.');
+    if (argv.includes('--force') && (argv.includes('--connect') || argv.includes('--migrate')))
+        throw new Error('init --force는 .env 생성에만 사용하세요.');
+    if (argv.includes('--migrate')) {
+        if (argv.includes('--connect'))
+            throw new Error('--migrate와 --connect는 각각 실행하세요.');
+        const index = argv.indexOf('--base');
+        const base = resolveSyncBase(index >= 0 ? argv[index + 1] : undefined) ?? process.cwd();
+        loadMapping(mappingPath(base));
+        loadWorkspace(base);
+        const count = migrateMetadata(base, argv.includes('--dry-run'));
+        console.log(`${argv.includes('--dry-run') ? '이전 미리보기' : '이전 완료'}: ${count}개 메타데이터. 문서·.env 유지, Confluence 호출 없음.`);
+        return;
+    }
+    if (argv.includes('--connect')) {
+        const index = argv.indexOf('--base');
+        const base = resolveSyncBase(index >= 0 ? argv[index + 1] : undefined) ?? process.cwd();
+        const workspace = await connectWorkspace(base, readEnv(base));
+        console.log(`${green('스페이스 연결 완료:')} ${cyan(base)} ↔ ${cyan(workspace.connection.spaceKey)}`);
+        return;
+    }
+    const baseIndex = argv.indexOf('--base');
+    const base = resolve(baseIndex >= 0 ? argv[baseIndex + 1] : process.cwd());
+    const target = resolve(base, '.env');
+    const next = base === process.cwd() ? 'csync pull' : `csync pull --base ${JSON.stringify(base)}`;
     const force = argv.includes('--force');
     const fields = [
         { key: 'CONFLUENCE_BASE_URL', hint: 'https://api.atlassian.com/ex/confluence/<CLOUD_ID>/wiki 형식 (CLOUD_ID: <도메인>.atlassian.net/_edge/tenant_info 에서 확인)' },
         { key: 'CONFLUENCE_EMAIL', hint: 'Atlassian 계정 이메일' },
         { key: 'CONFLUENCE_API_TOKEN', hint: 'Scoped API 토큰 (id.atlassian.com → Create API token with scopes). 입력은 가려집니다', secret: true },
         { key: 'CONFLUENCE_SPACE_KEY', hint: 'URL .../wiki/spaces/<KEY>/... 의 KEY' },
-        { key: 'CONFLUENCE_PARENT_ID', hint: '루트 앵커(페이지 또는 폴더 id). 비우면 공간 최상위', optional: true },
-        { key: 'CONFLUENCE_SYNC_BASE', hint: `동기화 루트 디렉토리 (기본: ${process.cwd()})`, optional: true, def: process.cwd() },
+        { key: 'CONFLUENCE_SYNC_BASE', hint: `스페이스 문서 작업공간 (기본: ${base})`, optional: true, def: base },
     ];
     const renderEnv = (vals) => '# confluence-sync 설정 (confluence-sync init 으로 생성)\n\n' +
         fields.map((f) => `# ${f.hint}\n${f.key}=${vals[f.key] ?? ''}`).join('\n\n') +
@@ -90,7 +129,7 @@ export async function runInit(argv) {
     // 비대화형(파이프/CI): 값 없이 빈 템플릿만 생성
     if (!input.isTTY) {
         writeFileSync(target, renderEnv({}));
-        console.log(`템플릿 .env 를 생성했습니다: ${target}\n각 값을 채워 넣으세요.`);
+        console.log(`템플릿 .env 를 생성했습니다: ${target}\n값 입력 후: ${next} (최초 전체 받기)\n다운로드 없이 연결만: csync init --connect --base ${JSON.stringify(base)}`);
         return;
     }
     // 대화형 마법사
@@ -116,5 +155,5 @@ export async function runInit(argv) {
     }
     writeFileSync(target, renderEnv(values));
     console.log(green(`\n✓ .env 생성 완료: ${target}`));
-    console.log(`  다음으로:  ${cyan('confluence-sync --dry-run')}  ${dim('(대상·상태 미리보기)')}`);
+    console.log(`  다음으로:  ${cyan(next)}  ${dim('(스페이스 전체를 최초로 가져옵니다)')}`);
 }

package/dist/cli/main.js

@@ -1,48 +1,79 @@
+import { withProgress } from '../shared/progress.js';
+import { red } from '../shared/colors.js';
+import { runRestore } from '../sync/restore.js';
+import { runStatus } from './status.js';
+import { runDiff } from '../sync/diff.js';
 /** CLI command dispatch. Feature modules do not run on import. */
-import 'dotenv/config';
 import { positionalArgs } from './args.js';
 import { printHelp, readPkgVersion } from './help.js';
 import { runInit } from './init.js';
 import { runConvert } from '../conversion/convert.js';
 import { runPull } from '../sync/pull.js';
 import { runRemap } from '../sync/remap.js';
+import { runFetch } from '../sync/fetch.js';
+import { runStaging } from '../sync/staging.js';
 import { runPush } from '../sync/push.js';
 const argv = process.argv.slice(2);
 try {
     if (argv.includes('--help') || argv.includes('-h'))
-        printHelp();
+        printHelp(positionalArgs(argv)[0]);
     else if (argv.includes('--version') || argv.includes('-v'))
         console.log(readPkgVersion());
     else {
         switch (positionalArgs(argv)[0]) {
+            case 'diff':
+                await withProgress(argv.includes('--remote') ? '원격 본문 비교' : '저장된 기준본과 문서 비교', () => runDiff(argv));
+                break;
+            case 'status':
+                await withProgress('로컬 변경과 업로드 선택 확인', () => runStatus(argv));
+                break;
+            case 'add':
+            case 'unstage':
+                await withProgress(positionalArgs(argv)[0] === 'add' ? '업로드 문서 선택 저장' : '업로드 선택 해제', () => runStaging(argv));
+                break;
             case 'init':
-                await runInit(argv);
+                if (argv.includes('--connect') || argv.includes('--migrate'))
+                    await withProgress(argv.includes('--connect') ? '스페이스 작업공간 연결' : '메타데이터 이전 확인', () => runInit(argv));
+                else
+                    await runInit(argv);
                 break;
             case 'convert':
-                await runConvert(argv);
+                await withProgress('로컬 문서 변환', () => runConvert(argv));
                 break;
             case 'remap':
-                await runRemap(argv);
+                await withProgress('페이지 ID와 로컬 경로 재연결', () => runRemap(argv));
                 break;
-            case 'sync': {
+            case 'push': {
                 const args = [...argv];
-                args.splice(args.indexOf('sync'), 1);
-                await runPush(args);
+                args.splice(args.indexOf(positionalArgs(argv)[0]), 1);
+                await withProgress(argv.includes('--list') ? '문서 목록 확인' : argv.includes('--dry-run') ? '업로드 미리보기' : 'Confluence 문서 업로드', () => runPush(args));
                 break;
             }
+            case 'fetch':
+                await withProgress('원격 페이지 메타데이터 확인', () => runFetch(argv));
+                break;
+            case 'restore':
+                await withProgress('선택한 로컬 문서를 원격에서 복구', () => runRestore(argv));
+                break;
             case 'pull':
-                await runPull(argv);
+                await withProgress('Confluence 문서 가져오기', () => runPull(argv));
                 break;
             case 'web': {
                 const { runWeb } = await import('../web/server.js');
                 await runWeb(argv);
                 break;
             }
-            default: await runPush(argv);
+            case undefined:
+                if (!argv.length) {
+                    printHelp();
+                    break;
+                }
+                throw new Error('실행할 명령을 지정하세요. 업로드: csync push, 가져오기: csync pull, 도움말: csync --help');
+            default: throw new Error('지원하지 않는 명령입니다. 업로드: csync push, 가져오기: csync pull, 도움말: csync --help');
         }
     }
 }
 catch (error) {
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(red(error instanceof Error ? error.message : String(error)));
     process.exitCode = 1;
 }

package/dist/cli/status.js

@@ -0,0 +1,83 @@
+/** Git-like status from local files and the last saved Fetch observation. */
+import { bold, cyan, blue, green, yellow, red, gray, dim } from '../shared/colors.js';
+import { lstatSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { readEnv } from '../confluence/config.js';
+import { inspectStaging } from '../sync/staging.js';
+import { observeChanges, changeGroup } from '../sync/changes.js';
+import { loadWorkspace, requireScope, resolveSyncBase } from '../sync/workspace.js';
+export async function runStatus(argv) {
+    let explicitBase;
+    const referenceRoots = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--base' || arg === '--reference-root') {
+            const value = argv[++i];
+            if (!value || value.startsWith('-'))
+                throw new Error(`${arg} 뒤에 폴더를 지정하세요.`);
+            if (arg === '--base')
+                explicitBase = value;
+            else
+                referenceRoots.push(value);
+        }
+        else if (!['status', '--no-color'].includes(arg))
+            throw new Error(`지원하지 않는 status 인자: ${arg}. csync status --help를 확인하세요.`);
+    }
+    const base = resolveSyncBase(explicitBase);
+    if (!base)
+        throw new Error('작업공간이 없습니다. .env를 준비하고 csync pull 또는 csync init --connect를 실행하세요.');
+    const workspace = loadWorkspace(base);
+    requireScope(workspace);
+    const env = readEnv(base);
+    const view = observeChanges(base, await inspectStaging(base, { referenceRoots, baseUrl: env.baseUrl }), env);
+    console.log(`${bold('작업공간:')} ${cyan(resolve(base))}\n${bold('스페이스:')} ${cyan(workspace.connection.spaceKey)}`);
+    console.log(view.remoteCheckedAt
+        ? `${dim('원격 확인: ' + view.remoteCheckedAt)}${view.remoteExpired ? yellow(' · 이전 조회 결과(2분 경과), csync fetch로 갱신하세요.') : dim(' · 저장된 Fetch 결과')}\n${dim('현재 상태는 마지막 조회 시점 기준입니다. 이번 API 요청: 0회')}`
+        : yellow('원격 미확인 · csync fetch로 원격 변경을 확인하세요. 이번 API 요청: 0회'));
+    if (view.remoteError)
+        console.log(yellow(view.remoteError));
+    const titles = { receive: '↓ 받을 변경', conflict: '! 양쪽 변경 · 비교 필요', attention: '! 확인 필요', send: '↑ 보낼 변경 · 로컬 작업', same: '변경 없음' };
+    const tones = { receive: cyan, conflict: red, attention: yellow, send: blue, same: gray };
+    const labels = { new: '로컬 신규', changed: '로컬 수정', moved: '로컬 이동', same: '로컬 변경 없음', unavailable: '로컬 파일 없음·제외 여부 확인' };
+    const detail = (row) => {
+        const selection = row.staged ? row.stale ? yellow('[재추가 필요]') : green('[추가됨]') : gray('[미선택]');
+        const group = changeGroup(row);
+        const pathTone = group === 'conflict' || group === 'attention' ? tones[group] : row.staged ? green : group === 'receive' ? cyan : (text) => text;
+        const remote = row.remoteState === 'unavailable' ? ' · 원격 조회 불가(삭제로 확정하지 않음)' : row.remoteState === 'unknown' ? ' · 원격 기준 확인 필요' : '';
+        const versions = row.remoteVersion !== undefined ? ` · 기준 v${row.baselineVersion ?? '?'} / 원격 v${row.remoteVersion}` : '';
+        return `  ${selection} ${pathTone(row.path)} · ${row.unmapped ? '받기 미완료 · 원격 대조 필요' : row.remoteState === 'new' ? '원격 신규' : row.renamed ? '로컬 경로 변경' : labels[row.status] ?? row.status}${gray(versions)}${yellow(remote)}`;
+    };
+    for (const group of ['receive', 'conflict', 'attention', 'send']) {
+        const rows = view.rows.filter(row => changeGroup(row) === group).sort((a, b) => a.path.localeCompare(b.path));
+        if (!rows.length)
+            continue;
+        console.log(`\n${bold(tones[group](titles[group] + ` (${rows.length}개)`))}`);
+        for (const row of rows) {
+            console.log(detail(row));
+            if (row.status === 'unavailable' && row.remoteState !== 'new' && row.pageId && !view.rows.some(other => other !== row && other.pageId === row.pageId && other.status !== 'unavailable')) {
+                try {
+                    lstatSync(resolve(base, row.path));
+                }
+                catch (error) {
+                    if (error.code === 'ENOENT')
+                        console.log(`    원격에서 복구: ${cyan(`csync restore ${JSON.stringify(row.path)}`)}`);
+                }
+            }
+            if (group === 'conflict' || group === 'attention')
+                for (const reason of row.remoteReasons ?? [])
+                    console.log(dim(`    ${reason}`));
+        }
+    }
+    if (view.rows.every(row => changeGroup(row) === 'same'))
+        console.log(view.remoteCheckedAt ? green('\n마지막 조회 기준 표시할 변경이 없습니다.') : dim('\n로컬 변경이 없습니다. 원격 상태는 아직 확인하지 않았습니다.'));
+    const staged = view.rows.filter(row => row.staged);
+    const attention = staged.filter(row => row.stale || row.status === 'unavailable').length;
+    console.log(`\n${bold('업로드 선택:')} ${green(`${staged.length}개`)} · 재추가·파일 확인 필요: ${(attention ? yellow : gray)(`${attention}개`)}`);
+    if (view.rows.some(row => changeGroup(row) === 'receive'))
+        console.log(`받기: ${cyan('csync pull')} · 원격 신규·변경 문서 받기, 로컬 수정·삭제 보존`);
+    if (view.rows.some(row => changeGroup(row) === 'conflict'))
+        console.log(`${red('양쪽 변경:')} ${cyan('csync diff "문서.md" --remote')}로 비교하세요. 자동 병합·덮어쓰기는 하지 않습니다.`);
+    if (view.rows.some(row => row.status === 'unavailable' && row.remoteState !== 'new'))
+        console.log(yellow('로컬 파일 누락·제외는 원격 삭제로 반영하지 않습니다. 이동·제외 규칙과 파일 위치를 확인하세요.'));
+    console.log(`보내기: ${cyan('csync add <파일·폴더>')} → ${cyan('csync push --dry-run')} → ${cyan('csync push')}\n선택 해제: ${cyan('csync unstage <파일·폴더>')} · 원본 유지\n새 원격 문서 확인: ${cyan('csync fetch')}`);
+}