byuckchon-frontend-cli 1.10.0 → 2.0.0

package/README.md

@@ -251,6 +251,8 @@ color는 `@theme`의 `--color-*`로, typography는 `@utility text-*`로, motion
 ```text
 .github/workflows/eslint-convention-review.yml   # 컨벤션 인라인 댓글
 .github/workflows/pr-check.yml                   # lint / typecheck / build 통과 여부 (bc init 전용)
+.github/workflows/pr-description.yml             # 커밋 내역을 PR 본문에 반영
+.github/pull_request_template.md
 tools/review.config.mjs
 ```
 
@@ -277,6 +279,24 @@ PR이 `dev` 브랜치를 대상으로 할 때, workflow가 기계적으로 판
 | Convention Review | 파일명, export 방식, boolean 변수명 등 | PR 인라인 `BLOCKING` 또는 `WARNING` 댓글 |
 | AI 리뷰 | 설계·예외 처리·비즈니스 판단 | 별도 AI 리뷰 workflow에서 구성 |
 
+### PR 본문 자동 작성
+
+`pr-description.yml` 이 PR 의 커밋을 타입별로 묶어 description 에 채워 넣습니다.
+
+```markdown
+### ✨ 기능
+- **settings** — tsconfig 프리셋 추가 (a1b2c3d)
+
+### 🐛 수정
+- letterSpacing % → em 변환 (b2c3d4e)
+```
+
+사람이 쓴 내용은 건드리지 않고 `<!-- byuckchon:commits:start -->` 마커 사이만 갱신하며,
+커밋을 추가로 푸시하면 목록도 따라 갱신됩니다. 머지 커밋은 제외하고, 컨벤션을 안 지킨
+커밋은 버리지 않고 "분류 없음"으로 모읍니다.
+
+생성되는 `.github/pull_request_template.md` 에 마커가 미리 들어 있습니다.
+
 같은 지적은 숨김 marker를 기준으로 중복 게시하지 않고, 메시지가 바뀌면 기존 댓글을 갱신합니다.
 모노레포에서는 workflow와 `tools/`가 루트에 한 번만 존재하며, PR에서 변경된 TypeScript 파일을
 대상으로 검사합니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.10.0",
+  "version": "2.0.0",
   "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,116 @@ 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\` | Accordion, Input, Checkbox, Toggle, Dropdown, Table, Tooltip, Pagination, Calendar, BottomSheet, Breadcrumb, Modal(Alert·Confirm·Choice), ToastMessage, UIThemeProvider |
+| \`@byuckchon-frontend/settings\` | ESLint / Prettier / tsconfig 프리셋, 모션 토큰, 디자인 토큰 변환 |
+
+**작업 순서**
+
+1. 위 표에서 찾아본다
+2. 애매하면 실제 export 를 확인한다 — 위 목록은 스냅샷이라 최신이 아닐 수 있다
+   \`\`\`bash
+   cat node_modules/@byuckchon-frontend/hooks/dist/index.d.ts
+   \`\`\`
+3. 없으면 그때 직접 구현한다
+
+없는 걸 억지로 끼워 맞추지는 마세요. 쓰임이 다르면 직접 만드는 게 맞습니다.
+
+## 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 +323,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 +356,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 +473,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 +485,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/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/src/generators/scaffoldReviewAutomation.js

@@ -74,7 +74,7 @@ async function copyFileIfAllowed(source, target, overwrite) {
  * @param {'single' | 'monorepo'} args.projectType 생성할 프로젝트 유형
  * @param {boolean} [args.overwrite=true] 기존 파일을 템플릿으로 덮어쓸지
  * @param {string[]} [args.exclude=[]] 제외할 워크플로 이름 (확장자·유형 접미사 제외)
- * @returns {Promise<{ toolsDir: string, workflows: string[] }>}
+ * @returns {Promise<{ toolsDir: string, workflows: string[], pullRequestTemplate: boolean }>}
  */
 export async function scaffoldReviewAutomation({
   projectRoot,
@@ -111,5 +111,16 @@ export async function scaffoldReviewAutomation({
     if (copied) copiedWorkflows.push(target);
   }
 
-  return { toolsDir: toolsTargetDir, workflows: copiedWorkflows };
+  // PR 템플릿 — 커밋 내역이 채워질 마커를 품고 있다.
+  const pullRequestTemplate = await copyFileIfAllowed(
+    path.join(TEMPLATE_ROOT, 'github', 'pull_request_template.md'),
+    path.join(projectRoot, '.github', 'pull_request_template.md'),
+    overwrite,
+  );
+
+  return {
+    toolsDir: toolsTargetDir,
+    workflows: copiedWorkflows,
+    pullRequestTemplate,
+  };
 }

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

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

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

@@ -0,0 +1,58 @@
+# PR 본문에 커밋 내역을 자동으로 채워 넣습니다.
+#
+# 사람이 쓴 내용은 건드리지 않고, 아래 마커 사이만 갱신합니다.
+#   <!-- byuckchon:commits:start --> ~ <!-- byuckchon:commits:end -->
+# 마커가 없으면 본문 끝에 한 번 덧붙입니다. (PR 템플릿이 없어도 동작)
+#
+# 커밋 메시지를 `feat:` `fix:` 처럼 쓰면 타입별로 묶이고,
+# 컨벤션을 안 지킨 커밋은 "분류 없음"으로 모입니다.
+#
+# 커밋 본문에 NOTE: 또는 TODO: 로 적은 줄은 "리뷰 포인트"로 따로 모입니다.
+# AI 로 코드를 짤 때 "여긴 리뷰어가 봐야 한다"를 남겨두는 용도로 쓰세요.
+#
+# PR 제목에는 브랜치명의 첫 토막이 대괄호로 붙습니다.
+#   feature/update-mypage-style/hyuk + "마이페이지 디자인 적용"
+#     → "[feature] 마이페이지 디자인 적용"
+# 사람이 쓴 제목은 그대로 두고 앞에만 붙이며, 이미 대괄호가 있으면 건드리지 않습니다.
+#
+# 복사된 파일이므로 프로젝트 소유입니다. 대상 브랜치 등은 자유롭게 수정하세요.
+
+name: PR Description
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+    branches:
+      - dev
+
+concurrency:
+  group: pr-description-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  describe:
+    name: 커밋 내역 반영
+    # changeset 릴리즈 PR 처럼 봇이 연 PR 은 본문을 그대로 둔다.
+    if: ${{ !endsWith(github.event.pull_request.user.login, '[bot]') }}
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+
+      - name: PR 본문 갱신
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          # 프로젝트가 고정한 settings 버전을 그대로 사용합니다.
+          # (전체 의존성 설치 없이 이 패키지만 받아 실행)
+          VERSION=$(node -p "const p=require('./package.json'); (p.devDependencies?.['@byuckchon-frontend/settings'] ?? p.dependencies?.['@byuckchon-frontend/settings'] ?? 'latest')")
+          npx --yes --package "@byuckchon-frontend/settings@${VERSION}" byuckchon-pr-description