nconv-cli 1.0.0 → 1.0.3

package/.claude/settings.local.json

@@ -6,7 +6,13 @@
       "Bash(chmod:*)",
       "Bash(npm run build:*)",
       "Bash(npm link:*)",
-      "Bash(notion-convertor:*)"
+      "Bash(notion-convertor:*)",
+      "Bash(npm install:*)",
+      "Bash(npm uninstall:*)",
+      "Bash(npx patch-package:*)",
+      "Bash(npx tsx:*)",
+      "Bash(node dist/index.js:*)",
+      "Bash(npm info:*)"
     ]
   }
 }

package/GITHUB_ABOUT.md

@@ -0,0 +1,53 @@
+# GitHub About / Description
+
+## English
+
+### Short (160 characters max - for GitHub About field)
+```
+A CLI tool to convert Notion pages into blog-ready Markdown, HTML, and PDF with automatic image handling and beautiful formatting
+```
+
+### Alternative (shorter)
+```
+Convert Notion pages to Markdown, HTML, PDF with auto image processing - ready to publish
+```
+
+### Tags/Topics
+```
+notion
+markdown
+html
+pdf
+converter
+cli
+blog
+exporter
+typescript
+notion-api
+```
+
+---
+
+## 한국어
+
+### Short (GitHub About용)
+```
+Notion 페이지를 블로그용 Markdown, HTML, PDF로 변환하는 CLI 도구 (이미지 자동 처리 및 아름다운 포맷팅)
+```
+
+### Alternative (짧은 버전)
+```
+Notion을 Markdown, HTML, PDF로 변환 - 이미지 자동 처리, 즉시 게시 가능
+```
+
+---
+
+## Key Differentiators (vs notion-exporter)
+
+**nconv-cli advantages:**
+- ✅ Multiple formats: Markdown + HTML + PDF (notion-exporter: MD + CSV only)
+- ✅ Perfect image handling: Local download + base64 embed in PDF (notion-exporter: no image processing)
+- ✅ Blog-ready structure: Post-level directories (notion-exporter: flat export)
+- ✅ Interactive TUI: Slash commands interface (notion-exporter: CLI only)
+- ✅ Beautiful PDF: GitHub-styled with embedded images (notion-exporter: no PDF)
+- ✅ Zero post-processing: Ready to publish (notion-exporter: requires manual organization)

package/README.md

@@ -1,196 +1,350 @@
-<p align="right">
-  <a href="./README.en.md">English</a>
+
+<p align="center">
+<a href="#-nconv-cli-english">English</a> | <a href="#-nconv-cli-한국어">한국어</a>
 </p>
 
-# nconv-cli (Notion Convertor CLI)
+---
 
-> Notion 글을 블로그에 바로 올릴 수 있는 마크다운으로 변환하는 CLI  
-> (이미지 자동 추출 및 경로 정리 포함)
+<div id="-nconv-cli-english">
 
-Notion 퍼블릭 페이지를 마크다운으로 변환하고  
-이미지 파일을 로컬로 추출해 블로그 친화적인 구조로 정리해주는 CLI 도구입니다.
+# 🚀 nconv-cli (Notion Converter CLI)
 
-## 특징
+> **Faster Workflow**: A CLI tool that automatically convert Notion pages into Markdown, HTML, and PDF.
+> Stop wasting time unzipping files and fixing broken image paths manually.
 
-- 🚀 Notion 퍼블릭 페이지를 블로그용 마크다운으로 바로 변환
-- 🖼️ 이미지 파일을 로컬로 자동 다운로드 및 상대경로로 변환
-- 📁 게시글 단위로 정리된 출력 디렉토리 구조
-- 🎨 간단한 CLI 인터페이스
 
+---
 
+## 1. Quick Start
 
-## 기존 Notion -> Markdown 변환의 문제점
+Choose your preferred way to work: **Interactive TUI** for easy setup or **Direct CLI** for speed.
 
-Notion에서 작성한 글을 블로그에 옮길 때,
-단순한 복사/붙여넣기나 기본 Markdown export는 포스팅에 불편함이 있습니다.
+### **Option A: Interactive TUI (Recommended for First-time)**
 
