sh-ui-cli 0.71.0 → 0.71.2

package/bin/sh-ui.mjs

@@ -109,7 +109,47 @@ try {
     }
     case "doctor": {
       const { doctor } = await import("../src/doctor.mjs");
-      await doctor({ cwd: process.cwd() });
+      const { existsSync, readdirSync } = await import("node:fs");
+      const { resolve } = await import("node:path");
+      // add 와 같은 walk-up + monorepo 라우팅. standalone 이면 그 root 1개,
+      // monorepo 면 packages/ui/ui-core + ui-apps/ui-* 모두 순회.
+      const ctx = findShUiContext(process.cwd());
+      if (!ctx) {
+        console.error(
+          "✗ sh-ui.config.json 또는 pnpm-workspace.yaml 을 cwd 부터 부모 트리에서 찾지 못했습니다.",
+        );
+        process.exit(1);
+      }
+      let anyFailed = false;
+      const targets = [];
+      if (ctx.kind === "config") {
+        targets.push(ctx.root);
+      } else {
+        const uiCore = resolve(ctx.root, "packages/ui/ui-core");
+        if (existsSync(resolve(uiCore, "sh-ui.config.json"))) targets.push(uiCore);
+        const uiAppsRoot = resolve(ctx.root, "packages/ui/ui-apps");
+        if (existsSync(uiAppsRoot)) {
+          for (const name of readdirSync(uiAppsRoot)) {
+            const dir = resolve(uiAppsRoot, name);
+            if (existsSync(resolve(dir, "sh-ui.config.json"))) targets.push(dir);
+          }
+        }
+        if (targets.length === 0) {
+          console.error(
+            "✗ monorepo 에서 sh-ui.config.json 가지는 패키지를 찾지 못했습니다.\n" +
+              "  packages/ui/ui-core/ 또는 packages/ui/ui-apps/ui-*/ 에 있어야 합니다.",
+          );
+          process.exit(1);
+        }
+      }
+      for (const target of targets) {
+        if (targets.length > 1) {
+          console.log(`\n────  ${target.replace(ctx.root + "/", "")}  ────`);
+        }
+        const result = await doctor({ cwd: target });
+        if (!result.ok) anyFailed = true;
+      }
+      if (anyFailed) process.exit(1);
       break;
     }
     case "theme": {

package/data/changelog/versions.json

@@ -2,6 +2,32 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.71.2",
+      "date": "2026-05-09",
+      "title": "fix(doctor) — monorepo walk-up + 컴포넌트-only 패키지 인식",
+      "type": "patch",
+      "highlights": [
+        "**doctor 의 walk-up + monorepo 라우팅** — `add` 와 같은 정책을 적용. monorepo 어느 디렉토리 (apps/web, ui-core 안 등) 에서 실행해도 `packages/ui/ui-core` 와 모든 `packages/ui/ui-apps/ui-*` 를 자동 순회. 각 패키지마다 헤더 출력 + 결과 집계, 하나라도 fail 이면 exit 1.",
+        "**컴포넌트-only 패키지 인식** — ui-core 처럼 `paths.tokens` 가 없는 패키지는 의도된 형태. 이전엔 'theme 미설정 / 토큰 검증 스킵' 로 fail/warn 폭발 → 이제 ✓ '(컴포넌트 only — 토큰 없음, 검증 스킵)' 한 줄로 정리.",
+        "**doctor 함수 시그니처** — `process.exit()` 직접 호출 대신 `{ ok, failCount, warnCount }` 반환. 호출부 (bin) 가 monorepo 순회 후 집계 exit. API consumer (테스트, 향후 lint:doctor 등) 도 활용 가능."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.71.2"
+    },
+    {
+      "version": "0.71.1",
+      "date": "2026-05-09",
+      "title": "chore(mcp): instructions 에 v0.68~0.71 신규 명령 가이드 반영",
+      "type": "patch",
+      "highlights": [
+        "**MCP `instructions` 갱신** — `sh-ui doctor` (v0.68), `sh-ui tokens diff/upgrade --apply/--replace` (v0.69), `sh-ui theme extract` (v0.70), `cssStrategy: bundled` (v0.71) 사용 시점을 명시. AI 가 사용자 의도 (\"focus 표시 안 보임\", \"새 토큰 받아줘\", \"색 base64 로 뽑아줘\", \"styles.css 너무 많아\") 와 Bash 명령 호출을 직접 매핑.",
+        "**진단 흐름** — UI 작업 후 시각적 깨짐 또는 사용자가 토큰을 손댄 직후 doctor 권장. 누락 토큰 신호 시 tokens upgrade --apply 로 incremental 적용.",
+        "**토큰 마이그레이션 가이드** — tokens diff 로 미리보기 → --apply (사용자 편집 보존) 또는 --replace (리셋) 선택. buildable preset 제약 + custom/rich preset 은 encode/decode round-trip 으로 우회.",
+        "**theme extract 활용 패턴** — encode 의 역방향. tokens.css 직접 편집 후 base64 추출 → 다른 앱에 동일 톤 박기 또는 디자인 시스템 문서 보존.",
+        "**cssStrategy: bundled 전환 가이드** — config 옵션 + paths.cssBundle 안내 + globals.css import 책임 + 마이그레이션 시 force=true 재실행."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.71.1"
+    },
     {
       "version": "0.71.0",
       "date": "2026-05-09",

package/package.json

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

package/src/doctor.mjs

@@ -72,16 +72,18 @@ async function loadConfig(cwd, report) {
     const config = JSON.parse(await readFile(configPath, "utf8"));
     const issues = [];
     if (!config.platform) issues.push("platform 미설정");
-    if (!config.theme) issues.push("theme 미설정");
     if (!config.paths) issues.push("paths 미설정");
+    // theme 은 컴포넌트-only 패키지 (monorepo ui-core, paths.tokens 없음) 에서는
+    // 의도적으로 비어 있다 — 그땐 누락이라고 보지 않음.
+    if (!config.theme && config.paths?.tokens) issues.push("theme 미설정");
     if (issues.length > 0) {
       report.fail("sh-ui.config.json", `필수 필드 누락: ${issues.join(", ")}`);
       return null;
     }
+    const themeInfo = config.theme?.base ? `theme.base=${config.theme.base}` : "(컴포넌트 only)";
     report.ok(
       "sh-ui.config.json",
-      `platform=${config.platform} theme.base=${config.theme?.base ?? "?"} ` +
-        `cssFramework=${config.cssFramework ?? "(기본 plain)"}`,
+      `platform=${config.platform} ${themeInfo} cssFramework=${config.cssFramework ?? "(기본 plain)"}`,
     );
     return config;
   } catch (err) {
@@ -93,10 +95,11 @@ async function loadConfig(cwd, report) {
 function checkTokensFile(config, cwd, report) {
   const rel = config.paths?.tokens;
   if (!rel) {
-    // 모노레포 ui-core 처럼 tokens 를 가지지 않는 패키지 — 이 경우 검사 스킵.
-    report.warn(
+    // 모노레포 ui-core 처럼 토큰을 가지지 않는 컴포넌트-only 패키지 — 이 케이스는
+    // 정상이라 안내 한 줄만 ok 로 표시 (warn 으로 노이즈 만들지 않음).
+    report.ok(
       "paths.tokens",
-      "config 에 paths.tokens 가 없습니다 — 토큰 검증 스킵.",
+      "(컴포넌트 only — 토큰 없음, 검증 스킵)",
     );
     return null;
   }
@@ -171,6 +174,14 @@ async function checkCssEntry(config, cwd, tokensPath, report) {
  */
 async function checkInstalledComponents(config, cwd, definedVars, report) {
   if (!definedVars) {
+    // tokens 없는 컴포넌트-only 패키지 — 의존성 검증은 의미 없음. 조용히 ok.
+    if (!config.paths?.tokens) {
+      report.ok(
+        "컴포넌트 토큰 의존성",
+        "(컴포넌트 only — 검증 스킵)",
+      );
+      return;
+    }
     report.warn(
       "컴포넌트 토큰 의존성",
       "tokens.css 가 없어 검증 스킵.",
@@ -290,6 +301,10 @@ function effectiveFramework(entry, cssFramework) {
   return hasVariant ? cssFramework : "plain";
 }
 
+/**
+ * @returns {Promise<{ ok: boolean, failCount: number, warnCount: number }>}
+ *          호출부가 exit code 결정. 한 cwd 에서 다른 cwd 로 이어 호출 가능 (monorepo 순회).
+ */
 export async function doctor({ cwd }) {
   console.log(`sh-ui doctor — ${relative(process.cwd(), cwd) || "."}\n`);
   const report = new Report();
@@ -297,7 +312,7 @@ export async function doctor({ cwd }) {
   const config = await loadConfig(cwd, report);
   if (!config) {
     report.render();
-    process.exit(1);
+    return { ok: false, failCount: report.failCount, warnCount: report.warnCount };
   }
 
   const tokensPath = checkTokensFile(config, cwd, report);
@@ -312,5 +327,5 @@ export async function doctor({ cwd }) {
   await checkInstalledComponents(config, cwd, definedVars, report);
 
   report.render();
-  if (report.failCount > 0) process.exit(1);
+  return { ok: report.failCount === 0, failCount: report.failCount, warnCount: report.warnCount };
 }

package/src/mcp.mjs

@@ -194,6 +194,43 @@ function buildServerInstructions(cliName) {
 - \`sh_ui_add_component\` / \`sh_ui_remove_component\` — 설치/삭제
 - \`sh_ui_get_changelog\` — 최근 변경 내역
 
+## 진단 — sh-ui doctor (v0.68+)
+
+UI 작업이 끝났는데 컴포넌트가 시각적으로 깨졌거나 ("focus outline 안 보임", "hover 색 변화 없음" 류) 사용자가 sh-ui 버전을 올린 직후 / 토큰을 손댄 직후라면 \`npx ${cliName} doctor\` 를 Bash 로 실행해 한 번에 점검:
+- sh-ui.config.json / paths.tokens / paths.cssEntry import / 설치된 컴포넌트의 토큰 의존성 검증
+- 누락 토큰 (silent breakage) 을 fail 로 표시 — 화면이 깨진 이유를 즉시 파악
+- exit 1 이면 사용자에게 어떤 토큰이 누락됐는지 보고 + \`sh-ui tokens upgrade --apply\` 권장
+
+## 토큰 마이그레이션 — tokens diff / upgrade (v0.69+)
+
+사용자가 sh-ui 버전을 올린 뒤 "새 토큰이 들어왔어?" / "tokens.css 업그레이드해줘" 류 요청 또는 doctor 가 누락 토큰을 신호하면:
+
+1. **\`npx ${cliName} tokens diff\`** — 현재 tokens.css vs buildTokens 결과의 added/changed/removed 미리보기. 사용자에게 결과를 보여주고 어떤 모드로 적용할지 확인.
+2. **\`npx ${cliName} tokens upgrade --apply\`** — added 변수만 incremental 추가 (사용자가 손댄 색은 보존). 대부분의 경우 이쪽.
+3. **\`npx ${cliName} tokens upgrade --replace\`** — 사용자가 "표준값으로 리셋" 명시할 때만. 모든 편집이 사라짐.
+
+제약: theme.base 가 buildable preset (neutral/zinc/slate) 일 때만 동작. custom (base64) / rich preset (rose/emerald/violet) 은 친절 에러로 종료 — 그땐 \`sh_ui_decode_theme\` → 객체 수정 → \`sh_ui_encode_theme\` round-trip 으로 새 base64 만들어 재스캐폴드.
+
+## 테마 추출 — theme extract (v0.70+)
+
+사용자가 "지금 색 그대로 다른 앱에 박고 싶어" / "현재 토큰 base64 로 뽑아줘" / "디자인 시스템 문서에 색 스냅샷 저장" 같은 요청에는 \`npx ${cliName} theme extract\` (Bash):
+- 현재 tokens.css 의 light/dark + radius 를 sh-ui base64 로 추출 (stdout, stderr 에 정보 분리)
+- 추출된 base64 를 \`sh_ui_create_project\` 의 \`theme\` 인자에 그대로 넘기면 동일 톤의 새 앱 생성
+- \`sh_ui_encode_theme\` 의 역방향 — 사용자가 tokens.css 를 직접 손댄 결과를 다시 base64 화
+
+제약: tokens.css 모든 필수 색이 #RRGGBB 여야 함. color-mix() / var() / rgba() 가 섞이면 친절 에러 — 먼저 \`tokens upgrade --replace\` 로 표준값 hex 화 후 재시도 권장.
+
+## CSS 번들 모드 — cssStrategy: bundled (v0.71+)
+
+사용자가 "컴포넌트 폴더에 styles.css 너무 많이 떨어진다" / "한 파일로 합치고 싶어" 류 요청 또는 50개+ 컴포넌트 깐 모노레포에서 파일 폭증을 호소하면:
+
+1. **\`sh-ui.config.json\` 에 \`cssStrategy: "bundled"\` + \`paths.cssBundle: "src/styles/sh-ui-components.css"\` 추가**.
+2. 사용자가 \`paths.cssBundle\` 을 globals.css 에서 한 번 import (자동화 안 함 — 사용자에게 안내).
+3. 이후 \`sh_ui_add_component\` 가 컴포넌트 styles.css 를 cssBundle 의 \`/* sh-ui:component:NAME-start ... -end */\` 마커 섹션으로 누적. 컴포넌트 .tsx 의 styles.css import 는 자동 제거.
+4. \`sh_ui_remove_component\` 도 .tsx + 번들 섹션을 같이 정리.
+
+제약: \`cssFramework: "plain"\` 에서만 동작. tailwind/css-modules/vanilla-extract 는 자체 스코프가 있어 bundled 무시. 기존 per-component 프로젝트에서 bundled 로 마이그레이션은 자동화 없음 — config 추가 후 모든 컴포넌트 \`sh_ui_add_component force=true\` 재실행 안내.
+
 ### 모노레포 라우팅 (v0.65+)
 
 monorepo 에서 \`sh_ui_add_component\` 호출 시: