npm package: @howuchoi/blog-cli
Description: 블로그 포스트 작성을 자동화하는 CLI 툴
Author: Howu
Latest version: 1.0.0

# 블로그 포스트 작성 CLI 툴

## 📋 프로젝트 개요

블로그 포스트 작성을 자동화하는 CLI 툴로, 폴더 생성부터 frontmatter 작성, 이미지 관리까지 한 번에 처리합니다.

## 🚀 빠른 시작

### 1. 설치

```bash
npm install
```

### 2. 설정 파일 생성

```bash
cp .blogrc.json.example .blogrc.json
```

### 3. 첫 포스트 생성

```bash
npm run blog create
```

### 4. 포스트 목록 확인

```bash
npm run blog list
```

## 📖 문서

- **[상세 사용 가이드](./USAGE_GUIDE.md)** - 모든 명령어와 옵션에 대한 자세한 설명
- **[구현 계획서](./IMPLEMENTATION_PLAN.md)** - 개발 계획 및 단계별 진행 상황

## 🎯 목표

- 포스트 작성 프로세스 자동화
- 실수 방지 (폴더/파일 이름 일치, frontmatter 형식 등)
- 빠른 포스트 생성
- 일관된 포스트 구조 유지

## 🏗️ 프로젝트 구조

```
blog-cli/
├── src/
│   ├── commands/
│   │   ├── create.ts          # 포스트 생성
│   │   ├── list.ts            # 포스트 목록
│   │   ├── edit.ts            # 포스트 편집
│   │   ├── delete.ts          # 포스트 삭제
│   │   ├── thumbnail.ts       # 썸네일 관리
│   │   └── image.ts           # 이미지 관리
│   ├── utils/
│   │   ├── slug.ts            # slug 생성/검증
│   │   ├── frontmatter.ts     # frontmatter 생성/파싱
│   │   ├── file.ts            # 파일 시스템 작업
│   │   └── template.ts        # 마크다운 템플릿
│   ├── config/
│   │   └── default.ts         # 기본 설정
│   └── index.ts               # CLI 진입점
├── templates/
│   └── post.md                # 포스트 템플릿
├── .blogrc.json               # 사용자 설정 파일
├── package.json
└── tsconfig.json
```

## 🛠️ 기술 스택

### 핵심 라이브러리

- **Commander.js** 또는 **yargs**: CLI 프레임워크
  - 명령어 파싱, 옵션 처리
  - 도움말 자동 생성
- **inquirer.js**: 인터랙티브 프롬프트
  - 사용자 입력 받기
  - 선택지 제공
- **chalk**: 터미널 색상
  - 성공/에러 메시지 스타일링
- **ora**: 로딩 스피너
  - 작업 진행 상황 표시
- **gray-matter**: frontmatter 파싱
  - 기존 프로젝트에서 사용 중이므로 재사용 가능

### 추가 라이브러리 (선택사항)

- **sharp**: 이미지 리사이징/최적화
  - 썸네일 자동 생성
  - 이미지 압축
- **date-fns**: 날짜 처리
  - 날짜 형식 검증/변환
- **fs-extra**: 파일 시스템 확장
  - 디렉토리 생성, 파일 복사 등

## 📝 주요 기능

### 1. 포스트 생성 (`create`)

**기본 사용법:**

```bash
npm run blog create
# 또는
npm run blog create "Next.js 가이드"
```

**인터랙티브 모드:**

1. 제목 입력 → slug 자동 생성 (제안)
2. slug 확인/수정
3. excerpt 입력
4. category 선택 (기존 카테고리 목록 표시)
5. tags 입력 (콤마 구분 또는 여러 번 입력)
6. publishedAt 입력 (기본값: 오늘 날짜)
7. 썸네일 추가 여부
8. 템플릿 선택 (기본/빈 파일)

**결과:**

- `public/posts/{slug}/` 폴더 생성
- `{slug}.md` 파일 생성 (frontmatter 포함)
- `imgs/` 폴더 생성
- 성공 메시지 및 다음 단계 안내

