@restnfeel/agentc-starter-kit/docs/publish_guide.md

한국어 기업용 CMS 모듈 - Task Master AI와 함께 빠르게 웹사이트를 구현할 수 있는 재사용 가능한 컴포넌트 시스템

# 📦 agentc-starter-kit 퍼블리시 가이드

## 🚨 퍼블리시 전 필수 확인사항

### 1. 📋 버전 관리

- **패치 버전만 증가**: 현재 버전이 `1.3.0`이므로 `1.3.1`, `1.3.2`와 같이 **마지막 숫자만** 증가
- 메이저/마이너 버전 변경은 신중히 검토 후 결정
- `package.json`의 `version` 필드 확인

```json
{
  "version": "1.3.1" // 패치 버전만 증가
}
```

### 2. 🔧 빌드 및 패키지 처리

퍼블리시 전 반드시 다음 순서로 진행:

```bash
# 1. 패키지 빌드
npm run build:package

# 2. Git 상태 확인
git status

# 3. dist 폴더 하위 모든 변경사항 커밋
git add dist/
git commit -m "build: update dist files for v1.3.x"

# 4. 모든 변경사항 푸시
git push origin main
```

**⚠️ 중요**: `dist/` 폴더 하위 파일들이 Git에 남지 않도록 모두 푸시해야 함

### 3. ✅ Export 확인

새로 만든 컴포넌트들이 제대로 export되어 있는지 **반드시** 확인:

#### 3.1 메인 Export 파일들 확인

- `src/index.ts` - 클라이언트 컴포넌트 export
- `dist/server.esm/rag/index.js` - RAG 모듈 export
- `dist/esm/components/ui/index.js` - UI 컴포넌트 export

#### 3.2 Export 테스트 실행

```bash
# 새 컴포넌트 import 테스트
node -e "
try {
  const { NewComponent } = require('./dist/esm/components/ui/index.js');
  console.log('✅ NewComponent export 성공');
} catch (error) {
  console.log('❌ Export 실패:', error.message);
}
"
```

#### 3.3 TypeScript 정의 확인

- `dist/index.d.ts` - 타입 정의 파일 확인
- 새 컴포넌트의 타입이 포함되어 있는지 확인

### 4. 📝 퍼블리시 체크리스트

퍼블리시 전 다음 항목들을 체크:

- [ ] 버전 번호 패치 증가 (`1.3.0` → `1.3.1`)
- [ ] `npm run build:package` 실행 완료
- [ ] `dist/` 폴더 모든 변경사항 Git 커밋
- [ ] Git 푸시 완료 (`git push origin main`)
- [ ] 새 컴포넌트 export 확인
- [ ] TypeScript 정의 파일 확인

### 5. 🚀 퍼블리시 명령어

모든 확인이 완료되면:

```bash
# NPM 퍼블리시
npm publish

# 또는 특정 태그로 퍼블리시
npm publish --tag latest
```

### 6. 📋 퍼블리시 후 확인사항

- [ ] NPM 레지스트리에서 새 버전 확인
- [ ] 설치 테스트: `npm install @restnfeel/agentc-starter-kit@latest`
- [ ] 새 기능 동작 확인
- [ ] 문서 업데이트 (필요시)

## ⚠️ 주의사항

1. **절대 메이저/마이너 버전을 임의로 올리지 말 것**
2. **dist 폴더 변경사항을 푸시하지 않으면 빌드된 내용이 반영되지 않음**
3. **새 컴포넌트 export 누락 시 사용자가 import할 수 없음**
4. **퍼블리시 전 반드시 로컬에서 테스트 완료할 것**

## 🔄 롤백 방법

문제 발생 시:

```bash
# 특정 버전으로 롤백
npm unpublish @restnfeel/agentc-starter-kit@1.3.1

# 또는 deprecate 처리
npm deprecate @restnfeel/agentc-starter-kit@1.3.1 "버그로 인한 롤백"
```

---

**마지막 업데이트**: 2024년 12월 (RAG 모듈 export 수정 반영)