sh-ui-cli 0.67.2 → 0.68.0

package/package.json

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

package/src/add.mjs

@@ -7,6 +7,10 @@ import { select } from "@inquirer/prompts";
 import { formatUnifiedDiff } from "./diff.mjs";
 import { getRegistryRoot, getTokensRoot, getPeerVersionsPath } from "./paths.mjs";
 import { THEME_BASES } from "./constants.js";
+import {
+  findMissingTokens,
+  loadDefinedVarsFromConfig,
+} from "./tokens-validate.mjs";
 
 /**
  * 기존 파일과 registry 파일 내용이 다를 때 keep/overwrite 결정.
@@ -245,7 +249,7 @@ function effectiveFramework(entry, cssFramework) {
   return hasVariant ? cssFramework : "plain";
 }
 
-async function addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver) {
+async function addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, validationCtx) {
   const registryRoot = getRegistryRoot(config.platform);
   const registry = JSON.parse(
     await readFile(resolve(registryRoot, "registry.json"), "utf8"),
@@ -260,6 +264,20 @@ async function addComponent(name, config, cwd, installed, pendingDeps, diffMode,
   const requestedFw = config.cssFramework ?? "plain";
   const cssFramework = effectiveFramework(entry, requestedFw);
 
+  // 컴포넌트가 요구하는 CSS 변수가 사용자 tokens.css 에 정의돼 있는지 검증.
+  // tokens.css 자체가 없거나, registry 에 메타가 없으면 검사 스킵 (정상 케이스).
+  if (validationCtx?.definedVars && !diffMode) {
+    const missing = await findMissingTokens({
+      platform: config.platform,
+      name,
+      framework: cssFramework,
+      defined: validationCtx.definedVars,
+    });
+    if (missing && missing.length > 0) {
+      validationCtx.missingTokenReports.push({ name, framework: cssFramework, missing });
+    }
+  }
+
   // 사용자가 plain 외 변종을 골랐는데 이 컴포넌트는 plain 으로 fallback 된 경우 한 줄 알림.
   // 동작에 문제는 없지만 일관성에 대한 기대를 정확히 셋업하기 위함.
   if (requestedFw !== "plain" && cssFramework === "plain" && !diffMode) {
@@ -276,7 +294,7 @@ async function addComponent(name, config, cwd, installed, pendingDeps, diffMode,
   }
 
   for (const dep of entry.registryDependencies ?? []) {
-    await addOne(dep, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver);
+    await addOne(dep, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, validationCtx);
   }
 
   for (const file of entry.files) {
@@ -408,8 +426,21 @@ export async function add({
   const installed = new Set();
   const pendingDeps = new Set();
   const summary = [];
+  // tokens.css 정의 변수는 한 번만 읽어서 모든 컴포넌트 검증에 재사용.
+  // tokens 가 같이 add 되는 경우엔 처리 후 컴포넌트가 add 되도록 names 가 보통
+  // [tokens, …components…] 순이라 미리 읽어도 OK — 누락 경고는 사용자가 실제로
+  // tokens.css 를 안 만들었을 때만 의미 있으므로.
+  const definedVars = await loadDefinedVarsFromConfig(config, cwd);
+  const missingTokenReports = [];
   for (const name of names) {
-    await addOne(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver);
+    await addOne(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, {
+      definedVars,
+      missingTokenReports,
+    });
+  }
+
+  if (!diffMode && missingTokenReports.length > 0) {
+    renderMissingTokenReport(missingTokenReports, config);
   }
 
   if (diffMode) {
@@ -452,16 +483,33 @@ export async function add({
   }
 }
 
-async function addOne(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver) {
+async function addOne(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, validationCtx) {
   if (installed.has(name)) return;
   installed.add(name);
   if (name === "tokens") {
     await addTokens(config, cwd, diffMode, summary, conflictResolver);
   } else {
-    await addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver);
+    await addComponent(name, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, validationCtx);
   }
 }
 
+/**
+ * 컴포넌트가 요구하는 CSS 변수 중 사용자 tokens.css 에 없는 것들을 한 번에 안내.
+ * fatal 이 아닌 경고 — 실제 silent breakage 는 시각적으로만 나타나므로 미리 짚어 준다.
+ */
+function renderMissingTokenReport(reports, config) {
+  const tokensRel = config.paths?.tokens ?? "(paths.tokens 미설정)";
+  console.log(`\n⚠ 일부 컴포넌트가 요구하는 CSS 변수가 ${tokensRel} 에 없습니다:`);
+  for (const r of reports) {
+    const preview = r.missing.slice(0, 6).join(", ");
+    const more = r.missing.length > 6 ? ` (+${r.missing.length - 6} more)` : "";
+    console.log(`  · ${r.name} [${r.framework}] — ${preview}${more}`);
+  }
+  console.log(
+    `  → 해결: \`sh-ui add tokens\` 로 토큰을 다시 빌드하거나, ${tokensRel} 을 직접 수정.`,
+  );
+}
+
 function renderDiffReport(summary) {
   const created = summary.filter((s) => s.kind === "new");
   const modified = summary.filter((s) => s.kind === "modified");

package/src/doctor.mjs

@@ -0,0 +1,289 @@
+// sh-ui doctor — 프로젝트 정합성 점검.
+//
+// 점검 항목:
+//   1) sh-ui.config.json 존재 + 필수 필드 (platform, theme, paths)
+//   2) paths.tokens 파일 존재
+//   3) paths.cssEntry (선택) 가 tokens.css 를 import 하는지
+//   4) 설치된 컴포넌트가 요구하는 CSS 변수가 tokens.css 에 모두 정의돼 있는지
+//
+// 출력: 항목별 ✓ / ⚠ / ✗ + 해결 힌트. 모든 검사가 통과하면 exit 0,
+//       하나라도 ✗ 면 exit 1 (CI 통합 가능).
+
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, relative, dirname, posix } from "node:path";
+import { getRegistryRoot } from "./paths.mjs";
+import {
+  extractDefinedVars,
+  findMissingTokens,
+} from "./tokens-validate.mjs";
+
+const ICON = { ok: "✓", warn: "⚠", fail: "✗" };
+
+class Report {
+  constructor() {
+    this.lines = [];
+    this.failCount = 0;
+    this.warnCount = 0;
+  }
+  ok(label, detail) {
+    this.lines.push({ kind: "ok", label, detail });
+  }
+  warn(label, detail) {
+    this.warnCount++;
+    this.lines.push({ kind: "warn", label, detail });
+  }
+  fail(label, detail) {
+    this.failCount++;
+    this.lines.push({ kind: "fail", label, detail });
+  }
+  render() {
+    for (const line of this.lines) {
+      const icon = ICON[line.kind === "ok" ? "ok" : line.kind === "warn" ? "warn" : "fail"];
+      const head = `${icon} ${line.label}`;
+      if (line.detail) {
+        console.log(head);
+        for (const d of line.detail.split("\n")) console.log(`    ${d}`);
+      } else {
+        console.log(head);
+      }
+    }
+    console.log("");
+    if (this.failCount === 0 && this.warnCount === 0) {
+      console.log(`✓ 모든 검사 통과`);
+    } else {
+      console.log(
+        `검사 완료 — ${this.failCount} 실패, ${this.warnCount} 경고`,
+      );
+    }
+  }
+}
+
+async function loadConfig(cwd, report) {
+  const configPath = resolve(cwd, "sh-ui.config.json");
+  if (!existsSync(configPath)) {
+    report.fail(
+      "sh-ui.config.json",
+      `${relative(cwd, configPath)} 가 없습니다. \`sh-ui init\` 으로 생성하세요.`,
+    );
+    return null;
+  }
+  try {
+    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 미설정");
+    if (issues.length > 0) {
+      report.fail("sh-ui.config.json", `필수 필드 누락: ${issues.join(", ")}`);
+      return null;
+    }
+    report.ok(
+      "sh-ui.config.json",
+      `platform=${config.platform} theme.base=${config.theme?.base ?? "?"} ` +
+        `cssFramework=${config.cssFramework ?? "(기본 plain)"}`,
+    );
+    return config;
+  } catch (err) {
+    report.fail("sh-ui.config.json", `JSON 파싱 실패: ${err.message}`);
+    return null;
+  }
+}
+
+function checkTokensFile(config, cwd, report) {
+  const rel = config.paths?.tokens;
+  if (!rel) {
+    // 모노레포 ui-core 처럼 tokens 를 가지지 않는 패키지 — 이 경우 검사 스킵.
+    report.warn(
+      "paths.tokens",
+      "config 에 paths.tokens 가 없습니다 — 토큰 검증 스킵.",
+    );
+    return null;
+  }
+  const tokensPath = resolve(cwd, rel);
+  if (!existsSync(tokensPath)) {
+    report.fail(
+      `paths.tokens — ${rel}`,
+      `파일이 없습니다. \`sh-ui add tokens\` 로 생성하세요.`,
+    );
+    return null;
+  }
+  report.ok(`paths.tokens — ${rel}`);
+  return tokensPath;
+}
+
+/**
+ * cssEntry 가 설정돼 있으면 그 파일이 tokens.css 를 import 하는지 검사.
+ * @import './tokens.css' 또는 @import "../shared/styles/tokens.css" 형태 모두 인정.
+ * 명시 import 없이 빌드 도구가 알아서 합치는 경우(Tailwind v4 의 @import "tailwindcss"
+ * 만 있는 경우) 도 있어 fail 이 아니라 warn.
+ */
+async function checkCssEntry(config, cwd, tokensPath, report) {
+  const entryRel = config.paths?.cssEntry;
+  if (!entryRel) {
+    report.ok(
+      "paths.cssEntry",
+      "(미설정 — 검사 스킵. 설정하면 tokens.css import 정합성을 검증합니다.)",
+    );
+    return;
+  }
+  const entryPath = resolve(cwd, entryRel);
+  if (!existsSync(entryPath)) {
+    report.fail(
+      `paths.cssEntry — ${entryRel}`,
+      `파일이 없습니다. config 의 paths.cssEntry 를 실제 globals.css 위치로 수정하세요.`,
+    );
+    return;
+  }
+  if (!tokensPath) {
+    report.warn(
+      `paths.cssEntry — ${entryRel}`,
+      "tokens.css 가 없어 import 검증 불가.",
+    );
+    return;
+  }
+  const text = await readFile(entryPath, "utf8");
+  const tokensFilename = posix.basename(entryRel.replaceAll("\\", "/"));
+  // 단순 휴리스틱: tokens 파일 베이스네임을 포함하는 @import 가 있는지.
+  const tokensBase = posix.basename(config.paths.tokens.replaceAll("\\", "/"));
+  const importRe = new RegExp(
+    `@import\\s+['"][^'"]*${tokensBase.replace(/\./g, "\\.")}['"]`,
+  );
+  if (importRe.test(text)) {
+    report.ok(
+      `paths.cssEntry — ${entryRel}`,
+      `${tokensBase} 를 import 합니다.`,
+    );
+    return;
+  }
+  // import 가 없어도 빌드 도구가 합치는 경우가 있으므로 fail 이 아닌 warn.
+  report.warn(
+    `paths.cssEntry — ${entryRel}`,
+    `${tokensBase} 를 import 하는 줄이 보이지 않습니다. ` +
+      `CSS 변수가 unresolved 로 남을 수 있으니 \`@import './${tokensBase}';\` 같은 줄을 추가하거나, ` +
+      `빌드 도구가 자동 합치는 게 맞다면 무시하세요. (현재 파일: ${entryRel})`,
+  );
+}
+
+/**
+ * 설치된 컴포넌트들의 토큰 의존성을 한 번에 검증.
+ * registry.json 을 순회하며 destination 파일이 존재하는 컴포넌트를 "설치됨" 으로 간주.
+ */
+async function checkInstalledComponents(config, cwd, definedVars, report) {
+  if (!definedVars) {
+    report.warn(
+      "컴포넌트 토큰 의존성",
+      "tokens.css 가 없어 검증 스킵.",
+    );
+    return;
+  }
+  const registryRoot = getRegistryRoot(config.platform);
+  const registryPath = resolve(registryRoot, "registry.json");
+  if (!existsSync(registryPath)) {
+    report.warn(
+      "컴포넌트 토큰 의존성",
+      `registry.json 을 찾을 수 없어 검증 스킵 (${registryPath}).`,
+    );
+    return;
+  }
+  const registry = JSON.parse(await readFile(registryPath, "utf8"));
+  const requestedFw = config.cssFramework ?? "plain";
+
+  let installedCount = 0;
+  const issues = [];
+
+  for (const [name, entry] of Object.entries(registry.components ?? {})) {
+    if (entry.type && entry.type !== "component") continue;
+    // 컴포넌트가 "설치됨" 으로 인정되려면 destination 파일 중 하나라도 존재해야 함.
+    let installed = false;
+    for (const file of entry.files ?? []) {
+      try {
+        const dest = resolveDest(file.dest, config);
+        if (existsSync(resolve(cwd, dest))) {
+          installed = true;
+          break;
+        }
+      } catch {
+        // paths placeholder 해석 실패 — 이 컴포넌트는 이 config 에서 install 불가
+      }
+    }
+    if (!installed) continue;
+    installedCount++;
+
+    // file 변종 분포로 effective framework 추정.
+    const cssFramework = effectiveFramework(entry, requestedFw);
+    const missing = await findMissingTokens({
+      platform: config.platform,
+      name,
+      framework: cssFramework,
+      defined: definedVars,
+    });
+    if (missing && missing.length > 0) {
+      issues.push({ name, framework: cssFramework, missing });
+    }
+  }
+
+  if (installedCount === 0) {
+    report.ok("설치된 컴포넌트 — 0개", "검증 대상 없음.");
+    return;
+  }
+
+  if (issues.length === 0) {
+    report.ok(
+      `설치된 컴포넌트 — ${installedCount}개`,
+      "모두 요구 토큰이 tokens.css 에 정의돼 있습니다.",
+    );
+    return;
+  }
+
+  const lines = issues.map((i) => {
+    const preview = i.missing.slice(0, 4).join(", ");
+    const more = i.missing.length > 4 ? ` (+${i.missing.length - 4} more)` : "";
+    return `· ${i.name} [${i.framework}] — ${preview}${more}`;
+  });
+  report.fail(
+    `설치된 컴포넌트 — ${installedCount}개 중 ${issues.length}개에 누락된 토큰`,
+    lines.join("\n") +
+      `\n해결: \`sh-ui add tokens\` 로 토큰을 다시 빌드하거나 ${config.paths.tokens} 를 직접 수정.`,
+  );
+}
+
+function resolveDest(template, config) {
+  return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (m, key) => {
+    const v = config.paths?.[key];
+    if (!v) throw new Error(`paths.${key} 미설정`);
+    return v;
+  });
+}
+
+function effectiveFramework(entry, cssFramework) {
+  if (cssFramework === "plain") return cssFramework;
+  const hasVariant = (entry.files ?? []).some(
+    (f) => f.frameworks && f.frameworks.includes(cssFramework),
+  );
+  return hasVariant ? cssFramework : "plain";
+}
+
+export async function doctor({ cwd }) {
+  console.log(`sh-ui doctor — ${relative(process.cwd(), cwd) || "."}\n`);
+  const report = new Report();
+
+  const config = await loadConfig(cwd, report);
+  if (!config) {
+    report.render();
+    process.exit(1);
+  }
+
+  const tokensPath = checkTokensFile(config, cwd, report);
+  await checkCssEntry(config, cwd, tokensPath, report);
+
+  let definedVars = null;
+  if (tokensPath) {
+    const text = await readFile(tokensPath, "utf8");
+    definedVars = extractDefinedVars(text);
+  }
+  await checkInstalledComponents(config, cwd, definedVars, report);
+
+  report.render();
+  if (report.failCount > 0) process.exit(1);
+}

