sh-ui-cli 0.73.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,19 @@
   "$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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.73.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/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",