@blastlabs/utils 1.20.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/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './form';
 export * from './string';
 export * from './number';
 export * from './mock';
+export * from './routes';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,UAAU,CAAC;AAGzB,cAAc,UAAU,CAAC;AAGzB,cAAc,QAAQ,CAAC;AAYvB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -15,3 +15,4 @@ export * from './mock';
 // export * from './array';
 // Object utilities (placeholder for future)
 // export * from './object';
+export * from './routes';

package/dist/routes/auth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 인증 관련 라우트 경로
+ */
+export declare const AUTH_ROUTES: {
+    readonly ROOT: "/auth";
+    readonly LOGIN: string;
+    readonly REGISTER: string;
+    readonly FORGOT_PASSWORD: string;
+    readonly RESET_PASSWORD: string;
+    readonly VERIFY_EMAIL: string;
+    readonly VERIFY_OTP: string;
+};
+//# sourceMappingURL=auth.d.ts.map

package/dist/routes/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/routes/auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,eAAO,MAAM,WAAW;;;;;;;;CAQd,CAAC"}

package/dist/routes/auth.js

@@ -0,0 +1,14 @@
+/**
+ * 인증 관련 라우트 경로
+ */
+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'),
+};

package/dist/routes/base.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 기본 라우트 경로
+ */
+export declare const BASE_ROUTES: {
+    readonly HOME: "/";
+};
+//# sourceMappingURL=base.d.ts.map

package/dist/routes/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/routes/base.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,WAAW;;CAEd,CAAC"}

package/dist/routes/base.js

@@ -0,0 +1,6 @@
+/**
+ * 기본 라우트 경로
+ */
+export const BASE_ROUTES = {
+    HOME: '/',
+};

package/dist/routes/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 애플리케이션 라우트 경로 상수
+ * Next.js App Router 기준으로 작성되었습니다.
+ *
+ * 사용 예시:
+ * - ROUTE_PATH.HOME
+ * - ROUTE_PATH.AUTH.LOGIN
+ * - withParam(ROUTE_PATH.USERS.DETAIL, { id: '123' })
+ */
+/**
+ * 라우트 경로 상수 객체
+ */
+export declare const ROUTE_PATH: {
+    readonly AUTH: {
+        readonly ROOT: "/auth";
+        readonly LOGIN: string;
+        readonly REGISTER: string;
+        readonly FORGOT_PASSWORD: string;
+        readonly RESET_PASSWORD: string;
+        readonly VERIFY_EMAIL: string;
+        readonly VERIFY_OTP: string;
+    };
+    readonly POST: {
+        readonly ROOT: "/post";
+        readonly LIST: "/post";
+        readonly CREATE: string;
+        readonly DETAIL: string;
+    };
+    readonly HOME: "/";
+};
+export { withParam, withQuery } from './utils/helpers';
+export type { RoutePath } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/routes/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;GAEG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;CAIb,CAAC;AAGX,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGvD,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC"}

package/dist/routes/index.js

@@ -0,0 +1,22 @@
+/**
+ * 애플리케이션 라우트 경로 상수
+ * 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,
+};
+// 유틸리티 함수 재내보내기
+export { withParam, withQuery } from './utils/helpers';

package/dist/routes/post.d.ts

@@ -0,0 +1,7 @@
+export declare const POST_ROUTES: {
+    readonly ROOT: "/post";
+    readonly LIST: "/post";
+    readonly CREATE: string;
+    readonly DETAIL: string;
+};
+//# sourceMappingURL=post.d.ts.map

package/dist/routes/post.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"post.d.ts","sourceRoot":"","sources":["../../src/routes/post.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW;;;;;CAKd,CAAC"}

package/dist/routes/post.js

@@ -0,0 +1,8 @@
+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]'),
+};

package/dist/routes/types.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 라우트 경로 관련 타입 정의
+ */
+import type { ROUTE_PATH } from './index';
+/**
+ * 라우트 경로 타입
+ */
+export type RoutePath = typeof ROUTE_PATH;
+//# sourceMappingURL=types.d.ts.map

package/dist/routes/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/routes/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,UAAU,CAAC"}

package/dist/routes/types.js

@@ -0,0 +1,4 @@
+/**
+ * 라우트 경로 관련 타입 정의
+ */
+export {};