-* 복사 & 붙여넣기 방식의 문제점
-  * 마크다운 식으로 텍스트는 변환되지만,
-  * 이미지는 Notion CDN URL로 유지되며
-  * Access Denied 로 이미지 접근이 깨지는 경우가 많습니다
+Enter a Claude Code-style shell to manage settings and convert multiple pages easily.
 
-* Notion Markdown Export 방식의 문제점
-  * 직접 다운받아서 수동으로 저장 후 압축을 해제해야하며,
-  * 게시글 단위로 정리하기 어렵습니다
+```bash
+# 1. Install globally
+npm install -g nconv-cli
 
-결과적으로 블로그에 게시하려면 이미지 개별 다운로드,
-파일명 및 경로 수정, 폴더 구조 재정리가 필요합니다.
+# 2. Enter Interactive Mode
+nconv
 
-| 방식 | 이미지 관리 | 블로그 사용성 |
-|------|------------|---------------|
-| 복사 & 붙여넣기 | ❌ Notion CDN 의존 | ❌ 이미지 깨짐 |
-| Notion Export | ⚠️ 수동 정리 필요 | ⚠️ 번거로움 |
-| **nconv-cli** | ✅ 로컬 자동 추출 | ✅ 즉시 사용 가능 |
+# 3. Setup environment & Convert (Inside TUI)
+nconv> /init           # Set your Notion tokens (Required once)
+nconv> /md <URL>       # Convert Notion page to Markdown
+nconv> /pdf <URL>      # Convert Notion page to PDF
 
-## 이런 분들에게 추천합니다
+```
 
-- Notion으로 글을 쓰고, Velog / Tistory / GitHub Pages / Hugo 등의 플랫폼에 마크다운으로 포스팅을 하시는 분
-- Notion 이미지 CDN 문제로 글이 깨져본 경험이 있는 분
-- 노션 문서 체계를 옵시디언 등으로 마이그레이션하기 원하시는 분
+### **Option B: Direct CLI**
 
+Instantly convert pages with one line. Perfect for scripts and automation.
 
-## 환경
-- **Node.js**: v20 이상 (npm v10 이상)
-- **TypeScript**: v5 이상
+```bash
+# Basic Markdown conversion
+nconv md "https://notion.so/your-page-url"
 
-## 설치
+nconv md "URL"
 
-```bash
-# 의존성 설치
-npm install
+# Generate a professional GitHub-style PDF
+nconv pdf "URL"
 
-# 빌드
-npm run build
+# Advanced: Save to ./blog as 'my-post.md' with images in 'assets'
+nconv md "URL" -o ./blog -f my-post -i assets
+
+# Bulk Conversion: Convert multiple links at once using a simple shell loop
+urls=("URL_1" "URL_2" "URL_3")
+for url in "${urls[@]}"; do nconv md "$url" -o ./dist; done
 
