sh-ui-cli 0.69.0 → 0.71.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,35 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.71.0",
+      "date": "2026-05-09",
+      "title": "cssStrategy: bundled — 단일 CSS 번들 모드 (Phase D)",
+      "type": "minor",
+      "highlights": [
+        "**`cssStrategy: \"bundled\"` 옵션 신설** — `sh-ui.config.json` 에서 켜면 모든 컴포넌트 CSS 가 `paths.cssBundle` 에 지정된 단일 파일로 누적. 컴포넌트별 `styles.css` 파일이 컴포넌트 폴더에 떨어지지 않음. 기본값은 `per-component` (기존 동작) — 옵트인.",
+        "**마커 기반 섹션 — `/* sh-ui:component:NAME-start ... -end */`** — sh-ui 가 마커 사이만 관리. 사용자 custom CSS 를 마커 밖에 추가해도 add/remove 가 그대로 보존. 같은 컴포넌트 재 add 면 안 내용만 교체.",
+        "**add 동작** — bundled 모드에서 컴포넌트 .tsx 의 `import \"./styles.css\";` 라인을 자동 제거 (번들이 한 번 import 되므로 불필요). conflict resolver 우회 (마커 사이는 sh-ui 영역).",
+        "**remove 동작** — .tsx 삭제 + 번들에서 해당 섹션 제거. 사용자 수정 검사도 stripStylesImport 변환 적용해 false positive 회피. 같은 dest 의 변종 중복 처리 fix.",
+        "**doctor 통합** — bundled 모드일 때 `paths.cssBundle` 존재 검증. 미설정/누락 시 fail.",
+        "**제약** — `cssFramework: \"plain\"` 에서만 동작 (tailwind/css-modules/vanilla-extract 는 자체 스코프 메커니즘). 사용자가 번들 파일을 globals.css 같은 곳에서 한 번 import 해야 스타일 적용 — 자동화 안 함."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.71.0"
+    },
+    {
+      "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.71.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {

package/src/add.mjs

@@ -11,6 +11,12 @@ import {
   findMissingTokens,
   loadDefinedVarsFromConfig,
 } from "./tokens-validate.mjs";
+import {
+  upsertSection,
+  stripStylesImport,
+  isStyleFile,
+  isTsxFile,
+} from "./css-bundle.mjs";
 
 /**
  * 기존 파일과 registry 파일 내용이 다를 때 keep/overwrite 결정.
@@ -224,6 +230,50 @@ async function addTokens(config, cwd, diffMode, summary, conflictResolver) {
   }
 }
 
+/**
+ * bundled 모드 — config.paths.cssBundle 에 컴포넌트 섹션 upsert.
+ * 파일이 없으면 헤더 주석과 함께 새로 만든다.
+ *
+ * 마커 사이만 sh-ui 가 관리하므로 conflict resolver 를 거치지 않는다 — 사용자가
+ * 손댄 다른 섹션 / 마커 밖 custom CSS 는 보존되고, 같은 이름 섹션만 교체.
+ */
+async function writeBundleSection({ name, css, config, cwd, diffMode, summary }) {
+  const bundleRel = config.paths?.cssBundle;
+  if (!bundleRel) {
+    throw new Error(
+      "cssStrategy='bundled' 인데 paths.cssBundle 이 sh-ui.config.json 에 없습니다.\n" +
+        "  예: \"paths\": { ..., \"cssBundle\": \"src/shared/styles/sh-ui-components.css\" }",
+    );
+  }
+  const bundlePath = resolve(cwd, bundleRel);
+  const exists = existsSync(bundlePath);
+  const existingText = exists
+    ? await readFile(bundlePath, "utf8")
+    : `/* sh-ui — 컴포넌트 CSS 번들 (cssStrategy: bundled). 마커 사이는 sh-ui 가 관리, 그 밖은 사용자 자유. */\n\n`;
+  const nextText = upsertSection(existingText, name, css);
+
+  if (existingText === nextText) {
+    return; // 변경 없음
+  }
+
+  if (diffMode) {
+    const rel = relative(cwd, bundlePath);
+    const { text, addCount, delCount } = formatUnifiedDiff(existingText, nextText, {
+      useColor: canUseColor(),
+    });
+    summary.push(
+      exists
+        ? { kind: "modified", rel, addCount, delCount, diff: text }
+        : { kind: "new", rel },
+    );
+    return;
+  }
+
+  await ensureDir(bundlePath);
+  await writeFile(bundlePath, nextText, "utf8");
+  console.log(`✓ ${name} → bundle ${relative(cwd, bundlePath)}`);
+}
+
 /**
  * registry 엔트리의 frameworks 필드와 현재 cssFramework 가 호환되는지.
  * 필드가 없으면 "모든 프레임워크에 적용" — 기본 케이스.
@@ -297,12 +347,29 @@ async function addComponent(name, config, cwd, installed, pendingDeps, diffMode,
     await addOne(dep, config, cwd, installed, pendingDeps, diffMode, summary, conflictResolver, validationCtx);
   }
 
+  // bundled 모드 여부. plain 변종에서만 의미 있음 (tailwind/css-modules/vanilla-extract
+  // 는 자체 스코프가 있어 단일 파일 합산이 부적절).
+  const bundled = config.cssStrategy === "bundled" && cssFramework === "plain";
+  let bundleAccumulated = "";
+
   for (const file of entry.files) {
     if (!frameworkMatches(file, cssFramework)) continue;
     const src = resolve(registryRoot, file.src);
-    const dest = resolve(cwd, resolveDest(file.dest, config));
     const raw = await readFile(src, "utf8");
-    const content = substitutePlaceholders(raw, config, file.src);
+    let content = substitutePlaceholders(raw, config, file.src);
+
+    if (bundled && isStyleFile(file)) {
+      // 컴포넌트별 styles.css 파일은 쓰지 않고 누적만 — 마지막에 bundle 에 upsert.
+      bundleAccumulated += (bundleAccumulated ? "\n\n" : "") + content.trim();
+      continue;
+    }
+    if (bundled && isTsxFile(file)) {
+      // .tsx 의 `import "./styles.css";` 제거 — bundled 모드는 사용자가 globals.css 에서
+      // bundle 을 한 번 import 하는 책임을 진다.
+      content = stripStylesImport(content);
+    }
+
+    const dest = resolve(cwd, resolveDest(file.dest, config));
     const result = await writeOrDiff({ dest, content, cwd, diffMode, summary, conflictResolver });
     if (!diffMode && result !== "unchanged") {
       const prefix = result === "kept" ? "↷" : "✓";
@@ -311,6 +378,10 @@ async function addComponent(name, config, cwd, installed, pendingDeps, diffMode,
     }
   }
 
+  if (bundled && bundleAccumulated) {
+    await writeBundleSection({ name, css: bundleAccumulated, config, cwd, diffMode, summary, conflictResolver });
+  }
+
   for (const dep of entry.dependencies ?? []) {
     // dep 은 string ("react-hook-form") 또는 object ({name, frameworks?: string[]}).
     // 후자는 cssFramework 에 따라 의존성을 분기 (예: cva 는 tailwind 변종에만 필요).

package/src/css-bundle.mjs

@@ -0,0 +1,105 @@
+// `cssStrategy: "bundled"` 모드에서 컴포넌트 CSS 를 단일 파일에 마커 기반 섹션으로 누적.
+//
+// 섹션 포맷:
+//   /* sh-ui:component:button-start */
+//   .sh-ui-button { ... }
+//   /* sh-ui:component:button-end */
+//
+// add 시 섹션을 append/replace, remove 시 섹션 제거. 마커 사이의 내용만 sh-ui 가 관리하고
+// 파일의 다른 부분 (사용자가 추가한 custom CSS) 은 그대로 둔다.
+
+const SEC_START = (name) => `/* sh-ui:component:${name}-start */`;
+const SEC_END = (name) => `/* sh-ui:component:${name}-end */`;
+
+/**
+ * bundle 텍스트에서 컴포넌트 섹션을 append 하거나 replace.
+ * 동일 이름 섹션이 이미 있으면 그 안의 내용만 교체.
+ *
+ * @param {string} bundleText 현재 번들 파일 내용 (없으면 빈 문자열)
+ * @param {string} name 컴포넌트 이름 (예: "button")
+ * @param {string} css 컴포넌트의 CSS (마커 제외)
+ * @returns {string} 갱신된 번들 텍스트
+ */
+export function upsertSection(bundleText, name, css) {
+  const start = SEC_START(name);
+  const end = SEC_END(name);
+  const startIdx = bundleText.indexOf(start);
+  const endIdx = bundleText.indexOf(end);
+  const trimmed = css.trim();
+  const block = `${start}\n${trimmed}\n${end}`;
+
+  if (startIdx >= 0 && endIdx > startIdx) {
+    return (
+      bundleText.slice(0, startIdx) +
+      block +
+      bundleText.slice(endIdx + end.length)
+    );
+  }
+
+  // append — 기존 내용이 있으면 빈 줄 한 개로 분리.
+  const sep = bundleText.length === 0
+    ? ""
+    : bundleText.endsWith("\n\n")
+      ? ""
+      : bundleText.endsWith("\n")
+        ? "\n"
+        : "\n\n";
+  return bundleText + sep + block + "\n";
+}
+
+/**
+ * bundle 텍스트에서 컴포넌트 섹션 제거. 없으면 그대로 반환.
+ */
+export function removeSection(bundleText, name) {
+  const start = SEC_START(name);
+  const end = SEC_END(name);
+  const startIdx = bundleText.indexOf(start);
+  const endIdx = bundleText.indexOf(end);
+  if (startIdx < 0 || endIdx <= startIdx) return bundleText;
+  // 섹션 + 다음 줄바꿈 한 번까지 제거 (중복 빈 줄 방지).
+  let cutEnd = endIdx + end.length;
+  if (bundleText[cutEnd] === "\n") cutEnd++;
+  return bundleText.slice(0, startIdx) + bundleText.slice(cutEnd);
+}
+
+/**
+ * bundle 텍스트에서 등록된 컴포넌트 이름 목록 추출 (시작 마커 기준).
+ */
+export function listSections(bundleText) {
+  const re = /\/\*\s*sh-ui:component:([a-z0-9-]+)-start\s*\*\//g;
+  const out = [];
+  let m;
+  while ((m = re.exec(bundleText))) out.push(m[1]);
+  return out;
+}
+
+/**
+ * 컴포넌트 .tsx 의 `import "./styles.css";` 라인을 제거.
+ * 번들 모드에서는 styles.css 가 없으므로 이 import 는 빌드 깨뜨림.
+ *
+ * 다양한 quote / 공백을 허용. 다른 import 는 보존.
+ */
+export function stripStylesImport(tsxText) {
+  // import "./styles.css"; / import './styles.css' / import "./styles.module.css" 등
+  // 줄 끝 newline 은 있을 수도/없을 수도 있어 (?:\n|$) 로 처리.
+  return tsxText.replace(
+    /^[ \t]*import\s+['"]\.\/styles\.(?:module\.)?css['"];?\s*(?:\n|$)/gm,
+    "",
+  );
+}
+
+/**
+ * registry 의 file 엔트리가 CSS 변종인지 (bundled 모드에서 별도 처리 대상).
+ */
+export function isStyleFile(file) {
+  const src = file?.src ?? "";
+  return /\.(css|module\.css|css\.ts)$/.test(src);
+}
+
+/**
+ * registry 의 file 엔트리가 .tsx 변종인지 (stripStylesImport 적용 대상).
+ */
+export function isTsxFile(file) {
+  const src = file?.src ?? "";
+  return /\.tsx$/.test(src);
+}

package/src/doctor.mjs

@@ -256,6 +256,32 @@ function resolveDest(template, config) {
   });
 }
 
