sh-ui-cli 0.110.0 → 0.111.0

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.111.0",
+      "date": "2026-05-22",
+      "title": "theme — extraTokens 패스스루 + 모노레포 공유 theme",
+      "type": "minor",
+      "highlights": [
+        "**`theme.extraTokens` 신규** — `sh-ui.config.json` 의 `theme.extraTokens: { root, light, dark }` 에 임의 토큰(`accent-soft`·`surface`·`cta-*`·`border-focus` 등)을 정의하면 tokens.css 와 `@theme inline` 양쪽에 자동 emit. TOKEN_KEYS/OPTIONAL_TOKEN_KEYS 의 고정 스키마를 벗어나는 디자인 시스템 확장을 config-driven 으로 — tokens.css 손-편집 후 `tokens upgrade`/재스캐폴드 시 날아가던 클로버 문제 해결. `root` 는 모드 무관 고정(CTA 같은 light/dark 공통), `light`/`dark` 는 모드별.",
+        "**모노레포 공유 theme** — `packages/ui/ui-core/sh-ui.config.json` 에 `theme` 블록을 두면 sibling `ui-apps/ui-*` 들이 묵시적 상속. ui-app 측 `theme` 가 있으면 deep-merge (app 키가 core 키 override). 같은 디자인 시스템을 쓰는 다중 앱이 토큰을 중복 정의하지 않음. `add_app` 가 ui-core 의 공유 theme 을 감지하면 새 ui-app 의 `theme` 블록을 자동으로 비워서 상속하게 만든다.",
+        "**`tokens upgrade` 가 공유 theme 반영** — `sh-ui tokens upgrade` 가 sibling ui-core 의 theme 을 머지한 effective config 로 buildTokens 호출 → ui-app 단독에 있는 토큰만 갖고 빌드하던 종전 동작 보강.",
+        "**Tailwind 유틸 자동 매핑** — `buildTokensCss` 의 `@theme inline` 블록이 extraTokens 키마다 `--color-<key>: var(--<key>)` 를 함께 emit → `bg-cta-bg`/`text-accent-soft-fg` 같은 Tailwind utility 가 별도 손-매핑 없이 즉시 사용 가능."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.111.0"
+    },
     {
       "version": "0.110.0",
       "date": "2026-05-22",

package/data/tokens/build.mjs

@@ -85,13 +85,22 @@ function toCssValue(entry) {
   return entry.value;
 }
 
-function emitCssBlock(selector, entries) {
-  const lines = Object.entries(entries)
-    .map(([p, entry]) => `  ${toCssVar(p)}: ${toCssValue(entry)};`)
-    .join("\n");
+function emitCssBlock(selector, entries, extraLines = []) {
+  const baseLines = Object.entries(entries)
+    .map(([p, entry]) => `  ${toCssVar(p)}: ${toCssValue(entry)};`);
+  const lines = [...baseLines, ...extraLines].join("\n");
   return `${selector} {\n${lines}\n}`;
 }
 
+/** extraTokens 카테고리(plain {key: value}) → CSS 라인 배열. key 가 '--' 로 시작하면 그대로. */
+function extraTokensToLines(map) {
+  if (!map || typeof map !== "object") return [];
+  return Object.entries(map).map(([rawKey, value]) => {
+    const key = rawKey.startsWith("--") ? rawKey.slice(2) : rawKey;
+    return `  --${key}: ${value};`;
+  });
+}
+
 /**
  * `prefers-color-scheme: dark` 자동 적용 블록.
  *
@@ -105,10 +114,12 @@ function emitCssBlock(selector, entries) {
  *   .light 클래스          → :root 만 적용 (강제 라이트, OS 무관)
  *   .dark 클래스           → .dark 블록이 마지막에 와서 항상 승리 (강제 다크)
  */
-function emitAutoDarkBlock(darkEntries) {
-  const lines = Object.entries(darkEntries)
-    .map(([p, entry]) => `    ${toCssVar(p)}: ${toCssValue(entry)};`)
-    .join("\n");
+function emitAutoDarkBlock(darkEntries, extraLines = []) {
+  const baseLines = Object.entries(darkEntries)
+    .map(([p, entry]) => `    ${toCssVar(p)}: ${toCssValue(entry)};`);
+  // 미디어쿼리 안쪽은 한 단계 더 들여쓰기 — extraTokens 라인도 같은 들여쓰기 적용.
+  const indentedExtras = extraLines.map((line) => `  ${line}`);
+  const lines = [...baseLines, ...indentedExtras].join("\n");
   return `@media (prefers-color-scheme: dark) {\n  :root:not(.light):not(.dark) {\n${lines}\n  }\n}`;
 }
 
@@ -131,13 +142,28 @@ function mergeThemeIndependent(tokens) {
  * radius 는 단일 토큰 (--radius) 이지만 Tailwind 의 rounded-{sm,md,lg,xl}
  * 4 단계로 expand. 템플릿이 손으로 박아두던 패턴을 단일 소스로 옮긴 것.
  */
-function buildTailwindThemeBlock(lightTokens) {
+function buildTailwindThemeBlock(lightTokens, extraTokens) {
   const lines = [];
   for (const path of Object.keys(lightTokens)) {
     const cssVar = toCssVar(path);
     const themeKey = cssVar.replace(/^--/, "--color-");
     lines.push(`  ${themeKey}: var(${cssVar});`);
   }
+  // extraTokens (v0.111.0+) → Tailwind utility 자동 생성용 매핑.
+  // root/light/dark 의 모든 키 합집합 — 각각 한 번씩만 --color-* 매핑 (var 가 모드별로 해석되므로).
+  if (extraTokens && typeof extraTokens === "object") {
+    const seen = new Set();
+    for (const cat of ["root", "light", "dark"]) {
+      const map = extraTokens[cat];
+      if (!map || typeof map !== "object") continue;
+      for (const rawKey of Object.keys(map)) {
+        const key = rawKey.startsWith("--") ? rawKey.slice(2) : rawKey;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        lines.push(`  --color-${key}: var(--${key});`);
+      }
+    }
+  }
   lines.push(`  --radius-sm: calc(var(--radius) - 2px);`);
   lines.push(`  --radius-md: var(--radius);`);
   lines.push(`  --radius-lg: calc(var(--radius) + 2px);`);
@@ -149,18 +175,27 @@ export async function buildTokensCss(config) {
   const tokens = await resolveTokens(config);
   const mode = config.theme.mode;
   const themeIndep = mergeThemeIndependent(tokens);
+
+  // extraTokens (v0.111.0+) — TOKEN_KEYS/OPTIONAL_TOKEN_KEYS 에 없는 자유 추가 토큰.
+  // root: 모드 무관 — light :root 에 emit (dark 블록이 덮어쓰지 않아 자동 cascade).
+  // light: light :root 에. dark: dark 블록 양쪽 (@media + .dark) 에.
+  const extra = config.theme?.extraTokens ?? {};
+  const extraRoot = extraTokensToLines(extra.root);
+  const extraLight = extraTokensToLines(extra.light);
+  const extraDark = extraTokensToLines(extra.dark);
+
   const blocks = [];
   if (mode === "light" || mode === "light-dark") {
-    blocks.push(emitCssBlock(":root", { ...tokens.light, ...themeIndep }));
+    blocks.push(emitCssBlock(":root", { ...tokens.light, ...themeIndep }, [...extraLight, ...extraRoot]));
   }
   if (mode === "dark") {
-    blocks.push(emitCssBlock(":root", { ...tokens.dark, ...themeIndep }));
+    blocks.push(emitCssBlock(":root", { ...tokens.dark, ...themeIndep }, [...extraDark, ...extraRoot]));
   }
   if (mode === "light-dark") {
-    blocks.push(emitAutoDarkBlock(tokens.dark));
-    blocks.push(emitCssBlock(".dark", tokens.dark));
+    blocks.push(emitAutoDarkBlock(tokens.dark, extraDark));
+    blocks.push(emitCssBlock(".dark", tokens.dark, extraDark));
   }
-  blocks.push(buildTailwindThemeBlock(tokens.light));
+  blocks.push(buildTailwindThemeBlock(tokens.light, extra));
   const header = `/* Generated by @sh-ui/tokens — do not edit directly */\n/* base=${config.theme.base} radius=${config.theme.radius} mode=${config.theme.mode} */\n`;
   return header + "\n" + blocks.join("\n\n") + "\n";
 }

package/package.json

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

package/sh-ui.schema.json

@@ -46,6 +46,16 @@
         "mode": {
           "enum": ["light", "dark", "light-dark"],
           "description": "다크 모드 전략. light-dark = OS 자동 + .light/.dark 클래스 토글, light/dark = 강제 단일 모드."
+        },
+        "extraTokens": {
+          "type": "object",
+          "description": "v0.111.0+ 신규. 디자인 시스템 자유 추가 토큰 — TOKEN_KEYS/OPTIONAL_TOKEN_KEYS 에 없는 임의 키(`accent-soft`, `surface`, `cta-bg` 등) 를 tokens.css 와 globals.css `@theme` 에 자동 emit. root=모드 무관 고정, light/dark=모드별. 모노레포에서 ui-core 의 theme 에 두면 모든 ui-app 이 상속 (app 측 override 시 deep-merge).",
+          "additionalProperties": false,
+          "properties": {
+            "root":  { "type": "object", "additionalProperties": { "type": "string" }, "description": "모드 무관 고정 토큰 (예: CTA 밴드 색 — light/dark 동일)." },
+            "light": { "type": "object", "additionalProperties": { "type": "string" }, "description": "라이트 모드 토큰." },
+            "dark":  { "type": "object", "additionalProperties": { "type": "string" }, "description": "다크 모드 토큰." }
+          }
         }
       }
     },

package/src/create/generator.js

@@ -604,6 +604,23 @@ export async function addApp(options = {}) {
   }
   await patchShUiConfig(path.join(uiAppDir, 'sh-ui.config.json'), css, themeBase);
 
+  // v0.111.0+ — ui-core 가 공유 theme 을 호스팅하고 사용자가 --theme 미지정 시,
+  // 새 ui-app 의 theme 블록을 제거해 ui-core 로부터 묵시적 상속. 같은 디자인 시스템을
+  // 쓰는 모노레포 다중 앱이 토큰을 중복 정의하지 않도록.
+  if (!options.theme) {
+    const uiAppConfigPath = path.join(uiAppDir, 'sh-ui.config.json');
+    const uiCoreConfigPath = path.resolve(cwd, 'packages', 'ui', 'ui-core', 'sh-ui.config.json');
+    if (await fs.pathExists(uiCoreConfigPath)) {
+      const coreCfg = await fs.readJson(uiCoreConfigPath);
+      if (coreCfg.theme && (coreCfg.theme.extraTokens || coreCfg.theme.base || coreCfg.theme.radius || coreCfg.theme.mode)) {
+        const appCfg = await fs.readJson(uiAppConfigPath);
+        delete appCfg.theme;
+        await fs.writeJson(uiAppConfigPath, appCfg, { spaces: 2 });
+        console.log(`\n  ℹ ui-core 가 공유 theme 을 호스팅 — 새 ui-app 은 theme 블록을 두지 않고 상속.`);
+      }
+    }
+  }
+
   console.log(`\n✅ apps/${appName} 이 추가되었습니다!`);
   console.log('\n  pnpm install');
   console.log(`  pnpm --filter ${appName} dev\n`);

package/src/create/theme/inject.js

@@ -37,15 +37,31 @@ export const buildCssColorsBlock = (theme) => {
   );
   const allKeys = [...TOKEN_KEYS, ...optionalKeys];
 
-  const lightLines = allKeys.map((k) => cssColorLine(k, theme.light[k])).join('\n');
-  const darkLines = allKeys.map((k) => cssColorLine(k, theme.dark[k])).join('\n');
+  // extraTokens (v0.111.0+) — TOKEN_KEYS/OPTIONAL_TOKEN_KEYS 에 없는 자유 추가 토큰.
+  // root: 모드 무관 고정 — :root 에만 emit (dark 블록에 덮어쓰지 않아 자동 cascade).
+  // light: :root 에 emit (light 가 :root 기본). dark: dark 블록 두 곳에 emit.
+  const extra = theme.extraTokens ?? {};
+  const extraRootLines = entriesToCssLines(extra.root);
+  const extraLightLines = entriesToCssLines(extra.light);
+  const extraDarkLines = entriesToCssLines(extra.dark);
+
+  const lightSection = [
+    ...allKeys.map((k) => cssColorLine(k, theme.light[k])),
+    ...extraLightLines,
+    ...extraRootLines,
+  ].join('\n');
+
+  const darkLines = [
+    ...allKeys.map((k) => cssColorLine(k, theme.dark[k])),
+    ...extraDarkLines,
+  ];
   // 미디어쿼리 안의 다크 라인은 한 단계 더 들여쓰기 (`:root:not(...)` 안쪽).
-  const darkLinesIndented = allKeys
-    .map((k) => `  ${cssColorLine(k, theme.dark[k])}`)
-    .join('\n');
+  const darkLinesIndented = darkLines.map((line) => `  ${line}`).join('\n');
+  const darkSection = darkLines.join('\n');
+
   return [
     ':root {',
-    lightLines,
+    lightSection,
     '}',
     '@media (prefers-color-scheme: dark) {',
     '  :root:not(.light):not(.dark) {',
@@ -53,11 +69,20 @@ export const buildCssColorsBlock = (theme) => {
     '  }',
     '}',
     '.dark {',
-    darkLines,
+    darkSection,
     '}',
   ].join('\n');
 };
 
+/** extraTokens 카테고리(plain object) → CSS 라인 배열. key 가 '--' 로 시작하면 그대로, 아니면 prepend. */
+function entriesToCssLines(map) {
+  if (!map || typeof map !== 'object') return [];
+  return Object.entries(map).map(([rawKey, value]) => {
+    const key = rawKey.startsWith('--') ? rawKey.slice(2) : rawKey;
+    return cssColorLine(key, value);
+  });
+}
+
 export const buildCssRadiusBlock = (theme) => {
   return `  --radius: ${theme.radius}rem;`;
 };

package/src/create/theme/resolveTheme.js

@@ -0,0 +1,95 @@
+// resolveTheme — ui-core/sh-ui.config.json 의 공유 theme 과 ui-app/sh-ui.config.json 의
+// app theme 을 머지해 effective theme 반환. v0.111.0+ 의 shared-theme 메커니즘.
+//
+// 머지 규칙:
+//   - 스칼라 (base/radius/mode): app 값 우선 (undefined 면 core)
+//   - extraTokens.{root,light,dark}: 키 단위 deep-merge — app 키가 core 키 override, 누락 키는 core 상속
+//   - extraTokens 카테고리 자체가 한쪽만 있으면 그쪽 그대로
+//
+// 모노레포 ui-core 의 theme 이 없으면 (or coreConfig 미제공) app theme 그대로 반환 — backward-compat.
+
+import path from 'node:path';
+import { promises as fsp } from 'node:fs';
+
+/** ui-app config 경로에서 sibling ui-core/sh-ui.config.json 을 찾는다. 모노레포 컨벤션 가정:
+ *   .../packages/ui/ui-apps/ui-{name}/sh-ui.config.json
+ *   .../packages/ui/ui-core/sh-ui.config.json
+ * 못 찾으면 null. */
+export async function findUiCoreConfigPath(uiAppConfigPath) {
+  // ui-apps/ui-{name}/ -> ../../ui-core/
+  const appDir = path.dirname(path.resolve(uiAppConfigPath));
+  const candidate = path.resolve(appDir, '..', '..', 'ui-core', 'sh-ui.config.json');
+  try {
+    await fsp.access(candidate);
+    return candidate;
+  } catch {
+    return null;
+  }
+}
+
+/** sh-ui.config.json 을 읽어 객체 반환. 파일 없거나 파싱 실패 시 null. */
+export async function readShUiConfig(configPath) {
+  if (!configPath) return null;
+  try {
+    const text = await fsp.readFile(configPath, 'utf-8');
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** extraTokens 한 카테고리(root/light/dark) deep-merge. app 키 우선. 둘 다 없으면 undefined. */
+function mergeTokenMap(coreMap, appMap) {
+  if (!coreMap && !appMap) return undefined;
+  return { ...(coreMap ?? {}), ...(appMap ?? {}) };
+}
+
+/** extraTokens 블록 deep-merge. */
+function mergeExtraTokens(coreExtra, appExtra) {
+  if (!coreExtra && !appExtra) return undefined;
+  const result = {};
+  for (const cat of ['root', 'light', 'dark']) {
+    const merged = mergeTokenMap(coreExtra?.[cat], appExtra?.[cat]);
+    if (merged && Object.keys(merged).length > 0) result[cat] = merged;
+  }
+  return Object.keys(result).length > 0 ? result : undefined;
+}
+
+/**
+ * theme block 두 개를 머지해 effective theme 반환.
+ * 둘 다 null/undefined 면 null. 한쪽만 있으면 그쪽 그대로.
+ */
+export function resolveTheme(coreTheme, appTheme) {
+  if (!coreTheme && !appTheme) return null;
+  if (!coreTheme) return appTheme;
+  if (!appTheme) return coreTheme;
+
+  const merged = {
+    ...coreTheme,
+    ...appTheme,  // app 의 스칼라(base/radius/mode) 가 core 를 override
+  };
+
+  const extra = mergeExtraTokens(coreTheme.extraTokens, appTheme.extraTokens);
+  if (extra) merged.extraTokens = extra;
+  else delete merged.extraTokens;
+
+  return merged;
+}
+
+/**
+ * ui-app config 객체 + (선택) ui-core config 객체로부터 effective theme 계산.
+ * config 자체에 theme 필드가 없으면 null 자리에서 시작.
+ */
+export function resolveThemeFromConfigs(coreConfig, appConfig) {
+  return resolveTheme(coreConfig?.theme ?? null, appConfig?.theme ?? null);
+}
+
+/**
+ * ui-app config 경로에서 sibling ui-core 를 찾아 머지된 theme 을 반환.
+ * 모노레포가 아니거나 sibling 없으면 app theme 그대로.
+ */
+export async function loadResolvedTheme(uiAppConfigPath, appConfig) {
+  const corePath = await findUiCoreConfigPath(uiAppConfigPath);
+  const coreConfig = corePath ? await readShUiConfig(corePath) : null;
+  return resolveThemeFromConfigs(coreConfig, appConfig);
+}

package/src/tokens-cmd.mjs

@@ -34,23 +34,41 @@ async function loadConfig(cwd) {
 
 /**
  * config 로 expected tokens.css 를 생성. custom / non-buildable preset 은 throw.
+ *
+ * v0.111.0+ — 모노레포 ui-app 의 경우 sibling ui-core/sh-ui.config.json 의
+ * 공유 theme 을 merge (resolveTheme: app 키가 core 키 override).
  */
-async function buildExpected(config) {
-  if (config.theme?.base === "custom") {
+async function buildExpected(config, cwd) {
+  const effectiveConfig = await applySharedTheme(config, cwd);
+  const effectiveBase = effectiveConfig.theme?.base;
+  if (effectiveBase === "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)) {
+  if (effectiveBase && !THEME_BASES.includes(effectiveBase)) {
     throw new Error(
-      `'${base}' preset 은 buildTokens 로 재생성 불가 (primitives 미정의 — buildable: ${THEME_BASES.join("/")}). ` +
+      `'${effectiveBase}' preset 은 buildTokens 로 재생성 불가 (primitives 미정의 — buildable: ${THEME_BASES.join("/")}). ` +
         "diff/upgrade 는 base 가 neutral/zinc/slate 일 때만 사용 가능합니다.",
     );
   }
   const { buildTokens } = await loadTokensBuilder();
-  return buildTokens(config);
+  return buildTokens(effectiveConfig);
+}
+
+/** 모노레포 ui-app 의 sibling ui-core 의 theme 을 머지한 config 를 반환. ui-core 없으면 그대로. */
+async function applySharedTheme(config, cwd) {
+  const { findUiCoreConfigPath, readShUiConfig, resolveThemeFromConfigs } =
+    await import("./create/theme/resolveTheme.js");
+  const appConfigPath = resolve(cwd, "sh-ui.config.json");
+  const corePath = await findUiCoreConfigPath(appConfigPath);
+  // 같은 파일을 가리키면 (이게 곧 ui-core) merge 불필요.
+  if (!corePath || corePath === appConfigPath) return config;
+  const coreConfig = await readShUiConfig(corePath);
+  if (!coreConfig?.theme) return config;
+  const mergedTheme = resolveThemeFromConfigs(coreConfig, config);
+  return { ...config, theme: mergedTheme };
 }
 
 async function loadCurrent(config, cwd) {
@@ -106,7 +124,7 @@ function renderDiffReport({ added, removed, changed, unchangedCount }, rel) {
 
 export async function runTokensDiff({ cwd }) {
   const config = await loadConfig(cwd);
-  const expectedText = await buildExpected(config);
+  const expectedText = await buildExpected(config, cwd);
   const { text: currentText, rel } = await loadCurrent(config, cwd);
   const diff =
     config.platform === "flutter"
@@ -117,7 +135,7 @@ export async function runTokensDiff({ cwd }) {
 
 export async function runTokensUpgrade({ cwd, mode }) {
   const config = await loadConfig(cwd);
-  const expectedText = await buildExpected(config);
+  const expectedText = await buildExpected(config, cwd);
   const current = await loadCurrent(config, cwd);
   const isFlutter = config.platform === "flutter";