@blastlabs/utils 1.12.1 → 1.14.0

package/bin/generate-entity.cjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// 엔티티 이름을 kebab-case로 변환
+function toKebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+// 엔티티 이름을 PascalCase로 변환
+function toPascalCase(str) {
+  return str
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}
+
+// 엔티티 이름을 camelCase로 변환
+function toCamelCase(str) {
+  const pascalCase = toPascalCase(str);
+  return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+
+function createEntityStructure(entityName, targetDir) {
+  const kebabName = toKebabCase(entityName);
+  const pascalName = toPascalCase(kebabName);
+  const camelName = toCamelCase(kebabName);
+
+  // 현재 작업 디렉토리 기준으로 생성
+  const basePath = path.join(targetDir, kebabName);
+
+  // 디렉토리 생성
+  const dirs = [
+    basePath,
+    path.join(basePath, "api"),
+    path.join(basePath, "api", "mapper"),
+    path.join(basePath, "api", "query"),
+    path.join(basePath, "model"),
+  ];
+
+  dirs.forEach((dir) => {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  });
+
+  // 파일 템플릿 생성
+  createFiles(basePath, kebabName, pascalName, camelName);
+
+  console.log(`✅ ${kebabName} 엔티티가 성공적으로 생성되었습니다!`);
+  console.log(`📍 위치: ${basePath}`);
+  console.log(`\n생성된 파일들:`);
+  console.log(`📁 ${kebabName}/`);
+  console.log(`├── index.ts`);
+  console.log(`├── api/`);
+  console.log(`│   ├── get-${kebabName}-list.ts`);
+  console.log(`│   ├── get-${kebabName}-detail.ts`);
+  console.log(`│   ├── ${kebabName}-queries.ts`);
+  console.log(`│   ├── index.ts`);
+  console.log(`│   ├── mapper/`);
+  console.log(`│   │   ├── map-${kebabName}.ts`);
+  console.log(`│   │   └── map-${kebabName}-detail.ts`);
+  console.log(`│   └── query/`);
+  console.log(`│       └── ${kebabName}-list-query.ts`);
+  console.log(`└── model/`);
+  console.log(`    ├── ${kebabName}.ts`);
+  console.log(`    └── ${kebabName}-detail.ts`);
+
+  console.log(`\n⚠️  추가 작업이 필요합니다:`);
+  console.log(
+    `1. query-keys.ts 파일에 ${pascalName.toUpperCase()}_QUERY_KEYS 추가`,
+  );
+  console.log(`2. API 스키마에 맞게 model과 mapper 수정`);
+  console.log(`3. 실제 API 엔드포인트에 맞게 get-${kebabName}-list.ts 수정`);
+}
+
+function createFiles(basePath, kebabName, pascalName, camelName) {
+  // index.ts
+  const indexContent = `export * as ${camelName}Api from "./api";
+`;
+
+  // api/index.ts
+  const apiIndexContent = `export { get${pascalName}List } from "./get-${kebabName}-list";
+export { get${pascalName}Detail } from "./get-${kebabName}-detail";
+export { ${camelName}Queries } from "./${kebabName}-queries";
+`;
+
+  // api/get-{entity}-list.ts
+  const getListContent = `// TODO: API 클라이언트 import 추가
+// import { apiClient } from "@/shared/api";
+import { ${pascalName}ListQuery } from "./query/${kebabName}-list-query";
+
+export const get${pascalName}List = async (filters: ${pascalName}ListQuery) => {
+  // TODO: 실제 API 호출로 변경 필요
+  // return apiClient.get("/api/${kebabName}", { params: filters });
+  throw new Error("API 호출 구현 필요");
+};
+`;
+
+  // api/get-{entity}-detail.ts
+  const getDetailContent = `// TODO: API 클라이언트 import 추가
+// import { apiClient } from "@/shared/api";
+
+export const get${pascalName}Detail = async (id: number) => {
+  // TODO: 실제 API 호출로 변경 필요
+  // return apiClient.get(\`/api/${kebabName}/\${id}\`);
+  throw new Error("API 호출 구현 필요");
+};
+`;
+
+  // api/{entity}-queries.ts
+  const queriesContent = `import { queryOptions } from "@tanstack/react-query";
+import { ${pascalName}ListQuery } from "./query/${kebabName}-list-query";
+import { get${pascalName}List } from "./get-${kebabName}-list";
+import { get${pascalName}Detail } from "./get-${kebabName}-detail";
+import { map${pascalName} } from "./mapper/map-${kebabName}";
+import { map${pascalName}Detail } from "./mapper/map-${kebabName}-detail";
+
+export const ${camelName}Queries = {
+  all: () => ["${kebabName}"],
+  lists: () => [...${camelName}Queries.all(), "list"],
+  list: (filters: ${pascalName}ListQuery) =>
+    queryOptions({
+      queryKey: [...${camelName}Queries.lists(), filters],
+      queryFn: () => get${pascalName}List(filters),
+      select: (data) => {
+        return {
+          ...data,
+          items: data.items.map(map${pascalName}),
+        };
+      },
+    }),
+  details: () => [...${camelName}Queries.all(), "detail"],
+  detail: (id: number) =>
+    queryOptions({
+      queryKey: [...${camelName}Queries.details(), id],
+      queryFn: () => get${pascalName}Detail(id),
+      select: (data) => map${pascalName}Detail(data),
+    }),
+};
+`;
+
+  // api/mapper/map-{entity}.ts
+  const mapperContent = `import { ${pascalName}Schema } from "../../model/${kebabName}";
+
+// TODO: API 응답 타입을 실제 타입으로 변경
+type ${pascalName}Response = {
+  id: number;
+  createDate: string;
+  updateDate: string;
+};
+
+export const map${pascalName} = (item: ${pascalName}Response) => {
+  const res = ${pascalName}Schema.safeParse({
+    id: item.id,
+    // TODO: 실제 API 응답 구조에 맞게 매핑 수정 필요
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  if (!res.success) {
+    console.error(res.error);
+    return undefined;
+  }
+  return res.data;
+};
+`;
+
+  // api/mapper/map-{entity}-detail.ts
+  const mapperDetailContent = `import { ${pascalName}DetailSchema } from "../../model/${kebabName}-detail";
+
+// TODO: API 응답 타입을 실제 타입으로 변경
+type ${pascalName}DetailResponse = {
+  id: number;
+  createDate: string;
+  updateDate: string;
+};
+
+export const map${pascalName}Detail = (item: ${pascalName}DetailResponse) => {
+  const res = ${pascalName}DetailSchema.safeParse({
+    id: item.id,
+    // TODO: 실제 API 응답 구조에 맞게 매핑 수정 필요
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  if (!res.success) {
+    console.error(res.error);
+    return undefined;
+  }
+  return res.data;
+};
+`;
+
+  // api/query/{entity}-list-query.ts
+  const queryContent = `export type ${pascalName}ListQuery = {
+  limit?: number;
+  offset?: number;
+  // TODO: 추가 필터링 옵션이 필요한 경우 여기에 추가
+};
+`;
+
+  // model/{entity}.ts
+  const modelContent = `import { z } from "zod";
+
+export const ${pascalName}Schema = z.object({
+  id: z.number(),
+  createDate: z.string(),
+  updateDate: z.string(),
+  // TODO: 실제 데이터 구조에 맞게 스키마 수정 필요
+});
+
+export type ${pascalName}Type = z.infer<typeof ${pascalName}Schema>;
+`;
+
+  //model/{entity}-detail.ts
+  const detailContent = `import { z } from "zod";
+
+export const ${pascalName}DetailSchema = z.object({
+  id: z.number(),
+  createDate: z.string(),
+  updateDate: z.string(),
+});
+
+export type ${pascalName}DetailType = z.infer<typeof ${pascalName}DetailSchema>;
+`;
+
+  // 파일 쓰기
+  fs.writeFileSync(path.join(basePath, "index.ts"), indexContent);
+  fs.writeFileSync(path.join(basePath, "api", "index.ts"), apiIndexContent);
+  fs.writeFileSync(
+    path.join(basePath, "api", `get-${kebabName}-list.ts`),
+    getListContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", `get-${kebabName}-detail.ts`),
+    getDetailContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", `${kebabName}-queries.ts`),
+    queriesContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "mapper", `map-${kebabName}.ts`),
+    mapperContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "mapper", `map-${kebabName}-detail.ts`),
+    mapperDetailContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "query", `${kebabName}-list-query.ts`),
+    queryContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "model", `${kebabName}.ts`),
+    modelContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "model", `${kebabName}-detail.ts`),
+    detailContent,
+  );
+}
+
+// CLI 실행
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log("@blastlabs/utils - FSD Entity Generator\n");
+  console.log("사용법: npx blastlabs-generate-entity <entity-name>\n");
+  console.log("⚠️  entities 폴더 내에서 실행해주세요!\n");
+  console.log("예시:");
+  console.log("  cd src/entities");
+  console.log("  npx blastlabs-generate-entity user");
+  console.log("  npx blastlabs-generate-entity my-new-entity");
+  console.log("  npx blastlabs-generate-entity MyNewEntity");
+  process.exit(1);
+}
+
+const entityName = args[0];
+const targetDir = process.cwd();
+
+createEntityStructure(entityName, targetDir);