-# 로컬에 CLI 설치
-npm link
 ```
 
-## 설정
+## 2. Configuration & Requirements
+
+* **Public Page (Required)**: Your Notion page must be **"Published to web"** (Share -> Publish).
+* **Tokens**: Run `nconv init` to set `TOKEN_V2` and `FILE_TOKEN` (found in your browser's notion.so cookies).
+
+### How to Find Your Notion Tokens
+
+1.  Log in to [notion.so](https://notion.so) in your browser.
+2.  Open your browser's developer tools (usually F12).
+3.  Go to the "Application" tab.
+4.  Select `https://www.notion.so` under the "Cookies" section.
+5.  Copy the value of the `token_v2` cookie and paste it into the `TOKEN_V2` field.
+6.  Copy the value of the `file_token` cookie and paste it into the `FILE_TOKEN` field.
+
+## 3. Core Features
+
+- ⚡️ **Faster Workflow**: Creates a ready-to-publish structure with automatic image downloads and relative path conversion.
+- 🎨 **Multi-format Support**:
+    - **Markdown**: Optimized for static site generators (Hugo, Jekyll) and tech blogs (Velog, Tistory).
+    - **HTML**: Perfect for quick web sharing and style previews.
+    - **PDF**: Clean, professional archiving with GitHub-style CSS formatting.
+- 🖼️ **Smart Image Handling**:
+    - **Markdown/HTML**: Extracts images locally and auto-updates internal paths.
+    - **PDF**: Encodes all images to **Base64** to prevent resource loss within a single file.
+- ✨ **Zero Manual Work**: No more manual renaming or fixing broken image paths.
+- 💬 **Interactive TUI**: Provides a **Claude Code style** slash command interface.
+- 📁 **Better Organization**: Automatically creates separate folders for each document title.
+## 4. Why nconv-cli?
+
+|  | Copy & Paste | Default Export | **nconv-cli** |
+| --- | --- | --- | --- |
+| **Images** | ❌ Broken Links | ⚠️ Manual Cleanup | **✅ Auto Download** |
+| **Paths** | ❌ Manual Fix | ⚠️ Manual Fix | **✅ Auto Fix** |
+| **Speed** | ❌ Slow | ⚠️ Annoying | **🚀 Fast & Easy** |
+
+## 5. Recommended For
+
+- Users who write in Notion and post to **Velog, Tistory, GitHub Pages, Hugo, and more**.
+- Users who have experienced broken images due to Notion's private CDN issues.
+- Those migrating their Notion workspace to tools like **Obsidian, Bear, etc**.
+  
+## 6. Advanced TUI Usage (Interactive)
+
+The interactive mode (`nconv`) allows for more flexible control.
+
+* **Check Configuration & Get Help**:
+  ```bash
+  nconv> /config  # View current settings like TOKEN_V2.
+  nconv> /help    # See all available slash commands.
+  ```
+
+* **Convert with Options**:
+  In addition to basic commands, you can specify options like output directory (`-o`) and filename (`-f`).
+  ```bash
+  # Save Markdown to './blog' as 'my-post.md'
+  nconv> /md <URL> -o ./blog -f my-post
+
+  # Save PDF to './docs' as 'my-doc.pdf'
+  nconv> /pdf <URL> -o ./docs -f my-doc
+  ```
 
-`.env` 파일에 Notion 인증 토큰을 설정해야 합니다.
+## 7. Advanced CLI Usage (Direct)
+
+The CLI mode is powerful for scripting and automation. Combine options for fine-grained control.
+
+### CLI Options
+
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--output <dir>` | `-o` | Output directory | `./nconv-output` |
+| `--image-dir <dir>` | `-i` | Image folder name (relative to output) | `images` |
+| `--filename <name>` | `-f` | Output filename (without extension) | Extracted from URL |
+| `--verbose` | `-v` | Enable verbose logging | `false` |
+
+### CLI Combination Examples
 
 ```bash
-# .env 파일 생성
-cp .env.example .env
+# 1. HTML: Save to './web-dist' as 'index.html' with images in 'img'
+nconv html "URL" -o ./web-dist -f index -i img
+
+# 2. PDF: Save to './documents' as 'report.pdf' and enable verbose logs
+nconv pdf "URL" -o ./documents -f report -v
+
+# 3. Markdown (All Options): Save to './blog' as 'post-1.md' with images in 'assets'
+nconv md "URL" -o ./blog -i assets -f "post-1" -v
 ```
 
-`.env` 파일을 열고 아래 값들을 설정하세요:
+## 8. For Developers
+
+### **Project Structure**
+
+```text
+src/
+├── core/      # Notion export & Image logic
+├── commands/  # CLI command definitions
+├── repl/      # Interactive TUI mode
+└── utils/     # File & Logger helpers
 
 ```
-TOKEN_V2=your_token_v2_here
-FILE_TOKEN=your_file_token_here
+
+### **Contribution**
+
+```bash
+git clone https://github.com/itsme-shawn/nconv-cli.git
+npm install
+npm link
+npm run dev
+
 ```
 
-### Notion env 값 확인하는 방법
+</div>
+
+---
+
+<br>
+<p align="center">
+<a href="#-nconv-cli-english">English</a> | <a href="#-nconv-cli-한국어">한국어</a>
+</p>
+
+---
+
+<div id="-nconv-cli-한국어">
 
-1. [notion.so](https://notion.so)에 로그인
-2. 브라우저 개발자 도구 열기 (F12)
-3. Application > Cookies > notion.so
-4. `token_v2` 값 복사 → `.env`의 `TOKEN_V2`에 붙여넣기
-5. `file_token` 값 복사 → `.env`의 `FILE_TOKEN`에 붙여넣기
+# 🚀 nconv-cli (Notion Converter CLI)
 
-## 사용법
+> 노션 페이지를 CLI 도구를 통해 Markdown, HTML, PDF로 자동 변환합니다.
+> 수동으로 압축을 풀거나 깨진 이미지 경로를 수정하는 시간을 단축해줍니다.
 
-### 기본 사용법
+---
+
+## 1. 빠른 시작 (Quick Start)
+
+쉬운 설정을 위한 **대화형 TUI** 또는 빠른 작업을 위한 **CLI 직접 명령** 중 하나를 선택하세요.
+
+### **Option A: 대화형 TUI (처음 사용자 권장)**
+
+설정을 관리하고 여러 페이지를 쉽게 변환할 수 있는 Claude Code 스타일의 쉘에 진입합니다.
 
 ```bash
