sh-ui-cli 0.68.1 → 0.70.0

package/bin/sh-ui.mjs

@@ -16,6 +16,13 @@ const usage = `사용법:
                                    특수값: tokens → 설정 기반 토큰 파일 생성
   sh-ui list                       현재 설치된 컴포넌트 목록 표시
   sh-ui doctor                     프로젝트 정합성 점검 (config / tokens / 설치된 컴포넌트)
+  sh-ui tokens diff                tokens.css 와 buildTokens 결과 비교 (added/changed/removed)
+  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>/
@@ -105,6 +112,51 @@ 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
+      const sub = rest[0];
+      const flags = rest.slice(1);
+      const { runTokensDiff, runTokensUpgrade } = await import("../src/tokens-cmd.mjs");
+      if (sub === "diff") {
+        await runTokensDiff({ cwd: process.cwd() });
+      } else if (sub === "upgrade") {
+        const apply = flags.includes("--apply");
+        const replace = flags.includes("--replace");
+        if (apply && replace) {
+          console.error("에러: --apply 와 --replace 은 함께 쓸 수 없습니다.\n");
+          process.exit(1);
+        }
+        if (!apply && !replace) {
+          console.error(
+            "에러: `sh-ui tokens upgrade` 는 --apply 또는 --replace 가 필요합니다.\n" +
+              "  --apply   추가된 변수만 적용 (사용자 편집 보존)\n" +
+              "  --replace buildTokens 결과로 통째 덮어쓰기\n" +
+              "미리보기는 `sh-ui tokens diff`.",
+          );
+          process.exit(1);
+        }
+        await runTokensUpgrade({ cwd: process.cwd(), mode: apply ? "apply" : "replace" });
+      } else {
+        console.error(`에러: 알 수 없는 tokens 서브명령 '${sub ?? ""}'. 'diff' 또는 'upgrade'.\n`);
+        process.exit(1);
+      }
+      break;
+    }
     case "mcp": {
       // `sh-ui mcp init ...` → 설정 파일에 엔트리 추가
       // `sh-ui mcp`         → MCP 서버 시작

package/data/changelog/versions.json

@@ -2,6 +2,34 @@
   "$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",
+      "title": "sh-ui tokens diff / upgrade — incremental 토큰 마이그레이션 (Phase B)",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui tokens diff` 신설** — 현재 tokens.css 와 buildTokens 결과를 비교해 added(신규) / changed(값 다름) / removed(사용자 전용) 를 selector 블록 단위로 표시. sh-ui 버전 업그레이드 후 어떤 토큰이 새로 들어왔는지 즉시 파악.",
+        "**`sh-ui tokens upgrade --apply`** — added 변수만 매칭 selector 블록 끝에 incremental 삽입. 사용자가 손댄 색 (changed) 과 추가한 custom 변수 (removed) 는 그대로 보존. 매칭 selector 가 없으면 파일 끝에 새 블록 append (`/* sh-ui upgrade — added */` 주석 표시).",
+        "**`sh-ui tokens upgrade --replace`** — buildTokens 결과로 tokens.css 통째 덮어쓰기. `add tokens --force` 와 동일한 동작이지만 의도가 명시적 (사용자가 모든 편집을 의도적으로 버릴 때만).",
+        "**CSS 블록 파서 자체 구현** — 의존성 없는 1-pass 스캐너 (`packages/cli/src/tokens-diff.mjs`). `:root`, `.dark`, `@media (...) { :root:not(.light):not(.dark) { ... } }` 같은 nested 까지 평탄화 (key 형식: `@media (...) > :root:not(...)`). 같은 selector 가 여러 번 나오면 vars 자동 병합 (CSS cascade 룰).",
+        "**제약** — buildable theme.base (neutral/zinc/slate) 에서만 동작. custom base64 / rich preset (rose/emerald/violet) 은 buildTokens 가 primitives 미정의로 throw — 친절 메시지로 일찍 종료. Flutter platform 은 미지원 (Dart 토큰 생성 형식이 달라 별도 도구 필요)."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.69.0"
+    },
     {
       "version": "0.68.1",
       "date": "2026-05-09",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.68.1",
+  "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 인자에 그대로 전달)`,
+  );
+}

