@blastlabs/utils 1.18.0 → 1.19.0

package/bin/init-ai-rules.cjs

@@ -7,7 +7,9 @@ const path = require("path");
 const RULE_CATEGORIES = {
   // 기본 규칙 (항상 포함)
   base: [
+    "development-workflow.md",
     "typescript-standards.md",
+    "naming-convention.md",
     "react-hooks.md",
     "testing.md",
     "documentation.md",
@@ -29,6 +31,7 @@ function parseArgs(args) {
     all: false,
     list: false,
     help: false,
+    force: false,
   };
 
   for (const arg of args) {
@@ -40,6 +43,8 @@ function parseArgs(args) {
       options.all = true;
     } else if (arg === "--list" || arg === "-l") {
       options.list = true;
+    } else if (arg === "--force" || arg === "-f") {
+      options.force = true;
     }
   }
 
@@ -53,12 +58,14 @@ function showHelp() {
   console.log("Options:");
   console.log("  --fsd         FSD 아키텍처 규칙 포함");
   console.log("  --all         모든 규칙 설치 (base + fsd)");
+  console.log("  --force, -f   기존 파일 덮어쓰기");
   console.log("  --list, -l    설치 가능한 규칙 목록 보기");
   console.log("  --help, -h    도움말 보기");
   console.log("\n예시:");
   console.log("  npx blastlabs-init-ai-rules          # 기본 규칙만");
   console.log("  npx blastlabs-init-ai-rules --fsd    # 기본 + FSD 규칙");
   console.log("  npx blastlabs-init-ai-rules --all    # 모든 규칙");
+  console.log("  npx blastlabs-init-ai-rules --force  # 기존 파일 덮어쓰기");
   console.log("\n생성되는 파일:");
   console.log("  .cursor/rules/*.mdc  - Cursor용 규칙 파일들");
   console.log("  .claude/rules/*.md   - Claude Code용 규칙 파일들");
@@ -176,7 +183,7 @@ function serializeClaudeFrontmatter(frontmatter) {
   return yaml;
 }
 
-function generateCursorRules(ruleFiles, sourceDir, targetDir) {
+function generateCursorRules(ruleFiles, sourceDir, targetDir, force = false) {
   const cursorDir = path.join(targetDir, ".cursor", "rules");
   if (!fs.existsSync(cursorDir)) {
     fs.mkdirSync(cursorDir, { recursive: true });
@@ -197,7 +204,7 @@ function generateCursorRules(ruleFiles, sourceDir, targetDir) {
       continue;
     }
 
-    if (fs.existsSync(targetPath)) {
+    if (fs.existsSync(targetPath) && !force) {
       console.log(`   ⏭️  ${targetName} - 이미 존재함, 건너뜀`);
       skipped++;
       continue;
@@ -208,14 +215,15 @@ function generateCursorRules(ruleFiles, sourceDir, targetDir) {
     const output = serializeCursorFrontmatter(frontmatter) + body;
 
     fs.writeFileSync(targetPath, output);
-    console.log(`   ✅ ${targetName}`);
+    const action = force && fs.existsSync(targetPath) ? "🔄" : "✅";
+    console.log(`   ${action} ${targetName}`);
     installed++;
   }
 
   return { installed, skipped };
 }
 
-function generateClaudeRules(ruleFiles, sourceDir, targetDir) {
+function generateClaudeRules(ruleFiles, sourceDir, targetDir, force = false) {
   const claudeDir = path.join(targetDir, ".claude", "rules");
   if (!fs.existsSync(claudeDir)) {
     fs.mkdirSync(claudeDir, { recursive: true });
@@ -235,7 +243,7 @@ function generateClaudeRules(ruleFiles, sourceDir, targetDir) {
       continue;
     }
 
-    if (fs.existsSync(targetPath)) {
+    if (fs.existsSync(targetPath) && !force) {
       console.log(`   ⏭️  ${ruleName} - 이미 존재함, 건너뜀`);
       skipped++;
       continue;
@@ -246,7 +254,8 @@ function generateClaudeRules(ruleFiles, sourceDir, targetDir) {
     const output = serializeClaudeFrontmatter(frontmatter) + body;
 
     fs.writeFileSync(targetPath, output);
-    console.log(`   ✅ ${ruleName}`);
+    const action = force && fs.existsSync(targetPath) ? "🔄" : "✅";
+    console.log(`   ${action} ${ruleName}`);
     installed++;
   }
 
@@ -291,11 +300,11 @@ function main() {
 
   // Cursor 규칙 생성
   console.log("🔧 Cursor 규칙 생성:\n");
-  const cursor = generateCursorRules(rulesToInstall, rulesSourceDir, targetDir);
+  const cursor = generateCursorRules(rulesToInstall, rulesSourceDir, targetDir, options.force);
 
   // Claude 규칙 생성
   console.log("\n🤖 Claude 규칙 생성:\n");
-  const claude = generateClaudeRules(rulesToInstall, rulesSourceDir, targetDir);
+  const claude = generateClaudeRules(rulesToInstall, rulesSourceDir, targetDir, options.force);
 
   const totalInstalled = cursor.installed + claude.installed;
   const totalSkipped = cursor.skipped + claude.skipped;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/rules/development-workflow.md

@@ -0,0 +1,96 @@
+---
+description: "개발 워크플로우: PRD 참고 및 테스트 기본 진행"
+alwaysApply: true
+---
+
+# Development Workflow
+
+## 필수 원칙
+
+### 1. PRD 먼저 확인
+
+모든 기능 개발 전에 **반드시** PRD(Product Requirement Document)를 먼저 확인하세요:
+
+- **PRD가 있다면** 내용을 확인하고 스펙 파악
+- **PRD가 없다면** 사용자와 함께 PRD를 작성
+  - 사용자로부터 요구사항 수집
+  - AI가 PRD 초안 작성
+  - 사용자 확인 후 개발 진행
+- PRD에서 요구사항, UI/UX 스펙, 비즈니스 로직을 명확히 파악
+- 불확실한 부분은 PRD를 통해 명확화 후 개발 진행
+
+**PRD 확인 체크리스트:**
+- [ ] 기능 목적과 목표가 명확한가?
+- [ ] UI/UX 스펙이 정의되어 있는가?
+- [ ] API 스펙이 정의되어 있는가?
+- [ ] 예외 상황과 에러 처리가 정의되어 있는가?
+
+### 2. 테스트 기본 진행
+
+**모든 기능 구현은 테스트 코드와 함께 진행합니다.**
+
+#### 테스트 우선 원칙
+
+1. **테스트 없이 구현하지 않기**
+   - 기능 구현 전 테스트 케이스 먼저 작성
+   - 테스트가 실패하면 구현으로 간주하지 않음
+
+2. **최소 테스트 커버리지 준수**
+   - 새로운 hook: 100% 커버리지 권장
+   - 컴포넌트: 주요 사용자 시나리오 테스트
+   - 유틸리티 함수: 100% 커버리지
+
+3. **테스트 실행 후 PR**
+   - `npm test` 통과 확인
+   - 빌드 성공 확인
+   - 테스트 실패 시 PR 불가
+
+## 개발 순서
+
+### Step 1: PRD 확인/작성
+```
+사용자: "로그인 기능 추가해줘"
+AI: "PRD가 있나요? 없다면 먼저 함께 작성해요.
+
+먼저 몇 가지 질문드릴게요:
+1. 로그인 방법 (이메일/소셜)
+2. 필요한 UI 컴포넌트
+3. 연동할 API 엔드포인트
+
+이를 바탕으로 PRD 초안을 작성할게요."
+```
+
+### Step 2: 테스트 코드 작성
+```
+AI: "테스트 코드부터 작성할게요."
+→ 로그인 테스트 작성
+→ 실패하는 것 확인
+```
+
+### Step 3: 기능 구현
+```
+AI: "이제 로그인 기능을 구현할게요."
+→ 최소한의 구현으로 테스트 통과
+```
+
+### Step 4: 리팩토링
+```
+AI: "코드를 정리할게요."
+→ 리팩토링 후 테스트 재실행
+→ 모든 테스트 통과 확인
+```
+
+## 예외 사항
+
+**테스트를 생략할 수 있는 경우:**
+- 프로토타이핑 (코드 폐기 예정)
+- 스타일만 변경하는 경우
+- 명시적으로 테스트 제외 요청 시
+
+**그 외에는 무조건 테스트 작성**
+
+## 중요
+
+- **Always** check PRD first before implementation
+- **Always** write tests before or with implementation
+- **Never** skip tests without explicit reason

package/rules/documentation.md

@@ -1,6 +1,8 @@
 ---
-description: "문서화 가이드라인"
+description: '문서화 가이드라인'
 alwaysApply: false
+paths:
+  - '**/docs/**'
 ---
 
 # Documentation Guidelines
@@ -14,7 +16,7 @@ alwaysApply: false
 ## 문서 업데이트
 
 - 기능 추가 시 README.md 업데이트
-- 새 hooks 추가 시 관련 docs/*.md 업데이트
+- 새 hooks 추가 시 관련 docs/\*.md 업데이트
 - 변경사항은 반드시 CHANGELOG.md에 기록
 
 ## CHANGELOG 작성

package/rules/entities-layer.md

@@ -1,14 +1,17 @@
 ---
-description: "Entities 레이어 구조 및 API 패턴"
+description: 'Entities 레이어 구조 및 API 패턴'
 paths:
-  - "**/entities/**"
+  - '**/entities/**'
 ---
 
 # Entities Layer (엔티티)
 
 엔티티는 도메인 모델과 API 로직을 관리합니다.
+mapper는 받은데이터를 model에 설계한 방식으로 map을 합니다.
+query는 params로 보통 get에서 사용합니다.
 
 ## 구조
+
 ```
 entities/
 └── (엔티티 이름)/          예: inquiry, popular-product
@@ -22,29 +25,27 @@ entities/
     │   ├── get-(엔티티 이름)-list.ts
     │   ├── get-(엔티티 이름)-detail.ts
     │   ├── (엔티티 이름)-queries.ts
-    │   ├── mutate.ts
-    │   ├── query.ts
     │   └── index.ts
     ├── model/
     │   ├── (엔티티 이름).ts
     │   ├── (엔티티 이름)-detail.ts
     │   └── (엔티티 이름)-update.ts
-    ├── schema.ts
     └── index.ts
 ```
 
 ## 각 파일의 역할
+
 - **mapper/**: API 응답을 도메인 모델로 변환
 - **query/**: 쿼리 파라미터 타입 정의
-- **get-*-list.ts**: 리스트 조회 API 함수
-- **get-*-detail.ts**: 상세 조회 API 함수
+- **get-\*-list.ts**: 리스트 조회 API 함수
+- **get-\*-detail.ts**: 상세 조회 API 함수
+- **post-\*.ts** : post API 함수 (delete, put같은것도 앞에 접두사가 변함)
 - **\*-queries.ts**: TanStack Query queryOptions 정의 (all, lists, list, details, detail 등)
-- **mutate.ts**: mutation 함수들
 - **model/**: 도메인 모델 타입 정의
-- **schema.ts**: zod 스키마 정의 및 변환 함수
 - **index.ts**: `export * as (엔티티 이름)Api from "./api"`
 
 ## 예시
+
 ```
 entities/inquiry/
 ├── api/
@@ -60,8 +61,12 @@ entities/inquiry/
 ├── model/
 │   ├── inquiry.ts
 │   └── inquiry-detail.ts
-└── schema.ts
 ```
 
 ## TanStack Query 패턴
+
 서버 상태 관리는 TanStack Query의 queryOptions 패턴을 사용합니다.
+
+## model의 규칙
+
+zod를 사용하며 export const (엔티티)Schema와 export type (엔티티)Type 의 네이밍 규칙을 활용한다

package/rules/naming-convention.md

@@ -0,0 +1,212 @@
+---
+description: "파일 및 변수 네이밍 컨벤션"
+alwaysApply: false
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+---
+
+# Naming Convention
+
+## 파일 네이밍
+
+### 기본 규칙
+
+**모든 파일/폴더는 `kebab-case` 사용**
+
+```
+✅ good
+user-profile/
+use-user-data/
+button-group.tsx
+
+❌ bad
+UserProfile/
+useUserData/
+buttonGroup.tsx
+```
+
+### 예외: React 컴포넌트
+
+**컴포넌트 파일은 `PascalCase` 사용**
+
+```
+components/
+  ✅ ButtonGroup.tsx
+  ✅ UserProfile.tsx
+  ✅ FormInput.tsx
+
+  ❌ button-group.tsx
+  ❌ user-profile.tsx
+```
+
+**단, 폴더는 `kebab-case`**
+
+```
+components/
+  button-group/
+    ButtonGroup.tsx
+    ButtonGroup.test.tsx
+```
+
+### Hooks
+
+**`use-` prefix + `camelCase`**
+
+```
+hooks/
+  ✅ use-user-data.ts
+  ✅ use-form-state.ts
+  ✅ use-debounce.ts
+
+  ❌ userData.ts
+  ❌ useUserData.ts (파일명)
+  ❌ form-state.ts
+```
+
+### 타입 파일
+
+**`.types.ts` 또는 `.type.ts` 접미사**
+
+```
+model/
+  ✅ user.types.ts
+  ✅ product.type.ts
+  ✅ api.types.ts
+
+  ❌ UserTypes.ts
+  ❷ user-type.ts (단수型)
+```
+
+### 테스트 파일
+
+**대상 파일명 + `.test.` + 확장자**
+
+```
+ButtonGroup.tsx → ButtonGroup.test.tsx
+useUserData.ts → useUserData.test.ts
+api.ts → api.test.ts
+```
+
+### 폴더 구조
+
+**FSD 아키텍처 예시**
+
+```
+src/
+├── entities/
+│   └── user/                    # kebab-case
+│       ├── model/
+│       │   ├── user.types.ts
+│       │   └── user-detail.types.ts
+│       ├── api/
+│       │   ├── get-user-list.ts
+│       │   ├── use-user-query.ts
+│       │   └── user.test.ts
+│       └── ui/
+│           ├── UserCard.tsx      # PascalCase
+│           └── UserCard.test.tsx
+├── features/
+│   └── auth-login/               # kebab-case
+│       ├── model/
+│       ├── api/
+│       └── ui/
+│           └── LoginForm.tsx     # PascalCase
+├── shared/
+│   └── ui/
+│       └── button/               # kebab-case
+│           ├── Button.tsx        # PascalCase
+│           └── Button.test.tsx
+```
+
+## 변수/함수 네이밍
+
+### 변수
+
+**`camelCase` 사용**
+
+```typescript
+✅ good
+const userName = '...';
+const isActive = true;
+const maxCount = 10;
+
+❌ bad
+const user_name = '...';
+const IsActive = true;
+const MAX_COUNT = 10; (const가 아니라면)
+```
+
+### 상수
+
+**`UPPER_SNAKE_CASE` 사용**
+
+```typescript
+✅ good
+const MAX_RETRY_COUNT = 3;
+const API_BASE_URL = 'https://...';
+const DEFAULT_TIMEOUT = 5000;
+
+❌ bad
+const maxRetryCount = 3;
+const apiBaseUrl = 'https://...';
+```
+
+### 함수
+
+**`camelCase` + 동사로 시작**
+
+```typescript
+✅ good
+function getUserData() { }
+function handleSubmit() { }
+function isValidEmail() { }
+
+❌ bad
+function userData() { }
+function form_submit() { }
+function ValidEmail() { }
+```
+
+### 인터페이스/타입
+
+**`PascalCase` 사용**
+
+```typescript
+✅ good
+interface UserProfile { }
+type LoginFormData = { };
+interface ApiResponse<T> { }
+
+❌ bad
+interface userProfile { }
+type loginFormData = { }
+```
+
+### Enum
+
+**`PascalCase` + 멤버는 `UPPER_SNAKE_CASE`**
+
+```typescript
+✅ good
+enum UserRole {
+  ADMIN = 'ADMIN',
+  USER = 'USER',
+  GUEST = 'GUEST',
+}
+
+❌ bad
+enum userRole {
+  admin = 'admin',
+  USER = 'user',
+}
+```
+
+## 중요
+
+- **Always** use kebab-case for files and folders
+- **Always** use PascalCase for component files
+- **Always** use camelCase for variables and functions
+- **Always** use UPPER_SNAKE_CASE for constants

package/rules/shared-layer.md

@@ -1,7 +1,7 @@
 ---
-description: "Shared 레이어 구조 및 lib vs utils 구분"
+description: 'Shared 레이어 구조 및 lib vs utils 구분'
 paths:
-  - "**/shared/**"
+  - '**/shared/**'
 ---
 
 # Shared Layer (공유 레이어)
@@ -9,11 +9,10 @@ paths:
 프로젝트 전체에서 공유되는 코드를 관리합니다.
 
 ## 구조
+
 ```
 shared/
 ├── api/                    API 인스턴스 설정 (instance_v2.ts 등)
-├── constant/               공통 상수 (path.ts 등)
-├── hooks/                  공통 React 훅
 ├── mock-data/              개발용 목 데이터
 ├── lib/                    라이브러리 래퍼 및 설정
 │   └── (라이브러리명)/
@@ -28,14 +27,15 @@ shared/
 │   │       └── (컴포넌트명).tsx
 │   ├── theme/              테마 관련 CSS 파일
 │   └── utils/              UI 관련 유틸리티 함수
-├── util/                   일반 유틸리티 함수
 └── utils/                  추가 유틸리티 함수
 ```
 
 ## lib vs utils 구분 기준
 
 ### `shared/lib/`
+
 외부 라이브러리를 프로젝트에 맞게 감싸거나 설정하는 코드
+
 - 라이브러리 래퍼(wrapper) 컴포넌트
 - 라이브러리 초기 설정 및 Provider
 - 예시:
@@ -43,16 +43,19 @@ shared/
   - `shared/lib/tanstack-query/query-client.tsx`
   - `shared/lib/suspense/suspense-wrapper.tsx`
 
-### `shared/utils/` (또는 `shared/util/`)
+### `shared/utils/`
+
 순수 유틸리티 함수 및 비즈니스 로직 헬퍼
+
 - 라이브러리와 무관한 순수 함수
 - 라이브러리 기능을 사용하는 유틸 함수
 - 예시:
-  - `shared/util/convert-price.ts` - 가격 변환 함수
-  - `shared/util/export-excel.ts` - 엑셀 내보내기 함수
-  - `shared/util/form-validation.ts` - 폼 검증 유틸
+  - `shared/utils/convert-price.ts` - 가격 변환 함수
+  - `shared/utils/export-excel.ts` - 엑셀 내보내기 함수
+  - `shared/utils/form-validation.ts` - 폼 검증 유틸
 
 ## 판단 기준
+
 - 라이브러리를 감싸는가? → `lib/`
 - 라이브러리와 무관한 로직인가? → `utils/`
 - 라이브러리 기능을 사용하는 유틸인가? → `utils/`

package/rules/views-layer.md

@@ -1,72 +1,34 @@
 ---
-description: "Views 레이어 (페이지) 구조"
+description: 'Views 레이어 (페이지) 구조'
 paths:
-  - "**/views/**"
+  - '**/views/**'
 ---
 
 # Views Layer (페이지 레이어)
 
 페이지 단위의 UI와 로직을 관리합니다.
+기본적으로 fsd 방식을 따릅니다
 
 ## 구조
+
 ```
 views/
 └── (페이지명)/             예: inquiry, product, seller
     ├── page.tsx            메인 페이지 컴포넌트 (필수)
-    ├── (페이지명)-list-page.tsx
-    ├── (페이지명)-detail-page.tsx
     ├── detail/
     │   ├── page.tsx
     │   ├── ui/
-    │   ├── hooks/          use-(페이지명)-detail-data.tsx 등
-    │   └── components/
-    ├── list/
-    │   ├── (컬럼명)-column.tsx
-    │   ├── search.tsx
-    │   └── (모달명)-modal.tsx
     ├── ui/
-    ├── hooks/              use-(페이지명)-data.tsx, use-(페이지명)-actions.tsx 등
-    ├── components/
     ├── utils/
-    ├── schema/             zod 스키마
-    └── constants.ts
 ```
 
 ## 예시
 
 ### 기본 페이지 구조
+
 ```
 views/inquiry/
 ├── detail/
 │   └── page.tsx
-├── inquiry-list-page.tsx
-└── list/
-    ├── inquiry-column.tsx
-    ├── inquiry-modal.tsx
-    └── search.tsx
-```
-
-### 상세 페이지 구조
-```
-views/ai-management/agency/agency-detail/
-├── page.tsx
-├── hooks/
-│   ├── use-agency-detail-data.tsx
-│   └── use-agency-data-actions.tsx
-├── components/
-│   └── agency-basic-info-tab.tsx
-└── schema/
-    └── agency-detail.ts
-```
-
-### 관리 페이지 구조
-```
-views/product/category-management/
-├── page.tsx
-├── hooks/
-│   ├── use-category-data.tsx
-│   └── use-category-actions.tsx
-└── ui/
-    ├── category-management.tsx
-    └── category-modal.tsx
+│ page.tsx
 ```