+/**
+ * cssStrategy='bundled' 인 경우 paths.cssBundle 파일 존재 + 마커 sanity 검사.
+ * per-component 모드면 검사 자체를 스킵 (필드가 없어도 정상).
+ */
+function checkCssBundle(config, cwd, report) {
+  if (config.cssStrategy !== "bundled") return;
+  const rel = config.paths?.cssBundle;
+  if (!rel) {
+    report.fail(
+      "paths.cssBundle",
+      "cssStrategy='bundled' 인데 paths.cssBundle 이 미설정. " +
+        "예: \"cssBundle\": \"src/shared/styles/sh-ui-components.css\"",
+    );
+    return;
+  }
+  const bundlePath = resolve(cwd, rel);
+  if (!existsSync(bundlePath)) {
+    report.warn(
+      `paths.cssBundle — ${rel}`,
+      "파일 없음 — 컴포넌트를 add 하면 자동 생성됩니다.",
+    );
+    return;
+  }
+  report.ok(`paths.cssBundle — ${rel}`, "(bundled 모드)");
+}
+
 function effectiveFramework(entry, cssFramework) {
   if (cssFramework === "plain") return cssFramework;
   const hasVariant = (entry.files ?? []).some(
@@ -276,6 +302,7 @@ export async function doctor({ cwd }) {
 
   const tokensPath = checkTokensFile(config, cwd, report);
   await checkCssEntry(config, cwd, tokensPath, report);
+  checkCssBundle(config, cwd, report);
 
   let definedVars = null;
   if (tokensPath) {

package/src/remove.mjs

@@ -1,7 +1,14 @@
-import { readFile, rm, rmdir, readdir } from "node:fs/promises";
+import { readFile, rm, rmdir, readdir, writeFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, resolve, relative } from "node:path";
 import { getRegistryRoot } from "./paths.mjs";
+import { removeSection, isStyleFile, stripStylesImport, isTsxFile } from "./css-bundle.mjs";
+
+/** registry file 엔트리가 현재 cssFramework 와 호환되는지 (add.mjs 와 동일 규칙). */
+function frameworkMatches(entry, cssFramework) {
+  if (!entry.frameworks) return true;
+  return entry.frameworks.includes(cssFramework);
+}
 
 function resolveDest(template, config) {
   return template.replace(/\{([a-zA-Z0-9_]+)\}/g, (m, key) => {
@@ -27,13 +34,16 @@ async function loadRegistry(platform) {
   return JSON.parse(await readFile(registryPath, "utf8"));
 }
 
-/** 설치된 파일이 레지스트리 원본과 동일한지(= 사용자가 수정하지 않았는지). */
-async function isUnmodified(srcAbs, destAbs) {
+/**
+ * 설치된 파일이 레지스트리 원본과 동일한지(= 사용자가 수정하지 않았는지).
+ * bundled 모드에서 .tsx 는 add 시 `import "./styles.css";` 가 제거된 상태로 저장됐으므로
+ * 비교 전에 같은 변환을 src 에 적용해 false positive 회피.
+ */
+async function isUnmodified(srcAbs, destAbs, { transform } = {}) {
   try {
-    const [src, dest] = await Promise.all([
-      readFile(srcAbs, "utf8"),
-      readFile(destAbs, "utf8"),
-    ]);
+    let src = await readFile(srcAbs, "utf8");
+    if (transform) src = transform(src);
+    const dest = await readFile(destAbs, "utf8");
     return src === dest;
   } catch {
     return false;
@@ -71,13 +81,34 @@ export async function remove({ cwd, names, force = false, dryRun = false }) {
     }
 
     const registryRoot = getRegistryRoot(config.platform);
+    const bundled = config.cssStrategy === "bundled";
+    const cssFramework = config.cssFramework ?? "plain";
+    const seenDest = new Set();
     for (const file of entry.files) {
+      if (!frameworkMatches(file, cssFramework)) continue;
+      // bundled 모드에선 CSS 파일이 sh-ui-components.css 내 섹션이라 개별 파일이 없음.
+      // .tsx 만 일반 삭제 흐름을 타고, 섹션 제거는 별도 단계에서 처리.
+      if (bundled && isStyleFile(file)) continue;
       const srcAbs = resolve(registryRoot, file.src);
       const destAbs = resolve(cwd, resolveDest(file.dest, config));
+      // 같은 dest 가 여러 file 변종에서 나올 수 있음 (예: index.tsx 와 index.tailwind.tsx
+      // 가 동일 dest 로 매핑) — 한 번만 처리.
+      if (seenDest.has(destAbs)) continue;
+      seenDest.add(destAbs);
 
       if (!existsSync(destAbs)) continue;
 
-      const unmodified = await isUnmodified(srcAbs, destAbs);
+      // dest 는 add 시 substitutePlaceholders + (bundled.tsx 면) stripStylesImport 가
+      // 적용된 채로 저장됐다. unmodified 비교는 같은 변환을 src 에 먹여 false positive 회피.
+      const transform = (text) => {
+        let out = text;
+        if (config.aliases?.utils) {
+          out = out.replaceAll("@SH_UI_UTILS@", config.aliases.utils);
+        }
+        if (bundled && isTsxFile(file)) out = stripStylesImport(out);
+        return out;
+      };
+      const unmodified = await isUnmodified(srcAbs, destAbs, { transform });
       if (!unmodified && !force) {
         modifiedBlocked.push({ name, dest: destAbs });
         continue;
@@ -127,6 +158,24 @@ export async function remove({ cwd, names, force = false, dryRun = false }) {
     touchedDirs.add(dirname(d.dest));
   }
 
+  // bundled 모드 — 각 컴포넌트의 CSS 섹션을 번들에서 제거.
+  if (config.cssStrategy === "bundled" && config.paths?.cssBundle) {
+    const bundlePath = resolve(cwd, config.paths.cssBundle);
+    if (existsSync(bundlePath)) {
+      let text = await readFile(bundlePath, "utf8");
+      let removedAny = false;
+      for (const name of names) {
+        const next = removeSection(text, name);
+        if (next !== text) {
+          text = next;
+          removedAny = true;
+          console.log(`✓ 번들 섹션 제거: ${name} → ${relative(cwd, bundlePath)}`);
+        }
+      }
+      if (removedAny) await writeFile(bundlePath, text, "utf8");
+    }
+  }
+
   // 컴포넌트 폴더가 비면 정리 (paths.components 상위까지)
   const componentsRoot = config.paths?.components
     ? resolve(cwd, config.paths.components)

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 인자에 그대로 전달)`,
+  );
+}