sh-ui-cli 0.109.1 → 0.111.0

package/data/changelog/versions.json

@@ -2,6 +2,31 @@
   "$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",
+      "title": "create — inPlace 비파괴 머지 + .npmrc 템플릿 parity",
+      "type": "minor",
+      "highlights": [
+        "**`inPlace` 옵션 신규** — `sh_ui_create_project` 의 `inPlace` 인자 / `sh-ui create --in-place`. 기존 디렉토리를 삭제하지 않고 비파괴 머지 — 이미 있는 파일은 보존하고 없는 파일만 채운다. 커스터마이즈된 monorepo 루트(`CLAUDE.md`·`.gitignore` 등)와 `.git` 을 지키며 `apps/`·`packages/` 를 재생성할 때 사용. tmpdir 에 스캐폴드 후 `overwrite:false` 머지로 구현 — 전체 generator 파이프라인은 그대로, 마지막 머지만 비파괴.",
+        "**`.npmrc` 템플릿 parity 수정** — npm publish 가 패키지 tarball 에서 `.npmrc` 를 항상 strip(레지스트리 토큰 유출 방지)해, published CLI 의 monorepo 스캐폴드에 `.npmrc` 가 누락되던 버그. `describe_template` 은 정적 매니페스트 기준이라 계속 `.npmrc` 를 보고 → dry-run ↔ 실제 산출물 불일치. `gitignore` 와 동일 패턴으로 템플릿을 `npmrc`(점 없음)로 두고 `finalizeProject` 가 `.npmrc` 로 복원하도록 수정 (`STRIPPED_DOTFILES` 맵으로 일반화).",
+        "**CLI `--git-init`/`--locale` 전달 버그 수정** — 두 플래그를 파싱·검증만 하고 `createProject` 로 넘기지 않아 무시되던 문제. `--in-place` 와 함께 연결."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.110.0"
+    },
     {
       "version": "0.109.1",
       "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.109.1",
+  "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/cli-args.js

@@ -18,7 +18,7 @@ const VALUE_FLAGS = ['platform', 'structure', 'plugins', 'theme', 'app', 'css',
 // `locale` (단수) 은 한국어/일본어 같은 사용자 지역 디폴트 가정 (폰트 등) 을 활성화하는
 // 옵션. `locales` (복수) 와 다르다: locales 는 i18n 활성화 시 생성할 locale 코드 목록.
 const VALID_LOCALES = ['default', 'ko'];
-const BOOL_FLAGS = ['yes', 'help', 'dry-run', 'no-git-init', 'git-init'];
+const BOOL_FLAGS = ['yes', 'help', 'dry-run', 'no-git-init', 'git-init', 'in-place'];
 
 const SUBCOMMANDS = ['add-app', 'add-component'];
 
@@ -45,9 +45,11 @@ export const parseArgs = (argv) => {
     const name = arg.slice(2);
     if (BOOL_FLAGS.includes(name)) {
       // dry-run → dryRun. --no-git-init → gitInit:false. --git-init → gitInit:true.
+      // --in-place → inPlace:true (기존 디렉토리 비파괴 머지).
       if (name === 'dry-run') flags.dryRun = true;
       else if (name === 'no-git-init') flags.gitInit = false;
       else if (name === 'git-init') flags.gitInit = true;
+      else if (name === 'in-place') flags.inPlace = true;
       else flags[name] = true;
       continue;
     }

package/src/create/describeTemplate.js

@@ -375,18 +375,20 @@ function finalize(groups) {
  * generator.js 의 `finalizeProject` 가 실제 fs 단계에서 적용하는 rename 을
  * file plan 텍스트 레벨에서 mock-apply (v0.96.0+ — 피드백 #3 buglet).
  *
- * 현재 규칙:
- *  - basename 이 정확히 'gitignore' 인 경로 → '.gitignore' 로 prefix dot 추가.
- *    (npm publish 가 .gitignore 를 strip 하므로 템플릿엔 점 없이 두고 emit 후 dot-prefix.)
- *  - 이미 '.gitignore' 인 경로는 그대로.
+ * 현재 규칙 — npm publish 가 strip 하는 dotfile 의 점 없는 템플릿 이름을 복원:
+ *  - 'gitignore' → '.gitignore'  (npm 이 strip, generator 의 STRIPPED_DOTFILES 와 일치)
+ *  - 'npmrc'     → '.npmrc'      (npm 이 publish 시 항상 strip)
+ *  - 이미 점 붙은 경로는 그대로.
  *
- * 미래에 다른 fs-level rename 이 추가되면 여기에 같이 등록 (describeTemplate 의
- * file-plan ↔ create_project 의 실제 emit 1:1 정합성 유지).
+ * 미래에 다른 fs-level rename 이 추가되면 generator.js 의 STRIPPED_DOTFILES 와
+ * 함께 여기에 등록 (describeTemplate 의 file-plan ↔ create_project 실제 emit 1:1 정합성).
  */
+const STRIPPED_DOTFILES = { gitignore: '.gitignore', npmrc: '.npmrc' };
+
 function applyFinalizeRenames(p) {
   const slash = p.lastIndexOf('/');
   const dir = slash === -1 ? '' : p.slice(0, slash + 1);
   const base = slash === -1 ? p : p.slice(slash + 1);
-  if (base === 'gitignore') return dir + '.gitignore';
+  if (STRIPPED_DOTFILES[base]) return dir + STRIPPED_DOTFILES[base];
   return p;
 }

package/src/create/generator.js

@@ -290,19 +290,28 @@ export async function createProject(options = {}) {
     }
   }
 
-  // dry-run 은 tmpdir 에 그대로 생성한 뒤 파일 목록 출력 + 정리.
-  // 사용자 cwd 를 건드리지 않으면서 실제 generation 흐름을 그대로 검증한다.
+  // inPlace — 이미 커스터마이즈된 디렉토리(루트 docs·git 보존)에 비파괴 머지.
+  // generation 은 dry-run 과 동일하게 tmpdir 에서 돌린 뒤, 이미 있는 파일은
+  // 건드리지 않고 새 파일만 realTargetDir 로 복사한다.
+  const inPlace = options.inPlace === true && !options.dryRun;
+  const realTargetDir = path.resolve(process.cwd(), projectName);
+
+  // dry-run / inPlace 는 tmpdir 에 생성. dry-run 은 목록 출력 후 정리,
+  // inPlace 는 realTargetDir 로 비파괴 머지. 일반 모드는 cwd/name 에 직접 생성.
   const targetDir = options.dryRun
     ? await fs.mkdtemp(path.join(os.tmpdir(), 'sh-ui-dry-'))
-    : path.resolve(process.cwd(), projectName);
+    : inPlace
+      ? await fs.mkdtemp(path.join(os.tmpdir(), 'sh-ui-inplace-'))
+      : realTargetDir;
 
-  // 방어 가드 — projectName 검증을 이미 통과했어도 `fs.remove` 직전에 한 번 더 확인.
-  // dry-run 은 tmpdir 이라 parent 가 cwd 가 아니므로 스킵.
+  // 방어 가드 — projectName 검증을 이미 통과했어도 fs 쓰기 직전에 한 번 더 확인.
+  // dry-run / inPlace 의 targetDir 는 tmpdir 이므로 실제 목적지를 검증한다.
   if (!options.dryRun) {
-    assertWithin(process.cwd(), targetDir);
+    assertWithin(process.cwd(), realTargetDir);
   }
 
-  if (!options.dryRun && await fs.pathExists(targetDir)) {
+  // 일반 모드만 기존 디렉토리 덮어쓰기 확인. inPlace 는 비파괴라 remove 하지 않는다.
+  if (!options.dryRun && !inPlace && await fs.pathExists(targetDir)) {
     if (options.yes) {
       await fs.remove(targetDir);
     } else {
@@ -318,9 +327,29 @@ export async function createProject(options = {}) {
     }
   }
 
+  // finalizeProject + (inPlace 면) temp → realTargetDir 비파괴 머지.
+  // 세 플랫폼 경로(flutter/vite/next)가 공통으로 호출한다.
+  async function finalizeAndCommit() {
+    await finalizeProject(targetDir, {
+      dryRun: options.dryRun,
+      // inPlace 는 temp 에서 git init 해봐야 버려지므로 스킵 — realTargetDir 의
+      // 기존 .git 을 그대로 둔다 (gitignore/npmrc 복원은 finalize 안에서 수행됨).
+      gitInit: inPlace ? false : options.gitInit,
+      locale: options.locale,
+    });
+    if (inPlace) {
+      await fs.ensureDir(realTargetDir);
+      await fs.copy(targetDir, realTargetDir, { overwrite: false, errorOnExist: false });
+      await fs.remove(targetDir);
+      console.log(
+        `\n  ℹ inPlace — 기존 디렉토리에 비파괴 머지 완료 (이미 있는 파일은 보존).`,
+      );
+    }
+  }
+
   if (platform === 'flutter') {
     await generateFlutter(targetDir, projectName, theme, cssFramework, themeBase);
-    await finalizeProject(targetDir, { dryRun: options.dryRun, gitInit: options.gitInit, locale: options.locale });
+    await finalizeAndCommit();
     console.log(`\n✅ ${projectName} Flutter 프로젝트가 생성되었습니다!`);
     console.log(`\n  cd ${projectName}`);
     console.log('  flutter pub get');
@@ -355,7 +384,7 @@ export async function createProject(options = {}) {
       });
     }
 
-    await finalizeProject(targetDir, { dryRun: options.dryRun, gitInit: options.gitInit, locale: options.locale });
+    await finalizeAndCommit();
 
     if (options.dryRun) {
       const files = await listAllFiles(targetDir);
@@ -401,7 +430,7 @@ export async function createProject(options = {}) {
     });
   }
 
-  await finalizeProject(targetDir, { dryRun: options.dryRun, gitInit: options.gitInit, locale: options.locale });
+  await finalizeAndCommit();
 
   if (options.dryRun) {
     const files = await listAllFiles(targetDir);
@@ -575,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`);
@@ -1644,11 +1690,17 @@ async function stripTailwindFromPrettier(prettierPath) {
 }
 
 /**
- * 스캐폴드 마무리 — `gitignore` 파일을 `.gitignore` 로 되돌리고 `git init` 실행.
- *
- * 왜 이름을 우회하는가: npm publish 는 패키지 안의 `.gitignore` 를 자동으로
- * strip 한다(없으면 `.npmignore` fallback 으로 사용). 사용자에게 도착하지 않으니
- * 템플릿엔 `gitignore` 로 두고 복사 직후 dot-prefix 를 붙인다.
+ * npm publish 가 패키지 tarball 에서 strip/변형하는 dotfile 들 — 템플릿엔 점 없는
+ * 이름으로 두고 스캐폴드 직후 점을 복원한다.
+ *   - `.gitignore` → npm 이 strip (없으면 `.npmignore` fallback 으로 사용)
+ *   - `.npmrc`     → npm 이 항상 strip (publish 시 레지스트리 토큰 유출 방지)
+ * 둘 다 published CLI 엔 도착하지 않으므로 템플릿엔 `gitignore` / `npmrc` 로 둔다.
+ */
+const STRIPPED_DOTFILES = { gitignore: '.gitignore', npmrc: '.npmrc' };
+
+/**
+ * 스캐폴드 마무리 — strip 된 dotfile(`gitignore`/`npmrc`) 을 점 붙은 이름으로
+ * 되돌리고 `git init` 실행.
  *
  * gitInit 옵션:
  *   - undefined (auto): parent 가 이미 git tree 안이면 스킵, 아니면 init. nested .git
@@ -1659,9 +1711,9 @@ async function stripTailwindFromPrettier(prettierPath) {
  * git init 은 dry-run 에서는 스킵하고, 실패해도(git 미설치 등) 조용히 넘어간다.
  */
 async function finalizeProject(targetDir, { dryRun = false, gitInit, locale } = {}) {
-  // 모노레포 / sub-app 까지 모든 `gitignore` 를 `.gitignore` 로 rename.
+  // 모노레포 / sub-app 까지 strip 된 dotfile(gitignore/npmrc) 을 점 붙은 이름으로 복원.
   // root 만 처리하면 apps/<name>/gitignore 가 그대로 남아 node_modules/dist 가 staged 된다 (v0.93.0 버그).
-  await renameAllGitignoreRecursive(targetDir);
+  await restoreStrippedDotfilesRecursive(targetDir);
 
   // locale 후처리 — 한국어면 globals.css 들에 Pretendard 자동 적용 (Aifice 피드백 3.1).
   // dryRun 이면 skip — globals.css 가 디스크에 안 써졌을 수 있다.
@@ -1790,7 +1842,7 @@ function describeAppPlatform(platform) {
   return 'Next.js 앱 (App Router + Server Components). 라우트 + 비즈니스 로직.';
 }
 
-async function renameAllGitignoreRecursive(dir) {
+async function restoreStrippedDotfilesRecursive(dir) {
   let entries;
   try {
     entries = await fs.readdir(dir, { withFileTypes: true });
@@ -1802,9 +1854,9 @@ async function renameAllGitignoreRecursive(dir) {
     if (entry.isDirectory()) {
       // 스캐폴드 직후엔 node_modules / .git 가 없지만 방어적으로.
       if (entry.name === 'node_modules' || entry.name === '.git') continue;
-      await renameAllGitignoreRecursive(fullPath);
-    } else if (entry.name === 'gitignore') {
-      await fs.move(fullPath, path.join(dir, '.gitignore'), { overwrite: true });
+      await restoreStrippedDotfilesRecursive(fullPath);
+    } else if (STRIPPED_DOTFILES[entry.name]) {
+      await fs.move(fullPath, path.join(dir, STRIPPED_DOTFILES[entry.name]), { overwrite: true });
     }
   }
 }

package/src/create/index.mjs

@@ -32,6 +32,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
   --locales <ko,en>                  i18n 활성화 시 생성할 locale 코드 (comma-separated). 기본 'ko,en'
   --locale <default|ko>              사용자 지역 디폴트 가정 — 'ko' 선택 시 globals.css 에 Pretendard 자동 적용 (v0.103.0+)
   --yes                              디렉토리 덮어쓰기 + 모노레포 기본값 자동 채택
+  --in-place                         기존 디렉토리에 비파괴 머지 — 이미 있는 파일은 보존, 없는 파일만 채움. 커스텀 루트 docs·.git 보존하며 재생성 (디렉토리 삭제 안 함)
   --dry-run                          파일을 쓰지 않고 작성될 파일 목록만 출력
   --no-git-init                      git init 스킵 (기존 git tree 안에서 호출 시 nested .git 충돌 방지). 기본 auto — parent 가 git tree 안이면 자동 스킵
   --git-init                         git init 무조건 실행 (nested 가 의도된 경우)
@@ -105,6 +106,11 @@ export async function runCreate(rest) {
       port: flags.port,
       yes: flags.yes,
       dryRun: flags.dryRun,
+      // gitInit / locale / inPlace — 이전엔 파싱만 하고 createProject 로
+      // 전달하지 않아 무시되던 버그. v0.110.0 에서 함께 연결.
+      gitInit: flags.gitInit,
+      locale: flags.locale,
+      inPlace: flags.inPlace,
     });
   }
 }

package/src/create/templateManifest.js

@@ -17,11 +17,11 @@ export const TEMPLATE_MANIFEST = {
   "monorepo": {
     "base": [
       ".dockerignore",
-      ".npmrc",
       ".prettierrc",
       "CLAUDE.md",
       "README.md",
       "gitignore",
+      "npmrc",
       "package.json",
       "packages/eslint-config/base.js",
       "packages/eslint-config/flat.js",

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/mcp.mjs

@@ -488,7 +488,14 @@ export async function startMcpServer() {
         cwd: z.string().optional()
           .describe("부모 디렉토리. 기본 process.cwd()"),
         force: z.boolean().optional()
-          .describe("기존 디렉토리 덮어쓰기. 기본 false (안전)"),
+          .describe("기존 디렉토리 덮어쓰기 — 디렉토리 전체를 삭제 후 새로 스캐폴드. 기본 false (안전)."),
+        inPlace: z.boolean().optional()
+          .describe(
+            "기존 디렉토리에 비파괴 머지 — 디렉토리를 삭제하지 않고, 이미 있는 파일은 보존한 채 " +
+            "없는 파일만 채워 넣는다. 커스터마이즈된 monorepo 루트(CLAUDE.md·.gitignore 등)·.git 을 " +
+            "지키면서 apps/·packages/ 를 재생성할 때 사용. force 와 상호배타 — force 는 전체 삭제, " +
+            "inPlace 는 보존. 재생성하려는 파일은 미리 지워두면 그 자리만 새로 채워진다. v0.110.0+ 신규.",
+          ),
         i18n: z.enum(I18N_LIBRARIES).optional()
           .describe(
             "i18n 라이브러리 — platform=vite 일 때만 의미. 'react-i18next' 로 설정 시 i18next + react-i18next + browser-languagedetector + http-backend 셋업 + " +
@@ -549,15 +556,25 @@ export async function startMcpServer() {
           }],
         };
       }
+      if (input.force && input.inPlace) {
+        return {
+          isError: true,
+          content: [{
+            type: "text",
+            text: "force 와 inPlace 는 동시에 쓸 수 없습니다 — force 는 디렉토리 전체 삭제, inPlace 는 보존 머지.",
+          }],
+        };
+      }
       const targetParent = resolveCwd(input);
       const targetDir = resolve(targetParent, input.name);
-      if (existsSync(targetDir) && !input.force) {
+      // inPlace 는 기존 디렉토리를 전제로 하므로 '이미 존재' 가 에러가 아니다.
+      if (existsSync(targetDir) && !input.force && !input.inPlace) {
         return {
           isError: true,
           content: [
             {
               type: "text",
-              text: `'${targetDir}' 가 이미 존재합니다. 덮어쓰려면 force: true.`,
+              text: `'${targetDir}' 가 이미 존재합니다. 덮어쓰려면 force: true, 보존 머지하려면 inPlace: true.`,
             },
           ],
         };
@@ -580,6 +597,7 @@ export async function startMcpServer() {
             port: input.port,
             gitInit: input.gitInit,
             locale: input.locale,
+            inPlace: input.inPlace,
             yes: true, // 사전 검사를 마쳤으니 generator 의 confirm 프롬프트 우회
           }),
         );

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";
 

package/templates/monorepo/npmrc

@@ -0,0 +1,5 @@
+# pnpm 으로 워크스페이스 패키지의 peer dep 자동 설치 (host 가 아니라 패키지 자체).
+auto-install-peers=true
+
+# `pnpm install` 시 lock 의 strict-version 검사 활성. CI 와 로컬 일관성.
+strict-peer-dependencies=false