**옵션:**

```bash
--title, -t        # 제목 (비인터랙티브 모드)
--slug, -s         # slug (기본값: 제목에서 자동 생성)
--excerpt, -e      # 요약
--category, -c     # 카테고리
--tags             # 태그 (콤마 구분)
--date, -d         # 발행일 (YYYY-MM-DD)
--template         # 템플릿 선택
--no-thumbnail     # 썸네일 폴더 생성 안 함
```

### 2. 포스트 목록 (`list`)

**기본 사용법:**

```bash
npm run blog list
```

**출력 예시:**

```
📝 블로그 포스트 목록 (5개)

1. nextjs-fsd-guide
   제목: Next.js와 FSD 아키텍처
   카테고리: 개발
   발행일: 2024-12-15
   태그: Next.js, FSD, Architecture

2. typescript-tips
   제목: TypeScript 팁 모음
   카테고리: 개발
   발행일: 2024-12-10
   태그: TypeScript

...
```

**옵션:**

```bash
--category, -c     # 카테고리별 필터링
--tag, -t          # 태그별 필터링
--sort             # 정렬 (date, title)
--format           # 출력 형식 (table, json, simple)
```

### 3. 포스트 편집 (`edit`)

**기본 사용법:**

```bash
npm run blog edit nextjs-fsd-guide
```

**기능:**

- frontmatter 필드 수정
- 제목, excerpt, category, tags 등
- 마크다운 파일 열기 (기본 에디터)

**옵션:**

```bash
--field, -f        # 특정 필드만 수정
--editor           # 에디터 지정
```

### 4. 포스트 삭제 (`delete`)

**기본 사용법:**

```bash
npm run blog delete nextjs-fsd-guide
```

**기능:**

- 확인 프롬프트
- 폴더 전체 삭제
- 삭제 전 백업 옵션

**옵션:**

```bash
--force, -f        # 확인 없이 삭제
--backup           # 삭제 전 백업
```

### 5. 썸네일 관리 (`thumbnail`)

**기본 사용법:**

```bash
npm run blog thumbnail nextjs-fsd-guide
```

**기능:**

- 이미지 파일 선택
- 자동 리사이징 (400x400px 권장)
- `thumbnail.png`로 복사/이동
- 기존 썸네일 덮어쓰기 확인

**옵션:**

```bash
--path, -p         # 이미지 경로 직접 지정
--resize           # 리사이징 옵션 (400x400, 800x800 등)
--no-resize        # 리사이징 안 함
```

### 6. 이미지 관리 (`image`)

**기본 사용법:**

```bash
npm run blog image add nextjs-fsd-guide ./my-image.png
```

**기능:**

- 이미지를 `imgs/` 폴더로 복사
- 중복 파일명 처리
- 이미지 최적화 옵션
- 이미지 목록 보기

**서브 명령어:**

```bash
add <slug> <image>  # 이미지 추가
list <slug>         # 이미지 목록
remove <slug> <image> # 이미지 삭제
optimize <slug>     # 모든 이미지 최적화
```

## ⚙️ 설정 파일 (`.blogrc.json`)

프로젝트 루트에 설정 파일 생성:

```json
{
  "postsDirectory": "public/posts",
  "defaultAuthor": "Howu",
  "defaultCategory": "개발",
  "defaultTags": [],
  "thumbnailSize": {
    "width": 400,
    "height": 400
  },
  "imageOptimization": {
    "enabled": true,
    "quality": 80,
    "format": "webp"
  },
  "editor": "code", // VS Code, vim, nano 등
  "templates": {
    "default": "templates/post.md",
    "custom": "templates/custom.md"
  }
}
```

## 📄 템플릿 시스템

### 기본 템플릿 (`templates/post.md`)

```markdown
---
title: "{{title}}"
excerpt: "{{excerpt}}"
publishedAt: "{{publishedAt}}"
category: "{{category}}"
tags: { { tags } }
---

## 소개

{{excerpt}}

## 본문

여기에 포스트 내용을 작성하세요.

## 결론

마무리 내용을 작성하세요.
```

