tylersong 1.0.9 → 1.0.10

package/docs/development.md

@@ -0,0 +1,394 @@
+# 개발 가이드
+
+## 개발 환경 요구사항
+
+### 필수 요구사항
+
+- **Node.js**: 18.x 이상
+- **Bun**: 최신 버전 (권장)
+- **Git**: 버전 관리
+- **에디터**: VS Code 또는 기타 TypeScript 지원 에디터
+
+### Bun 설치
+
+```bash
+# macOS/Linux
+curl -fsSL https://bun.sh/install | bash
+
+# Windows (PowerShell)
+powershell -c "irm bun.sh/install.ps1 | iex"
+
+# 또는 npm을 통해
+npm install -g bun
+```
+
+## 프로젝트 설정
+
+### 1. 저장소 클론
+
+```bash
+git clone https://github.com/alstjd0051/npm_readMe.git
+cd npm_readMe
+```
+
+### 2. 의존성 설치
+
+```bash
+# Bun 사용 (권장)
+bun install
+
+# 또는 npm 사용
+npm install
+```
+
+### 3. 개발 서버 실행
+
+```bash
+# Bun으로 직접 실행
+bun run dev:bun
+
+# 또는 tsx 사용
+bun run dev
+```
+
+## 프로젝트 구조
+
+```
+npm_readMe/
+├── .github/
+│   └── workflows/          # GitHub Actions 워크플로우
+│       ├── ci.yml          # 지속적 통합
+│       └── publish.yml     # NPM 배포
+├── docs/                   # 문서
+│   ├── testing.md          # 테스트 가이드
+│   ├── pipeline.md         # CI/CD 파이프라인
+│   ├── development.md      # 개발 가이드 (이 파일)
+│   └── ...
+├── src/
+│   └── index.ts            # 메인 소스 코드
+├── test/
+│   └── index.test.ts       # 테스트 파일
+├── dist/                   # 빌드 출력 (gitignore)
+├── .eslintrc.json          # ESLint 설정
+├── .prettierrc             # Prettier 설정
+├── .editorconfig           # 에디터 설정
+├── .gitignore              # Git ignore 규칙
+├── vitest.config.ts        # Vitest 설정
+├── tsconfig.json           # TypeScript 설정
+├── bunfig.toml             # Bun 설정
+├── package.json            # 패키지 정보
+└── README.md               # 프로젝트 README
+```
+
+## 개발 워크플로우
+
+### 1. 기능 개발
+
+```bash
+# 1. 새 브랜치 생성
+git checkout -b feature/new-feature
+
+# 2. 코드 작성
+# src/index.ts 수정
+
+# 3. 타입 체크
+bun run typecheck
+
+# 4. 린트
+bun run lint:fix
+
+# 5. 테스트 작성 및 실행
+# test/index.test.ts 작성
+bun run test
+
+# 6. 로컬 테스트
+bun run dev:bun
+
+# 7. 커밋
+git add .
+git commit -m "feat: 새 기능 추가"
+
+# 8. 푸시 및 PR 생성
+git push origin feature/new-feature
+```
+
+### 2. 버그 수정
+
+```bash
+# 1. 버그 재현 테스트 작성
+# test/index.test.ts에 실패하는 테스트 추가
+
+# 2. 코드 수정
+# src/index.ts 수정
+
+# 3. 테스트 통과 확인
+bun run test
+
+# 4. 커밋
+git commit -m "fix: 버그 수정"
+```
+
+## 코드 스타일 가이드
+
+### TypeScript 규칙
+
+1. **타입 명시**
+   ```typescript
+   // ✅ 좋은 예
+   const openUrl = (url: string): void => {
+     // ...
+   };
+
+   // ❌ 나쁜 예
+   const openUrl = (url) => {
+     // ...
+   };
+   ```
+
+2. **인터페이스 정의**
+   ```typescript
+   // ✅ 좋은 예
+   interface UserAnswer {
+     showInfo: boolean;
+   }
+
+   // ❌ 나쁜 예
+   type UserAnswer = {
+     showInfo: boolean;
+   };  // 객체 타입에는 interface 선호
+   ```
+
+3. **에러 핸들링**
+   ```typescript
+   // ✅ 좋은 예
+   try {
+     // 위험한 작업
+   } catch (error) {
+     if (error instanceof Error) {
+       console.error(error.message);
+     }
+   }
+
+   // ❌ 나쁜 예
+   try {
+     // 위험한 작업
+   } catch (error) {
+     console.error(error);  // 타입 체크 없음
+   }
+   ```
+
+### 네이밍 컨벤션
+
+- **변수/함수**: camelCase (`openUrl`, `getUserInfo`)
+- **타입/인터페이스**: PascalCase (`UserAnswer`, `ProgramOptions`)
+- **상수**: UPPER_SNAKE_CASE (`MAX_RETRIES`, `DEFAULT_TIMEOUT`)
+- **파일명**: kebab-case (`index.ts`, `user-utils.ts`)
+
+### 코드 포맷팅
+
+Prettier가 자동으로 처리하지만, 기본 규칙:
+
+- **들여쓰기**: 2 스페이스
+- **세미콜론**: 사용
+- **따옴표**: 쌍따옴표 (")
+- **줄 길이**: 80자
+- **후행 쉼표**: ES5 호환
+
+## 테스트 작성
+
+### 단위 테스트
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('함수명', () => {
+  it('특정 조건에서 기대되는 동작을 해야 함', () => {
+    // Arrange
+    const input = 'test';
+    
+    // Act
+    const result = someFunction(input);
+    
+    // Assert
+    expect(result).toBe('expected');
+  });
+});
+```
+
+### 통합 테스트
+
+```typescript
+describe('CLI 통합 테스트', () => {
+  it('전체 플로우가 정상 작동해야 함', async () => {
+    // CLI 실행 시뮬레이션
+    // 여러 컴포넌트 통합 테스트
+  });
+});
+```
+
+## 디버깅
+
+### VS Code 디버깅 설정
+
+`.vscode/launch.json` 생성:
+
+```json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug TypeScript",
+      "runtimeExecutable": "bun",
+      "runtimeArgs": ["run", "src/index.ts"],
+      "skipFiles": ["<node_internals>/**"]
+    }
+  ]
+}
+```
+
+### 콘솔 디버깅
+
+```typescript
+// 개발 중에만 사용
+console.log(chalk.gray('[DEBUG]'), variableName);
+```
+
+## 빌드 및 배포
+
+### 로컬 빌드
+
+```bash
+# TypeScript 컴파일러 사용
+bun run build
+
+# Bun 번들러 사용 (더 빠름)
+bun run build:bun
+
+# 빌드 결과 확인
+ls -la dist/
+```
+
+### 로컬에서 패키지 테스트
+
+```bash
+# 1. 전역 링크 생성
+npm link
+
+# 2. CLI 실행 테스트
+tylersong
+
+# 3. 테스트 완료 후 링크 제거
+npm unlink -g tylersong
+```
+
+### 버전 배포
+
+```bash
+# 1. 변경사항 커밋
+git add .
+git commit -m "feat: 새 기능"
+
+# 2. 버전 업데이트
+npm version patch  # 1.0.9 → 1.0.10
+
+# 3. 푸시 (태그 포함)
+git push origin main --tags
+
+# 4. GitHub Actions가 자동으로 NPM에 배포
+```
+
+## 품질 체크리스트
+
+배포 전 확인사항:
+
+- [ ] 모든 테스트 통과 (`bun run test`)
+- [ ] 린트 오류 없음 (`bun run lint`)
+- [ ] 타입 체크 통과 (`bun run typecheck`)
+- [ ] 빌드 성공 (`bun run build`)
+- [ ] 로컬에서 CLI 정상 작동 (`bun run dev:bun`)
+- [ ] 문서 업데이트 (필요시)
+- [ ] CHANGELOG 업데이트 (필요시)
+
+## 문제 해결
+
+### Bun 관련 문제
+
+```bash
+# Bun 재설치
+curl -fsSL https://bun.sh/install | bash
+
+# 캐시 삭제
+rm -rf ~/.bun/install/cache
+bun install
+```
+
+### 의존성 문제
+
+```bash
+# lockfile 삭제 후 재설치
+rm -f bun.lock package-lock.json
+bun install
+```
+
+### TypeScript 오류
+
+```bash
+# node_modules 재설치
+rm -rf node_modules
+bun install
+
+# tsconfig.json 확인
+bun run typecheck
+```
+
+## 기여 가이드
+
+1. **이슈 생성**: 버그 리포트 또는 기능 제안
+2. **브랜치 생성**: `feature/`, `fix/`, `docs/` 접두사 사용
+3. **커밋 메시지**: [Conventional Commits](https://www.conventionalcommits.org/) 형식
+   - `feat:` - 새 기능
+   - `fix:` - 버그 수정
+   - `docs:` - 문서 변경
+   - `test:` - 테스트 추가/수정
+   - `refactor:` - 리팩토링
+   - `style:` - 코드 스타일 변경
+   - `chore:` - 기타 변경사항
+4. **Pull Request**: 명확한 설명과 함께 제출
+5. **코드 리뷰**: 피드백 반영
+
+## 유용한 명령어 모음
+
+```bash
+# 개발
+bun run dev:bun              # 개발 모드 실행
+
+# 테스트
+bun run test                 # 테스트 실행
+bun run test:watch           # 테스트 감시
+bun run test:coverage        # 커버리지 포함
+
+# 코드 품질
+bun run lint                 # 린트 검사
+bun run lint:fix             # 린트 자동 수정
+bun run format               # 코드 포맷팅
+bun run typecheck            # 타입 체크
+
+# 빌드
+bun run build                # TypeScript 빌드
+bun run build:bun            # Bun 빌드
+
+# 실행
+bun run start                # 빌드된 파일 실행
+bun run start:bun            # Bun으로 실행
+```
+
+## 추가 리소스
+
+- [Bun 공식 문서](https://bun.sh/docs)
+- [TypeScript 핸드북](https://www.typescriptlang.org/docs/)
+- [Vitest 가이드](https://vitest.dev/guide/)
+- [ESLint 규칙](https://eslint.org/docs/rules/)
+- [Prettier 옵션](https://prettier.io/docs/en/options.html)
+

package/docs/direct-deployment.md

@@ -0,0 +1,116 @@
+# NPM 직접 배포 가이드
+
+## 🎯 개요
+
+이 문서는 GitHub Actions 태그 자동화 없이 NPM에 직접 배포하는 방법을 설명합니다.
+
+## 📋 사전 준비사항
+
+- NPM 계정 및 로그인
+- TypeScript 프로젝트 빌드 환경
+- 적절한 권한(패키지 소유자 또는 메인테이너)
+
+## 🚀 배포 단계
+
+### 1. 버전 업데이트
+
+```bash
+# 패치 버전 자동 증가 (1.0.4 → 1.0.5)
+npm version patch
+
+# 또는 마이너 버전 증가 (1.0.4 → 1.1.0)
+npm version minor
+
+# 또는 메이저 버전 증가 (1.0.4 → 2.0.0)
+npm version major
+```
+
+### 2. TypeScript 소스 코드 수정
+
+버전이 하드코딩된 경우 소스코드도 업데이트:
+
+```typescript
+// src/index.ts
+program.version("1.0.5").description("송민성의 개발자 프로필 CLI");
+```
+
+### 3. 프로젝트 빌드
+
+```bash
+# TypeScript 컴파일
+npm run build
+```
+
+### 4. NPM 로그인 확인
+
+```bash
+# 현재 로그인 상태 확인
+npm whoami
+
+# 로그인되지 않은 경우 로그인
+npm login
+```
+
+### 5. NPM 배포
+
+```bash
+# 패키지 배포
+npm publish
+```
+
+## ✅ 배포 성공 확인
+
+### 배포된 패키지 정보 확인
+
+```bash
+# 최신 버전 정보 확인
+npm view tylersong
+
+# 모든 버전 목록 확인
+npm view tylersong versions --json
+```
+
+### 패키지 설치 및 테스트
+
+```bash
+# 전역 설치
+npm install -g tylersong@latest
+
+# 실행 테스트
+tylersong
+```
+
+## 📦 배포 결과 (2024.08.04)
+
+### 성공적으로 배포된 버전: `1.0.5`
+
+- **배포 시간**: 방금 전 (just now)
+- **패키지 크기**: 21.0 kB
+- **압축 해제 크기**: 58.1 kB
+- **포함된 파일**: 19개
+- **메인테이너**: miiinsseong <wsc7202@gmail.com>
+
+### 전체 버전 히스토리
+
+```json
+["1.0.0", "1.0.1", "1.0.3", "1.0.4", "1.0.5"]
+```
+
+## 🔧 주요 변경사항 (v1.0.5)
+
+- ✨ JavaScript에서 TypeScript로 완전 변환
+- 📦 타입 정의 파일 포함 (`dist/index.d.ts`)
+- 🛠️ 자동 빌드 스크립트 (`prepublishOnly`)
+- 📚 상세한 문서화 완료
+
+## 💡 팁
+
+1. **자동 빌드**: `prepublishOnly` 스크립트가 설정되어 있어 배포 시 자동으로 빌드됩니다.
+2. **타입 안전성**: TypeScript로 변환되어 더 안정적인 코드가 되었습니다.
+3. **버전 관리**: 소스코드의 하드코딩된 버전도 함께 업데이트해야 합니다.
+
+## 🚨 주의사항
+
+- 같은 버전을 두 번 배포할 수 없습니다.
+- 배포 전 반드시 빌드와 테스트를 수행하세요.
+- NPM 로그인 상태를 확인하세요.

package/docs/discord-setup.md

@@ -0,0 +1,158 @@
+# Discord 알림 설정 가이드
+
+GitHub Actions에서 Discord로 빌드 및 배포 알림을 받을 수 있도록 설정하는 방법입니다.
+
+## 🎯 Discord Webhook 생성
+
+### 1. Discord 서버에서 Webhook 생성
+
+1. Discord 서버에서 알림을 받을 채널로 이동
+2. 채널 설정 (⚙️) → **연동** → **웹후크**
+3. **새 웹후크** 버튼 클릭
+4. 웹후크 이름 설정 (예: "GitHub Actions")
+5. 아바타 이미지 설정 (선택사항)
+6. **웹후크 URL 복사** 버튼으로 URL 복사
+
+### 2. GitHub Secrets에 Webhook URL 저장
+
+1. GitHub 저장소 → **Settings** → **Secrets and variables** → **Actions**
+2. **New repository secret** 클릭
+3. **Name**: `DISCORD_WEBHOOK_URL`
+4. **Secret**: 복사한 Discord 웹후크 URL 붙여넣기
+5. **Add secret** 클릭
+
+## 📢 알림 유형
+
+### 🔍 CI 알림 (ci.yml)
+
+**전송 시점**: 모든 CI 작업 완료 후
+**포함 정보**:
+
+- ✅/❌ 전체 CI 결과
+- 🌿 브랜치 정보
+- 📝 커밋 해시 및 링크
+- 🧪 테스트 결과
+- 🏗️ 빌드 결과
+- 🔍 린팅 결과
+- 👤 작업자 정보
+
+**예시 메시지**:
+
+```
+✅ CI 성공 🎉
+모든 테스트, 빌드, 린팅이 성공적으로 완료되었습니다.
+
+브랜치: main               커밋: a1b2c3d
+테스트: ✅ 성공            빌드: ✅ 성공
+린팅: ✅ 성공             작업자: tylersong
+```
+
+### 🚀 배포 알림 (publish.yml)
+
+**전송 시점**: NPM 배포 완료 후
+**포함 정보**:
+
+- ✅/❌ 배포 결과
+- 📦 새 버전 정보
+- 🏷️ 배포 타입 (자동/태그)
+- 🌿 브랜치/태그 정보
+- 🔗 NPM 패키지 링크
+- 💻 설치 명령어
+- 👤 배포자 정보
+
+**예시 메시지**:
+
+```
+🚀 패키지 배포 성공 🚀
+tylersong v1.0.5이 NPM에 성공적으로 배포되었습니다!
+
+버전: v1.0.5              배포 타입: Auto Deploy
+브랜치/태그: main
+
+NPM: tylersong 패키지
+설치 명령어: npx tylersong
+배포자: tylersong
+```
+
+## 🎨 Discord 메시지 스타일
+
+### 색상 코드
+
+- 🟢 **성공**: 초록색 (`00FF00`)
+- 🔴 **실패**: 빨간색 (`FF0000`)
+- 🟠 **취소**: 주황색 (`FFA500`)
+- 🔵 **기본**: Discord 파란색 (`5865F2`)
+
+### 이모지 사용
+
+- ✅ 성공 작업
+- ❌ 실패 작업
+- ⚠️ 경고/취소
+- 🎉 CI 성공
+- 🚀 배포 성공
+- 💥 오류 발생
+
+## 🔧 고급 설정
+
+### 알림 비활성화
+
+Discord 알림을 일시적으로 비활성화하려면:
+
+1. GitHub Secrets에서 `DISCORD_WEBHOOK_URL` 삭제 또는
+2. Secret 값을 빈 문자열로 설정
+
+### 커스텀 알림
+
+특정 상황에서만 알림을 받고 싶다면 워크플로우 파일을 수정:
+
+```yaml
+- name: Send Discord notification
+  if: env.DISCORD_WEBHOOK_URL != '' && github.ref == 'refs/heads/main'
+  # main 브랜치에서만 알림
+```
+
+### 멘션 추가
+
+특정 사용자나 역할을 멘션하려면 description에 추가:
+
+```yaml
+echo "description=<@사용자ID> 배포가 완료되었습니다!" >> $GITHUB_OUTPUT
+```
+
+## 🛠️ 트러블슈팅
+
+### 알림이 오지 않는 경우
+
+1. **Discord 웹후크 URL 확인**
+
+   - GitHub Secrets에 올바른 URL이 저장되었는지 확인
+   - 웹후크가 삭제되지 않았는지 Discord에서 확인
+
+2. **권한 확인**
+
+   - 봇/웹후크가 해당 채널에 메시지를 보낼 권한이 있는지 확인
+
+3. **워크플로우 로그 확인**
+   - GitHub Actions 로그에서 Discord 알림 단계 확인
+   - curl 명령어 실행 결과 확인
+
+### 메시지 포맷 오류
+
+JSON 구문 오류가 발생하면:
+
+- 필드 값에 특수문자나 따옴표가 있는지 확인
+- 멀티라인 텍스트는 적절히 이스케이프 처리
+
+### 웹후크 제한사항
+
+Discord 웹후크 제한사항:
+
+- 요청당 최대 10개의 embeds
+- Embed당 최대 25개의 fields
+- 분당 30개 메시지 제한
+
+## 📚 참고 자료
+
+- [Discord Webhook 가이드](https://support.discord.com/hc/ko/articles/228383668)
+- [Discord API - Webhook](https://discord.com/developers/docs/resources/webhook)
+- [GitHub Actions - Secrets](https://docs.github.com/ko/actions/security-guides/encrypted-secrets)