tylersong 1.0.4 → 1.0.6

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)

package/docs/github-actions-fixes.md

@@ -0,0 +1,142 @@
+# GitHub Actions 수정 사항
+
+## 🔧 주요 수정 내용
+
+### 1. YAML 구조 문제 수정
+
+#### CI 워크플로우 (ci.yml)
+- **문제**: `lint` job이 `build` job 내부에 잘못 배치됨
+- **수정**: 올바른 들여쓰기로 독립적인 job으로 분리
+
+#### 배포 워크플로우 (publish.yml)  
+- **문제**: `notify` job이 잘못된 들여쓰기
+- **수정**: 올바른 job 레벨로 수정
+
+### 2. Job Dependency 문제 수정
+
+#### 문제점
+- `version-check` job이 항상 `check-ci`를 필요로 함
+- `check-ci`는 `workflow_run` 이벤트에서만 실행되어 다른 이벤트에서 오류 발생
+
+#### 수정 방안
+```yaml
+check-ci:
+  if: always()  # 모든 이벤트에서 실행
+  steps:
+    - name: Check CI workflow status
+      run: |
+        if [ "${{ github.event_name }}" == "workflow_run" ]; then
+          # workflow_run 이벤트에서만 CI 상태 체크
+        else
+          # 다른 이벤트에서는 성공으로 가정
+          echo "success=true" >> $GITHUB_OUTPUT
+        fi
+```
+
+### 3. Discord 알림 조건 수정
+
+#### 문제점
+- `if: env.DISCORD_WEBHOOK_URL != ''` 조건이 작동하지 않음
+- Environment variables는 secrets에 접근할 수 없음
+
+#### 수정 방안
+```yaml
+- name: Send Discord notification
+  if: secrets.DISCORD_WEBHOOK_URL != ''
+  # secrets 직접 체크로 변경
+```
+
+### 4. Deprecated Action 대체
+
+#### 문제점
+- `actions/create-release@v1`은 deprecated됨
+
+#### 수정 방안
+```yaml
+- name: Create GitHub Release
+  uses: actions/github-script@v7
+  with:
+    script: |
+      await github.rest.repos.createRelease({
+        // 최신 API 사용
+      });
+```
+
+### 5. Artifact 접근 문제 해결
+
+#### 문제점
+- `workflow_run` 이벤트에서 다른 워크플로우의 artifact 접근 어려움
+
+#### 수정 방안
+- 배포 시 직접 빌드하도록 변경
+- CI의 artifact 의존성 제거
+
+### 6. Discord JSON 안전성 개선
+
+#### 문제점
+- 특수문자로 인한 JSON 파싱 오류 가능성
+
+#### 수정 방안
+```bash
+# jq를 사용한 안전한 JSON 생성
+PAYLOAD=$(jq -n \
+  --arg title "$TITLE" \
+  --arg description "$DESCRIPTION" \
+  '{embeds: [{title: $title, description: $description}]}')
+```
+
+## 🚀 개선된 기능
+
+### 1. 안정성 향상
+- YAML 구문 오류 제거
+- Job dependency 안정화
+- JSON 파싱 오류 방지
+
+### 2. 호환성 개선
+- 최신 GitHub Actions 사용
+- Deprecated action 제거
+- 모든 이벤트 타입 지원
+
+### 3. 오류 처리 강화
+- curl 명령어에 오류 처리 추가
+- 빌드 artifact 검증 강화
+- 조건부 실행 로직 개선
+
+## 📋 검증 체크리스트
+
+- [x] YAML 구문 오류 수정
+- [x] Job dependency 문제 해결
+- [x] Discord 알림 조건 수정
+- [x] Deprecated action 대체
+- [x] JSON 안전성 개선
+- [x] 오류 처리 강화
+
+## 🔍 테스트 방법
+
+### 1. CI 테스트
+```bash
+# Pull Request 생성으로 CI 테스트
+git checkout -b test-ci
+git push origin test-ci
+# PR 생성 후 Actions 탭에서 확인
+```
+
+### 2. 배포 테스트
+```bash
+# 버전 업데이트 후 main push
+npm version patch
+git push origin main
+# 자동 배포 확인
+```
+
+### 3. Discord 알림 테스트
+- Discord 웹훅 URL 설정 후
+- CI/배포 실행하여 알림 수신 확인
+
+## 🛡️ 보안 고려사항
+
+1. **Secret 관리**: Discord 웹훅 URL은 반드시 GitHub Secrets에 저장
+2. **권한 최소화**: 필요한 최소 권한만 부여
+3. **환경 분리**: Production 환경에서 안전한 배포
+
+이제 GitHub Actions가 안정적으로 작동하며, 모든 이벤트 타입에서 정상적으로 실행됩니다.

