sh-ui-cli 0.64.6 → 0.65.0

package/data/changelog/versions.json

@@ -2,6 +2,31 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.65.0",
+      "date": "2026-05-09",
+      "title": "monorepo 컴포넌트 단일 SoT — ui-core 도입, ui-app 은 tokens-only",
+      "type": "minor",
+      "highlights": [
+        "**컴포넌트 중복 emit 제거** — monorepo 에서 `sh-ui add <component>` 가 `packages/ui/ui-core` 한 곳에만 컴포넌트/훅을 떨어뜨림. 이전엔 ui-{app} 마다 같은 파일이 복제돼 sync 비용이 컸다.",
+        "**역할 분리** — `ui-core` 가 컴포넌트/훅/lib SoT, `ui-{app}` 은 토큰/스타일 전용 (`role: \"tokens-only\"` 마커). `sh-ui add tokens` 만 ui-app 으로 라우팅, 그 외는 모두 ui-core.",
+        "**친절한 거부 메시지** — 사용자가 ui-app 에서 직접 `sh-ui add button` 을 실행하면 \"ui-core 에 추가하세요\" 안내 후 종료. 잘못된 위치에 컴포넌트 누적 차단.",
+        "**v0.64.x 호환 fallback** — 기존 monorepo 레이아웃(ui-core 부재)에서는 자동으로 ui-apps 직접 라우팅으로 폴백. 마이그레이션 자동 도구는 후속 v0.66.0 (PR-D)."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.65.0"
+    },
+    {
+      "version": "0.64.7",
+      "date": "2026-05-08",
+      "title": "patch — MCP instructions 에 \"UI 짤 때 사고 순서\" 섹션 추가 (raw HTML 기본값 회피)",
+      "type": "patch",
+      "highlights": [
+        "**MCP server `instructions` 에 AI 행동 가이드 추가** — sh-ui MCP 가 등록되면 매 세션 상단에 노출되는 instructions 텍스트에 \"UI 짤 때 사고 순서\" 섹션 추가. AI 가 `<aside>` / `<nav>` / `<header>` / `<table>` 같은 시맨틱 태그를 raw 로 쓰기 전에 `sh_ui_list_components` 로 카탈로그를 훑고, Sidebar / Header / Breadcrumb 같은 위젯 단위 컴포넌트를 우선 사용하도록 유도.",
+        "**흔한 누락 패턴 4건 명시** — Sidebar 직접 짜기, Breadcrumb 직접 짜기, DialogClose render prop 누락, Card 미사용. 이전 세션에서 실제로 반복된 실수를 instructions 에 박아 같은 회귀 차단.",
+        "**raw HTML 폴백이 정당한 경우 가이드** — 카탈로그에 매칭 없음 / 의도적 변형 / ad-hoc 레이아웃. 코드에 한 줄 코멘트로 의도 남기기 권장."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.64.7"
+    },
     {
       "version": "0.64.6",
       "date": "2026-05-08",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.64.6",
+  "version": "0.65.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/add.mjs

@@ -363,6 +363,19 @@ export async function add({
     );
   }
 
+  // role: "tokens-only" 패키지 (v0.65+ ui-app) 는 tokens 만 허용.
+  // 컴포넌트는 sibling ui-core 패키지로 라우팅되도록 친절한 에러로 안내.
+  if (config.role === "tokens-only") {
+    const offending = names.filter((n) => n !== "tokens");
+    if (offending.length > 0) {
+      throw new Error(
+        `이 패키지는 'tokens-only' role 입니다 — ${offending.map((n) => `'${n}'`).join(', ')} 컴포넌트를 추가할 수 없습니다.\n` +
+          `컴포넌트는 sibling ui-core 패키지에 추가하세요 (예: cd ../ui-core && sh-ui add ${offending[0]}).\n` +
+          `또는 monorepo 루트에서 \`sh-ui add ${offending[0]}\` 실행 시 자동으로 ui-core 로 라우팅됩니다.`,
+      );
+    }
+  }
+
   // 비대화형(non-TTY)이면 prompt 를 못 띄우니 안전하게 keep 으로 강등.
   const effectiveStrategy =
     onConflict === "prompt" && !process.stdin.isTTY ? "keep" : onConflict;

package/src/create/generator.js

@@ -401,9 +401,45 @@ export async function addComponent(componentName, appName) {
     return;
   }
 
-  // Monorepo: packages/ui/ui-apps/* 에서 실행
+  // Monorepo (v0.65+): tokens 는 packages/ui/ui-apps/ui-{app} 으로, 그 외 컴포넌트/훅은
+  // packages/ui/ui-core 단일 SoT 로 라우팅. 컴포넌트 중복 emit 제거가 v0.65 의 핵심.
+  // v0.64.x 호환: ui-core/sh-ui.config.json 미존재 시 (구 모노레포 레이아웃) 기존 ui-apps
+  //   직접 라우팅 분기로 내려감.
+  const uiCoreDir = path.join(cwd, 'packages', 'ui', 'ui-core');
   const uiAppsDir = path.join(cwd, 'packages', 'ui', 'ui-apps');
-  if (!(await fs.pathExists(uiAppsDir))) {
+  const hasUiCore = await fs.pathExists(path.join(uiCoreDir, 'sh-ui.config.json'));
+  const hasUiApps = await fs.pathExists(uiAppsDir);
+
+  if (!hasUiCore && !hasUiApps) {
+    console.log('❌ packages/ui/ui-core 또는 packages/ui/ui-apps/ 디렉토리가 없습니다.');
+    return;
+  }
+
+  if (!componentName) {
+    componentName = await input({ message: '컴포넌트 이름:' });
+  }
+
+  const isTokens = componentName === 'tokens';
+
+  // ─── 비-tokens (컴포넌트/훅/lib) → ui-core 단일 라우팅 ───
+  if (!isTokens && hasUiCore) {
+    if (appName) {
+      console.log(
+        `ℹ️  v0.65+ 에서 컴포넌트는 packages/ui/ui-core 에 단일 emit 됩니다 (--app ${appName} 무시).`,
+      );
+    }
+    console.log(`\n📦 packages/ui/ui-core 에 ${componentName} 추가 중...`);
+    try {
+      execSync(`npx sh-ui add ${componentName}`, { cwd: uiCoreDir, stdio: 'inherit' });
+      console.log(`✅ packages/ui/ui-core 완료`);
+    } catch (error) {
+      console.log(`❌ packages/ui/ui-core 실패: ${error.message}`);
+    }
+    return;
+  }
+
+  // ─── tokens → ui-apps/ui-{app}(s), 또는 v0.64.x 호환 fallback (ui-core 없음) ───
+  if (!hasUiApps) {
     console.log('❌ packages/ui/ui-apps/ 디렉토리가 없습니다.');
     return;
   }
@@ -418,10 +454,6 @@ export async function addComponent(componentName, appName) {
     return;
   }
 
-  if (!componentName) {
-    componentName = await input({ message: '컴포넌트 이름:' });
-  }
-
   let targets;
   if (appName) {
     const pkgName = `ui-${appName}`;
@@ -431,9 +463,11 @@ export async function addComponent(componentName, appName) {
       return;
     }
     targets = [pkgName];
+  } else if (uiPackages.length === 1) {
+    targets = uiPackages;
   } else {
     const choice = await select({
-      message: '어디에 추가할까요?',
+      message: isTokens ? '어느 ui 패키지에 토큰을 추가할까요?' : '어디에 추가할까요?',
       choices: [
         { name: '모든 ui 패키지', value: 'all' },
         ...uiPackages.map((name) => ({ name: `packages/ui/ui-apps/${name}`, value: name })),

package/src/mcp.mjs

@@ -175,6 +175,30 @@ function buildServerInstructions(cliName) {
 - \`sh_ui_add_component\` / \`sh_ui_remove_component\` — 설치/삭제
 - \`sh_ui_get_changelog\` — 최근 변경 내역
 
+## UI 짤 때 사고 순서 (raw HTML 기본값 회피)
+
+새 위젯·페이지를 작성할 때 \`<aside>\` / \`<nav>\` / \`<header>\` / \`<table>\` / \`<button>\` 같은 시맨틱 태그를 raw 로 쓰기 전에:
+
+1. **\`sh_ui_list_components\` 로 카탈로그 한 번 훑기** — Sidebar / Header / AppShell / Breadcrumb / Pagination / Tabs 등 **위젯 단위** 컴포넌트도 있다 (Button/Input 같은 primitive 만 있는 게 아님). "사이드바 직접 짜야지" 같은 자동 사고를 의식적으로 멈추고 카탈로그 확인.
+2. 매칭되는 sh-ui 컴포넌트가 있으면 **그걸 우선 사용**. \`sh_ui_get_component\` 로 props/사용 패턴 확인.
+3. 매칭 없을 때만 raw HTML + Tailwind 폴백.
+4. \`sh_ui_add_component\` 로 설치한 컴포넌트는 페이지 작성 단계에서 다시 의식적으로 import — install 해놓고 안 쓰는 누락이 잦다 (Breadcrumb / DropdownMenu 류). add 시점에 사용처를 머릿속에 메모하고, 페이지 짤 때 그 목록을 한 번 훑기.
+
+### raw HTML 폴백이 정당한 경우
+- 카탈로그에 매칭 컴포넌트 없음 (예: \`<table>\` — sh-ui 에 table 없음)
+- 의도적인 변형 (sh-ui 변종에 없는 dashed border 카드 등)
+- 한 번 쓰는 ad-hoc 레이아웃
+
+이런 경우라도 **"sh-ui 에 X 없어서 직접"** 같은 코멘트를 짧게 남기면 다음 작업자(사람·AI) 가 의도 인식 가능.
+
+### 흔한 누락 패턴
+
+이전 세션에서 반복된 실수:
+- 사이드바를 \`<aside>\` + \`<Link>\` 로 직접 짬 → sh-ui 의 \`Sidebar\` / \`SidebarProvider\` / \`SidebarMenu\` 등 풍부한 API 가 있음
+- breadcrumb 을 \`<nav><Link>···<ChevronRight />···</nav>\` 로 직접 짬 → \`Breadcrumb\` / \`BreadcrumbList\` / \`BreadcrumbItem\` / \`BreadcrumbSeparator\` 가 카탈로그에 있음
+- 다이얼로그 cancel 버튼을 \`<Button onClick={() => setOpen(false)}>\` 로 우회 → 정석은 \`<DialogClose render={<Button>취소</Button>} />\` (Base UI render prop)
+- table 외관의 카드 그리드를 raw \`<div>\` 로 → \`Card\` / \`CardHeader\` / \`CardContent\` / \`CardFooter\` 사용
+
 ## 앱 이름 변경 (monorepo)
 
 사용자가 "apps/web 을 apps/dashboard 로 바꿔줘" 같이 모노레포 앱 이름 변경을 요청하면 \`sh_ui_rename_app\` 사용 — 손으로 6~10 군데 (디렉토리, package.json name, tsconfig paths, Dockerfile WORKDIR, next.config transpilePackages, sh-ui.config aliases, README, .github/workflows) 갈아엎지 않도록 자동화. \`dryRun: true\` 로 먼저 변경 매트릭스 보여주고 사용자 확인 후 실행 권장.

package/templates/monorepo/packages/ui/ui-core/package.json

@@ -7,17 +7,29 @@
     "lint": "eslint . --max-warnings 0"
   },
   "dependencies": {
+    "@base-ui/react": "^1.4.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "tailwind-merge": "^3.5.0"
+    "lucide-react": "^0.563.0",
+    "next-themes": "^0.4.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-hook-form": "^7.56.4",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
     "@workspace/eslint-config": "workspace:*",
     "@workspace/typescript-config": "workspace:*",
     "eslint": "^9.39.2",
     "typescript": "^5.9.3"
   },
   "exports": {
+    "./components/*": "./src/components/*.tsx",
+    "./hooks/*": "./src/hooks/*.ts",
     "./lib/*": "./src/lib/*.ts"
   }
 }

package/templates/monorepo/packages/ui/ui-core/sh-ui.config.json

@@ -0,0 +1,15 @@
+{
+  "platform": "react",
+  "cssFramework": "plain",
+  "paths": {
+    "components": "src/components",
+    "hooks": "src/hooks",
+    "utils": "src/lib/utils.ts"
+  },
+  "aliases": {
+    "components": "@workspace/ui-core/components",
+    "hooks": "@workspace/ui-core/hooks",
+    "utils": "@workspace/ui-core/lib/utils",
+    "ui": "@workspace/ui-core/components"
+  }
+}

package/templates/ui-app-template/package.json

@@ -7,15 +7,9 @@
     "lint": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@base-ui/react": "^1.4.1",
     "@workspace/ui-core": "workspace:*",
-    "lucide-react": "^0.563.0",
-    "next-themes": "^0.4.6",
     "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "react-hook-form": "^7.56.4",
-    "sonner": "^2.0.7",
-    "zod": "^4.3.6"
+    "react-dom": "^19.2.4"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",
@@ -30,9 +24,6 @@
   },
   "exports": {
     "./globals.css": "./src/styles/globals.css",
-    "./postcss.config": "./postcss.config.mjs",
-    "./lib/*": "./src/lib/*.ts",
-    "./components/*": "./src/components/*.tsx",
-    "./hooks/*": "./src/hooks/*.ts"
+    "./postcss.config": "./postcss.config.mjs"
   }
 }

package/templates/ui-app-template/sh-ui.config.json

@@ -1,6 +1,7 @@
 {
   "platform": "react",
   "cssFramework": "plain",
+  "role": "tokens-only",
   "theme": {
     "base": "neutral",
     "radius": "md",
@@ -8,13 +9,6 @@
   },
   "paths": {
     "tokens": "src/styles/tokens.css",
-    "styles": "src/styles",
-    "components": "src/components",
-    "utils": "src/lib/utils.ts"
-  },
-  "aliases": {
-    "components": "@workspace/ui-app-name/components",
-    "utils": "@workspace/ui-app-name/lib/utils",
-    "ui": "@workspace/ui-app-name/components"
+    "styles": "src/styles"
   }
 }