### 커스텀 템플릿 지원

사용자가 자신만의 템플릿을 만들 수 있도록 지원.

## 🎨 사용자 경험 (UX)

### 1. 인터랙티브 모드

- 명령어만 입력하면 단계별 프롬프트
- 이전 값 수정 가능
- 기본값 제공으로 빠른 입력

### 2. 비인터랙티브 모드

- 모든 옵션을 명령줄에서 제공
- 스크립트/자동화에 적합

### 3. 에러 처리

- 명확한 에러 메시지
- 해결 방법 제안
- 롤백 기능 (실패 시 생성한 파일 삭제)

### 4. 검증

- slug 형식 검증 (영문, 숫자, 하이픈만)
- 날짜 형식 검증 (YYYY-MM-DD)
- 중복 slug 확인
- 필수 필드 확인

## 📦 패키지 스크립트

`package.json`에 추가:

```json
{
  "scripts": {
    "blog": "tsx src/index.ts",
    "blog:create": "tsx src/index.ts create",
    "blog:list": "tsx src/index.ts list",
    "blog:edit": "tsx src/index.ts edit",
    "blog:delete": "tsx src/index.ts delete"
  }
}
```

## 🚀 구현 단계

### Phase 1: 기본 기능 (MVP)

1. ✅ 포스트 생성 (`create`)

   - 폴더/파일 생성
   - 기본 frontmatter 생성
   - slug 검증

2. ✅ 포스트 목록 (`list`)
   - 기존 포스트 읽기
   - 간단한 목록 출력

### Phase 2: 편집 기능

3. ✅ 포스트 편집 (`edit`)

   - frontmatter 수정
   - 에디터 열기

4. ✅ 포스트 삭제 (`delete`)
   - 안전한 삭제 (확인)

### Phase 3: 이미지 관리

5. ✅ 썸네일 관리 (`thumbnail`)

   - 이미지 추가
   - 자동 리사이징

6. ✅ 이미지 관리 (`image`)
   - 이미지 추가/삭제
   - 최적화

### Phase 4: 고급 기능

7. ✅ 템플릿 시스템

   - 커스텀 템플릿
   - 여러 템플릿 지원

8. ✅ 검증 및 검사

   - 포스트 유효성 검사
   - 누락된 필드 확인
   - 이미지 경로 검증

9. ✅ 통계 및 분석
   - 포스트 통계
   - 카테고리/태그 분석

## 🔧 기술적 고려사항

### 1. slug 생성 로직

```typescript
function generateSlug(title: string): string {
  return title
    .toLowerCase()
    .replace(/[^\w\s-]/g, "") // 특수문자 제거
    .replace(/\s+/g, "-") // 공백을 하이픈으로
    .replace(/-+/g, "-") // 연속 하이픈 제거
    .trim();
}
```

### 2. frontmatter 생성

```typescript
function generateFrontmatter(data: {
  title: string;
  excerpt: string;
  publishedAt: string;
  category?: string;
  tags?: string[];
  thumbnail?: string;
}): string {
  return matter.stringify("", data);
}
```

### 3. 파일 시스템 작업

- 비동기 처리 (`fs/promises`)
- 에러 핸들링
- 트랜잭션 처리 (실패 시 롤백)

### 4. 설정 파일 관리

- 기본값 제공
- 사용자 설정 병합
- 설정 검증

## 📚 사용 예시

### 시나리오 1: 새 포스트 작성

```bash
$ npm run blog create

? 포스트 제목: Next.js와 FSD 아키텍처
? slug (nextjs-fsd-architecture): [Enter]
? 요약: Feature-Sliced Design을 Next.js에 적용하는 방법
? 카테고리: 개발
? 태그 (콤마 구분): Next.js, FSD, Architecture
? 발행일 (2024-12-15): [Enter]
? 썸네일을 추가하시겠습니까? (y/N): y
? 썸네일 이미지 경로: ./thumbnail.png

✅ 포스트가 생성되었습니다!
📁 위치: public/posts/nextjs-fsd-architecture/
📝 파일: nextjs-fsd-architecture.md
🖼️ 썸네일: thumbnail.png

다음 단계:
1. 마크다운 파일을 편집하세요
2. 이미지를 imgs/ 폴더에 추가하세요
3. npm run dev로 확인하세요
```

