sh-ui-cli 0.72.0 → 0.74.0

package/bin/sh-ui.mjs

@@ -16,6 +16,7 @@ const usage = `사용법:
                                    특수값: tokens → 설정 기반 토큰 파일 생성
   sh-ui list                       현재 설치된 컴포넌트 목록 표시
   sh-ui doctor                     프로젝트 정합성 점검 (config / tokens / 설치된 컴포넌트)
+  sh-ui upgrade-cli [--apply]      sh-ui-cli 자체를 최신으로 업그레이드 + 설치 후 진단
   sh-ui tokens diff                tokens.css 와 buildTokens 결과 비교 (added/changed/removed)
   sh-ui tokens upgrade [--apply|--replace]
                                    --apply: 추가만 incremental (사용자 편집 보존)
@@ -155,6 +156,12 @@ try {
       if (anyFailed) process.exit(1);
       break;
     }
+    case "upgrade-cli": {
+      const apply = rest.includes("--apply");
+      const { runUpgradeCli } = await import("../src/upgrade-cli.mjs");
+      await runUpgradeCli({ cwd: process.cwd(), apply });
+      break;
+    }
     case "theme": {
       const sub = rest[0];
       const flags = rest.slice(1);

package/data/changelog/versions.json

@@ -2,6 +2,33 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.74.0",
+      "date": "2026-05-10",
+      "title": "DX — sh-ui.config.json JSON Schema + sh-ui upgrade-cli",
+      "type": "minor",
+      "highlights": [
+        "**JSON Schema for sh-ui.config.json** — `packages/cli/sh-ui.schema.json` 신설. `$schema` 필드를 GitHub raw URL 로 통일 (`https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json`). VS Code / Cursor 등이 자동 fetch 해서 키 자동완성 + enum 값 제안 + 오타 빨간 줄. platform / cssFramework / cssStrategy / theme.base / paths.* / aliases.* 모두 description 과 examples 포함.",
+        "**조건부 require** — `cssStrategy: \"bundled\"` 면 `paths.cssBundle` 필수, JSON Schema if/then 으로 자동 검증.",
+        "**`sh-ui upgrade-cli` 명령** — npm registry 의 latest 버전과 사용자 node_modules 의 설치본 비교. 사이의 changelog highlights (versions.json) 자동 출력. `--apply` 시 사용자 패키지 매니저로 자동 install + 설치 후 doctor / tokens diff 권장 흐름 안내.",
+        "**모든 템플릿 + init/create + apps/docs 의 sh-ui.config.json 에 \\$schema 일괄 적용** — 신규 프로젝트는 처음부터 IDE validation 동작."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.74.0"
+    },
+    {
+      "version": "0.73.0",
+      "date": "2026-05-10",
+      "title": "Flutter — theme extract + tokens diff/upgrade Dart 지원",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui theme extract` Flutter 지원** — `sh_ui_tokens.dart` 의 `static const light/dark` 블록에서 `Color(0xFFRRGGBB)` 를 추출해 sh-ui base64 로 인코딩. alpha 채널은 무시 (#RRGGBB 만 인코딩), `defaultRadius` 픽셀값을 16 으로 나눠 rem 변환.",
+        "**`sh-ui tokens diff` Flutter 지원** — Dart 의 `static const` 블록을 `<ClassName>.<staticName>` 키로 평탄화 후 field-level 비교. nested 함수 호출 (`Color(0x...)`, `Cubic(0.4, 0, 0.2, 1)`, `Duration(milliseconds: 120)`, `<BoxShadow>[...]`) 를 깊이 카운터로 안전하게 split — 간단 정규식 파서가 깨지지 않음.",
+        "**`sh-ui tokens upgrade --replace` Flutter 지원** — buildTokensDart 결과로 통째 덮어쓰기.",
+        "**`--apply` 는 Flutter 미지원** — Dart 클래스에 필드 추가는 (1) class field 선언, (2) constructor 파라미터, (3) 모든 static const 인스턴스화 3 군데를 동시에 수정해야 해서 incremental 적용이 위험. 친절 에러로 안내 + `--replace` 권장.",
+        "**dispatch 통합** — tokens-cmd / theme-extract 가 platform 으로 분기. React (CSS) 와 Flutter (Dart) 가 같은 명령 표면 공유."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.73.0"
+    },
     {
       "version": "0.72.0",
       "date": "2026-05-10",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.72.0",
+  "version": "0.74.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {
@@ -56,6 +56,7 @@
     "src",
     "data",
     "templates",
+    "sh-ui.schema.json",
     "LICENSE",
     "README.md"
   ]

package/sh-ui.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
+  "title": "sh-ui project configuration",
+  "description": "sh-ui CLI 가 읽는 프로젝트 설정. 컴포넌트 추가/제거/토큰 빌드의 모든 동작이 이 파일을 따라간다.",
+  "type": "object",
+  "required": ["platform", "paths"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema URL — IDE 자동완성용. 그대로 두는 게 안전."
+    },
+    "platform": {
+      "enum": ["react", "flutter"],
+      "description": "타겟 플랫폼. React (웹) 또는 Flutter."
+    },
+    "cssFramework": {
+      "enum": ["plain", "tailwind", "css-modules", "vanilla-extract"],
+      "description": "CSS 변종. plain = 표준 CSS + var(--*), tailwind = utility class, css-modules = .module.css, vanilla-extract = .css.ts (실험). React 전용 — Flutter 면 무시.",
+      "default": "plain"
+    },
+    "cssStrategy": {
+      "enum": ["per-component", "bundled"],
+      "description": "컴포넌트 CSS 전략. per-component = 각 컴포넌트 폴더에 styles.css (기본). bundled = paths.cssBundle 단일 파일에 마커 섹션 (v0.71+). React + plain 만 지원.",
+      "default": "per-component"
+    },
+    "role": {
+      "enum": ["tokens-only"],
+      "description": "v0.65+ 모노레포 ui-app 에 부여 — 컴포넌트 추가는 sibling ui-core 로 라우팅하고 tokens 만 허용."
+    },
+    "theme": {
+      "type": "object",
+      "description": "디자인 토큰의 색·radius·모드 설정. buildTokens 가 이 값으로 tokens.css 또는 sh_ui_tokens.dart 를 생성.",
+      "additionalProperties": false,
+      "properties": {
+        "base": {
+          "type": "string",
+          "description": "기본 색 스케일. buildable preset (neutral/zinc/slate) 은 buildTokens 로 재생성 가능. rich preset (rose/emerald/violet) 또는 'custom' (base64 originated) 은 보존-only.",
+          "examples": ["neutral", "zinc", "slate", "rose", "emerald", "violet", "custom"]
+        },
+        "radius": {
+          "enum": ["none", "sm", "md", "lg", "xl", "full"],
+          "description": "기본 코너 반경 — buildTokens 가 --radius CSS 변수로 emit."
+        },
+        "mode": {
+          "enum": ["light", "dark", "light-dark"],
+          "description": "다크 모드 전략. light-dark = OS 자동 + .light/.dark 클래스 토글, light/dark = 강제 단일 모드."
+        }
+      }
+    },
+    "paths": {
+      "type": "object",
+      "description": "프로젝트 내 파일/디렉토리 위치. CLI 가 컴포넌트 dest, tokens 위치, alias placeholder 해석에 사용.",
+      "additionalProperties": false,
+      "properties": {
+        "tokens": {
+          "type": "string",
+          "description": "tokens.css (React) 또는 sh_ui_tokens.dart (Flutter) 파일 경로.",
+          "examples": ["src/styles/tokens.css", "src/shared/styles/tokens.css", "lib/styles/tokens.css", "lib/sh_ui/foundation/sh_ui_tokens.dart"]
+        },
+        "cssEntry": {
+          "type": "string",
+          "description": "tokens.css 를 import 하는 globals.css 의 경로 (선택). doctor 가 import 정합성 검증에 사용. v0.68+.",
+          "examples": ["app/globals.css", "src/styles/globals.css"]
+        },
+        "cssBundle": {
+          "type": "string",
+          "description": "cssStrategy=bundled 일 때 컴포넌트 CSS 가 누적되는 단일 파일 경로. v0.71+.",
+          "examples": ["src/styles/sh-ui-components.css"]
+        },
+        "styles": {
+          "type": "string",
+          "description": "styles 디렉토리 (tokens, base 등 공유 CSS 위치).",
+          "examples": ["src/styles", "src/shared/styles"]
+        },
+        "components": {
+          "type": "string",
+          "description": "컴포넌트가 복사될 디렉토리. CLI 의 add 가 이 아래 <name>/index.tsx 등을 작성.",
+          "examples": ["src/components/ui", "src/shared/ui", "lib/sh_ui/widgets"]
+        },
+        "utils": {
+          "type": "string",
+          "description": "cn 유틸 등을 둘 utils 파일 경로 (React)."
+        },
+        "hooks": {
+          "type": "string",
+          "description": "hooks 디렉토리 (선택)."
+        },
+        "foundation": {
+          "type": "string",
+          "description": "Flutter foundation 디렉토리 (tokens.dart 등이 있는 곳)."
+        },
+        "widgets": {
+          "type": "string",
+          "description": "Flutter widgets 디렉토리."
+        }
+      }
+    },
+    "aliases": {
+      "type": "object",
+      "description": "TS module alias — 컴포넌트가 cn 유틸 등을 import 할 때 치환. tsconfig.json 의 paths 와 정합되어야 함.",
+      "additionalProperties": true,
+      "properties": {
+        "components": {
+          "type": "string",
+          "examples": ["@/components/ui", "@workspace/ui-core/components"]
+        },
+        "utils": {
+          "type": "string",
+          "examples": ["@/lib/utils", "@workspace/ui-core/lib/utils"]
+        },
+        "ui": {
+          "type": "string"
+        },
+        "hooks": {
+          "type": "string"
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "cssStrategy": { "const": "bundled" } },
+        "required": ["cssStrategy"]
+      },
+      "then": {
+        "properties": {
+          "paths": { "required": ["cssBundle"] }
+        }
+      }
+    }
+  ]
+}

package/src/init.mjs

@@ -152,7 +152,7 @@ function labelFor(key) {
 
 function buildConfig({ platform, base, radius, mode, cssFramework }) {
   return {
-    $schema: "https://your-ds.dev/sh-ui.schema.json",
+    $schema: "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
     platform,
     cssFramework,
     theme: { base, radius, mode },

package/src/theme-extract.mjs

@@ -17,6 +17,30 @@ import { resolve, relative } from "node:path";
 import { parseBlocks } from "./tokens-diff.mjs";
 import { encodeTheme } from "./create/theme/encode.js";
 
+/**
+ * Dart 의 ShUiColorTokens 필드명 ↔ TOKEN_KEYS (hyphen) 매핑.
+ * inject.js 의 DART_FIELD_SOURCES 와 같은 매핑을 reverse 로 사용.
+ */
+const DART_FIELD_TO_KEY = {
+  background: "background",
+  backgroundSubtle: "background-subtle",
+  backgroundMuted: "background-muted",
+  backgroundInverse: "background-inverse",
+  foreground: "foreground",
+  foregroundMuted: "foreground-muted",
+  foregroundSubtle: "foreground-subtle",
+  foregroundInverse: "foreground-inverse",
+  border: "border",
+  borderStrong: "border-strong",
+  primary: "primary",
+  primaryForeground: "primary-foreground",
+  primaryHover: "primary-hover",
+  danger: "danger",
+  dangerForeground: "danger-foreground",
+  dangerHover: "danger-hover",
+  ring: "ring",
+};
+
 const TOKEN_KEYS_REQUIRED = [
   "background", "background-subtle", "background-muted", "background-inverse",
   "foreground", "foreground-muted", "foreground-subtle", "foreground-inverse",
@@ -150,6 +174,79 @@ export function extractThemeFromCss(cssText) {
   };
 }
 
+/**
+ * Dart sh_ui_tokens.dart 텍스트에서 light/dark + radius 추출 → base64.
+ *
+ * 파싱 전략:
+ *   - `static const light = ShUiColorTokens(...)` 블록 찾기 (dark 도 동일)
+ *   - 본문에서 `field: Color(0xAARRGGBB)` 추출, alpha 무시 (#RRGGBB 만 인코딩)
+ *   - `static const tokens = ShUiRadiusTokens(...)` 에서 `defaultRadius: X.X,` 추출,
+ *     X.X / 16 를 rem 으로 사용 (buildTokensDart 가 rem×16 으로 픽셀화한 값)
+ */
+export function extractThemeFromDart(dartText) {
+  const light = extractDartColorBlock(dartText, "light");
+  const dark = extractDartColorBlock(dartText, "dark");
+
+  const radiusMatch = /ShUiRadiusTokens\s*\([^)]*defaultRadius:\s*(\d+(?:\.\d+)?)/s.exec(
+    dartText,
+  );
+  if (!radiusMatch) {
+    throw new Error(
+      "theme extract 실패: ShUiRadiusTokens.defaultRadius 를 찾지 못했습니다.",
+    );
+  }
+  const radiusPx = parseFloat(radiusMatch[1]);
+  const radius = Number((radiusPx / 16).toFixed(4));
+
+  const theme = { light, dark, radius };
+  const base64 = encodeTheme(theme);
+  return {
+    base64,
+    theme,
+    summary: {
+      requiredKeys: Object.keys(light).length,
+      optionalKeys: 0,
+      optionalEmitted: [],
+      radius,
+    },
+  };
+}
+
+/**
+ * `static const light = ShUiColorTokens(...)` 의 본문에서 field: hex 맵 빌드.
+ * Dart `Color(0xFFRRGGBB)` 또는 `Color(0xAARRGGBB)` (alpha 비-FF 는 의미 손실되지만
+ * sh-ui base64 는 #RRGGBB 만 지원해 alpha 잘라냄).
+ */
+function extractDartColorBlock(dartText, mode) {
+  const blockRe = new RegExp(
+    `static\\s+const\\s+${mode}\\s*=\\s*ShUiColorTokens\\s*\\(([\\s\\S]*?)\\);`,
+    "m",
+  );
+  const m = blockRe.exec(dartText);
+  if (!m) {
+    throw new Error(
+      `theme extract 실패: \`static const ${mode} = ShUiColorTokens(...)\` 블록을 찾지 못했습니다.`,
+    );
+  }
+  const body = m[1];
+  const fieldRe = /([a-zA-Z_]\w*):\s*Color\(0x([0-9a-fA-F]{8})\)/g;
+  const out = {};
+  let fm;
+  while ((fm = fieldRe.exec(body))) {
+    const field = fm[1];
+    const hexFull = fm[2].toUpperCase();
+    const key = DART_FIELD_TO_KEY[field];
+    if (!key) continue; // 알 수 없는 필드는 무시 (사용자가 ShUiColorTokens 확장한 경우)
+    out[key] = `#${hexFull.slice(2)}`;
+  }
+  if (Object.keys(out).length === 0) {
+    throw new Error(
+      `theme extract 실패: ${mode} 블록에서 Color 필드를 추출하지 못했습니다.`,
+    );
+  }
+  return out;
+}
+
 async function loadConfig(cwd) {
   const configPath = resolve(cwd, "sh-ui.config.json");
   if (!existsSync(configPath)) {
@@ -162,22 +259,21 @@ async function loadConfig(cwd) {
 
 export async function runThemeExtract({ cwd, output }) {
   const config = await loadConfig(cwd);
-  if (config.platform !== "react") {
-    throw new Error(
-      `theme extract 는 React 만 지원합니다 (현재: ${config.platform}). Flutter 는 별도 도구 필요.`,
-    );
-  }
   const tokensRel = config.paths?.tokens;
   if (!tokensRel) throw new Error("paths.tokens 가 sh-ui.config.json 에 없습니다.");
   const tokensPath = resolve(cwd, tokensRel);
   if (!existsSync(tokensPath)) {
     throw new Error(
-      `tokens.css 가 없습니다 (${tokensRel}). \`sh-ui add tokens\` 로 먼저 생성하세요.`,
+      `토큰 파일이 없습니다 (${tokensRel}). \`sh-ui add tokens\` 로 먼저 생성하세요.`,
     );
   }
 
-  const cssText = await readFile(tokensPath, "utf8");
-  const { base64, summary } = extractThemeFromCss(cssText);
+  const tokensText = await readFile(tokensPath, "utf8");
+  const result =
+    config.platform === "flutter"
+      ? extractThemeFromDart(tokensText)
+      : extractThemeFromCss(tokensText);
+  const { base64, summary } = result;
 
   if (output) {
     await writeFile(resolve(cwd, output), base64 + "\n", "utf8");

package/src/tokens-cmd.mjs

@@ -15,6 +15,7 @@ import { pathToFileURL } from "node:url";
 import { getTokensRoot } from "./paths.mjs";
 import { THEME_BASES } from "./constants.js";
 import { parseBlocks, diffBlocks, applyAdditions } from "./tokens-diff.mjs";
+import { parseDartTokens, diffDartTokens } from "./tokens-diff-dart.mjs";
 
 async function loadTokensBuilder() {
   const url = pathToFileURL(resolve(getTokensRoot(), "build.mjs")).href;
@@ -48,12 +49,6 @@ async function buildExpected(config) {
         "diff/upgrade 는 base 가 neutral/zinc/slate 일 때만 사용 가능합니다.",
     );
   }
-  if (config.platform !== "react") {
-    throw new Error(
-      `tokens diff/upgrade 는 React 만 지원합니다 (현재: ${config.platform}). ` +
-        "Flutter 는 향후 추가 예정.",
-    );
-  }
   const { buildTokens } = await loadTokensBuilder();
   return buildTokens(config);
 }
@@ -74,7 +69,7 @@ function renderDiffReport({ added, removed, changed, unchangedCount }, rel) {
   console.log(`\nsh-ui tokens diff — ${rel}\n`);
 
   if (added.length === 0 && removed.length === 0 && changed.length === 0) {
-    console.log(`✓ 변경 없음 — 사용자 tokens.css 가 buildTokens 결과와 동일 (${unchangedCount} 변수).`);
+    console.log(`✓ 변경 없음 — 사용자 토큰 파일이 buildTokens 결과와 동일 (${unchangedCount} 항목).`);
     return;
   }
 
@@ -113,7 +108,10 @@ export async function runTokensDiff({ cwd }) {
   const config = await loadConfig(cwd);
   const expectedText = await buildExpected(config);
   const { text: currentText, rel } = await loadCurrent(config, cwd);
-  const diff = diffBlocks(parseBlocks(currentText), parseBlocks(expectedText));
+  const diff =
+    config.platform === "flutter"
+      ? diffDartTokens(parseDartTokens(currentText), parseDartTokens(expectedText))
+      : diffBlocks(parseBlocks(currentText), parseBlocks(expectedText));
   renderDiffReport(diff, rel);
 }
 
@@ -121,7 +119,19 @@ export async function runTokensUpgrade({ cwd, mode }) {
   const config = await loadConfig(cwd);
   const expectedText = await buildExpected(config);
   const current = await loadCurrent(config, cwd);
-  const diff = diffBlocks(parseBlocks(current.text), parseBlocks(expectedText));
+  const isFlutter = config.platform === "flutter";
+
+  if (isFlutter && mode === "apply") {
+    throw new Error(
+      "Flutter 에선 `tokens upgrade --apply` 미지원 — Dart 클래스에 필드 추가는 " +
+        "선언/생성자/static const 3 군데를 동시에 수정해야 해서 incremental 적용이 위험합니다.\n" +
+        "  대신 `sh-ui tokens upgrade --replace` 로 통째 재생성하세요.",
+    );
+  }
+
+  const diff = isFlutter
+    ? diffDartTokens(parseDartTokens(current.text), parseDartTokens(expectedText))
+    : diffBlocks(parseBlocks(current.text), parseBlocks(expectedText));
 
   console.log(`\nsh-ui tokens upgrade — ${current.rel} (${mode})\n`);
 

package/src/tokens-diff-dart.mjs

@@ -0,0 +1,147 @@
+// Flutter sh_ui_tokens.dart 와 buildTokensDart 결과를 비교한다.
+//
+// Dart 의 토큰 파일 구조:
+//   class ShUiColorTokens { final Color background; ...
+//     static const light = ShUiColorTokens(
+//       background: Color(0xFFFFFFFF),
+//       ...
+//     );
+//     static const dark = ShUiColorTokens(...);
+//   }
+//   class ShUiSpacingTokens { ...
+//     static const tokens = ShUiSpacingTokens(s0: 0.0, s1: 4.0, ...);
+//   }
+//
+// 비교 단위는 `<ClassName>.<staticName>` (예: ShUiColorTokens.light) — 그 안의
+// field: value 맵으로 평탄화 후 added / changed / removed 분류.
+//
+// Apply 정책:
+//   Dart 클래스에 새 필드 추가는 (1) class field 선언, (2) constructor 파라미터,
+//   (3) 모든 static const 인스턴스화 — 3 군데 동기 수정 필요. 위험성/구현 복잡도가
+//   CSS 마커 기반과 비교 불가. v1 Flutter 는 --replace 만 지원, --apply 는 안내 에러.
+
+/**
+ * `static const NAME = ClassName(...)` 블록들을 추출.
+ * @returns { [`ClassName.staticName`]: { field: rawValue } }
+ */
+export function parseDartTokens(dartText) {
+  const out = {};
+  // 의도적으로 단순 — `static const NAME = ClassName(...)` 의 본문 (마지막 `;` 까지) 을 캡처.
+  // 본문엔 nested 함수 호출 (Color(0x...), Cubic(...), Duration(...)) 이 가능하므로
+  // 간단한 깊이 카운터로 닫는 `)` 매칭.
+  const re = /static\s+const\s+([a-zA-Z_]\w*)\s*=\s*(ShUi[A-Z]\w*)\s*\(/g;
+  let m;
+  while ((m = re.exec(dartText))) {
+    const staticName = m[1];
+    const className = m[2];
+    const bodyStart = m.index + m[0].length;
+    const bodyEnd = findClosingParen(dartText, bodyStart);
+    if (bodyEnd < 0) continue;
+    const body = dartText.slice(bodyStart, bodyEnd);
+    const fields = parseDartFieldList(body);
+    if (Object.keys(fields).length === 0) continue;
+    out[`${className}.${staticName}`] = fields;
+  }
+  return out;
+}
+
+function findClosingParen(text, start) {
+  let depth = 1;
+  let i = start;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * `field: value, field: value, ...` 본문을 { field: value-string } 으로.
+ * 값은 trim 된 raw 문자열 — `Color(0xFF...)`, `0.5`, `Duration(milliseconds: 120)`,
+ * `Cubic(0.4, 0, 0.2, 1)`, `<BoxShadow>[...]` 등 그대로 보존.
+ */
+function parseDartFieldList(body) {
+  const out = {};
+  const items = splitByTopLevelComma(body);
+  for (const item of items) {
+    const trimmed = item.trim();
+    if (!trimmed) continue;
+    const colonIdx = findTopLevelColon(trimmed);
+    if (colonIdx < 0) continue;
+    const field = trimmed.slice(0, colonIdx).trim();
+    const value = trimmed.slice(colonIdx + 1).trim();
+    if (field && value) out[field] = value;
+  }
+  return out;
+}
+
+/** 깊이 0 콤마로 split. (), [], {} 안의 콤마는 보호. */
+function splitByTopLevelComma(text) {
+  const parts = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === "," && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/** 깊이 0 의 첫 ':' — `field: Color(0x...)` 형식 분리용. */
+function findTopLevelColon(text) {
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c === "(" || c === "[" || c === "{") depth++;
+    else if (c === ")" || c === "]" || c === "}") depth--;
+    else if (c === ":" && depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * 두 Dart 토큰 트리 비교. CSS 측 diffBlocks 와 같은 결과 모양.
+ */
+export function diffDartTokens(currentTokens, expectedTokens) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  let unchangedCount = 0;
+
+  const allKeys = new Set([
+    ...Object.keys(currentTokens),
+    ...Object.keys(expectedTokens),
+  ]);
+
+  for (const blockKey of allKeys) {
+    const cur = currentTokens[blockKey] ?? {};
+    const exp = expectedTokens[blockKey] ?? {};
+    const fieldKeys = new Set([...Object.keys(cur), ...Object.keys(exp)]);
+    for (const field of fieldKeys) {
+      const cv = cur[field];
+      const ev = exp[field];
+      if (cv === undefined && ev !== undefined) {
+        added.push({ selector: blockKey, name: field, value: ev });
+      } else if (ev === undefined && cv !== undefined) {
+        removed.push({ selector: blockKey, name: field, value: cv });
+      } else if (cv !== ev) {
+        changed.push({ selector: blockKey, name: field, expected: ev, current: cv });
+      } else {
+        unchangedCount++;
+      }
+    }
+  }
+  return { added, removed, changed, unchangedCount };
+}

package/src/upgrade-cli.mjs

@@ -0,0 +1,180 @@
+// `sh-ui upgrade-cli` — sh-ui-cli 자체 업그레이드 + 설치 후 자동 진단.
+//
+// 동작:
+//   1) npm registry 에서 sh-ui-cli 의 latest 버전 조회.
+//   2) 현재 실행 중인 CLI 의 package.json 에서 버전 읽음.
+//   3) 동일하면 "이미 최신" 안내 + 설치된 sh-ui-cli 패키지 (사용자의 node_modules)
+//      가 다른지 확인 — devDep 갱신 안내.
+//   4) 다르면 install 명령 출력 (사용자의 패키지 매니저에 맞춰).
+//   5) --apply 면 실제 install 실행.
+//   6) install 후 next-step 안내 — sh-ui doctor / tokens diff.
+
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const CLI_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const REGISTRY_URL = "https://registry.npmjs.org/sh-ui-cli/latest";
+
+async function readCliVersion() {
+  const pkg = JSON.parse(
+    await readFile(resolve(CLI_ROOT, "package.json"), "utf8"),
+  );
+  return pkg.version;
+}
+
+/** 사용자 프로젝트의 node_modules/sh-ui-cli/package.json 버전 (devDep 으로 설치된 것) */
+async function readInstalledVersion(cwd) {
+  let dir = resolve(cwd);
+  while (true) {
+    const candidate = resolve(dir, "node_modules/sh-ui-cli/package.json");
+    if (existsSync(candidate)) {
+      try {
+        const pkg = JSON.parse(await readFile(candidate, "utf8"));
+        return { version: pkg.version, path: candidate };
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+async function fetchLatestVersion() {
+  // node 18+ 는 fetch 기본. 의존성 없는 단순 GET.
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      headers: { accept: "application/json" },
+    });
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}`);
+    }
+    const data = await res.json();
+    return data.version;
+  } catch (err) {
+    throw new Error(
+      `npm registry 에서 latest 버전을 가져오지 못했습니다 (${err.message}). ` +
+        "오프라인이거나 registry 접근이 막혔을 수 있습니다.",
+    );
+  }
+}
+
+function detectPackageManager(cwd) {
+  let dir = resolve(cwd);
+  while (true) {
+    if (existsSync(resolve(dir, "pnpm-lock.yaml"))) return "pnpm";
+    if (existsSync(resolve(dir, "pnpm-workspace.yaml"))) return "pnpm";
+    if (
+      existsSync(resolve(dir, "bun.lockb")) ||
+      existsSync(resolve(dir, "bun.lock"))
+    )
+      return "bun";
+    if (existsSync(resolve(dir, "yarn.lock"))) return "yarn";
+    if (existsSync(resolve(dir, "package-lock.json"))) return "npm";
+    const parent = dirname(dir);
+    if (parent === dir) return "npm";
+    dir = parent;
+  }
+}
+
+function installCommand(pm, version) {
+  const addCmd = pm === "npm" ? "install -D" : "add -D";
+  return `${pm} ${addCmd} sh-ui-cli@${version}`;
+}
+
+function runInstall(pm, version, cwd) {
+  const args = pm === "npm" ? ["install", "-D"] : ["add", "-D"];
+  args.push(`sh-ui-cli@${version}`);
+  console.log(`\n실행: ${pm} ${args.join(" ")}\n`);
+  const isWin = process.platform === "win32";
+  return new Promise((ok, bad) => {
+    const child = spawn(pm, args, { cwd, stdio: "inherit", shell: isWin });
+    child.on("exit", (code) =>
+      code === 0 ? ok() : bad(new Error(`${pm} exited with code ${code}`)),
+    );
+    child.on("error", bad);
+  });
+}
+
+/**
+ * versions.json 에서 from..to 사이의 highlights 를 추출.
+ * from = 사용자 현재, to = latest. 없으면 최근 N개만.
+ */
+async function readChangelogRange(fromVersion, toVersion) {
+  const candidates = [
+    resolve(CLI_ROOT, "data/changelog/versions.json"), // bundled
+    resolve(CLI_ROOT, "../changelog/versions.json"), // monorepo dev
+  ];
+  let path;
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      path = p;
+      break;
+    }
+  }
+  if (!path) return null;
+  const data = JSON.parse(await readFile(path, "utf8"));
+  const versions = data.versions ?? [];
+  if (!fromVersion || !toVersion) return versions.slice(0, 5);
+  // versions 는 최신 → 옛날 순. from 보다 새로운 것만 추출 (from 자기 자신은 제외).
+  const out = [];
+  for (const v of versions) {
+    if (v.version === fromVersion) break;
+    out.push(v);
+  }
+  return out;
+}
+
+export async function runUpgradeCli({ cwd, apply }) {
+  const installed = await readInstalledVersion(cwd);
+  console.log(`\nsh-ui-cli 업그레이드 점검\n`);
+
+  const latest = await fetchLatestVersion();
+  console.log(`  npm latest    : v${latest}`);
+  if (installed) {
+    console.log(`  현재 설치본    : v${installed.version}`);
+  } else {
+    console.log(`  현재 설치본    : (찾지 못함 — npx 로 실행 중일 수 있음)`);
+  }
+
+  const reference = installed?.version ?? (await readCliVersion());
+  if (reference === latest) {
+    console.log(`\n✓ 이미 최신.\n`);
+    console.log(`다음 단계 권장:\n  sh-ui doctor — 프로젝트 정합성 점검`);
+    return;
+  }
+
+  const changelog = await readChangelogRange(reference, latest);
+  if (changelog && changelog.length > 0) {
+    console.log(`\n변경 highlights (${changelog.length}개 릴리즈):`);
+    for (const v of changelog) {
+      const type = v.type ? ` [${v.type}]` : "";
+      console.log(`  v${v.version}${type} — ${v.title}`);
+    }
+  }
+
+  const pm = detectPackageManager(cwd);
+  const cmd = installCommand(pm, latest);
+
+  if (!apply) {
+    console.log(`\n설치 명령:\n  ${cmd}\n`);
+    console.log(
+      `실제 실행하려면: \`sh-ui upgrade-cli --apply\` (자동 install + 설치 후 doctor)`,
+    );
+    return;
+  }
+
+  // --apply
+  await runInstall(pm, latest, cwd);
+  console.log(`\n✓ sh-ui-cli@${latest} 설치 완료.\n`);
+  console.log(
+    `다음 단계 (필요 시):\n` +
+      `  sh-ui doctor                — 신규 토큰 누락 / config 이슈 진단\n` +
+      `  sh-ui tokens diff           — buildTokens 와 비교 미리보기\n` +
+      `  sh-ui tokens upgrade --apply — 추가만 incremental 적용 (사용자 편집 보존)`,
+  );
+}

package/templates/flutter-standalone/sh-ui.config.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
   "platform": "flutter",
   "theme": {
     "base": "neutral",

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

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
   "platform": "react",
   "cssFramework": "plain",
   "paths": {

package/templates/nextjs-standalone/_arch/flat/sh-ui.config.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
   "platform": "react",
   "cssFramework": "plain",
   "theme": {

package/templates/nextjs-standalone/_arch/fsd/sh-ui.config.json

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
   "platform": "react",
   "cssFramework": "plain",
   "theme": {

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

@@ -1,4 +1,5 @@
 {
+  "$schema": "https://raw.githubusercontent.com/sanghyeonKim0201/sh-ui/live/packages/cli/sh-ui.schema.json",
   "platform": "react",
   "cssFramework": "plain",
   "role": "tokens-only",