package/dist/routes/users.example.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 사용자 관련 라우트 경로 예시
+ *
+ * 새로운 도메인 라우트를 추가할 때 이 파일을 참고하세요.
+ *
+ * 사용 방법:
+ * 1. 이 파일을 users.ts로 이름 변경
+ * 2. routes/index.ts에서 import하여 ROUTE_PATH에 추가
+ */
+export declare const USERS_ROUTES: {
+    readonly ROOT: "/users";
+    readonly LIST: "/users";
+    readonly DETAIL: string;
+    readonly CREATE: string;
+    readonly EDIT: string;
+    readonly SETTINGS: string;
+    readonly PROFILE: string;
+};
+//# sourceMappingURL=users.example.d.ts.map

package/dist/routes/users.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users.example.d.ts","sourceRoot":"","sources":["../../src/routes/users.example.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,eAAO,MAAM,YAAY;;;;;;;;CAQf,CAAC"}

package/dist/routes/users.example.js

@@ -0,0 +1,20 @@
+/**
+ * 사용자 관련 라우트 경로 예시
+ *
+ * 새로운 도메인 라우트를 추가할 때 이 파일을 참고하세요.
+ *
+ * 사용 방법:
+ * 1. 이 파일을 users.ts로 이름 변경
+ * 2. routes/index.ts에서 import하여 ROUTE_PATH에 추가
+ */
+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'),
+    SETTINGS: createRoute(USERS_BASE, '/[id]/settings'),
+    PROFILE: createRoute(USERS_BASE, '/profile'),
+};