package/src/tokens-cmd.mjs

@@ -0,0 +1,174 @@
+// `sh-ui tokens diff` / `sh-ui tokens upgrade` 명령 핸들러.
+//
+// 두 명령 다 사용자 tokens.css 와 buildTokens(config) 결과를 비교한다.
+//   - diff   — 미리보기만 (added / removed / changed 표).
+//   - upgrade --apply  — added 만 incremental 적용 (사용자 손댄 값 보존).
+//   - upgrade --replace — buildTokens 결과로 통째 덮어쓰기 (`add tokens --force` 동일).
+//
+// custom theme (theme.base === 'custom' 또는 buildable 아닌 preset) 은
+// buildTokens 가 throw 하므로 안내 메시지로 일찍 종료.
+
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { resolve, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getTokensRoot } from "./paths.mjs";
+import { THEME_BASES } from "./constants.js";
+import { parseBlocks, diffBlocks, applyAdditions } from "./tokens-diff.mjs";
+
+async function loadTokensBuilder() {
+  const url = pathToFileURL(resolve(getTokensRoot(), "build.mjs")).href;
+  return import(url);
+}
+
+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"));
+}
+
+/**
+ * config 로 expected tokens.css 를 생성. custom / non-buildable preset 은 throw.
+ */
+async function buildExpected(config) {
+  if (config.theme?.base === "custom") {
+    throw new Error(
+      "custom theme 은 buildTokens 로 재생성 불가 (base64 가 단일 진실). " +
+        "tokens diff/upgrade 는 buildable preset (neutral/zinc/slate) 에서만 동작합니다.",
+    );
+  }
+  const base = config.theme?.base;
+  if (base && !THEME_BASES.includes(base)) {
+    throw new Error(
+      `'${base}' preset 은 buildTokens 로 재생성 불가 (primitives 미정의 — buildable: ${THEME_BASES.join("/")}). ` +
+        "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);
+}
+
+async function loadCurrent(config, cwd) {
+  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\` 로 먼저 생성하세요.`,
+    );
+  }
+  return { text: await readFile(tokensPath, "utf8"), path: tokensPath, rel: tokensRel };
+}
+
+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} 변수).`);
+    return;
+  }
+
+  if (added.length > 0) {
+    console.log(`+ 추가 (${added.length}) — buildTokens 가 새로 제공:`);
+    for (const a of added) {
+      console.log(`    [${a.selector}] ${a.name}: ${a.value};`);
+    }
+  }
+
+  if (changed.length > 0) {
+    console.log(`\n~ 변경 (${changed.length}) — 양쪽 정의값이 다름 (사용자가 손댔거나 sh-ui 가 갱신):`);
+    for (const c of changed) {
+      console.log(`    [${c.selector}] ${c.name}`);
+      console.log(`      current  : ${c.current}`);
+      console.log(`      expected : ${c.expected}`);
+    }
+  }
+
+  if (removed.length > 0) {
+    console.log(`\n- 제거 (${removed.length}) — 사용자 tokens.css 에만 존재 (custom 추가 또는 deprecated):`);
+    for (const r of removed) {
+      console.log(`    [${r.selector}] ${r.name}: ${r.value};`);
+    }
+  }
+
+  console.log(
+    `\n동일 ${unchangedCount} 변수.\n\n` +
+      `적용 옵션:\n` +
+      `  sh-ui tokens upgrade --apply     추가만 incremental 적용 (변경/제거 보존)\n` +
+      `  sh-ui tokens upgrade --replace   buildTokens 결과로 통째 덮어쓰기 (모든 사용자 편집 손실)`,
+  );
+}
+
+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));
+  renderDiffReport(diff, rel);
+}
+
+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));
+
+  console.log(`\nsh-ui tokens upgrade — ${current.rel} (${mode})\n`);
+
+  if (mode === "replace") {
+    if (current.text === expectedText) {
+      console.log(`✓ 변경 없음 — buildTokens 결과와 이미 동일.`);
+      return;
+    }
+    await writeFile(current.path, expectedText, "utf8");
+    console.log(
+      `✓ ${current.rel} 을 buildTokens 결과로 덮어썼습니다.\n` +
+        `  추가 ${diff.added.length} / 변경 ${diff.changed.length} / 제거 ${diff.removed.length}.`,
+    );
+    return;
+  }
+
+  // mode === "apply" — added 만 incremental.
+  if (diff.added.length === 0) {
+    if (diff.changed.length > 0 || diff.removed.length > 0) {
+      console.log(
+        `✓ 추가할 변수 없음. 변경 ${diff.changed.length}, 제거 ${diff.removed.length} 는 사용자 의도로 보존.`,
+      );
+    } else {
+      console.log(`✓ 변경 없음.`);
+    }
+    return;
+  }
+  const next = applyAdditions(current.text, diff.added);
+  await writeFile(current.path, next, "utf8");
+  console.log(
+    `✓ ${diff.added.length} 개 변수 추가 적용:\n` +
+      diff.added
+        .slice(0, 12)
+        .map((a) => `    + [${a.selector}] ${a.name}`)
+        .join("\n") +
+      (diff.added.length > 12 ? `\n    +${diff.added.length - 12} more` : ""),
+  );
+  if (diff.changed.length > 0) {
+    console.log(
+      `\nℹ 값 변경 ${diff.changed.length} 개는 보존됨. ` +
+        `sh-ui 의 새 권장값을 보려면 \`sh-ui tokens diff\`. ` +
+        `통째 덮어쓰기는 \`sh-ui tokens upgrade --replace\`.`,
+    );
+  }
+  if (diff.removed.length > 0) {
+    console.log(
+      `ℹ 사용자 추가 변수 ${diff.removed.length} 개는 그대로 유지.`,
+    );
+  }
+}

