byuckchon-frontend-cli 1.10.1 → 2.0.1

package/bin/index.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire } from 'node:module';
+
 import { config as loadDotenv } from 'dotenv';
 import { Command } from 'commander';
 import chalk from 'chalk';
@@ -24,12 +26,17 @@ import {
 // 프로젝트 .env 가 있으면 자동 로드 (ANTHROPIC_API_KEY, OPENAI_API_KEY 등).
 loadDotenv({ quiet: true });
 
+// 버전은 package.json 에서 읽는다. 여기에 직접 적으면 changesets 가 올린 버전과
+// 어긋나서, 실제로는 최신인데 옛 버전이라고 표시되는 일이 생긴다.
+const require = createRequire(import.meta.url);
+const { version } = require('../package.json');
+
 const program = new Command();
 
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.10.0');
+  .version(version);
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.10.1",
+  "version": "2.0.1",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {

package/src/generators/createApp.js

@@ -163,11 +163,12 @@ async function applyMonorepoConventions(appDir, config, scope) {
           compilerOptions: {
             // 공통 옵션은 config-typescript → settings 프리셋에 있다.
             tsBuildInfoFile: './node_modules/.tmp/tsconfig.tsbuildinfo',
-            baseUrl: '.',
+            // baseUrl 은 TypeScript 7 에서 제거 대상이다.
+            // 생략하면 paths 가 이 tsconfig 파일 위치 기준으로 해석되므로 ./ 을 붙인다.
             paths: {
-              '@/*': ['src/*'],
-              '@icons/*': ['src/assets/icons/*'],
-              '@images/*': ['src/assets/images/*'],
+              '@/*': ['./src/*'],
+              '@icons/*': ['./src/assets/icons/*'],
+              '@images/*': ['./src/assets/images/*'],
             },
           },
           include: ['src', 'vite.config.ts'],
@@ -183,7 +184,7 @@ async function applyMonorepoConventions(appDir, config, scope) {
         {
           extends: `@${scope}/config-typescript/next.json`,
           compilerOptions: {
-            baseUrl: '.',
+            // baseUrl 없이 paths 만 쓴다. (TypeScript 7 에서 baseUrl 제거)
             paths: { '@/*': ['./src/*'] },
           },
           include: [

package/src/generators/createBaseFiles.js

@@ -26,6 +26,151 @@ import { defineTokenConfig } from "@byuckchon-frontend/settings/tokens";
 export default defineTokenConfig();
 `;
 
+// ─── AI 에이전트 가이드 ────────────────────────────────────────────────────────
+
+/**
+ * AGENTS.md 를 만든다. Codex 와 bc chat 이 이 이름을 기본으로 찾고,
+ * CLAUDE.md 는 이 파일을 import 하는 한 줄짜리로 둬서 문서를 하나만 관리한다.
+ *
+ * 매 세션 컨텍스트에 실리므로 짧게 유지한다. 상세 API 는 각 패키지 README 로 넘긴다.
+ */
+export function agentsDoc(framework) {
+  const isReact = framework === "react";
+
+  return `# 작업 규칙
+
+이 프로젝트에서 코드를 작성할 때 지켜야 할 것들입니다.
+
+## 1. 사내 패키지를 먼저 쓴다
+
+직접 구현하기 전에 아래 패키지에 이미 있는지 **반드시 먼저 확인하세요.**
+같은 기능을 새로 만들면 유지보수 비용이 프로젝트 수만큼 늘어납니다.
+
+| 패키지 | 무엇이 있나 |
+| --- | --- |
+| \`@byuckchon-frontend/hooks\` | useDebounce, useThrottle, useTimer, useInfiniteScroll, useIntersectionObserver, useDetectClose, useAutoFocus, useFileUpload, usePagination, usePullToRefresh, useScrollTop, useCheckList, useMonthCalendar, useVisibilityEvent, usePasswordVisibility, useImpressionRef, useInstallPWA, useScrollToSelectedItem |
+| \`@byuckchon-frontend/utils\` | 포맷(formatData), 검증(validate), 에러 처리(handleError), 쿼리 파라미터(filterParams), userAgent, sanitizeHtml, dateUtils, editorUtils |
+| \`@byuckchon-frontend/core\` | Overlay, ErrorBoundary, SanitizeHtmlRender |
+| \`@byuckchon-frontend/basic-ui\` | ⚠️ **먼저 쓰지 않는다** — 아래 설명 참고 |
+| \`@byuckchon-frontend/settings\` | ESLint / Prettier / tsconfig 프리셋, 모션 토큰, 디자인 토큰 변환 |
+
+**작업 순서**
+
+1. 위 표에서 찾아본다
+2. 애매하면 실제 export 를 확인한다 — 위 목록은 스냅샷이라 최신이 아닐 수 있다
+   \`\`\`bash
+   cat node_modules/@byuckchon-frontend/hooks/dist/index.d.ts
+   \`\`\`
+3. 없으면 그때 직접 구현한다
+
+없는 걸 억지로 끼워 맞추지는 마세요. 쓰임이 다르면 직접 만드는 게 맞습니다.
+
+### basic-ui 는 예외입니다
+
+\`@byuckchon-frontend/basic-ui\` 는 **사용자가 명시적으로 요청했을 때만** 씁니다.
+프로젝트마다 디자인이 달라서 기본 UI 컴포넌트를 그대로 쓰면 오히려 덜어내는 작업이 늘어납니다.
+
+UI 컴포넌트는 이 프로젝트의 디자인에 맞춰 직접 만드세요.
+(Accordion, Input, Modal, Table 등이 필요하면 basic-ui 에 있으니 참고만 하세요)
+
+### 모션은 settings 의 클래스를 씁니다
+
+전환 효과가 필요하면 \`duration-200\` 같은 Tailwind 기본 클래스를 직접 쓰지 말고,
+\`@byuckchon-frontend/settings\` 의 모션 유틸리티를 쓰세요. 팀 전체가 같은 속도·곡선을 공유합니다.
+
+| 상황 | 클래스 |
+| --- | --- |
+| hover 확대 / 클릭 눌림 | \`motion-hover-scale\` \`motion-press\` |
+| 펼침·접힘 / 화살표 회전 | \`motion-collapse\` \`motion-rotate\` |
+| 팝업·드롭다운 진입 | \`motion-scale-in\` |
+| 배경 딤 | \`motion-backdrop\` |
+| 바텀시트 / 드로어 | \`motion-sheet\` \`motion-slide-x-left\` \`motion-slide-x-right\` |
+| 토스트 / 툴팁 | \`motion-toast\` \`motion-tooltip\` |
+| 토글 / 체크 / 라벨 | \`motion-toggle-knob\` \`motion-check-pop\` \`motion-label-float\` |
+| 탭 인디케이터 | \`motion-tab-indicator\` |
+
+\`data-open\` 이 필요한 클래스가 있습니다. 열림 상태를 \`data-open={isOpen}\` 으로 내려주세요.
+
+\`\`\`tsx
+<div data-open={isOpen} className="motion-collapse"><div>{content}</div></div>
+\`\`\`
+
+### 클래스 병합은 cn 을 씁니다
+
+\`src/lib/utils/cn.ts\` 의 \`cn\` 을 쓰세요. \`twMerge\` 를 직접 쓰면
+타이포그래피 유틸(\`text-body-sm-regular\`)이 글자 색으로 분류되어 조용히 사라집니다.
+
+## 2. 설정 파일은 직접 고치지 않는다
+
+\`eslint.config.js\`, \`prettier.config.js\`, \`tsconfig.*.json\`, \`token.config.js\` 는
+\`@byuckchon-frontend/settings\` 를 참조만 합니다. 규칙 본체는 node_modules 안에 있습니다.
+
+예외가 필요하면 **덮어쓰지 말고 뒤에 이어붙이세요.**
+
+\`\`\`js
+// eslint.config.js — 배열 뒤쪽이 이깁니다
+import byuckchon from '@byuckchon-frontend/settings/eslint/react';
+
+export default [
+  ...byuckchon,
+  { rules: { '@typescript-eslint/no-explicit-any': 'warn' } },
+];
+\`\`\`
+
+\`.vscode/settings.json\`, \`.nvmrc\`${isReact ? "" : ""} 같은 파일은 \`npx byuckchon-settings-sync\` 로 갱신합니다.
+
+## 3. 커밋 메시지
+
+\`\`\`
+<type>: <요약>
+\`\`\`
+
+\`feat\` \`fix\` \`refactor\` \`perf\` \`style\` \`docs\` \`test\` \`chore\`
+
+**리뷰어가 확인해야 할 것은 커밋 본문에 남깁니다.** PR 본문의 "리뷰 포인트"로 자동 수집됩니다.
+
+\`\`\`
+feat: 주문 목록 API 연동
+
+NOTE: 응답 스키마가 미확정이라 types/order.ts 에 any 가 남아 있습니다
+TODO: 에러 처리 미구현 — 백엔드 에러 코드 확정 후 작업 예정
+\`\`\`
+
+확신이 없거나, 임시로 둔 코드가 있거나, 리뷰어의 판단이 필요하면 **반드시 남기세요.**
+말없이 넘어가면 리뷰에서 놓칩니다.
+
+## 4. 브랜치 이름
+
+\`\`\`
+<type>/<작업 요약>/<작업자>
+feature/update-mypage-style/hyuk
+\`\`\`
+
+PR 제목은 첫 토막이 대괄호로 자동으로 붙습니다. → \`[feature] 마이페이지 디자인 적용\`
+
+## 5. 폴더 구조
+
+${
+  isReact
+    ? `\`\`\`
+src/lib        공용 로직·유틸      src/store      전역 상태
+src/api        API 호출           src/hooks      커스텀 훅
+src/context    Context            src/components 컴포넌트
+src/layouts    레이아웃           src/pages      페이지
+src/assets     이미지·아이콘
+\`\`\``
+    : `\`\`\`
+src/app        App Router         src/components 컴포넌트
+src/lib        공용 로직·유틸      src/hooks      커스텀 훅
+src/providers  Provider           src/constant   상수
+src/assets     이미지·아이콘
+\`\`\``
+}
+
+경로 별칭은 \`@/\` 를 씁니다. (\`@/lib/utils/cn\`)
+`;
+}
+
 // ─── 공통 설정 파일 ────────────────────────────────────────────────────────────
 
 async function createPrettierConfig(rootDir) {
@@ -213,11 +358,12 @@ export default defineConfig({
         extends: "@byuckchon-frontend/settings/tsconfig/react.json",
         compilerOptions: {
           tsBuildInfoFile: "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
-          baseUrl: ".",
+          // baseUrl 은 TypeScript 7 에서 제거 대상이다.
+          // 생략하면 paths 가 이 tsconfig 파일 위치 기준으로 해석되므로 ./ 을 붙인다.
           paths: {
-            "@/*": ["src/*"],
-            "@icons/*": ["src/assets/icons/*"],
-            "@images/*": ["src/assets/images/*"],
+            "@/*": ["./src/*"],
+            "@icons/*": ["./src/assets/icons/*"],
+            "@images/*": ["./src/assets/images/*"],
           },
         },
         include: ["src"],
@@ -245,6 +391,8 @@ export default defineConfig({
   );
 
   await write(path.join(rootDir, ".nvmrc"), await readSettingsAsset("project/nvmrc"));
+  await write(path.join(rootDir, "AGENTS.md"), agentsDoc("react"));
+  await write(path.join(rootDir, "CLAUDE.md"), "@AGENTS.md\n");
 
   await createPrettierConfig(rootDir);
   await createEslintConfig(rootDir);
@@ -360,7 +508,7 @@ export default nextConfig;
       {
         extends: "@byuckchon-frontend/settings/tsconfig/next.json",
         compilerOptions: {
-          baseUrl: ".",
+          // baseUrl 없이 paths 만 쓴다. (TypeScript 7 에서 baseUrl 제거)
           paths: { "@/*": ["./src/*"] },
         },
         include: ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
@@ -372,6 +520,8 @@ export default nextConfig;
   );
 
   await write(path.join(rootDir, ".nvmrc"), await readSettingsAsset("project/nvmrc"));
+  await write(path.join(rootDir, "AGENTS.md"), agentsDoc("next"));
+  await write(path.join(rootDir, "CLAUDE.md"), "@AGENTS.md\n");
 
   await createPrettierConfig(rootDir);
   await createNextEslintConfig(rootDir);

package/src/generators/createFolders.js

@@ -54,12 +54,14 @@ export async function createFolders(rootDir, config) {
   // 각 레이어에 placeholder 파일 생성
   await writeFile(
     path.join(rootDir, 'src/lib/utils/cn.ts'),
-    `import { clsx, type ClassValue } from 'clsx';
-import { twMerge } from 'tailwind-merge';
-
-export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
-}
+    `// 클래스 병합은 @byuckchon-frontend/utils 가 관리합니다.
+// twMerge 기본 설정은 타이포그래피 유틸(text-body-sm-regular 등)을 글자 색으로 분류해서
+// 색과 함께 쓰면 타이포가 조용히 사라집니다. utils 의 cn 은 그 부분을 고쳐둔 것입니다.
+//
+// 토큰 이름 체계가 기본 패턴과 다르면 createCn 으로 직접 지정하세요.
+//   import { createCn } from '@byuckchon-frontend/utils';
+//   export const cn = createCn({ typography: ['tab-bar', 'subtitle'] });
+export { cn } from '@byuckchon-frontend/utils';
 `,
   );
   await writeFile(

package/src/generators/createMonorepo.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 
 import { versions } from '../constants/versions.js';
 import { readSettingsAsset } from '../utils/settingsAssets.js';
+import { agentsDoc } from './createBaseFiles.js';
 import { createApp } from './createApp.js';
 import { scaffoldReviewAutomation } from './scaffoldReviewAutomation.js';
 
@@ -134,6 +135,10 @@ packages:
 
   await write(path.join(root, '.nvmrc'), await readSettingsAsset('project/nvmrc'));
 
+  // AI 에이전트 가이드 — 루트에 두면 모든 앱에서 공통으로 읽힌다.
+  await write(path.join(root, 'AGENTS.md'), agentsDoc(config.framework));
+  await write(path.join(root, 'CLAUDE.md'), '@AGENTS.md\n');
+
   await write(
     path.join(root, 'prettier.config.mjs'),
     `// 포맷 규칙은 @byuckchon-frontend/settings 가 관리합니다.

package/templates/review-automation/github/pull_request_template.md

@@ -1,30 +1,27 @@
 ## 작업 내용
 
-<!-- 무엇을, 왜 바꿨는지 적어주세요. -->
+<!--
+  아래 마커 사이는 커밋 내역으로 자동 채워집니다. 직접 수정하지 마세요.
+  덧붙일 설명이 있으면 이 주석 위·아래에 자유롭게 적으면 됩니다.
+-->
+<!-- byuckchon:commits:start -->
+<!-- byuckchon:commits:end -->
 
 ## 확인 사항
 
-<!-- 리뷰어가 중점적으로 봐야 할 부분이 있다면 적어주세요. -->
-
-## 테스트
-
-- [ ] 로컬에서 동작 확인
-- [ ] `lint` / `typecheck` / `build` 통과
-
 <!--
-  아래 마커 사이는 워크플로가 자동으로 채웁니다. 직접 수정하지 마세요.
-
-  - 커밋 내역: 커밋 메시지 첫 줄을 타입별로 묶습니다. (feat / fix / docs ...)
-  - 리뷰 포인트: 커밋 본문에 NOTE: 또는 TODO: 로 적은 줄을 모읍니다.
+  아래 마커 사이는 커밋 본문의 NOTE: / TODO: 로 자동 채워집니다.
 
       feat: 주문 목록 API 연동
 
       NOTE: 응답 스키마가 미확정이라 any 가 남아 있습니다
       TODO: 에러 처리 미구현
 
-  PR 제목은 브랜치명의 첫 토막이 대괄호로 붙습니다.
-      feature/update-mypage-style/hyuk + "마이페이지 디자인 적용"
-        → "[feature] 마이페이지 디자인 적용"
+  리뷰어가 봐야 할 다른 내용은 이 주석 아래에 적어주세요.
 -->
-<!-- byuckchon:commits:start -->
-<!-- byuckchon:commits:end -->
+<!-- byuckchon:notes:start -->
+<!-- byuckchon:notes:end -->
+
+## 기타
+
+<!-- 참고 링크, 스크린샷, 남은 작업 등 자유롭게 적어주세요. -->

package/templates/review-automation/github/workflows/pr-description.yml

@@ -22,8 +22,8 @@ name: PR Description
 on:
   pull_request:
     types: [opened, synchronize, reopened]
-    branches:
-      - dev
+    # 대상 브랜치를 제한하지 않습니다. PR 본문을 채우는 일이라
+    # dev 든 main 이든 동작하는 편이 낫습니다.
 
 concurrency:
   group: pr-description-${{ github.event.pull_request.number }}