@blastlabs/utils 1.15.2 → 1.17.0

package/bin/init-ai-rules.cjs

@@ -7,18 +7,18 @@ const path = require("path");
 const RULE_CATEGORIES = {
   // 기본 규칙 (항상 포함)
   base: [
-    "typescript-standards.mdc",
-    "react-hooks.mdc",
-    "testing.mdc",
-    "documentation.mdc",
-    "git-commit.mdc",
+    "typescript-standards.md",
+    "react-hooks.md",
+    "testing.md",
+    "documentation.md",
+    "git-commit.md",
   ],
   // FSD 아키텍처 규칙
   fsd: [
-    "fsd-architecture.mdc",
-    "entities-layer.mdc",
-    "shared-layer.mdc",
-    "views-layer.mdc",
+    "fsd-architecture.md",
+    "entities-layer.md",
+    "shared-layer.md",
+    "views-layer.md",
   ],
 };
 
@@ -47,7 +47,7 @@ function parseArgs(args) {
 
 function showHelp() {
   console.log("@blastlabs/utils - AI Rules Installer (Cursor + Claude)\n");
-  console.log("프로젝트에 .cursor/rules/ 와 CLAUDE.md를 설치합니다.\n");
+  console.log("프로젝트에 .cursor/rules/ 와 .claude/rules/ 를 설치합니다.\n");
   console.log("사용법: npx blastlabs-init-ai-rules [options]\n");
   console.log("Options:");
   console.log("  --fsd         FSD 아키텍처 규칙 포함");
@@ -60,83 +60,191 @@ function showHelp() {
   console.log("  npx blastlabs-init-ai-rules --all    # 모든 규칙");
   console.log("\n생성되는 파일:");
   console.log("  .cursor/rules/*.mdc  - Cursor용 규칙 파일들");
-  console.log("  CLAUDE.md            - Claude Code용 규칙 파일");
+  console.log("  .claude/rules/*.md   - Claude Code용 규칙 파일들");
   console.log("\n⚠️  프로젝트 루트 디렉토리에서 실행해주세요!");
 }
 
 function showList() {
   console.log("📋 설치 가능한 규칙 목록\n");
-  
+
   console.log("📦 기본 규칙 (base) - 항상 포함:");
   for (const rule of RULE_CATEGORIES.base) {
     console.log(`   ├── ${rule}`);
   }
-  
+
   console.log("\n🏗️  FSD 아키텍처 규칙 (--fsd):");
   for (const rule of RULE_CATEGORIES.fsd) {
     console.log(`   ├── ${rule}`);
   }
-  
-  console.log("\n💡 각 규칙은 globs 패턴으로 자동 적용됩니다.");
+
+  console.log("\n💡 Cursor (.mdc)와 Claude (.md) 형식으로 각각 생성됩니다.");
 }
 
 function getRulesSourceDir() {
-  // 패키지 내 .cursor/rules 경로
-  return path.join(__dirname, "..", ".cursor", "rules");
+  return path.join(__dirname, "..", "rules");
 }
 
-function copyRule(ruleName, sourceDir, targetDir) {
-  const sourcePath = path.join(sourceDir, ruleName);
-  const targetPath = path.join(targetDir, ruleName);
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
 
-  if (!fs.existsSync(sourcePath)) {
-    console.log(`   ⚠️  ${ruleName} - 소스 파일 없음, 건너뜀`);
-    return false;
+  const yamlBlock = match[1];
+  const body = match[2];
+
+  const frontmatter = {};
+  let currentKey = null;
+
+  for (const line of yamlBlock.split("\n")) {
+    // 키-값 쌍 파싱
+    const kvMatch = line.match(/^(\w+):\s*(.*)$/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      let value = kvMatch[2].trim();
+
+      if (value === "true") value = true;
+      else if (value === "false") value = false;
+      else if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      } else if (value === "") {
+        value = undefined;
+      }
+
+      if (value !== undefined) {
+        frontmatter[currentKey] = value;
+      }
+    } else if (line.startsWith("  -") && currentKey) {
+      // 배열 값 처리 (paths 등)
+      const arrayValueMatch = line.match(/^\s*-\s*"([^"]+)"\s*$/);
+      if (arrayValueMatch) {
+        const arrayValue = arrayValueMatch[1];
+        // 현재 키의 값이 배열이 아니면 배열로 초기화
+        if (!Array.isArray(frontmatter[currentKey])) {
+          frontmatter[currentKey] = [];
+        }
+        frontmatter[currentKey].push(arrayValue);
+      }
+    }
   }
 
-  if (fs.existsSync(targetPath)) {
-    console.log(`   ⏭️  ${ruleName} - 이미 존재함, 건너뜀`);
-    return false;
+  return { frontmatter, body };
+}
+
+function serializeCursorFrontmatter(frontmatter) {
+  let yaml = "---\n";
+  if (frontmatter.description) {
+    yaml += `description: ${frontmatter.description}\n`;
+  }
+  if (frontmatter.globs) {
+    yaml += `globs: "${frontmatter.globs}"\n`;
   }
+  if (frontmatter.alwaysApply !== undefined) {
+    yaml += `alwaysApply: ${frontmatter.alwaysApply}\n`;
+  }
+  yaml += "---\n";
+  return yaml;
+}
 
-  fs.copyFileSync(sourcePath, targetPath);
-  console.log(`   ✅ ${ruleName}`);
-  return true;
+function serializeClaudeFrontmatter(frontmatter) {
+  let yaml = "---\n";
+  if (frontmatter.description) {
+    yaml += `description: "${frontmatter.description}"\n`;
+  }
+  // paths는 항상 적용되지 않는 경우에만 포함
+  if (frontmatter.paths && frontmatter.alwaysApply !== true) {
+    if (Array.isArray(frontmatter.paths)) {
+      yaml += "paths:\n";
+      for (const p of frontmatter.paths) {
+        yaml += `  - "${p}"\n`;
+      }
+    } else {
+      yaml += `paths:\n  - "${frontmatter.paths}"\n`;
+    }
+  }
+  // alwaysApply는 Claude에서 사용하지 않으므로 생략
+  yaml += "---\n";
+  return yaml;
 }
 
-function extractMdcContent(filePath) {
-  // .mdc 파일에서 frontmatter 제거하고 내용만 추출
-  const content = fs.readFileSync(filePath, "utf-8");
-  const frontmatterMatch = content.match(/^---\n[\s\S]*?\n---\n/);
-  if (frontmatterMatch) {
-    return content.slice(frontmatterMatch[0].length).trim();
+function generateCursorRules(ruleFiles, sourceDir, targetDir) {
+  const cursorDir = path.join(targetDir, ".cursor", "rules");
+  if (!fs.existsSync(cursorDir)) {
+    fs.mkdirSync(cursorDir, { recursive: true });
   }
-  return content.trim();
+
+  console.log("  .cursor/rules/");
+  let installed = 0;
+  let skipped = 0;
+
+  for (const ruleName of ruleFiles) {
+    const sourcePath = path.join(sourceDir, ruleName);
+    const targetName = ruleName.replace(/\.md$/, ".mdc");
+    const targetPath = path.join(cursorDir, targetName);
+
+    if (!fs.existsSync(sourcePath)) {
+      console.log(`   ⚠️  ${targetName} - 소스 파일 없음, 건너뜀`);
+      skipped++;
+      continue;
+    }
+
+    if (fs.existsSync(targetPath)) {
+      console.log(`   ⏭️  ${targetName} - 이미 존재함, 건너뜀`);
+      skipped++;
+      continue;
+    }
+
+    const content = fs.readFileSync(sourcePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+    const output = serializeCursorFrontmatter(frontmatter) + body;
+
+    fs.writeFileSync(targetPath, output);
+    console.log(`   ✅ ${targetName}`);
+    installed++;
+  }
+
+  return { installed, skipped };
 }
 
-function generateClaudeMd(ruleFiles, sourceDir, targetDir) {
-  const claudePath = path.join(targetDir, "CLAUDE.md");
-  
-  if (fs.existsSync(claudePath)) {
-    console.log("   ⏭️  CLAUDE.md - 이미 존재함, 건너뜀");
-    return false;
+function generateClaudeRules(ruleFiles, sourceDir, targetDir) {
+  const claudeDir = path.join(targetDir, ".claude", "rules");
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
   }
 
-  let content = "# Project Development Rules\n\n";
-  content += "이 파일은 Claude Code를 위한 프로젝트 규칙입니다.\n\n";
-  content += "---\n\n";
+  console.log("  .claude/rules/");
+  let installed = 0;
+  let skipped = 0;
 
   for (const ruleName of ruleFiles) {
     const sourcePath = path.join(sourceDir, ruleName);
-    if (fs.existsSync(sourcePath)) {
-      const ruleContent = extractMdcContent(sourcePath);
-      content += ruleContent + "\n\n---\n\n";
+    const targetPath = path.join(claudeDir, ruleName);
+
+    if (!fs.existsSync(sourcePath)) {
+      console.log(`   ⚠️  ${ruleName} - 소스 파일 없음, 건너뜀`);
+      skipped++;
+      continue;
+    }
+
+    if (fs.existsSync(targetPath)) {
+      console.log(`   ⏭️  ${ruleName} - 이미 존재함, 건너뜀`);
+      skipped++;
+      continue;
     }
+
+    const content = fs.readFileSync(sourcePath, "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+    const output = serializeClaudeFrontmatter(frontmatter) + body;
+
+    fs.writeFileSync(targetPath, output);
+    console.log(`   ✅ ${ruleName}`);
+    installed++;
   }
 
-  fs.writeFileSync(claudePath, content.trim() + "\n");
-  console.log("   ✅ CLAUDE.md");
-  return true;
+  return { installed, skipped };
 }
 
 function main() {
@@ -154,7 +262,6 @@ function main() {
   }
 
   const targetDir = process.cwd();
-  const rulesTargetDir = path.join(targetDir, ".cursor", "rules");
   const rulesSourceDir = getRulesSourceDir();
 
   // 소스 디렉토리 확인
@@ -164,12 +271,6 @@ function main() {
     process.exit(1);
   }
 
-  // .cursor/rules 디렉토리 생성
-  if (!fs.existsSync(rulesTargetDir)) {
-    fs.mkdirSync(rulesTargetDir, { recursive: true });
-    console.log("📁 .cursor/rules/ 디렉토리 생성됨\n");
-  }
-
   // 설치할 규칙 목록 결정
   let rulesToInstall = [...RULE_CATEGORIES.base];
 
@@ -182,33 +283,23 @@ function main() {
 
   console.log("📥 규칙 설치 중...\n");
 
-  let installedCount = 0;
-  let skippedCount = 0;
+  // Cursor 규칙 생성
+  console.log("🔧 Cursor 규칙 생성:\n");
+  const cursor = generateCursorRules(rulesToInstall, rulesSourceDir, targetDir);
 
-  for (const rule of rulesToInstall) {
-    const installed = copyRule(rule, rulesSourceDir, rulesTargetDir);
-    if (installed) {
-      installedCount++;
-    } else {
-      skippedCount++;
-    }
-  }
+  // Claude 규칙 생성
+  console.log("\n🤖 Claude 규칙 생성:\n");
+  const claude = generateClaudeRules(rulesToInstall, rulesSourceDir, targetDir);
 
-  // CLAUDE.md 생성
-  console.log("\n📄 CLAUDE.md 생성 중...\n");
-  const claudeCreated = generateClaudeMd(rulesToInstall, rulesSourceDir, targetDir);
-  if (claudeCreated) {
-    installedCount++;
-  } else {
-    skippedCount++;
-  }
+  const totalInstalled = cursor.installed + claude.installed;
+  const totalSkipped = cursor.skipped + claude.skipped;
 
   console.log("\n" + "─".repeat(40));
-  console.log(`\n✨ 완료! ${installedCount}개 설치, ${skippedCount}개 건너뜀`);
+  console.log(`\n✨ 완료! ${totalInstalled}개 설치, ${totalSkipped}개 건너뜀`);
 
   console.log("\n📁 생성된 파일:");
   console.log("   ├── .cursor/rules/*.mdc (Cursor용)");
-  console.log("   └── CLAUDE.md (Claude Code용)");
+  console.log("   └── .claude/rules/*.md (Claude Code용)");
 
   console.log("\n📦 포함된 규칙:");
   console.log("   ├── base (기본 규칙)");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.15.2",
+  "version": "1.17.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,7 @@
   "files": [
     "dist",
     "bin",
-    ".cursor/rules"
+    "rules"
   ],
   "scripts": {
     "prepare": "npm run build:tsc",

package/{.cursor/rules/documentation.mdc → rules/documentation.md}

@@ -1,6 +1,5 @@
 ---
-description: 문서화 가이드라인
-globs: 
+description: "문서화 가이드라인"
 alwaysApply: false
 ---
 

package/{.cursor/rules/entities-layer.mdc → rules/entities-layer.md}

@@ -1,6 +1,7 @@
 ---
 description: "Entities 레이어 구조 및 API 패턴"
-globs: ["**/entities/**"]
+paths:
+  - "**/entities/**"
 ---
 
 # Entities Layer (엔티티)

package/{.cursor/rules/git-commit.mdc → rules/git-commit.md}

@@ -1,6 +1,5 @@
 ---
-description: Git 커밋 컨벤션
-globs: 
+description: "Git 커밋 컨벤션"
 alwaysApply: false
 ---
 

package/{.cursor/rules/react-hooks.mdc → rules/react-hooks.md}

@@ -1,7 +1,10 @@
 ---
-description: React Hooks 개발 규칙 및 SSR 안전성
-globs: "**/use*.ts,**/use*.tsx"
-alwaysApply: false
+description: "React Hooks 개발 규칙 및 SSR 안전성"
+paths:
+  - "src/hooks/**/*.ts"
+  - "src/hooks/**/*.tsx"
+  - "**/use*.ts"
+  - "**/use*.tsx"
 ---
 
 # React Hooks Rules

package/{.cursor/rules/shared-layer.mdc → rules/shared-layer.md}

@@ -1,6 +1,7 @@
 ---
 description: "Shared 레이어 구조 및 lib vs utils 구분"
-globs: ["**/shared/**"]
+paths:
+  - "**/shared/**"
 ---
 
 # Shared Layer (공유 레이어)

package/rules/testing.md

@@ -0,0 +1,117 @@
+---
+description: "테스트 작성 가이드라인"
+paths:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/__tests__/**"
+---
+
+# Testing Guidelines
+
+## 테스트 도구
+
+- Vitest 사용
+- @testing-library/react 사용
+
+## 테스트 전략
+
+### 테스트 작성 원칙
+
+#### 컴포넌트 (Component) - 단위 테스트 위주
+
+- **대상**: `shared/ui/component/`, `views/*/ui/`, `views/*/components/` 등 재사용 가능한 컴포넌트
+- **목적**: 컴포넌트의 독립적인 동작 검증
+- **방법**:
+  - 컴포넌트를 격리하여 테스트
+  - Props와 사용자 상호작용에 집중
+  - 외부 의존성(API, 라우팅 등)은 mock 처리
+  - 렌더링, 이벤트 핸들링, 상태 변경 등을 검증
+- **예시**:
+  ```typescript
+  // shared/ui/component/button/button.test.tsx
+  // views/seller/ui/seller-login-info-form.test.tsx
+  ```
+
+#### 페이지 (Page) - 기능 테스트 위주
+
+- **대상**: `views/*/page.tsx` 등 페이지 레벨 컴포넌트
+- **목적**: 사용자 시나리오와 비즈니스 로직 검증
+- **방법**:
+  - 실제 컴포넌트를 렌더링하여 통합 테스트
+  - 외부 의존성(API, toast)만 mock 처리
+  - 사용자 플로우 전체를 검증
+  - 여러 컴포넌트 간 상호작용 검증
+- **Mock 최소화 원칙**:
+  - 외부 의존성(API 호출, toast)만 mock
+  - `shared` 패키지 컴포넌트는 실제로 렌더링
+  - 내부 컴포넌트도 실제로 렌더링하여 통합 테스트
+  - `data-testid` 대신 `getByRole`, `getByText` 등 접근성 기반 쿼리 사용
+
+### Testing Library 쿼리 우선순위
+
+Testing Library에서는 요소를 찾을 때 사용자가 코드와 상호작용하는 방식과 최대한 비슷해야 하므로, 아래와 같은 우선순위로 쿼리를 사용해야 합니다:
+
+**1순위 (가장 권장):**
+
+- `getByRole` - 접근성 역할 기반 (button, textbox, checkbox 등)
+- `getByLabelText` - label과 연결된 폼 요소
+- `getByPlaceholderText` - placeholder가 있는 입력 필드
+- `getByText` - 텍스트 내용으로 찾기
+- `getByDisplayValue` - 입력 필드의 현재 값으로 찾기
+
+**2순위:**
+
+- `getByAltText` - 이미지의 alt 텍스트
+- `getByTitle` - title 속성
+
+**3순위 (최후의 수단):**
+
+- `getByTestId` - `data-testid` 속성 사용 (가능한 한 피해야 함)
+
+**예시:**
+
+```typescript
+// ✅ 좋은 예
+screen.getByRole('button', { name: '저장' });
+screen.getByRole('checkbox');
+screen.getByText('셀러 정보를 찾을 수 없습니다.');
+screen.getByLabelText(/대표자명/);
+
+// ❌ 나쁜 예 (가능한 한 피해야 함)
+screen.getByTestId('save-button');
+screen.getByTestId('checkbox');
+```
+
+- **예시**:
+  ```typescript
+  // views/seller/seller-support-edit-page.test.tsx
+  // views/seller/seller-store-edit-page.test.tsx
+  ```
+
+### 테스트 파일 위치
+
+- 컴포넌트 테스트: 컴포넌트와 같은 디렉토리에 `*.test.tsx`
+- 페이지 테스트: 페이지와 같은 디렉토리에 `*.test.tsx`
+
+### 테스트 유틸리티
+
+- `apps/admin/src/test/test-utils.tsx`: 공통 테스트 헬퍼 함수
+  - `createTestQueryClient()`: QueryClient 생성
+  - `renderWithProviders()`: Provider 래핑된 렌더링 헬퍼
+
+## 테스트 원칙
+
+- 모든 hooks에 대해 포괄적인 테스트 작성
+- SSR 시나리오 테스트 포함
+- 높은 테스트 커버리지 목표
+
+## 테스트 실행
+
+```bash
+npm test
+```
+
+## 필수 사항
+
+- **Always** write tests for new features
+- 새 기능 추가 시 반드시 테스트 포함

package/{.cursor/rules/typescript-standards.mdc → rules/typescript-standards.md}

@@ -1,7 +1,8 @@
 ---
-description: TypeScript 코딩 표준 및 타입 규칙
-globs: "**/*.ts,**/*.tsx"
-alwaysApply: false
+description: "TypeScript 코딩 표준 및 타입 규칙"
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
 ---
 
 # TypeScript Standards

package/{.cursor/rules/views-layer.mdc → rules/views-layer.md}

@@ -1,6 +1,7 @@
 ---
 description: "Views 레이어 (페이지) 구조"
-globs: ["**/views/**"]
+paths:
+  - "**/views/**"
 ---
 
 # Views Layer (페이지 레이어)

package/.cursor/rules/project-overview.mdc

@@ -1,44 +0,0 @@
----
-description: @blastlabs/utils 프로젝트 개요 및 기본 가이드라인
-globs: 
-alwaysApply: true
----
-
-# @blastlabs/utils Development Rules
-
-React 애플리케이션을 위한 종합 TypeScript 유틸리티 라이브러리입니다.
-
-## 제공 기능
-
-- Authentication management (useAuth, AuthGuard)
-- UI/UX hooks (useTabs, useMediaQuery, useWindowSize)
-- Form management (useCRUDForm)
-- Time utilities (useCountdown, useStopwatch, useInterval)
-- Storage hooks (useLocalStorage, useSessionStorage, useCopyToClipboard)
-- State management hooks (useToggle, usePrevious)
-- Performance hooks (useDebounce, useThrottle, useIntersectionObserver)
-- Event hooks (useEventListener, useClickOutside)
-
-## 문서
-
-- [Development Guide](docs/development-guide.md) - 개발 가이드 통합 문서
-- [Authentication Hooks](docs/auth-hooks.md) - useAuth, AuthGuard
-- [UI Hooks](docs/ui-hooks.md) - useTabs, useMediaQuery, useWindowSize
-
-## 파일 구조
-
-```
-src/
-├── hooks/
-│   ├── auth/           # Authentication hooks
-│   ├── ui/             # UI/UX hooks
-│   ├── time/           # Time-related hooks
-│   ├── form/           # Form management hooks
-│   ├── storage/        # Storage hooks
-│   ├── state/          # State management hooks
-│   ├── performance/    # Performance hooks
-│   └── event/          # Event hooks
-└── components/
-    ├── auth/           # Auth components (AuthGuard)
-    └── dev/            # Development components
-```

package/.cursor/rules/testing.mdc

@@ -1,29 +0,0 @@
----
-description: 테스트 작성 가이드라인
-globs: "**/*.test.ts,**/*.test.tsx,**/__tests__/**"
-alwaysApply: false
----
-
-# Testing Guidelines
-
-## 테스트 도구
-
-- Vitest 사용
-- @testing-library/react 사용
-
-## 테스트 원칙
-
-- 모든 hooks에 대해 포괄적인 테스트 작성
-- SSR 시나리오 테스트 포함
-- 높은 테스트 커버리지 목표
-
-## 테스트 실행
-
-```bash
-npm test
-```
-
-## 필수 사항
-
-- **Always** write tests for new features
-- 새 기능 추가 시 반드시 테스트 포함