package/src/tokens-diff.mjs

@@ -0,0 +1,404 @@
+// tokens.css 비교/병합 로직.
+//
+// 설계:
+//   - 사용자 tokens.css 를 selector 별 블록으로 파싱 (`:root`, `.dark`,
+//     `@media (...)` 안의 nested selector 까지).
+//   - 같은 작업을 buildTokens 결과에도 적용해 "expected" 블록 트리 생성.
+//   - 두 트리를 selector 매칭으로 비교:
+//       added    — expected 에만 존재하는 변수 (사용자에게 새로 제공된 토큰)
+//       removed  — current 에만 존재하는 변수 (사용자 커스텀 또는 deprecated)
+//       changed  — 양쪽에 존재하지만 값이 다름 (사용자가 손댔거나 sh-ui 가 갱신)
+//       unchanged— 양쪽 동일
+//
+// 적용(apply) 정책:
+//   - added 만 자동 적용 — 사용자가 손댄 값은 건드리지 않음.
+//   - 같은 selector 블록을 current 에서 찾아 닫는 `}` 바로 전에 라인 삽입.
+//   - 매칭 selector 블록이 없으면 파일 끝에 신규 블록을 append.
+//   - 결과는 새 텍스트 — 호출부가 파일에 쓰는지 결정.
+
+/**
+ * tokens.css 텍스트를 셀렉터 블록 트리로 파싱.
+ *
+ * 단순 1-pass 스캐너 — `selector { ... }` 형태의 블록을 추출하고, 중첩이면
+ * inner block 도 별도 항목으로 평탄화한다 (parent selector 와 결합한 키로).
+ *
+ * 예:
+ *   :root { --x: 1; }
+ *   @media (prefers-color-scheme: dark) { :root:not(.light):not(.dark) { --x: 2; } }
+ *   .dark { --x: 3; }
+ *
+ * → [
+ *     { key: ":root", vars: { "--x": "1" } },
+ *     { key: "@media (prefers-color-scheme: dark) > :root:not(.light):not(.dark)",
+ *       vars: { "--x": "2" } },
+ *     { key: ".dark", vars: { "--x": "3" } }
+ *   ]
+ */
+export function parseBlocks(css) {
+  const ctx = { css, i: 0, blocks: [], stack: [] };
+  parseTopLevel(ctx);
+  return ctx.blocks;
+}
+
+/** top-level (또는 @rule 내부) 의 selector 들을 발견할 때마다 본문 파싱. */
+function parseTopLevel(ctx) {
+  const { css } = ctx;
+  const n = css.length;
+  while (ctx.i < n) {
+    const c = css[ctx.i];
+    if (c === "}") return; // 부모 호출에서 닫힘 처리
+    if (c === "/" && css[ctx.i + 1] === "*") {
+      const end = css.indexOf("*/", ctx.i + 2);
+      if (end < 0) {
+        ctx.i = n;
+        return;
+      }
+      ctx.i = end + 2;
+      continue;
+    }
+    if (/\s/.test(c)) {
+      ctx.i++;
+      continue;
+    }
+    // selector 수집 — '{' 또는 ';' 또는 '}' 까지
+    const selStart = ctx.i;
+    while (ctx.i < n) {
+      const ch = css[ctx.i];
+      if (ch === "{" || ch === "}" || ch === ";") break;
+      if (ch === "/" && css[ctx.i + 1] === "*") {
+        const end = css.indexOf("*/", ctx.i + 2);
+        if (end < 0) {
+          ctx.i = n;
+          break;
+        }
+        ctx.i = end + 2;
+        continue;
+      }
+      ctx.i++;
+    }
+    const head = css.slice(selStart, ctx.i).trim();
+    if (!head) {
+      ctx.i++;
+      continue;
+    }
+    if (css[ctx.i] === "{") {
+      ctx.i++; // skip '{'
+      ctx.stack.push(head);
+      parseBlockBody(ctx);
+      ctx.stack.pop();
+      // body 끝나면 ctx.i 는 '}' 다음.
+    } else {
+      // ';' — top-level @import 등. 무시.
+      ctx.i++;
+    }
+  }
+}
+
+/**
+ * `{` 직후 위치부터 본문을 스캔. `--name: value;` 는 vars 로 수집하고,
+ * 다른 selector 가 나오면 parseTopLevel 재귀 — 평탄화된 key 로 blocks 에 push.
+ * 닫는 `}` 만나면 종료, ctx.i 는 `}` 다음을 가리킨다.
+ */
+function parseBlockBody(ctx) {
+  const { css } = ctx;
+  const n = css.length;
+  const vars = {};
+
+  while (ctx.i < n) {
+    const c = css[ctx.i];
+    if (c === "}") {
+      ctx.i++;
+      // 자기 자신의 vars 가 있으면 blocks 에 push (selector chain 그대로 join).
+      if (Object.keys(vars).length > 0) {
+        ctx.blocks.push({ key: ctx.stack.join(" > "), vars });
+      }
+      return;
+    }
+    if (c === "/" && css[ctx.i + 1] === "*") {
+      const end = css.indexOf("*/", ctx.i + 2);
+      if (end < 0) {
+        ctx.i = n;
+        return;
+      }
+      ctx.i = end + 2;
+      continue;
+    }
+    if (/\s/.test(c)) {
+      ctx.i++;
+      continue;
+    }
+    // 변수 선언 — `--name: value;`
+    if (c === "-" && css[ctx.i + 1] === "-") {
+      const colonIdx = css.indexOf(":", ctx.i);
+      if (colonIdx < 0) {
+        ctx.i = n;
+        return;
+      }
+      const semiIdx = findStatementEnd(css, colonIdx + 1);
+      if (semiIdx < 0) {
+        ctx.i = n;
+        return;
+      }
+      const name = css.slice(ctx.i, colonIdx).trim();
+      const value = css.slice(colonIdx + 1, semiIdx).trim();
+      vars[name] = value;
+      ctx.i = semiIdx + 1;
+      continue;
+    }
+    // 일반 선언 또는 nested selector — `{` 또는 `;` 를 만날 때까지 스캔.
+    let j = ctx.i;
+    while (j < n) {
+      const ch = css[j];
+      if (ch === "{" || ch === "}" || ch === ";") break;
+      if (ch === "/" && css[j + 1] === "*") {
+        const end = css.indexOf("*/", j + 2);
+        if (end < 0) {
+          j = n;
+          break;
+        }
+        j = end + 2;
+        continue;
+      }
+      j++;
+    }
+    if (css[j] === "{") {
+      // nested selector — 평탄화 위해 stack 에 push, parseBlockBody 재귀.
+      const inner = css.slice(ctx.i, j).trim();
+      ctx.i = j + 1;
+      ctx.stack.push(inner);
+      parseBlockBody(ctx);
+      ctx.stack.pop();
+      continue;
+    }
+    // 일반 property — 무시 (var 아닌 일반 css 선언)
+    ctx.i = j + 1;
+  }
+  // EOF — 마무리
+  if (Object.keys(vars).length > 0) {
+    ctx.blocks.push({ key: ctx.stack.join(" > "), vars });
+  }
+}
+
+/**
+ * `;` 또는 블록 끝 `}` 위치 — 변수 선언의 종결점.
+ * 괄호 깊이를 추적해 `var(--a, var(--b))` 처럼 안에 ',' 가 있어도 무사.
+ */
+function findStatementEnd(css, start) {
+  let i = start;
+  let depth = 0;
+  const n = css.length;
+  while (i < n) {
+    const c = css[i];
+    if (c === "(") depth++;
+    else if (c === ")") depth--;
+    else if (depth === 0 && (c === ";" || c === "}")) return i;
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * 두 블록 트리 비교. selector 키로 매칭 후 변수별 added/removed/changed 분류.
+ *
+ * @returns {{
+ *   added: Array<{ selector: string, name: string, value: string }>,
+ *   removed: Array<{ selector: string, name: string, value: string }>,
+ *   changed: Array<{ selector: string, name: string, expected: string, current: string }>,
+ *   unchangedCount: number
+ * }}
+ */
+export function diffBlocks(currentBlocks, expectedBlocks) {
+  const added = [];
+  const removed = [];
+  const changed = [];
+  let unchangedCount = 0;
+
+  // 같은 selector 가 파일에 여러 번 등장하면 (예: 색 :root 와 spacing :root 가 분리)
+  // vars 를 병합해야 한다 — 단순 Map 으로는 뒤 등장이 앞을 덮어써 오탐 발생.
+  const currentByKey = mergeBlocks(currentBlocks);
+  const expectedByKey = mergeBlocks(expectedBlocks);
+
+  // expected 기준 — added / changed / unchanged 분류
+  for (const [key, eb] of expectedByKey) {
+    const cb = currentByKey.get(key);
+    if (!cb) {
+      // 매칭 셀렉터 자체가 없으면 모든 expected var 가 added.
+      for (const [name, value] of Object.entries(eb.vars)) {
+        added.push({ selector: key, name, value });
+      }
+      continue;
+    }
+    for (const [name, eValue] of Object.entries(eb.vars)) {
+      const cValue = cb.vars[name];
+      if (cValue === undefined) {
+        added.push({ selector: key, name, value: eValue });
+      } else if (cValue !== eValue) {
+        changed.push({ selector: key, name, expected: eValue, current: cValue });
+      } else {
+        unchangedCount++;
+      }
+    }
+  }
+
+  // current 기준 — removed (expected 에 없는 사용자 변수)
+  for (const [key, cb] of currentByKey) {
+    const eb = expectedByKey.get(key);
+    if (!eb) {
+      // 매칭 셀렉터가 expected 에 없음 — 사용자 커스텀 블록. removed 에 안 넣음.
+      // (사용자가 의도적으로 추가했을 가능성 — 자동 제거 위험)
+      continue;
+    }
+    for (const [name, cValue] of Object.entries(cb.vars)) {
+      if (!(name in eb.vars)) {
+        removed.push({ selector: key, name, value: cValue });
+      }
+    }
+  }
+
+  return { added, removed, changed, unchangedCount };
+}
+
+/** 같은 selector key 의 vars 를 병합. 뒤 등장이 앞 값을 덮어쓰는 CSS cascade 룰 따름. */
+function mergeBlocks(blocks) {
+  const out = new Map();
+  for (const b of blocks) {
+    const prev = out.get(b.key);
+    if (!prev) {
+      out.set(b.key, { key: b.key, vars: { ...b.vars } });
+    } else {
+      Object.assign(prev.vars, b.vars);
+    }
+  }
+  return out;
+}
+
+/**
+ * added 변수만 current text 에 incremental insert.
+ *
+ * 정책:
+ *   - 같은 selector 블록을 current 에서 찾아 닫는 `}` 바로 전에 한 줄 추가.
+ *   - 매칭 블록이 없으면 파일 끝에 새 블록을 한 번 append (selector 별로 묶음).
+ *   - changed / removed 는 건드리지 않음 (사용자 의도 보존).
+ *
+ * @returns {string} 새로운 css 텍스트
+ */
+export function applyAdditions(currentText, added) {
+  if (added.length === 0) return currentText;
+
+  // selector 별로 묶기
+  const bySelector = new Map();
+  for (const a of added) {
+    if (!bySelector.has(a.selector)) bySelector.set(a.selector, []);
+    bySelector.get(a.selector).push(a);
+  }
+
+  let result = currentText;
+  const orphans = [];
+
+  for (const [selector, items] of bySelector) {
+    const inserted = tryInsertIntoExistingBlock(result, selector, items);
+    if (inserted !== null) {
+      result = inserted;
+    } else {
+      orphans.push({ selector, items });
+    }
+  }
+
+  if (orphans.length > 0) {
+    result += "\n\n/* sh-ui upgrade — added */\n";
+    for (const { selector, items } of orphans) {
+      const segments = selector.split(" > ");
+      if (segments.length > 1) {
+        // nested — 첫 segment 가 outer (@media 등), 마지막이 inner selector.
+        const outer = segments[0];
+        const inner = segments[segments.length - 1];
+        result += `${outer} {\n  ${inner} {\n`;
+        for (const it of items) result += `    ${it.name}: ${it.value};\n`;
+        result += "  }\n}\n";
+      } else {
+        // 단순 selector 또는 @rule — 그대로 한 블록.
+        result += `${selector} {\n`;
+        for (const it of items) result += `  ${it.name}: ${it.value};\n`;
+        result += "}\n";
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * current 안에서 같은 셀렉터 블록을 찾아 닫는 `}` 직전에 라인 삽입.
+ * 못 찾으면 null 반환 — 호출부가 orphan 처리.
+ */
+function tryInsertIntoExistingBlock(currentText, selector, items) {
+  // selector 가 nested 인 경우 — 단순화 위해 마지막 segment 만으로 매칭.
+  // 예: "@media (...) > :root:not(.light):not(.dark)" → ":root:not(.light):not(.dark)"
+  const segments = selector.split(" > ");
+  const target = segments[segments.length - 1];
+
+  // target { 의 첫 매칭. selector 정확 일치 (공백 정규화).
+  const targetNormalized = target.replace(/\s+/g, " ").trim();
+  const re = new RegExp(
+    `(${escapeRegex(targetNormalized).replace(/ /g, "\\s+")})\\s*\\{`,
+    "g",
+  );
+  let m;
+  while ((m = re.exec(currentText))) {
+    const blockStart = m.index + m[0].length;
+    // 이 블록의 닫는 `}` 찾기 — 깊이 추적
+    const closeIdx = findMatchingBrace(currentText, blockStart);
+    if (closeIdx < 0) continue;
+    // 닫기 직전 위치에 줄 삽입.
+    // 들여쓰기 — 마지막 의미 있는 줄의 들여쓰기 따르기.
+    const indent = detectIndent(currentText, closeIdx);
+    const insertion = items
+      .map((it) => `${indent}${it.name}: ${it.value};`)
+      .join("\n") + "\n";
+    return (
+      currentText.slice(0, closeIdx) + insertion + currentText.slice(closeIdx)
+    );
+  }
+  return null;
+}
+
+function findMatchingBrace(text, start) {
+  let depth = 1;
+  let i = start;
+  const n = text.length;
+  while (i < n) {
+    const c = text[i];
+    if (c === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      if (end < 0) return -1;
+      i = end + 2;
+      continue;
+    }
+    if (c === "{") depth++;
+    else if (c === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return -1;
+}
+
+function detectIndent(text, closeIdx) {
+  // 닫는 `}` 직전 줄의 들여쓰기 추출.
+  // 한 줄 위로 올라가 마지막 의미있는 줄 시작점 찾기.
+  let i = closeIdx - 1;
+  while (i >= 0 && text[i] !== "\n") i--;
+  // i 는 직전 줄의 \n. 다음 줄 시작에서 공백 카운트.
+  let j = i + 1;
+  let indent = "";
+  while (j < closeIdx && (text[j] === " " || text[j] === "\t")) {
+    indent += text[j];
+    j++;
+  }
+  return indent || "  ";
+}
+
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}