### 시나리오 2: 빠른 생성 (옵션 사용)

```bash
$ npm run blog create \
  --title "TypeScript 팁" \
  --category "개발" \
  --tags "TypeScript,JavaScript" \
  --date "2024-12-15"

✅ 포스트가 생성되었습니다!
📁 위치: public/posts/typescript-tips/
```

### 시나리오 3: 포스트 목록 확인

```bash
$ npm run blog list

📝 블로그 포스트 목록 (3개)

1. nextjs-fsd-guide
   제목: Next.js와 FSD 아키텍처
   카테고리: 개발
   발행일: 2024-12-15

2. typescript-tips
   제목: TypeScript 팁
   카테고리: 개발
   발행일: 2024-12-10

3. daily-log
   제목: 일상 기록
   카테고리: 일상
   발행일: 2024-12-05
```

## 🎯 확장 가능성

### 향후 추가 가능한 기능

1. **마이그레이션 도구**

   - 다른 블로그 플랫폼에서 가져오기
   - 포맷 변환

2. **배치 작업**

   - 여러 포스트 한 번에 생성
   - 일괄 수정

3. **검색 기능**

   - 포스트 내용 검색
   - 태그/카테고리 검색

4. **통계 대시보드**

   - 포스트 수, 카테고리 분포
   - 태그 클라우드

5. **자동화 스크립트**
   - 새 포스트 알림
   - 자동 배포 트리거

## 📋 체크리스트

### 개발 전

- [ ] 프로젝트 구조 설계
- [ ] 기술 스택 결정
- [ ] 사용자 시나리오 정의
- [ ] API 설계

### 개발 중

- [ ] 기본 명령어 구현
- [ ] 에러 처리
- [ ] 테스트 작성
- [ ] 문서화

### 배포 전

- [ ] 사용자 테스트
- [ ] 버그 수정
- [ ] 성능 최적화
- [ ] README 작성

## 💡 참고사항

- 기존 프로젝트의 `gray-matter` 라이브러리 재사용
- `shared/lib/markdown.ts`의 로직 참고
- TypeScript로 타입 안정성 확보
- 에러 메시지는 한국어로 제공 (선택 가능)

## 📚 추가 문서

- **[사용 가이드](./USAGE_GUIDE.md)** - 상세한 사용법 및 문제 해결 가이드
- **[배포 가이드](./DEPLOYMENT.md)** - npm 패키지 배포 및 설치 방법
- **[구현 계획서](./IMPLEMENTATION_PLAN.md)** - 개발 계획 및 단계별 진행 상황
- **[프로젝트 요약](./PROJECT_SUMMARY.md)** - 프로젝트 현황 및 통계

## ✅ 완성된 기능

### Phase 0: 프로젝트 초기 설정 ✅

- 프로젝트 구조 생성
- 의존성 설치
- 기본 CLI 프레임워크

### Phase 1: 기본 기능 (MVP) ✅

- 포스트 생성 (`create`)
- 포스트 목록 (`list`)

### Phase 2: 편집 기능 ✅

- 포스트 편집 (`edit`)
- 포스트 삭제 (`delete`)

### Phase 3: 이미지 관리 ✅

- 썸네일 관리 (`thumbnail`)
- 이미지 관리 (`image`)

### Phase 4: 고급 기능 ✅

- 포스트 검증 (`validate`)
- 통계 조회 (`stats`)

## 🎉 프로젝트 완료!

모든 계획된 기능이 구현되었습니다. 이제 블로그 포스트 작성을 더욱 효율적으로 관리할 수 있습니다!