sh-ui-cli 0.64.6 → 0.64.7

package/data/changelog/versions.json

@@ -2,6 +2,18 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "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.64.7",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

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\` 로 먼저 변경 매트릭스 보여주고 사용자 확인 후 실행 권장.