-nconv md <notion-url>
+# 1. 전역 설치
+npm install -g nconv-cli
+
+# 2. 대화형 모드 진입
+nconv
+
+# 3. 환경 설정 및 변환 (TUI 내부)
+nconv> /init           # 노션 토큰 설정 (최초 1회 필수)
+nconv> /md <URL>       # 노션 페이지를 마크다운으로 변환
+nconv> /pdf <URL>      # 노션 페이지를 PDF로 변환
+
 ```
 
-### 예시
+### **Option B: CLI 직접 명령**
+
+스크립트 작성이나 자동화에 최적화되어 있습니다.
 
 ```bash
-# 기본 사용 (./output 폴더에 저장)
-nconv md "https://notion.so/My-Page-abc123"
+# 기본 마크다운 변환
+nconv md "https://notion.so/페이지-URL"
 
-# 출력 디렉토리 지정
-nconv md "https://notion.so/My-Page-abc123" -o ./blog-posts
+# 마크다운 변환 실행
+nconv md "URL"
 
-# 커스텀 파일명
-nconv md "https://notion.so/My-Page-abc123" -f "my-article"
+# GitHub 스타일의 깔끔한 PDF 생성
+nconv pdf "URL"
 
-# 상세 로그 출력
-nconv md "https://notion.so/My-Page-abc123" -v
+# 고급설정: ./blog 폴더에 'my-post.md'로 저장하고 이미지는 'assets'에 수집
+nconv md "URL" -o ./blog -f my-post -i assets
+
+# 벌크 처리: 여러 링크를 한 번에 처리 (쉘 루프 활용)
+urls=("URL_1" "URL_2" "URL_3")
+for url in "${urls[@]}"; do nconv md "$url" -o ./dist; done
 
-# 모든 옵션 사용
-nconv md "https://notion.so/My-Page-abc123" -o ./blog -i assets -f "article-1" -v
 ```
 
-## 옵션
+## 2. 설정 및 주의사항
 
-| 옵션 | 단축 | 설명 | 기본값 |
-|------|------|------|--------|
-| `--output <dir>` | `-o` | 출력 디렉토리 | `./output` |
-| `--image-dir <dir>` | `-i` | 이미지 폴더명 (output 기준 상대경로) | `images` |
-| `--filename <name>` | `-f` | 출력 파일명 (확장자 제외 또는 포함) | URL에서 자동 추출 |
-| `--verbose` | `-v` | 상세 로그 출력 | `false` |
+* **공개 페이지 설정 (필수)**: 변환하려는 노션 페이지는 반드시 **"웹에 게시"** 상태여야 합니다 (공유 -> 게시).
+* **토큰 설정**: `nconv init`을 실행하여 `TOKEN_V2`와 `FILE_TOKEN`을 설정하세요 (브라우저의 notion.so 쿠키에서 확인 가능).
 
-## 출력 구조
+### Notion 토큰 값 확인하는 방법
 
-```
-output/
-├── my-article-folder/
-    ├── my-article.md          # 마크다운 파일
-    └── images/
-        ├── abc12345.png       # 다운로드된 이미지들
-        ├── def67890.jpg
-        └── ...
-```
+1. 브라우저에서 [notion.so](https://notion.so)에 로그인합니다.
+2. 브라우저 개발자 도구(보통 F12)를 엽니다.
+3. "Application" 탭으로 이동합니다.
+4. "Cookies" 섹션에서 `https://www.notion.so`를 선택합니다.
+5. `token_v2` 쿠키 값을 복사하여 `TOKEN_V2` 필드에 붙여넣습니다.
+6. `file_token` 쿠키 값을 복사하여 `FILE_TOKEN` 필드에 붙여넣습니다.
 
