sh-ui-cli 0.69.0 → 0.70.0

package/bin/sh-ui.mjs

@@ -20,6 +20,9 @@ const usage = `사용법:
   sh-ui tokens upgrade [--apply|--replace]
                                    --apply: 추가만 incremental (사용자 편집 보존)
                                    --replace: 통째 덮어쓰기 (add tokens --force 와 동일)
+  sh-ui theme extract [--out <path>]
+                                   현재 tokens.css 의 색·radius 를 base64 로 추출
+                                   stdout 출력, --out 으로 파일 저장
   sh-ui remove <component...>      설치된 컴포넌트 파일 삭제
   sh-ui rename-app <old> <new>     monorepo 의 앱 이름 일괄 변경
                                    (apps/<old>/, packages/ui/ui-apps/ui-<old>/
@@ -109,6 +112,20 @@ try {
       await doctor({ cwd: process.cwd() });
       break;
     }
+    case "theme": {
+      const sub = rest[0];
+      const flags = rest.slice(1);
+      if (sub === "extract") {
+        const outIdx = flags.indexOf("--out");
+        const output = outIdx !== -1 ? flags[outIdx + 1] : null;
+        const { runThemeExtract } = await import("../src/theme-extract.mjs");
+        await runThemeExtract({ cwd: process.cwd(), output });
+      } else {
+        console.error(`에러: 알 수 없는 theme 서브명령 '${sub ?? ""}'. 'extract' 만 지원.\n`);
+        process.exit(1);
+      }
+      break;
+    }
     case "tokens": {
       // sh-ui tokens diff
       // sh-ui tokens upgrade --apply | --replace

package/data/changelog/versions.json

@@ -2,6 +2,20 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.70.0",
+      "date": "2026-05-09",
+      "title": "sh-ui theme extract — tokens.css → base64 라운드트립 (Phase C)",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui theme extract` 신설** — 사용자가 손본 tokens.css 의 색·radius 를 sh-ui base64 테마 문자열로 추출. stdout 출력 (또는 `--out <path>` 로 파일 저장). 추출 정보는 stderr 로 분리되어 pipe-friendly.",
+        "**라운드트립 검증** — 추출 → `sh-ui create --theme <base64>` 또는 MCP `sh_ui_create_project` 의 theme 인자로 그대로 재사용. encodeTheme 이 즉시 decodeTheme 으로 round-trip 검증해 잘못된 입력은 실패 시점이 빠름.",
+        "**옵셔널 토큰 보수적 처리** — light/dark 양쪽에 모두 hex 가 정의된 옵셔널 키 (success/warning/info/danger-hover/ring) 만 emit. 한쪽만 있으면 디자인 어긋남 위험 — 둘 다 skip.",
+        "**hex-only 정책** — 모든 필수 색이 `#RRGGBB` 여야 함. `color-mix() / var() / rgba()` 등이 섞이면 친절 에러로 종료 + `sh-ui tokens upgrade --replace` 또는 직접 hex 화 권장. 파싱 실패가 정적 vs 동적 색 의도를 흐리지 않게.",
+        "**활용 패턴** — custom brand 색을 한 번 박은 뒤 다른 앱에도 같은 색으로 스캐폴드 / 디자인 시스템 문서에 토큰 스냅샷 보존 / 색 살짝 바꾼 후 새 base64 추출해 brand 변형판 만들기."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.70.0"
+    },
     {
       "version": "0.69.0",
       "date": "2026-05-09",

package/package.json

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

package/src/theme-extract.mjs

@@ -0,0 +1,198 @@
+// `sh-ui theme extract` — 사용자 tokens.css 의 색·radius 를 추출해 sh-ui base64
+// 테마 문자열로 인코딩한다. 산출물을 `sh-ui create --theme <base64>` 에 그대로
+// 넘기거나, 팀/디자인 시스템 문서에 보존 가능.
+//
+// 동작:
+//   1) sh-ui.config.json 의 paths.tokens 를 읽음.
+//   2) parseBlocks 로 :root (light) / .dark (dark) 블록 추출.
+//   3) TOKEN_KEYS + 옵셔널 색을 #RRGGBB 형식으로 검증, --radius 값을 rem 으로 파싱.
+//   4) encodeTheme() 으로 base64 생성 (round-trip 검증 포함).
+//
+// 제약: tokens.css 의 모든 색이 #RRGGBB 형식이어야 한다. color-mix() / var() /
+// rgba() 가 섞여 있으면 안내 에러로 종료 (사용자에게 --replace 또는 직접 hex 화 권장).
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, relative } from "node:path";
+import { parseBlocks } from "./tokens-diff.mjs";
+import { encodeTheme } from "./create/theme/encode.js";
+
+const TOKEN_KEYS_REQUIRED = [
+  "background", "background-subtle", "background-muted", "background-inverse",
+  "foreground", "foreground-muted", "foreground-subtle", "foreground-inverse",
+  "border", "border-strong",
+  "primary", "primary-foreground", "primary-hover",
+  "danger", "danger-foreground",
+];
+
+const TOKEN_KEYS_OPTIONAL = [
+  "success", "success-foreground",
+  "warning", "warning-foreground",
+  "info", "info-foreground",
+  "danger-hover",
+  "ring",
+];
+
+const HEX_RE = /^#[0-9A-Fa-f]{6}$/;
+const REM_RE = /^(-?\d*\.?\d+)rem$/;
+
+/**
+ * 같은 selector 키가 여러 번 등장하면 vars 를 cascade 순으로 병합 (뒤가 앞을 덮음).
+ * tokens-diff 의 mergeBlocks 와 같은 정책이지만 여기서는 평탄 vars map 만 필요해 단순 병합.
+ */
+function mergeVarsForSelector(blocks, selector) {
+  const merged = {};
+  for (const b of blocks) {
+    if (b.key === selector) Object.assign(merged, b.vars);
+  }
+  return merged;
+}
+
+function pickHexOrThrow(vars, name, mode) {
+  const value = vars["--" + name];
+  if (value === undefined) {
+    throw new Error(
+      `theme extract 실패: ${mode}.${name} 가 tokens.css 에 없습니다.\n` +
+        `  → \`sh-ui tokens upgrade --replace\` 로 buildTokens 결과를 적용해 모든 토큰을 hex 로 채운 뒤 다시 시도하세요.`,
+    );
+  }
+  if (!HEX_RE.test(value)) {
+    throw new Error(
+      `theme extract 실패: ${mode}.${name} 가 hex (#RRGGBB) 가 아닙니다 (현재: ${value}).\n` +
+        `  → tokens.css 의 해당 변수를 #RRGGBB 형식으로 바꾸거나, ` +
+        `\`sh-ui tokens upgrade --replace\` 로 표준값으로 리셋한 후 색을 다시 편집하세요.\n` +
+        `  (color-mix() / var() / rgba() 등은 추출 대상이 아님 — 색 추출은 정적 hex 만)`,
+    );
+  }
+  return value.toUpperCase();
+}
+
+function pickHexIfPresent(vars, name) {
+  const value = vars["--" + name];
+  if (value === undefined) return null;
+  if (!HEX_RE.test(value)) return null;
+  return value.toUpperCase();
+}
+
+function pickRadiusOrThrow(rootVars) {
+  const value = rootVars["--radius"];
+  if (value === undefined) {
+    throw new Error("theme extract 실패: --radius 가 tokens.css 에 없습니다.");
+  }
+  const m = REM_RE.exec(value);
+  if (!m) {
+    throw new Error(
+      `theme extract 실패: --radius 가 rem 단위가 아닙니다 (현재: ${value}). 예: '0.5rem'.`,
+    );
+  }
+  const num = parseFloat(m[1]);
+  if (!Number.isFinite(num) || num < 0 || num > 1.5) {
+    throw new Error(
+      `theme extract 실패: --radius 값이 0~1.5 범위 밖입니다 (현재: ${num}).`,
+    );
+  }
+  return num;
+}
+
+/**
+ * tokens.css 텍스트에서 base64 theme 산출.
+ * @returns {{ base64: string, theme: object, summary: object }}
+ */
+export function extractThemeFromCss(cssText) {
+  const blocks = parseBlocks(cssText);
+  const lightVars = mergeVarsForSelector(blocks, ":root");
+  const darkVars = mergeVarsForSelector(blocks, ".dark");
+
+  if (Object.keys(lightVars).length === 0) {
+    throw new Error("theme extract 실패: :root 블록이 tokens.css 에 없습니다.");
+  }
+  if (Object.keys(darkVars).length === 0) {
+    throw new Error(
+      "theme extract 실패: .dark 블록이 tokens.css 에 없습니다 (light-only 모드는 미지원).",
+    );
+  }
+
+  const light = {};
+  const dark = {};
+
+  for (const name of TOKEN_KEYS_REQUIRED) {
+    light[name] = pickHexOrThrow(lightVars, name, "light");
+    dark[name] = pickHexOrThrow(darkVars, name, "dark");
+  }
+
+  // 옵셔널 — 양쪽 모두 hex 로 정의돼야 emit. 한쪽만 있으면 둘 다 skip
+  // (디자인이 어긋날 위험 — 보수적으로).
+  const optionalEmitted = [];
+  for (const name of TOKEN_KEYS_OPTIONAL) {
+    const lv = pickHexIfPresent(lightVars, name);
+    const dv = pickHexIfPresent(darkVars, name);
+    if (lv && dv) {
+      light[name] = lv;
+      dark[name] = dv;
+      optionalEmitted.push(name);
+    }
+  }
+
+  const radius = pickRadiusOrThrow(lightVars);
+
+  const theme = { light, dark, radius };
+  const base64 = encodeTheme(theme);
+
+  return {
+    base64,
+    theme,
+    summary: {
+      requiredKeys: TOKEN_KEYS_REQUIRED.length,
+      optionalKeys: optionalEmitted.length,
+      optionalEmitted,
+      radius,
+    },
+  };
+}
+
+async function loadConfig(cwd) {
+  const configPath = resolve(cwd, "sh-ui.config.json");
+  if (!existsSync(configPath)) {
+    throw new Error(
+      "sh-ui.config.json 을 찾을 수 없습니다. 먼저 `sh-ui init` 또는 `sh-ui create`.",
+    );
+  }
+  return JSON.parse(await readFile(configPath, "utf8"));
+}
+
+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\` 로 먼저 생성하세요.`,
+    );
+  }
+
+  const cssText = await readFile(tokensPath, "utf8");
+  const { base64, summary } = extractThemeFromCss(cssText);
+
+  if (output) {
+    await writeFile(resolve(cwd, output), base64 + "\n", "utf8");
+    console.log(`✓ ${output} 에 base64 저장 (${base64.length} 바이트).`);
+  } else {
+    console.log(base64);
+  }
+
+  console.error(
+    `\n추출 정보 (stderr — base64 와 분리):\n` +
+      `  필수 토큰: ${summary.requiredKeys}\n` +
+      `  옵셔널 토큰: ${summary.optionalKeys} (${summary.optionalEmitted.join(", ") || "—"})\n` +
+      `  radius: ${summary.radius}rem\n\n` +
+      `사용:\n` +
+      `  sh-ui create my-app --theme '${base64.slice(0, 24)}…'\n` +
+      `  (또는 'sh_ui_create_project' MCP 툴의 theme 인자에 그대로 전달)`,
+  );
+}