package/docs/usage.md

@@ -0,0 +1,112 @@
+# tylersong CLI 사용법
+
+## 설치
+
+NPX를 통해 바로 실행할 수 있습니다:
+
+```bash
+npx tylersong
+```
+
+## 옵션
+
+### 기본 사용법
+
+```bash
+npx tylersong
+```
+
+인터랙티브 모드로 개발자 프로필 정보를 확인할 수 있습니다.
+
+### 명령어 옵션
+
+- `-V, --version`: 버전 정보 출력
+- `-g, --github`: GitHub 프로필을 브라우저에서 바로 열기
+- `-h, --help`: 도움말 출력
+
+### 예시
+
+```bash
+# 버전 확인
+npx tylersong --version
+
+# GitHub 프로필 열기
+npx tylersong --github
+
+# 도움말 보기
+npx tylersong --help
+```
+
+## 개발
+
+### TypeScript로 개발
+
+#### NPM 사용
+
+```bash
+# 의존성 설치
+npm install
+
+# 개발 모드 실행
+npm run dev
+
+# 빌드
+npm run build
+
+# 빌드된 파일 실행
+npm start
+```
+
+#### Bun 사용 (더 빠른 성능!)
+
+```bash
+# 의존성 설치
+bun install
+
+# 개발 모드 실행 (TypeScript 직접 실행)
+bun run dev:bun
+
+# 빌드 (bun 번들러 사용)
+bun run build:bun
+
+# 빌드된 파일 실행
+bun run start:bun
+
+# 또는 TypeScript 소스를 직접 실행
+bun run src/index.ts
+```
+
+### 프로젝트 구조
+
+```
+tylersong/
+├── src/
+│   └── index.ts        # 메인 TypeScript 소스 파일
+├── dist/               # 빌드된 JavaScript 파일들
+├── docs/               # 문서 파일들
+├── package.json        # 패키지 설정
+└── tsconfig.json       # TypeScript 설정
+```
+
+## 기능
+
+- 🚀 개발자 프로필 정보 표시
+- 💻 GitHub 프로필 바로 열기
+- ✨ 터미널에서 색상과 아이콘으로 꾸며진 출력
+- 📧 이메일 연락처 정보 제공
+
+## 배포
+
+자세한 배포 가이드는 [docs/deployment.md](./deployment.md)를 참고해주세요.
+
+### 빠른 배포
+
+```bash
+# 패치 버전 업데이트 후 자동 배포
+npm version patch
+git push origin main
+
+# 또는 태그와 함께 즉시 배포
+npm version patch
+git push origin main --tags
+```

package/docs/workflows.md