-마크다운 파일 내 이미지 경로는 상대경로로 변환됩니다:
+## 3. 주요 특징
 
-```markdown
-![image](./images/abc12345.png)
-```
+* ⚡️ **워크플로우 단축**: 이미지 자동 다운로드 및 상대 경로 변환을 통해 즉시 게시 가능한 구조를 생성합니다.
+* 🎨 **멀티 포맷 지원**:
+  * **Markdown**: 정적 사이트 생성기(Hugo, Jekyll) 및 기술 블로그(Velog, Tistory) 최적화.
+  * **HTML**: 빠른 웹 공유 및 스타일 확인용.
+  * **PDF**: GitHub 스타일 CSS가 적용된 깔끔한 배포/아카이빙용 문서.
+
+* 🖼️ **지능형 이미지 처리**:
+  * **Markdown/HTML**: 이미지를 로컬로 추출하고 문서 내 경로를 자동 업데이트합니다.
+  * **PDF**: 모든 이미지를 **Base64**로 인코딩하여 단일 파일 내에 포함합니다 (리소스 유실 방지).
+* ✨ **수동 작업 최소화**: 파일명 변경이나 깨진 이미지 경로 수정 등 반복적인 작업이 필요 없습니다.
+* 💬 **인터랙티브 TUI**: **Claude Code 스타일**의 슬래시 커맨드 인터페이스를 제공합니다.
+* 📁 **체계적 관리**: 문서 제목별로 독립된 폴더 구조를 자동으로 생성합니다.
+
+## 4. Why nconv-cli?
+
+| 비교 항목 | 단순 복사 & 붙여넣기 | 노션 기본 내보내기 | **nconv-cli** |
+| --- | --- | --- | --- |
+| **이미지 관리** | ❌ 링크 깨짐 발생 | ⚠️ 수동 정리 필요 | **✅ 로컬 자동 추출** |
+| **경로 설정** | ❌ 수동 수정 필요 | ⚠️ 수동 재설정 필요 | **✅ 경로 자동 최적화** |
+| **작업 속도** | ❌ 매우 느림 | ⚠️ 번거로운 프로세스 | **🚀 매우 빠르고 간편** |
+
+## 5. 이런 분들에게 추천합니다
+
+* 노션으로 글을 쓰고 **Velog, Tistory, GitHub Pages, Hugo 등**에 포스팅하는 개발자.
+* 노션 전용 이미지 CDN 문제로 블로그 이미지가 깨져본 경험이 있는 분.
+* 노션 문서 체계를 **Obsidian, Bear 등**의 도구로 마이그레이션하려는 분.
+
+## 6. TUI 고급 사용법 (대화형)
+
+`nconv`를 실행하면 나오는 대화형 모드에서는 더 많은 옵션을 활용할 수 있습니다.
 