package/bin/init-ai-rules.cjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const TEMPLATES = {
+  base: "base.md",
+  fsd: "fsd.md",
+  testing: "testing.md",
+  nextjs: "nextjs.md",
+  vite: "vite.md",
+  monorepo: "monorepo.md",
+  project: "project-specific.md",
+};
+
+function parseArgs(args) {
+  const options = {
+    projectName: null,
+    projectDescription: "프로젝트 설명을 작성해주세요.",
+    framework: null,  // 'nextjs' or 'vite'
+    fsd: false,
+    testing: false,
+    monorepo: false,
+    packageManager: "pnpm",
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+    } else if (arg === "--next" || arg === "--nextjs") {
+      options.framework = "nextjs";
+    } else if (arg === "--vite") {
+      options.framework = "vite";
+    } else if (arg === "--fsd") {
+      options.fsd = true;
+    } else if (arg === "--testing" || arg === "--test") {
+      options.testing = true;
+    } else if (arg === "--monorepo") {
+      options.monorepo = true;
+    } else if (arg === "--npm") {
+      options.packageManager = "npm";
+    } else if (arg === "--yarn") {
+      options.packageManager = "yarn";
+    } else if (arg === "--pnpm") {
+      options.packageManager = "pnpm";
+    } else if (!arg.startsWith("--") && !options.projectName) {
+      options.projectName = arg;
+    } else if (!arg.startsWith("--") && options.projectName && !options.projectDescription) {
+      options.projectDescription = arg;
+    }
+  }
+
+  return options;
+}
+
+function showHelp() {
+  console.log("@blastlabs/utils - AI Rules Generator\n");
+  console.log("프로젝트에 .cursorrules와 CLAUDE.md 파일을 생성합니다.\n");
+  console.log("사용법: npx blastlabs-init-ai-rules <project-name> [options]\n");
+  console.log("Options:");
+  console.log("  --next, --nextjs    Next.js 프로젝트 규칙 포함");
+  console.log("  --vite              Vite 프로젝트 규칙 포함");
+  console.log("  --fsd               Feature-Sliced Design 규칙 포함");
+  console.log("  --testing, --test   테스트 전략 규칙 포함");
+  console.log("  --monorepo          모노레포 규칙 포함");
+  console.log("  --npm               npm 사용 (기본값: pnpm)");
+  console.log("  --yarn              yarn 사용");
+  console.log("  --pnpm              pnpm 사용 (기본값)");
+  console.log("\n예시:");
+  console.log('  npx blastlabs-init-ai-rules "My Project" --vite --fsd');
+  console.log('  npx blastlabs-init-ai-rules "Admin" --next --fsd --testing --monorepo');
+  console.log('  npx blastlabs-init-ai-rules "Web App" "React 웹 애플리케이션" --vite');
+  console.log("\n⚠️  프로젝트 루트 디렉토리에서 실행해주세요!");
+}
+
+function loadTemplate(name) {
+  const templatePath = path.join(__dirname, "..", "templates", name);
+  try {
+    return fs.readFileSync(templatePath, "utf-8");
+  } catch (error) {
+    console.error(`❌ 템플릿 파일을 찾을 수 없습니다: ${name}`);
+    return "";
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const options = parseArgs(args);
+
+  if (options.help || !options.projectName) {
+    showHelp();
+    process.exit(0);
+  }
+
+  const targetDir = process.cwd();
+
+  // 템플릿 조합
+  let content = loadTemplate(TEMPLATES.base);
+
+  if (options.fsd) {
+    content += "\n" + loadTemplate(TEMPLATES.fsd);
+  }
+
+  if (options.testing) {
+    content += "\n" + loadTemplate(TEMPLATES.testing);
+  }
+
+  if (options.framework === "nextjs") {
+    content += "\n" + loadTemplate(TEMPLATES.nextjs);
+  } else if (options.framework === "vite") {
+    content += "\n" + loadTemplate(TEMPLATES.vite);
+  }
+
+  if (options.monorepo) {
+    content += "\n" + loadTemplate(TEMPLATES.monorepo);
+  }
+
+  // 항상 project-specific 섹션 추가
+  content += "\n" + loadTemplate(TEMPLATES.project);
+
+  // 플레이스홀더 치환
+  const frameworkName = options.framework === "nextjs" ? "Next.js" : 
+                        options.framework === "vite" ? "Vite" : "React";
+  
+  content = content
+    .replace(/\{\{PROJECT_NAME\}\}/g, options.projectName)
+    .replace(/\{\{PROJECT_DESCRIPTION\}\}/g, options.projectDescription)
+    .replace(/\{\{PACKAGE_MANAGER\}\}/g, options.packageManager)
+    .replace(/\{\{FRAMEWORK\}\}/g, frameworkName);
+
+  // .cursorrules 파일 생성
+  const cursorrulesPath = path.join(targetDir, ".cursorrules");
+  if (fs.existsSync(cursorrulesPath)) {
+    console.log("⚠️  .cursorrules 파일이 이미 존재합니다. 덮어쓰기를 건너뜁니다.");
+  } else {
+    fs.writeFileSync(cursorrulesPath, content);
+    console.log("✅ .cursorrules 생성 완료");
+  }
+
+  // CLAUDE.md 파일 생성 (루트)
+  const claudePath = path.join(targetDir, "CLAUDE.md");
+  if (fs.existsSync(claudePath)) {
+    console.log("⚠️  CLAUDE.md 파일이 이미 존재합니다. 덮어쓰기를 건너뜁니다.");
+  } else {
+    fs.writeFileSync(claudePath, content);
+    console.log("✅ CLAUDE.md 생성 완료");
+  }
+
+  console.log("\n📁 생성된 파일들:");
+  console.log("├── .cursorrules");
+  console.log("└── CLAUDE.md");
+
+  console.log("\n📦 포함된 규칙:");
+  console.log("├── base (공통 규칙)");
+  if (options.fsd) console.log("├── fsd (Feature-Sliced Design)");
+  if (options.testing) console.log("├── testing (테스트 전략)");
+  if (options.framework) console.log(`├── ${options.framework}`);
+  if (options.monorepo) console.log("├── monorepo");
+  console.log("└── project-specific");
+
+  console.log("\n💡 Tip: 생성된 파일을 프로젝트에 맞게 수정하세요!");
+}
+
+main();

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "blastlabs-generate-entity": "./bin/generate-entity.cjs",
+    "blastlabs-init-ai-rules": "./bin/init-ai-rules.cjs"
+  },
   "files": [
-    "dist"
+    "dist",
+    "bin",
+    "templates"
   ],
   "scripts": {
     "prepare": "npm run build:tsc",

package/templates/base.md

@@ -0,0 +1,111 @@
+# {{PROJECT_NAME}} Development Rules
+
+This file contains development guidelines for AI assistants (Cursor, Claude Code, etc.)
+
+## Project Overview
+
+{{PROJECT_DESCRIPTION}}
+
+---
+
+# 프로젝트 기본 정보
+
+- **패키지 매니저**: {{PACKAGE_MANAGER}}
+- **프레임워크**: {{FRAMEWORK}}
+
+## 기술 스택
+
+- TypeScript
+- React
+- TanStack Query
+- Tailwind CSS
+- Zod
+
+---
+
+# Common Rules (공통 규칙)
+
+## Code Style & Standards
+
+### TypeScript
+- Use strict type checking (`strict: true` in tsconfig)
+- Prefer explicit types over `any`
+- Export all public types and interfaces
+- Use generics for reusable components
+- Use `type` for unions/intersections, `interface` for object shapes
+
+### Naming Conventions
+- **Files/Folders**: kebab-case (`user-profile.tsx`, `use-auth.ts`)
+- **Components**: PascalCase (`UserProfile`, `AuthGuard`)
+- **Hooks**: camelCase with `use` prefix (`useAuth`, `useLocalStorage`)
+- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`, `MAX_RETRY_COUNT`)
+- **Types/Interfaces**: PascalCase (`UserProfile`, `AuthState`)
+
+### Import Order
+1. React/Framework imports
+2. Third-party libraries
+3. Internal modules (absolute paths)
+4. Relative imports
+5. Types (with `type` keyword)
+
+```typescript
+import React, { useState, useEffect } from 'react';
+import { useQuery } from '@tanstack/react-query';
+import { Button } from '@/components/ui';
+import { formatDate } from '../utils';
+import type { User } from '@/types';
+```
+
+## React Best Practices
+
+### Component Patterns
+- Use functional components with hooks
+- Keep components small and focused (single responsibility)
+- Extract reusable logic into custom hooks
+- Use composition over inheritance
+
+### Hooks Rules
+- Only call hooks at the top level
+- Only call hooks from React functions
+- Use `useCallback` for event handlers passed to children
+- Use `useMemo` for expensive calculations
+
+### State Management
+- Keep state as local as possible
+- Lift state up only when necessary
+- Use TanStack Query for server state
+- Use context or Zustand for client global state
+
+## Error Handling
+
+```typescript
+try {
+  const result = await someAsyncOperation();
+  return { data: result, error: null };
+} catch (error) {
+  console.error('Operation failed:', error);
+  return { data: null, error: error instanceof Error ? error : new Error('Unknown error') };
+}
+```
+
+## Git Commit Convention
+
+Use conventional commits format:
+- `feat(scope): description` - New features
+- `fix(scope): description` - Bug fixes
+- `refactor(scope): description` - Code refactoring
+- `docs(scope): description` - Documentation changes
+- `test(scope): description` - Test changes
+- `chore(scope): description` - Build/tooling changes
+
+Examples:
+- `feat(auth): add login functionality`
+- `fix(api): resolve timeout error`
+- `docs(readme): update installation guide`
+
+## Before Committing
+
+1. Run tests: `{{PACKAGE_MANAGER}} test`
+2. Build successfully: `{{PACKAGE_MANAGER}} build`
+3. Lint check: `{{PACKAGE_MANAGER}} lint`
+4. Format code: `{{PACKAGE_MANAGER}} format`

package/templates/fsd.md

@@ -0,0 +1,150 @@
+
+---
+
+# Feature-Sliced Design (FSD)
+
+프로젝트는 [FSD 공식문서](https://feature-sliced.github.io/documentation/kr/docs/get-started/overview)를 참고하여 구조화되어 있습니다.
+
+## 폴더 구조
+
+```
+src/
+├── app/          # 앱 설정, providers, 라우팅
+├── entities/     # 도메인 모델, API
+├── features/     # 사용자 기능 단위
+├── shared/       # 공유 컴포넌트, 유틸
+├── views/        # 페이지 컴포넌트
+└── widgets/      # 복합 UI 블록
+```
+
+## Entities Layer (엔티티)
+
+엔티티는 도메인 모델과 API 로직을 관리합니다.
+
+### 구조
+
+```
+entities/
+└── (엔티티 이름)/          예: inquiry, popular-product
+    ├── api/
+    │   ├── mapper/
+    │   │   ├── map-(엔티티 이름).ts
+    │   │   └── map-(엔티티 이름)-detail.ts
+    │   ├── query/
+    │   │   ├── (엔티티 이름)-list-query.ts
+    │   │   └── (엔티티 이름)-detail-query.ts
+    │   ├── get-(엔티티 이름)-list.ts
+    │   ├── get-(엔티티 이름)-detail.ts
+    │   ├── (엔티티 이름)-queries.ts
+    │   ├── mutate.ts
+    │   └── index.ts
+    ├── model/
+    │   ├── (엔티티 이름).ts
+    │   ├── (엔티티 이름)-detail.ts
+    │   └── (엔티티 이름)-update.ts
+    ├── schema.ts
+    └── index.ts
+```
+
+### 각 파일의 역할
+
+- **mapper/**: API 응답을 도메인 모델로 변환
+- **query/**: 쿼리 파라미터 타입 정의
+- **get-\*-list.ts**: 리스트 조회 API 함수
+- **get-\*-detail.ts**: 상세 조회 API 함수
+- **\*-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/
+│   ├── mapper/
+│   │   ├── map-inquiry.ts
+│   │   └── map-inquiry-detail.ts
+│   ├── query/
+│   │   ├── inquiry-list-query.ts
+│   │   └── inquiry-detail-query.ts
+│   ├── get-inquiry-list.ts
+│   ├── get-inquiry-detail.ts
+│   └── inquiry-queries.ts
+├── model/
+│   ├── inquiry.ts
+│   └── inquiry-detail.ts
+└── schema.ts
+```
+
+## Shared Layer (공유 레이어)
+
+프로젝트 전체에서 공유되는 코드를 관리합니다.
+
+### 구조
+
+```
+shared/
+├── api/                    API 인스턴스 설정
+├── constant/               공통 상수 (path.ts 등)
+├── hooks/                  공통 React 훅
+├── lib/                    라이브러리 래퍼 및 설정
+│   └── (라이브러리명)/
+│       ├── provider.tsx
+│       └── config.ts
+├── ui/
+│   ├── component/          재사용 가능한 UI 컴포넌트
+│   │   └── (컴포넌트명)/
+│   │       ├── index.tsx
+│   │       ├── types.ts
+│   │       └── (컴포넌트명).tsx
+│   ├── theme/              테마 관련 CSS 파일
+│   └── utils/              UI 관련 유틸리티 함수
+└── utils/                  일반 유틸리티 함수
+```
+
+### lib vs utils 구분 기준
+
+#### `shared/lib/`
+외부 라이브러리를 프로젝트에 맞게 감싸거나 설정하는 코드
+- 라이브러리 래퍼(wrapper) 컴포넌트
+- 라이브러리 초기 설정 및 Provider
+- 예시: `react-hook-form/form-provider.tsx`, `tanstack-query/query-client.tsx`
+
+#### `shared/utils/`
+순수 유틸리티 함수 및 비즈니스 로직 헬퍼
+- 라이브러리와 무관한 순수 함수
+- 예시: `convert-price.ts`, `export-excel.ts`, `format-date.ts`
+
+**판단 기준:**
+- 라이브러리를 감싸는가? → `lib/`
+- 순수 함수 또는 유틸인가? → `utils/`
+
+## Views Layer (페이지 레이어)
+
+페이지 단위의 UI와 로직을 관리합니다.
+
+### 구조
+
+```
+views/
+└── (페이지명)/
+    ├── 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
+    ├── hooks/
+    ├── components/
+    ├── utils/
+    ├── schema/
+    └── constants.ts
+```

package/templates/monorepo.md

@@ -0,0 +1,61 @@
+
+---
+
+# Monorepo Rules
+
+## Structure
+
+```
+root/
+├── apps/
+│   ├── web/            # 웹 앱
+│   ├── admin/          # 어드민
+│   └── mobile/         # 모바일 앱
+├── packages/
+│   ├── ui/             # 공유 UI 컴포넌트
+│   ├── utils/          # 공유 유틸리티
+│   ├── config/         # 공유 설정 (eslint, tsconfig)
+│   └── types/          # 공유 TypeScript 타입
+├── package.json
+└── pnpm-workspace.yaml
+```
+
+## Package Management
+- Use workspace protocol for internal packages (`workspace:*`)
+- Keep shared dependencies in root `package.json`
+- App-specific dependencies in app's `package.json`
+
+```json
+{
+  "dependencies": {
+    "@repo/ui": "workspace:*",
+    "@repo/utils": "workspace:*"
+  }
+}
+```
+
+## Build Order
+- Build packages before apps
+- Use Turborepo for build orchestration
+- Configure proper `dependsOn` in turbo.json
+
+## Shared Configurations
+- Extend base tsconfig in all packages
+- Share ESLint config from `packages/config`
+- Maintain consistent formatting across packages
+
+## Commands
+
+```bash
+# 전체 빌드
+pnpm build
+
+# 특정 앱만 빌드
+pnpm --filter @repo/admin build
+
+# 특정 앱 dev 서버
+pnpm --filter @repo/web dev
+
+# 전체 린트
+pnpm lint
+```

package/templates/nextjs.md

@@ -0,0 +1,67 @@
+
+---
+
+# Next.js Rules
+
+## App Router
+- Use Server Components by default
+- Add `'use client'` only when needed (hooks, browser APIs, interactivity)
+- Colocate loading.tsx, error.tsx, not-found.tsx with pages
+- Use route groups `(group)` for organization without affecting URL
+
+## File Structure
+```
+app/
+├── (auth)/
+│   ├── login/page.tsx
+│   └── register/page.tsx
+├── (main)/
+│   ├── dashboard/page.tsx
+│   └── settings/page.tsx
+├── api/
+│   └── [...route]/route.ts
+├── layout.tsx
+└── page.tsx
+```
+
+## Data Fetching
+- Prefer Server Components for data fetching
+- Use `fetch` with caching options in Server Components
+- Use React Query/SWR for client-side data fetching
+- Implement proper loading and error states
+
+## Environment Variables
+- `NEXT_PUBLIC_*` for client-side variables
+- Server-only variables without prefix
+- Use `.env.local` for local development
+
+## SSR Safety
+
+```typescript
+// ❌ Wrong - breaks SSR
+const token = localStorage.getItem('token');
+
+// ✅ Correct - SSR safe
+const token = typeof window !== 'undefined' 
+  ? localStorage.getItem('token') 
+  : null;
+```
+
+## SSR-Safe Hook Pattern
+
+```typescript
+const [value, setValue] = useState(() => {
+  if (typeof window === 'undefined') return defaultValue;
+  return window.localStorage.getItem(key);
+});
+
+useEffect(() => {
+  if (typeof window === 'undefined') return;
+  // Browser-only code
+}, []);
+```
+
+## Image Optimization
+- Always use `next/image` for images
+- Provide width and height or use `fill`
+- Use appropriate `sizes` prop for responsive images

package/templates/project-specific.md

@@ -0,0 +1,21 @@
+
+---
+
+# Project Specific Rules (프로젝트별 추가 규칙)
+
+<!-- 여기에 프로젝트 고유의 규칙을 추가하세요 -->
+
+## Custom Rules
+- Add your project-specific rules here
+- Document any exceptions to common rules
+- Include team agreements and decisions
+
+## API Conventions
+- Document API patterns used in this project
+- Specify error handling strategies
+- Define response/request formats
+
+## State Management
+- Document which state library is used
+- Define when to use local vs global state
+- Specify state structure conventions

package/templates/testing.md

@@ -0,0 +1,66 @@
+
+---
+
+# 테스트 전략
+
+## 테스트 작성 원칙
+
+### 컴포넌트 (Component) - 단위 테스트
+
+- **대상**: `shared/ui/component/`, 재사용 가능한 컴포넌트
+- **목적**: 컴포넌트의 독립적인 동작 검증
+- **방법**:
+  - Props와 사용자 상호작용에 집중
+  - 외부 의존성(API, 라우팅)은 mock 처리
+  - 렌더링, 이벤트 핸들링, 상태 변경 검증
+
+### 페이지 (Page) - 기능 테스트
+
+- **대상**: `views/*/page.tsx` 페이지 컴포넌트
+- **목적**: 사용자 시나리오와 비즈니스 로직 검증
+- **Mock 최소화 원칙**:
+  - 외부 의존성(API 호출, toast)만 mock
+  - 내부 컴포넌트는 실제로 렌더링하여 통합 테스트
+  - `data-testid` 대신 접근성 기반 쿼리 사용
+
+## 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');
+```
+
+## 테스트 파일 위치
+
+- 컴포넌트와 같은 디렉토리에 `*.test.tsx`
+
+## 테스트 구조
+
+```typescript
+describe('ComponentName', () => {
+  it('should render correctly', () => {});
+  it('should handle user interaction', () => {});
+  it('should show error state', () => {});
+});
+```

package/templates/vite.md

@@ -0,0 +1,53 @@
+
+---
+
+# Vite + React Rules
+
+## Environment Variables
+- Use `import.meta.env.VITE_*` for environment variables
+- Only `VITE_` prefixed variables are exposed to client
+
+```typescript
+// ✅ Correct
+const apiUrl = import.meta.env.VITE_API_URL;
+
+// ❌ Wrong - won't work
+const secret = import.meta.env.SECRET_KEY;
+```
+
+## File Structure
+```
+src/
+├── assets/         # Static assets
+├── components/     # React components
+├── hooks/          # Custom hooks
+├── pages/          # Page components
+├── routes/         # Routing configuration
+├── services/       # API services
+├── stores/         # State management
+├── utils/          # Utility functions
+└── main.tsx        # Entry point
+```
+
+## Path Aliases
+- Use `@/` alias for `src/` directory
+- Configure in `vite.config.ts` and `tsconfig.json`
+
+```typescript
+// vite.config.ts
+resolve: {
+  alias: {
+    '@': path.resolve(__dirname, './src'),
+  },
+}
+```
+
+## Build Optimization
+- Use dynamic imports for code splitting
+- Lazy load routes and heavy components
+- Analyze bundle size with `rollup-plugin-visualizer`
+
+```typescript
+// Lazy loading example
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+```