@@ -0,0 +1,176 @@
+# GitHub Actions 워크플로우 가이드
+
+이 프로젝트는 모듈화된 GitHub Actions 워크플로우를 사용합니다.
+
+## 📁 워크플로우 구조
+
+```
+.github/
+├── actions/
+│   └── setup-runtime/        # 재사용 가능한 컴포지트 액션
+│       └── action.yml
+└── workflows/
+    ├── ci.yml               # 지속적 통합 (테스트, 빌드, 린팅)
+    └── publish.yml          # NPM 배포
+```
+
+## 🔄 워크플로우 설명
+
+### 1. Continuous Integration (ci.yml)
+
+**트리거:**
+
+- `main`, `develop` 브랜치로의 push
+- `main`, `develop` 브랜치로의 pull request
+
+**작업:**
+
+- **test**: Node.js와 Bun 환경에서 테스트 실행
+- **build**: TypeScript 빌드 및 아티팩트 업로드
+- **lint**: 코드 품질 검사, 타입 체크, 보안 감사
+
+### 2. Publish to NPM (publish.yml)
+
+**트리거:**
+
+- `main` 브랜치로의 push
+- `v*` 형태의 태그 push
+- CI 워크플로우 완료 후 (workflow_run)
+
+**작업:**
+
+- **check-ci**: CI 워크플로우 성공 여부 확인
+- **version-check**: 버전 변경 사항 확인
+- **publish**: NPM에 패키지 배포
+- **notify**: 배포 결과 알림
+
+## 🔧 재사용 가능한 액션
+
+### setup-runtime
+
+Node.js 또는 Bun 런타임 환경을 설정하고 의존성을 설치합니다.
+
+**입력:**
+
+- `runtime`: 'node' 또는 'bun'
+- `node-version`: Node.js 버전 (기본: '20.x')
+- `bun-version`: Bun 버전 (기본: 'latest')
+
+**사용 예:**
+
+```yaml
+- name: Setup runtime environment
+  uses: ./.github/actions/setup-runtime
+  with:
+    runtime: node
+```
+
+### discord-notify
+
+Discord 웹후크를 통해 알림을 전송합니다.
+
+**입력:**
+
+- `webhook-url`: Discord 웹후크 URL (필수)
+- `status`: 워크플로우 상태 (success/failure/cancelled)
+- `title`: 알림 제목 (필수)
+- `description`: 알림 설명
+- `color`: Embed 색상 (hex, # 제외)
+- `fields`: 추가 필드 (JSON 배열)
+
+**사용 예:**
+
+```yaml
+- name: Send Discord notification
+  uses: ./.github/actions/discord-notify
+  with:
+    webhook-url: ${{ secrets.DISCORD_WEBHOOK_URL }}
+    status: success
+    title: "배포 완료!"
+    description: "새 버전이 배포되었습니다."
+```
+
+## 🚀 배포 시나리오
+
+### 자동 배포 (main 브랜치)
+
+1. 코드를 `main` 브랜치에 push
+2. CI 워크플로우 실행 (테스트, 빌드, 린팅)
+3. CI 성공 시 배포 워크플로우 실행
+4. package.json 버전이 NPM과 다르면 자동 배포
+
+### 즉시 배포 (태그)
+
+1. 버전 태그 push (`v1.0.5` 등)
+2. CI와 배포 워크플로우 동시 실행
+3. CI 성공 시 무조건 NPM에 배포
+4. GitHub Release 자동 생성
+
+### Pull Request
+
+1. PR 생성 시 CI 워크플로우만 실행
+2. 테스트, 빌드, 린팅 검사
+3. 배포는 실행되지 않음 (dry-run만)
+
+## 📋 워크플로우 흐름도
+
+```mermaid
+graph TD
+    A[코드 Push/PR] --> B[CI 워크플로우]
+    B --> C{테스트 통과?}
+    C -->|실패| D[❌ 빌드 실패]
+    C -->|성공| E[빌드 & 아티팩트 업로드]
+    E --> F{main 브랜치?}
+    F -->|No| G[✅ CI 완료]
+    F -->|Yes| H[배포 워크플로우]
+    H --> I{버전 변경?}
+    I -->|No| J[⏭️ 배포 스킵]
+    I -->|Yes| K[NPM 배포]
+    K --> L[✅ 배포 완료]
+```
+
+## ⚙️ 환경 설정
+
+### GitHub Secrets
+
+Repository Settings → Secrets and variables → Actions에서 설정:
+
+- `NPM_TOKEN`: NPM 액세스 토큰
+- `DISCORD_WEBHOOK_URL`: Discord 웹후크 URL (선택사항)
+- `GITHUB_TOKEN`: 자동으로 제공됨 (Release 생성용)
+
+> 💬 **Discord 알림**: 자세한 설정은 [Discord 설정 가이드](./discord-setup.md)를 참고하세요.
+
+### GitHub Environment
+
+`production` 환경 설정을 통해 배포 시 추가 보안 검토 가능
+
+## 🔍 모니터링
+
+### CI 상태 확인
+
+- Actions 탭에서 각 워크플로우 실행 상태 확인
+- 실패 시 로그를 통해 문제 진단
+
+### 배포 상태 확인
+
+- NPM: https://www.npmjs.com/package/tylersong
+- GitHub Releases: 태그 배포 시 자동 생성
+- 알림 작업에서 성공/실패 상태 확인
+
+## 🛠️ 트러블슈팅
+
+### CI 실패 시
+
+1. 테스트 실패: 코드 수정 후 재푸시
+2. 빌드 실패: TypeScript 오류 확인
+3. 린팅 실패: 코드 품질 이슈 해결
+
+### 배포 실패 시
+
+1. NPM_TOKEN 확인
+2. package.json 버전 확인
+3. 빌드 아티팩트 존재 확인
+4. NPM 패키지명 중복 확인
+
+이 구조를 통해 각 워크플로우의 책임이 명확히 분리되어 유지보수가 쉬워집니다.