package/dist/routes/utils/helpers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 라우트 경로 관련 유틸리티 함수
+ */
+/**
+ * 동적 라우트 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로 (예: '/users/[id]')
+ * @param params - 파라미터 객체 (예: { id: '123' })
+ * @returns 실제 경로 (예: '/users/123')
+ *
+ * @example
+ * ```ts
+ * const userPath = withParam('/users/[id]', { id: '123' });
+ * // '/users/123'
+ * ```
+ */
+export declare function withParam<T extends string>(path: T, params: Record<string, string | number>): string;
+/**
+ * 쿼리 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로
+ * @param query - 쿼리 파라미터 객체
+ * @returns 쿼리 파라미터가 포함된 경로
+ *
+ * @example
+ * ```ts
+ * const searchPath = withQuery('/search', { q: 'test', page: 1 });
+ * // '/search?q=test&page=1'
+ * ```
+ */
+export declare function withQuery(path: string, query: Record<string, string | number | boolean | null | undefined>): string;
+/**
+ * 라우트 경로를 생성하는 헬퍼 함수
+ * @param base - 기본 경로
+ * @param path - 추가 경로
+ * @returns 합쳐진 경로
+ *
+ * @example
+ * ```ts
+ * const route = createRoute('/auth', '/login');
+ * // '/auth/login'
+ * ```
+ */
+export declare function createRoute(base: string, path: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/routes/utils/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/routes/utils/helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EACxC,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GACtC,MAAM,CAMR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,GAClE,MAAM,CASR;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/routes/utils/helpers.js

@@ -0,0 +1,59 @@
+/**
+ * 라우트 경로 관련 유틸리티 함수
+ */
+/**
+ * 동적 라우트 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @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(path, params) {
+    let result = 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, query) {
+    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, path) {
+    return `${base}${path.startsWith('/') ? path : `/${path}`}`;
+}

package/dist/routes/utils/helpers.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=helpers.test.d.ts.map

package/dist/routes/utils/helpers.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.test.d.ts","sourceRoot":"","sources":["../../../src/routes/utils/helpers.test.ts"],"names":[],"mappings":""}

package/dist/routes/utils/helpers.test.js

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { withParam, withQuery, createRoute } from './helpers';
+describe('routes/utils/helpers', () => {
+    describe('withParam', () => {
+        it('should replace single parameter', () => {
+            expect(withParam('/users/[id]', { id: '123' })).toBe('/users/123');
+            expect(withParam('/posts/[postId]', { postId: '456' })).toBe('/posts/456');
+        });
+        it('should replace multiple parameters', () => {
+            expect(withParam('/posts/[postId]/comments/[commentId]', {
+                postId: '456',
+                commentId: '789',
+            })).toBe('/posts/456/comments/789');
+            expect(withParam('/users/[userId]/posts/[postId]/comments/[commentId]', {
+                userId: '1',
+                postId: '2',
+                commentId: '3',
+            })).toBe('/users/1/posts/2/comments/3');
+        });
+        it('should handle parameters in any order', () => {
+            const path = '/posts/[postId]/comments/[commentId]';
+            // 순서대로
+            expect(withParam(path, { postId: '456', commentId: '789' })).toBe('/posts/456/comments/789');
+            // 반대 순서
+            expect(withParam(path, { commentId: '789', postId: '456' })).toBe('/posts/456/comments/789');
+        });
+        it('should handle nested key names safely', () => {
+            // id가 postId의 부분 문자열이지만 정확한 일치만 바꿈
+            expect(withParam('/posts/[id]/comments/[postId]', { id: '123', postId: '456' })).toBe('/posts/123/comments/456');
+            expect(withParam('/posts/[id]/comments/[postId]', { postId: '456', id: '123' })).toBe('/posts/123/comments/456');
+        });
+        it('should replace only first occurrence (using replace, not replaceAll)', () => {
+            // 현재 구현은 replace()를 사용하므로 첫 번째 매칭만 바뀝니다
+            expect(withParam('/[id]/[id]/[id]', { id: '123' })).toBe('/123/[id]/[id]');
+        });
+        it('should handle numeric values', () => {
+            expect(withParam('/users/[id]', { id: 123 })).toBe('/users/123');
+            expect(withParam('/posts/[postId]/comments/[commentId]', {
+                postId: 1,
+                commentId: 2,
+            })).toBe('/posts/1/comments/2');
+        });
+        it('should leave unmatched parameters as is', () => {
+            expect(withParam('/users/[id]', { userId: '123' })).toBe('/users/[id]');
+            expect(withParam('/posts/[postId]/comments/[commentId]', { id: '123' })).toBe('/posts/[postId]/comments/[commentId]');
+        });
+        it('should handle values with brackets correctly', () => {
+            // 값에 [id]가 있어도 이미 처리된 패턴은 다시 바뀌지 않음
+            expect(withParam('/[placeholder]/[actual]', { placeholder: 'fixed', actual: '[id]' })).toBe('/fixed/[id]');
+        });
+    });
+    describe('withQuery', () => {
+        it('should add single query parameter', () => {
+            expect(withQuery('/search', { q: 'test' })).toBe('/search?q=test');
+            expect(withQuery('/users', { page: 1 })).toBe('/users?page=1');
+        });
+        it('should add multiple query parameters', () => {
+            expect(withQuery('/search', { q: 'test', page: 1 })).toBe('/search?q=test&page=1');
+            expect(withQuery('/filter', { category: 'tech', sort: 'asc', limit: 10 })).toBe('/filter?category=tech&sort=asc&limit=10');
+        });
+        it('should handle numeric values', () => {
+            expect(withQuery('/users', { page: 1, limit: 20 })).toBe('/users?page=1&limit=20');
+        });
+        it('should handle boolean values', () => {
+            expect(withQuery('/posts', { featured: true, archived: false })).toBe('/posts?featured=true&archived=false');
+        });
+        it('should filter out null and undefined values', () => {
+            expect(withQuery('/search', { q: 'test', page: null, limit: undefined })).toBe('/search?q=test');
+            expect(withQuery('/users', { id: undefined })).toBe('/users');
+        });
+        it('should handle empty object', () => {
+            expect(withQuery('/users', {})).toBe('/users');
+        });
+        it('should append query string (does not merge with existing query)', () => {
+            // 현재 구현은 기존 쿼리 스트링을 병합하지 않고 뒤에 붙입니다
+            expect(withQuery('/search?existing=1', { new: 'value' })).toBe('/search?existing=1?new=value');
+        });
+        it('should combine withParam and withQuery', () => {
+            const path = withQuery(withParam('/users/[id]', { id: '123' }), { tab: 'profile' });
+            expect(path).toBe('/users/123?tab=profile');
+            const path2 = withQuery(withParam('/posts/[postId]/comments/[commentId]', {
+                postId: '456',
+                commentId: '789',
+            }), { sort: 'asc', page: 1 });
+            expect(path2).toBe('/posts/456/comments/789?sort=asc&page=1');
+        });
+    });
+    describe('createRoute', () => {
+        it('should combine base and path', () => {
+            expect(createRoute('/auth', '/login')).toBe('/auth/login');
+            expect(createRoute('/users', '/create')).toBe('/users/create');
+        });
+        it('should handle path without leading slash', () => {
+            expect(createRoute('/auth', 'login')).toBe('/auth/login');
+            expect(createRoute('/users', 'create')).toBe('/users/create');
+        });
+        it('should handle base with trailing slash', () => {
+            expect(createRoute('/auth/', '/login')).toBe('/auth//login');
+            expect(createRoute('/auth/', 'login')).toBe('/auth//login');
+        });
+        it('should handle multiple levels', () => {
+            expect(createRoute('/api/v1', '/users')).toBe('/api/v1/users');
+            expect(createRoute('/admin', '/settings/profile')).toBe('/admin/settings/profile');
+        });
+    });
+});

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@blastlabs/utils",
-  "version": "1.20.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",