@blastlabs/utils 1.21.0 → 1.22.0

package/bin/Makefile

@@ -0,0 +1,23 @@
+.PHONY: help all init-routes init-ai-rules generate-entity
+
+help:
+	@echo "blastlabs CLI Tools"
+	@echo ""
+	@echo "Usage: make <command>"
+	@echo ""
+	@echo "Available commands:"
+	@echo "  make all             - Run all CLI commands"
+	@echo "  make init-routes     - Initialize routes folder structure"
+	@echo "  make init-ai-rules   - Initialize AI rules files"
+	@echo "  make generate-entity - Generate entity scaffold"
+
+all: init-routes init-ai-rules generate-entity
+
+init-routes:
+	node init-routes.cjs
+
+init-ai-rules:
+	node init-ai-rules.cjs
+
+generate-entity:
+	node generate-entity.cjs

package/bin/init-routes.cjs

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// routes 폴더 구조와 내용을 정의
+const routesStructure = {
+  "base.ts": `/**
+ * 기본 라우트 경로
+ */
+
+export const BASE_ROUTES = {
+  HOME: '/',
+} as const;
+`,
+  "types.ts": `/**
+ * 라우트 경로 관련 타입 정의
+ */
+
+import type { ROUTE_PATH } from './index';
+
+/**
+ * 라우트 경로 타입
+ */
+export type RoutePath = typeof ROUTE_PATH;
+`,
+  "auth.ts": `/**
+ * 인증 관련 라우트 경로
+ */
+
+import { createRoute } from './utils/helpers';
+
+const AUTH_BASE = '/auth';
+
+export const AUTH_ROUTES = {
+  ROOT: AUTH_BASE,
+  LOGIN: createRoute(AUTH_BASE, '/login'),
+  REGISTER: createRoute(AUTH_BASE, '/register'),
+  FORGOT_PASSWORD: createRoute(AUTH_BASE, '/forgot-password'),
+  RESET_PASSWORD: createRoute(AUTH_BASE, '/reset-password'),
+  VERIFY_EMAIL: createRoute(AUTH_BASE, '/verify-email'),
+  VERIFY_OTP: createRoute(AUTH_BASE, '/verify-otp'),
+} as const;
+`,
+  "post.ts": `/**
+ * 게시글 관련 라우트 경로
+ */
+
+import { createRoute } from './utils/helpers';
+
+const POST_BASE = '/post';
+
+export const POST_ROUTES = {
+  ROOT: POST_BASE,
+  LIST: POST_BASE,
+  CREATE: createRoute(POST_BASE, '/create'),
+  DETAIL: createRoute(POST_BASE, '/[id]'),
+} as const;
+`,
+  "users.example.ts": `/**
+ * 사용자 관련 라우트 경로 예시
+ * 복사해서 사용하세요
+ */
+
+import { createRoute } from './utils/helpers';
+
+const USERS_BASE = '/users';
+
+export const USERS_ROUTES = {
+  ROOT: USERS_BASE,
+  LIST: USERS_BASE,
+  DETAIL: createRoute(USERS_BASE, '/[id]'),
+  CREATE: createRoute(USERS_BASE, '/create'),
+  EDIT: createRoute(USERS_BASE, '/[id]/edit'),
+} as const;
+`,
+  "index.ts": `/**
+ * 애플리케이션 라우트 경로 상수
+ * Next.js App Router 기준으로 작성되었습니다.
+ *
+ * 사용 예시:
+ * - ROUTE_PATH.HOME
+ * - ROUTE_PATH.AUTH.LOGIN
+ * - withParam(ROUTE_PATH.USERS.DETAIL, { id: '123' })
+ */
+
+import { BASE_ROUTES } from './base';
+import { AUTH_ROUTES } from './auth';
+import { POST_ROUTES } from './post';
+
+/**
+ * 라우트 경로 상수 객체
+ */
+export const ROUTE_PATH = {
+  ...BASE_ROUTES,
+  AUTH: AUTH_ROUTES,
+  POST: POST_ROUTES,
+} as const;
+
+// 유틸리티 함수 재내보내기
+export { withParam, withQuery } from './utils/helpers';
+
+// 타입 내보내기
+export type { RoutePath } from './types';
+`,
+  "utils": {
+    "helpers.ts": `/**
+ * 라우트 경로 관련 유틸리티 함수
+ */
+
+/**
+ * 동적 라우트 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로 (예: '/users/[id]')
+ * @param params - 파라미터 객체 (예: { id: '123' })
+ * @returns 실제 경로 (예: '/users/123')
+ *
+ * @example
+ * \`\`\`ts
+ * const userPath = withParam('/users/[id]', { id: '123' });
+ * // '/users/123'
+ * \`\`\`
+ */
+export function withParam<T extends string>(
+  path: T,
+  params: Record<string, string | number>,
+): string {
+  let result: string = path;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(\`[\${key}]\`, String(value));
+  }
+  return result;
+}
+
+/**
+ * 쿼리 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로
+ * @param query - 쿼리 파라미터 객체
+ * @returns 쿼리 파라미터가 포함된 경로
+ *
+ * @example
+ * \`\`\`ts
+ * const searchPath = withQuery('/search', { q: 'test', page: 1 });
+ * // '/search?q=test&page=1'
+ * \`\`\`
+ */
+export function withQuery(
+  path: string,
+  query: Record<string, string | number | boolean | null | undefined>,
+): string {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== null && value !== undefined) {
+      searchParams.append(key, String(value));
+    }
+  }
+  const queryString = searchParams.toString();
+  return queryString ? \`\${path}?\${queryString}\` : path;
+}
+
+/**
+ * 라우트 경로를 생성하는 헬퍼 함수
+ * @param base - 기본 경로
+ * @param path - 추가 경로
+ * @returns 합쳐진 경로
+ *
+ * @example
+ * \`\`\`ts
+ * const route = createRoute('/auth', '/login');
+ * // '/auth/login'
+ * \`\`\`
+ */
+export function createRoute(base: string, path: string): string {
+  return \`\${base}\${path.startsWith('/') ? path : \`/\${path}\`}\`;
+}
+`,
+    "helpers.test.ts": `import { describe, it, expect } from 'vitest';
+import { withParam, withQuery, createRoute } from './helpers';
+
+describe('withParam', () => {
+  it('단일 파라미터를 변환한다', () => {
+    const result = withParam('/users/[id]', { id: '123' });
+    expect(result).toBe('/users/123');
+  });
+
+  it('여러 파라미터를 변환한다', () => {
+    const result = withParam('/posts/[postId]/comments/[commentId]', {
+      postId: '456',
+      commentId: '789'
+    });
+    expect(result).toBe('/posts/456/comments/789');
+  });
+
+  it('숫자 파라미터를 처리한다', () => {
+    const result = withParam('/users/[id]', { id: 123 });
+    expect(result).toBe('/users/123');
+  });
+});
+
+describe('withQuery', () => {
+  it('단일 쿼리 파라미터를 추가한다', () => {
+    const result = withQuery('/search', { q: 'test' });
+    expect(result).toBe('/search?q=test');
+  });
+
+  it('여러 쿼리 파라미터를 추가한다', () => {
+    const result = withQuery('/search', { q: 'test', page: 1 });
+    expect(result).toBe('/search?q=test&page=1');
+  });
+
+  it('null과 undefined을 무시한다', () => {
+    const result = withQuery('/search', { q: 'test', page: null, limit: undefined });
+    expect(result).toBe('/search?q=test');
+  });
+
+  it('빈 쿼리 객체는 경로를 변경하지 않는다', () => {
+    const result = withQuery('/search', {});
+    expect(result).toBe('/search');
+  });
+
+  it('boolean 파라미터를 처리한다', () => {
+    const result = withQuery('/users', { expanded: true });
+    expect(result).toBe('/users?expanded=true');
+  });
+});
+
+describe('createRoute', () => {
+  it('기본 경로와 하위 경로를 합친다', () => {
+    const result = createRoute('/auth', '/login');
+    expect(result).toBe('/auth/login');
+  });
+
+  it('슬래시 없는 하위 경로도 처리한다', () => {
+    const result = createRoute('/auth', 'login');
+    expect(result).toBe('/auth/login');
+  });
+});
+`
+  },
+  "README.md": `# 라우터 구조
+
+라우트 경로를 도메인별로 분리하여 관리하는 구조입니다.
+
+## 폴더 구조
+
+\`\`\`
+routes/
+├── utils/           # 유틸리티 함수
+│   └── helpers.ts   # withParam, withQuery, createRoute 등
+├── types.ts         # 타입 정의
+├── base.ts          # 기본 라우트 (HOME 등)
+├── auth.ts          # 인증 관련 라우트
+├── post.ts          # 게시글 관련 라우트
+├── users.example.ts # 확장 예시 파일
+└── index.ts         # 모든 라우트 통합 및 내보내기
+\`\`\`
+
+## 사용 방법
+
+### 기본 사용
+
+\`\`\`typescript
+import { ROUTE_PATH } from '@/app/routes';
+
+// 기본 라우트
+ROUTE_PATH.HOME              // '/'
+
+// 인증 라우트
+ROUTE_PATH.AUTH.LOGIN        // '/auth/login'
+ROUTE_PATH.AUTH.REGISTER     // '/auth/register'
+
+// 게시글 라우트
+ROUTE_PATH.POST.CREATE       // '/post/create'
+\`\`\`
+
+### 동적 라우트 파라미터
+
+\`\`\`typescript
+import { ROUTE_PATH, withParam } from '@/app/routes';
+
+// 단일 파라미터
+const postPath = withParam(ROUTE_PATH.POST.DETAIL, { id: '123' });
+// 결과: '/post/123'
+
+// 여러 파라미터 (파라미터가 여러 개인 경우)
+const customPath = withParam('/posts/[postId]/comments/[commentId]', {
+  postId: '456',
+  commentId: '789'
+});
+// 결과: '/posts/456/comments/789'
+\`\`\`
+
+### 파라미터와 쿼리 조합
+
+\`\`\`typescript
+import { ROUTE_PATH, withParam, withQuery } from '@/app/routes';
+
+// withParam으로 파라미터 변환 후 withQuery로 쿼리 추가
+const detailPath = withQuery(
+  withParam(ROUTE_PATH.POST.DETAIL, { id: '123' }),
+  { tab: 'edit', expanded: true }
+);
+// 결과: '/post/123?tab=edit&expanded=true'
+\`\`\`
+
+## 새로운 라우트 그룹 추가하기
+
+### 1. 새로운 라우트 파일 생성
+
+예: \`products.ts\`
+
+\`\`\`typescript
+import { createRoute } from './utils/helpers';
+
+const PRODUCTS_BASE = '/products';
+
+export const PRODUCTS_ROUTES = {
+  ROOT: PRODUCTS_BASE,
+  LIST: PRODUCTS_BASE,
+  DETAIL: createRoute(PRODUCTS_BASE, '/[id]'),
+  CREATE: createRoute(PRODUCTS_BASE, '/create'),
+} as const;
+\`\`\`
+
+### 2. index.ts에 추가
+
+\`\`\`typescript
+import { PRODUCTS_ROUTES } from './products'; // 추가
+
+export const ROUTE_PATH = {
+  ...BASE_ROUTES,
+  AUTH: AUTH_ROUTES,
+  POST: POST_ROUTES,
+  PRODUCTS: PRODUCTS_ROUTES, // 추가
+} as const;
+\`\`\`
+
+### 3. 사용하기
+
+\`\`\`typescript
+import { ROUTE_PATH } from '@/app/routes';
+
+ROUTE_PATH.PRODUCTS.LIST      // '/products'
+ROUTE_PATH.PRODUCTS.DETAIL    // '/products/[id]'
+\`\`\`
+
+## 파일 역할
+
+- **base.ts**: 애플리케이션 전체에서 공통으로 사용되는 기본 라우트 (HOME 등)
+- **auth.ts**: 인증 관련 라우트
+- **post.ts**: 게시글 관련 라우트
+- **[domain].ts**: 특정 도메인(예: users, products, orders)의 라우트
+- **utils/helpers.ts**: 라우트 생성 및 조작을 위한 유틸리티 함수
+- **types.ts**: 라우트 관련 타입 정의
+- **index.ts**: 모든 라우트를 통합하여 내보내는 진입점
+
+## 원칙
+
+1. **도메인별 분리**: 각 도메인은 별도 파일로 관리
+2. **일관된 네이밍**: 모든 라우트 그룹은 \`[DOMAIN]_ROUTES\` 형태로 명명
+3. **타입 안전성**: \`as const\`를 사용하여 타입 추론 최적화
+4. **재사용 가능한 유틸리티**: \`createRoute\`, \`withParam\`, \`withQuery\` 등을 활용
+`
+};
+
+// 디렉토리와 파일을 재귀적으로 생성하는 함수
+function createDirectoryStructure(basePath, structure) {
+  // basePath가 존재하지 않으면 생성
+  if (!fs.existsSync(basePath)) {
+    fs.mkdirSync(basePath, { recursive: true });
+  }
+
+  for (const [name, content] of Object.entries(structure)) {
+    const fullPath = path.join(basePath, name);
+
+    if (typeof content === 'object') {
+      // 디렉토리인 경우
+      if (!fs.existsSync(fullPath)) {
+        fs.mkdirSync(fullPath, { recursive: true });
+      }
+      createDirectoryStructure(fullPath, content);
+    } else {
+      // 파일인 경우
+      fs.writeFileSync(fullPath, content, 'utf8');
+    }
+  }
+}
+
+// CLI 실행
+function main() {
+  const targetDir = process.cwd();
+  const routesPath = path.join(targetDir, 'src', 'app', 'routes');
+
+  // 이미 routes 폴더가 있는지 확인
+  if (fs.existsSync(routesPath)) {
+    console.log('⚠️  src/app/routes 폴더가 이미 존재합니다.');
+    console.log('📂 기존 폴더를 삭제하고 다시 생성하려면 수동으로 삭제 후 다시 실행하세요.');
+    process.exit(1);
+  }
+
+  // routes 폴더 생성
+  createDirectoryStructure(routesPath, routesStructure);
+
+  console.log('✅ routes 폴더가 성공적으로 생성되었습니다!\\n');
+  console.log('📍 위치: src/app/routes\\n');
+  console.log('생성된 파일들:');
+  console.log('📁 routes/');
+  console.log('├── utils/');
+  console.log('│   ├── helpers.ts');
+  console.log('│   └── helpers.test.ts');
+  console.log('├── base.ts');
+  console.log('├── types.ts');
+  console.log('├── auth.ts');
+  console.log('├── post.ts');
+  console.log('├── users.example.ts');
+  console.log('├── index.ts');
+  console.log('└── README.md\\n');
+  console.log('사용 방법:');
+  console.log("  import { ROUTE_PATH, withParam, withQuery } from '@/app/routes';");
+  console.log("  ROUTE_PATH.AUTH.LOGIN  // '/auth/login'");
+}
+
+main();

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.21.0",
+  "version": "1.22.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"
+    "blastlabs-init-ai-rules": "./bin/init-ai-rules.cjs",
+    "blastlabs-init-routes": "./bin/init-routes.cjs"
   },
   "files": [
     "dist",