-## 라이브러리
-### 주요 라이브러리
-- **notion-exporter**: Notion 페이지를 마크다운으로 내보내는 라이브러리
-- **commander**: CLI 명령 정의 및 파싱 도구
-- **axios**: HTTP 클라이언트 (이미지 다운로드 등)
-- **dotenv**: 환경 변수 관리
-- **chalk**: 터미널 출력 색상화
-- **ora**: 터미널 스피너 (진행 상황 표시)
-- **slugify**: 문자열을 URL 슬러그로 변환
-- **uuid**: 고유 ID 생성
+* **설정 확인 및 도움말 보기**:
+  ```bash
+  nconv> /config  # 현재 TOKEN_V2 등 설정 값을 확인합니다.
+  nconv> /help    # 사용 가능한 모든 명령어를 봅니다.
+  ```
 
-### 오픈소스 라이선스
-- **nconv-cli**: [ISC License](LICENSE)
-- 본 프로젝트는 위에 명시된 주요 라이브러리 외에도 다수의 오픈소스 라이브러리를 사용하며, 각 라이브러리는 해당 라이선스 정책을 따릅니다.
+* **옵션을 포함한 변환**:
+  Quick Start에서 소개된 기본 변환 외에도, 출력 경로(`-o`), 파일명(`-f`) 등을 자유롭게 지정할 수 있습니다.
+  ```bash
+  # 마크다운을 'blog' 폴더에 'my-post.md'로 저장
+  nconv> /md <URL> -o ./blog -f my-post
 
-## 개발
+  # PDF를 'docs' 폴더에 'my-doc.pdf'로 저장
+  nconv> /pdf <URL> -o ./docs -f my-doc
+  ```
+
+## 7. CLI 고급 사용법 (직접 명령)
+
+### CLI 옵션
+
+| 옵션 | 단축 | 설명 | 기본값 |
+|---|---|---|---|
+| `--output <dir>` | `-o` | 결과물이 저장될 폴더 | `./nconv-output` |
+| `--image-dir <dir>` | `-i` | 이미지가 저장될 폴더 (output 폴더 기준 상대 경로) | `images` |
+| `--filename <name>` | `-f` | 확장자를 제외한 파일명 | 페이지 URL에서 추출 |
+| `--verbose` | `-v` | 상세 로그를 출력 | `false` |
+
+### CLI 조합 예시
 
 ```bash
-# 개발 모드 (파일 변경 감지)
-npm run dev
+# 1. HTML 변환: 'web-dist' 폴더에 'index.html'로 저장하고 이미지 폴더는 'img'로 지정
+nconv html "URL" -o ./web-dist -f index -i img
 
-# 빌드
-npm run build
+# 2. PDF 변환: 'documents' 폴더에 'report.pdf'로 저장하고 상세 로그 출력
+nconv pdf "URL" -o ./documents -f report -v
 
-# 로컬 테스트
-npm link
-nconv md "https://notion.so/test-page"
+# 3. 마크다운 변환: 모든 옵션 조합
+# './blog' 폴더 아래 'assets'에 이미지를 저장하고 'post-1.md'로 결과물 생성
+nconv md "URL" -o ./blog -i assets -f "post-1" -v
 ```
 
-## 프로젝트 구조
+## 8. 개발자를 위한 안내
+
+### **프로젝트 구조**
+
+```text
+src/
+├── core/      # 노션 내보내기 및 이미지 처리 핵심 로직
+├── commands/  # CLI 명령어 정의 (init, md, html 등)
+├── repl/      # 인터랙티브 TUI 모드 구현부
+└── utils/     # 파일 시스템 및 로거 유틸리티
 
 ```
-nconv/
-├── src/
-│   ├── index.ts              # CLI 진입점
-│   ├── config.ts             # 설정 관리
-│   ├── commands/
-│   │   └── md.ts             # md 명령어
-│   ├── core/
-│   │   ├── exporter.ts       # Notion 내보내기
-│   │   └── image-processor.ts # 이미지 처리
-│   └── utils/
-│       ├── file.ts           # 파일 유틸리티
-│       └── logger.ts         # 로깅
-├── bin/
-│   └── nconv.js   # 실행 파일
-├── package.json
-├── tsconfig.json
-└── tsup.config.ts
+
+### **기여 방법**
+
+```bash
+git clone https://github.com/itsme-shawn/nconv-cli.git
+npm install
+npm link
+npm run dev
+
 ```
+
+</div>
+
+