package/src/init.mjs

@@ -26,6 +26,10 @@ const DEFAULTS = INIT_DEFAULTS;
 const PATHS = {
   react: {
     tokens: "src/styles/tokens.css",
+    // cssEntry — tokens.css 를 import 하는 글로벌 CSS 진입점.
+    // doctor 가 import 정합성 검증에 사용. Next.js App Router 기본값 가정 —
+    // 다른 위치라면 사용자가 sh-ui.config.json 에서 수정.
+    cssEntry: "app/globals.css",
     styles: "src/styles",
     components: "src/components/ui",
     utils: "src/lib/utils.ts",

package/src/paths.mjs

@@ -40,6 +40,17 @@ export function getPeerVersionsPath(platform) {
     : resolve(MONOREPO_PACKAGES, "registry", platform, "peer-versions.json");
 }
 
+/**
+ * 컴포넌트별 토큰 의존성 매니페스트.
+ * scripts/build-registry-tokens.mjs 가 컴포넌트 CSS 의 var(--*) 참조를 추출해 생성.
+ * add 시점 검증 + sh-ui doctor 가 사용.
+ */
+export function getTokensUsedPath(platform) {
+  return isBundled
+    ? resolve(BUNDLED_DATA, "registry", platform, "tokens-used.json")
+    : resolve(MONOREPO_PACKAGES, "registry", platform, "tokens-used.json");
+}
+
 /** llms 요약 JSON (platform별) */
 export function getSummariesPath(platform) {
   return isBundled

package/src/tokens-validate.mjs

@@ -0,0 +1,86 @@
+// 컴포넌트가 요구하는 CSS 변수와 사용자 tokens.css 가 정의한 변수를 비교한다.
+//
+// 호출:
+//   - sh-ui add <component> 진입 시 (silent breakage 방지)
+//   - sh-ui doctor 가 설치된 컴포넌트 전체에 대해 (정합성 점검)
+//
+// 정책:
+//   - tokens.css 가 아예 없으면 누락 검사를 건너뛴다 (사용자가 곧 add tokens 할 거라
+//     가정 — add 시점 안내는 별도 메시지로 처리).
+//   - 컴포넌트 또는 framework 가 tokens-used.json 에 없으면 검사 스킵 (없는 게 정상).
+//   - Flutter platform 은 검사 대상 아님 — CSS var() 와 다른 추출 방식이라 별도 도구.
+
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { getTokensUsedPath } from "./paths.mjs";
+
+let tokensUsedCache = null;
+
+/** tokens-used.json 캐시 로드. 없거나 깨지면 null. */
+async function loadTokensUsed(platform) {
+  if (tokensUsedCache) return tokensUsedCache;
+  const path = getTokensUsedPath(platform);
+  if (!existsSync(path)) return null;
+  try {
+    const data = JSON.parse(await readFile(path, "utf8"));
+    tokensUsedCache = data;
+    return data;
+  } catch {
+    return null;
+  }
+}
+
+/** tokens.css 텍스트에서 정의된 --변수명 집합 추출 (선언만 — 참조는 무시). */
+export function extractDefinedVars(cssText) {
+  const out = new Set();
+  // `--name:` 선언만 잡고, var(--name) 참조는 무시한다.
+  // 음수 lookbehind 가 var( 인 경우를 제외.
+  const re = /(?<!var\(\s*)(--[a-zA-Z0-9_-]+)\s*:/g;
+  let m;
+  while ((m = re.exec(cssText))) out.add(m[1]);
+  return out;
+}
+
+/**
+ * 컴포넌트의 framework 별 토큰 요구사항 조회.
+ * 못 찾으면 null — 호출부는 검사를 스킵한다.
+ */
+export async function getRequiredTokens(platform, name, framework) {
+  if (platform === "flutter") return null;
+  const data = await loadTokensUsed(platform);
+  if (!data) return null;
+  const entry = data.components?.[name];
+  if (!entry) return null;
+  return entry[framework] ?? null;
+}
+
+/**
+ * 사용자 tokens.css 를 읽어 정의된 변수 집합을 반환.
+ * 파일이 없으면 null — 호출부는 "tokens.css 미생성" 메시지를 따로 처리.
+ */
+export async function loadDefinedVarsFromConfig(config, cwd) {
+  const tokensRel = config.paths?.tokens;
+  if (!tokensRel) return null;
+  const tokensPath = resolve(cwd, tokensRel);
+  if (!existsSync(tokensPath)) return null;
+  const text = await readFile(tokensPath, "utf8");
+  return extractDefinedVars(text);
+}
+
+/**
+ * 한 컴포넌트의 누락 토큰 목록 계산.
+ * @returns {Promise<string[]|null>} 누락 토큰 정렬 배열, 또는 null (검사 불가/스킵)
+ */
+export async function findMissingTokens({
+  platform,
+  name,
+  framework,
+  defined,
+}) {
+  const required = await getRequiredTokens(platform, name, framework);
+  if (!required || required.length === 0) return null;
+  if (!defined) return null;
+  const missing = required.filter((v) => !defined.has(v));
+  return missing.sort();
+}

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

@@ -8,6 +8,7 @@
   },
   "paths": {
     "tokens": "lib/styles/tokens.css",
+    "cssEntry": "app/globals.css",
     "styles": "lib/styles",
     "components": "components/common",
     "utils": "lib/utils/utils.ts"

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

@@ -8,6 +8,7 @@
   },
   "paths": {
     "tokens": "src/shared/styles/tokens.css",
+    "cssEntry": "app/globals.css",
     "styles": "src/shared/styles",
     "components": "src/shared/ui",
     "utils": "src/shared/lib/utils.ts"

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

@@ -9,6 +9,7 @@
   },
   "paths": {
     "tokens": "src/styles/tokens.css",
+    "cssEntry": "src/styles/globals.css",
     "styles": "src/styles"
   }
 }