sh-ui-cli 0.65.0 → 0.67.0

package/bin/sh-ui.mjs

@@ -3,6 +3,7 @@ import { init } from "../src/init.mjs";
 import { add } from "../src/add.mjs";
 import { list } from "../src/list.mjs";
 import { remove } from "../src/remove.mjs";
+import { findShUiContext } from "../src/resolve-context.mjs";
 
 const [, , cmd, ...rest] = process.argv;
 
@@ -18,6 +19,8 @@ const usage = `사용법:
   sh-ui rename-app <old> <new>     monorepo 의 앱 이름 일괄 변경
                                    (apps/<old>/, packages/ui/ui-apps/ui-<old>/
                                    디렉토리 + 모든 import/path 패턴)
+  sh-ui migrate-v065               v0.64.x → v0.65 자동 마이그레이션
+                                   (--dry-run 기본, --apply 로 실제 적용)
   sh-ui mcp                        MCP 서버(stdio) 시작 — IDE-내 AI용
   sh-ui mcp init --client <name>   IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
                                    (claude-code | cursor | claude-desktop)
@@ -27,6 +30,8 @@ const usage = `사용법:
     --force                        (add) 기존 파일을 모두 덮어쓰기 (prompt 없음)
                                    (remove) 사용자가 수정한 파일도 삭제
     --keep                         (add) 기존 파일을 모두 유지 (prompt 없음)
+    --app <name>                   (add) monorepo 라우팅 시 대상 ui-{name} 명시
+                                   (apps/<name>/ 안에서 실행하면 자동 추론)
     --all                          (list) 설치되지 않은 컴포넌트까지 표시
     --dry-run                      (remove, rename-app) 변경 대상만 출력하고 실행 안 함
     --yes                          (rename-app) 대화형 확인 생략
@@ -52,13 +57,41 @@ try {
         process.exit(1);
       }
       const onConflict = force ? "overwrite" : keepFlag ? "keep" : "prompt";
-      const names = rest.filter((a) => !a.startsWith("--"));
+      // --app 은 모노레포 라우팅 시 ui-{app} 명시 (tokens 또는 v0.64.x fallback).
+      const appIdx = rest.indexOf("--app");
+      const app = appIdx !== -1 ? rest[appIdx + 1] : null;
+      const names = rest.filter((a, i) => !a.startsWith("--") && rest[i - 1] !== "--app");
       if (names.length === 0) {
         console.error("에러: 추가할 컴포넌트 이름이 필요합니다.\n");
         console.error(usage);
         process.exit(1);
       }
-      await add({ cwd: process.cwd(), names, skipInstall, diffMode, onConflict });
+
+      // v0.67+: cwd 부터 walk-up 으로 sh-ui.config.json (standalone/ui-core/ui-app)
+      // 또는 pnpm-workspace.yaml (monorepo 루트) 발견. monorepo 면 자동 라우팅 (tokens →
+      // ui-app, 그 외 → ui-core), apps/<name>/ 안에서 실행하면 그 앱이 hintApp.
+      const ctx = findShUiContext(process.cwd());
+      if (!ctx) {
+        console.error(
+          "✗ sh-ui.config.json 또는 pnpm-workspace.yaml 을 cwd 부터 부모 트리에서 찾지 못했습니다.\n" +
+            "  먼저 `sh-ui init` 또는 `sh-ui create` 로 프로젝트를 초기화하세요.",
+        );
+        process.exit(1);
+      }
+      if (ctx.kind === "config") {
+        await add({ cwd: ctx.root, names, skipInstall, diffMode, onConflict });
+      } else {
+        const { addComponent } = await import("../src/create/generator.js");
+        await addComponent({
+          cwd: ctx.root,
+          names,
+          app,
+          hintApp: ctx.hintApp,
+          skipInstall,
+          diffMode,
+          onConflict,
+        });
+      }
       break;
     }
     case "list": {
@@ -93,6 +126,18 @@ try {
       await renameApp({ cwd: process.cwd(), oldName, newName, yes, dryRun, skipInstall });
       break;
     }
+    case "migrate-v065": {
+      const apply = rest.includes("--apply");
+      const skipImportRewrite = rest.includes("--skip-import-rewrite");
+      const { migrateToV065 } = await import("../src/migrate-v065.mjs");
+      const { summary } = await migrateToV065({
+        cwd: process.cwd(),
+        dryRun: !apply,
+        skipImportRewrite,
+      });
+      console.log(summary);
+      break;
+    }
     case "remove":
     case "rm": {
       const force = rest.includes("--force");

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.67.0",
+      "date": "2026-05-09",
+      "title": "monorepo 어디서든 sh-ui add — walk-up 컨텍스트 라우팅",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui add` 가 monorepo 전 디렉토리에서 동작** — `apps/web/`, monorepo 루트, `packages/ui/ui-core/`, `packages/ui/ui-apps/ui-{name}/` 어디서든. cwd 부터 부모 트리 walk-up 으로 `sh-ui.config.json` (standalone) 또는 `pnpm-workspace.yaml` (monorepo 루트) 자동 발견.",
+        "**hintApp 자동 추출** — `apps/web/`에서 `sh-ui add tokens` 실행 시 자동으로 ui-web 으로 라우팅 (별도 `--app` 불필요). `apps/admin/` 에선 ui-admin. monorepo 루트면 prompt (TTY) 또는 모든 앱 (비대화형 + tokens).",
+        "**npx subprocess 제거** — orchestrator 가 inner `npx sh-ui add` 대신 `add()` 함수를 in-process 호출. sh-ui-cli 가 모노레포에 local 설치 안 돼도 동작.",
+        "**다중 컴포넌트 + tokens 혼합** — `sh-ui add button card tokens` 한 줄로 ui-core 와 ui-app 양쪽에 라우팅 (이름별 그룹화).",
+        "**`--app <name>` 플래그 신규 (sh-ui add)** — hintApp 자동 추론을 명시적으로 덮어쓸 때.",
+        "**호환** — `sh-ui create add-component <name>` 는 alias 로 유지. v0.65/v0.66 의 ui-core SoT 라우팅 그대로."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.67.0"
+    },
+    {
+      "version": "0.66.0",
+      "date": "2026-05-09",
+      "title": "monorepo: sh_ui_add_app MCP 툴 + sh_ui_migrate_to_v065 자동 마이그레이션",
+      "type": "minor",
+      "highlights": [
+        "**`sh_ui_add_app` MCP 툴 신규** — 기존 모노레포에 새 Next.js 앱 추가 (`apps/{name}/` + `packages/ui/ui-apps/ui-{name}/` 동시 생성). v0.65 ui-core/ui-app 분리 레이아웃 자동 준수, theme/css 인자로 새 앱 별 톤/프레임워크 지정 가능. CLI 진입점 `sh-ui create add-app [name] [--port/--plugins/--theme/--css]` 도 동시 확장.",
+        "**`sh_ui_migrate_to_v065` 자동 마이그레이션** — v0.64.x → v0.65 monorepo 컴포넌트 통합 도구. ui-{app}/src/{components,hooks,lib}/ 의 파일을 ui-core 단일 SoT 로 이동, ui-app 에 `role: \"tokens-only\"` 마커 + paths/aliases/exports 정리, `apps/*` 의 `@workspace/ui-{app}/(components|hooks|lib)/` 임포트를 `@workspace/ui-core/...` 로 일괄 재작성. dryRun 기본, 컨텐츠 충돌 시 abort (자동 병합 안 함).",
+        "**`apps/docs/migrations/v0.65.md`** — 자동 도구 사용법 + 충돌 해결 가이드 + 수동 마이그레이션 6 단계 + 호환성 노트.",
+        "**addApp 옵션 객체 시그니처** — `addApp({ name, port, plugins, theme, css, cwd })`. 비대화형 (MCP daemon, CI) 지원 + 새 ui-app 의 tokens.css 에 theme 주입까지 createProject 흐름과 통일."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.66.0"
+    },
     {
       "version": "0.65.0",
       "date": "2026-05-09",

package/package.json

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

package/src/create/cli-args.js

@@ -12,7 +12,7 @@ const VALID_STRUCTURES = CREATE_STRUCTURES;
 const VALID_PLUGINS = allPlugins.map((p) => p.name);
 const VALID_ARCHES = allArchitectures.map((a) => a.name);
 
-const VALUE_FLAGS = ['platform', 'structure', 'plugins', 'theme', 'app', 'css', 'arch'];
+const VALUE_FLAGS = ['platform', 'structure', 'plugins', 'theme', 'app', 'css', 'arch', 'port'];
 const BOOL_FLAGS = ['yes', 'help', 'dry-run'];
 
 const SUBCOMMANDS = ['add-app', 'add-component'];

package/src/create/generator.js

@@ -337,47 +337,84 @@ async function listAllFiles(targetDir) {
 
 // ─── Add app to existing monorepo ───
 
-export async function addApp() {
-  const isMonorepo = await fs.pathExists(
-    path.resolve(process.cwd(), 'pnpm-workspace.yaml'),
-  );
+/**
+ * 기존 monorepo 에 새 Next.js 앱 추가 — apps/{name}/ + packages/ui/ui-apps/ui-{name}/ 동시 생성.
+ *
+ * 옵션 객체 시그니처 (v0.66+) — MCP `sh_ui_add_app` 와 CLI `sh-ui add-app` 모두 같은 진입점.
+ * 미지정 옵션은 TTY 면 prompt, 비대화형(MCP/CI)이면 기본값 또는 에러.
+ *
+ * 산출물: apps/{name}/ (Next.js + arch overlay) + packages/ui/ui-apps/ui-{name}/ (tokens-only,
+ * v0.65 layout) — theme 인자 주면 ui-app 의 tokens.css 에 주입, css 인자는 컴포넌트 변종 결정.
+ */
+export async function addApp(options = {}) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const isMonorepo = await fs.pathExists(path.resolve(cwd, 'pnpm-workspace.yaml'));
   if (!isMonorepo) {
-    console.log('❌ 현재 디렉토리가 모노레포가 아닙니다. pnpm-workspace.yaml이 없습니다.');
+    const msg = '현재 디렉토리가 모노레포가 아닙니다. pnpm-workspace.yaml 이 없습니다.';
+    if (!process.stdin.isTTY) throw new Error(msg);
+    console.log(`❌ ${msg}`);
     return;
   }
 
-  const appName = await input({
+  // 비대화형 (MCP daemon, CI) 가드 — name 만 필수. port/plugins 는 기본값.
+  if (!process.stdin.isTTY && !options.name) {
+    throw new Error('비대화형 환경(TTY 없음)에서는 name 이 필요합니다.');
+  }
+
+  const appName = options.name ?? await input({
     message: '앱 이름:',
     default: 'web',
   });
 
-  const port = await input({
-    message: '포트 번호:',
-    default: '3000',
-  });
-
-  const selectedPlugins = await checkbox({
-    message: '추가 기능 선택 (Space로 선택):',
-    choices: getPluginChoices(),
-  });
-
-  const plugins = getPluginsByNames(selectedPlugins);
+  const port = options.port ?? (process.stdin.isTTY
+    ? await input({ message: '포트 번호:', default: '3000' })
+    : '3000');
+
+  let plugins;
+  if (options.plugins) {
+    plugins = getPluginsByNames(options.plugins);
+  } else if (process.stdin.isTTY) {
+    const selected = await checkbox({
+      message: '추가 기능 선택 (Space로 선택):',
+      choices: getPluginChoices(),
+    });
+    plugins = getPluginsByNames(selected);
+  } else {
+    plugins = [];
+  }
   plugins.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
 
-  const appsDir = path.resolve(process.cwd(), 'apps', appName);
+  // theme/css resolve — createProject 와 같은 패턴.
+  let theme = null;
+  let themeBase = null;
+  if (options.theme) {
+    theme = resolveTheme(options.theme);
+    themeBase = THEME_PRESET_NAMES.includes(options.theme) ? options.theme : 'custom';
+  }
+  const css = options.css ?? CSS_FRAMEWORK_DEFAULT;
 
+  const appsDir = path.resolve(cwd, 'apps', appName);
   if (await fs.pathExists(appsDir)) {
-    console.log(`❌ apps/${appName} 디렉토리가 이미 존재합니다.`);
+    const msg = `apps/${appName} 디렉토리가 이미 존재합니다.`;
+    if (!process.stdin.isTTY) throw new Error(msg);
+    console.log(`❌ ${msg}`);
     return;
   }
 
-  // addApp 은 기존 monorepo 의 새 앱 추가 — arch 는 일관성을 위해 모노레포가 처음
-  // 만들어질 때 정한 값과 같아야 한다. 현재는 root sh-ui.config.json 등에 별도 저장
-  // 안 해 두므로 일단 DEFAULT_ARCH (fsd) 로 fallback. 향후 root config 에 arch 박아두고
-  // 여기서 읽어오는 흐름으로 개선 가능.
+  // arch 는 모노레포가 처음 만들어질 때 정한 값과 같아야 한다. root config 에 별도
+  // 저장 안 해 두므로 일단 DEFAULT_ARCH (fsd) fallback. 향후 root config 에 arch
+  // 박아두고 여기서 읽어오는 흐름으로 개선 가능.
   const arch = assertArchPlatformCompat(DEFAULT_ARCH, 'next');
 
-  await generateApp(appsDir, appName, port, plugins, arch);
+  await generateApp(appsDir, appName, port, plugins, arch, css);
+
+  // monorepo 의 새 ui-app 패키지 — tokens-only role + theme 주입 + cssFramework 패치.
+  // generateMonorepo 의 흐름과 정확히 동일.
+  const uiAppDir = path.resolve(cwd, 'packages', 'ui', 'ui-apps', `ui-${appName}`);
+  if (theme) {
+    await injectCssTheme(uiAppDir, theme);
+  }
+  await patchShUiConfig(path.join(uiAppDir, 'sh-ui.config.json'), css, themeBase);
 
   console.log(`\n✅ apps/${appName} 이 추가되었습니다!`);
   console.log('\n  pnpm install');
@@ -386,108 +423,163 @@ export async function addApp() {
 
 // ─── Add component to ui packages ───
 
-export async function addComponent(componentName, appName) {
-  const cwd = process.cwd();
-  const isMonorepo = await fs.pathExists(path.join(cwd, 'pnpm-workspace.yaml'));
+/**
+ * 컴포넌트/토큰 추가 오케스트레이터 — monorepo 의 어느 디렉토리에서든 의도대로 라우팅.
+ *
+ * **v0.67+ 시그니처**: 옵션 객체 받음. `bin/sh-ui.mjs` 가 walk-up 으로 monorepo 루트를 찾아
+ * 호출하고, `add()` 를 in-process 로 호출 (npx subprocess 없음 — 외부 sh-ui-cli 설치 의존 X).
+ *
+ * 라우팅 (monorepo, v0.65+):
+ *   - `tokens` → `packages/ui/ui-apps/ui-{hintApp 또는 app 또는 prompt 또는 단일}`
+ *   - 그 외(컴포넌트/훅/lib) → `packages/ui/ui-core` 단일 SoT
+ *
+ * v0.64.x 호환: ui-core/sh-ui.config.json 부재 시 모든 add 는 ui-apps/ui-{app} 으로 폴백.
+ *
+ * @param {Object} options
+ * @param {string} [options.cwd]                  monorepo 루트. 기본 process.cwd()
+ * @param {string[]} options.names                추가할 이름들 (예: ['button', 'tokens'])
+ * @param {string|null} [options.app]             명시적 --app 플래그 (있으면 hintApp 무시)
+ * @param {string|null} [options.hintApp]         walk-up 결과의 힌트 (apps/web → 'web')
+ * @param {boolean} [options.skipInstall]
+ * @param {boolean} [options.diffMode]
+ * @param {string} [options.onConflict]           'prompt' | 'keep' | 'overwrite'
+ */
+export async function addComponent(options = {}) {
+  const { add } = await import('../add.mjs');
+
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const names = (options.names ?? []).filter(Boolean);
+  const app = options.app ?? null;
+  const hintApp = options.hintApp ?? null;
+  const skipInstall = options.skipInstall === true;
+  const diffMode = options.diffMode === true;
+  const onConflict = options.onConflict ?? 'prompt';
+
+  if (names.length === 0) {
+    if (!process.stdin.isTTY) {
+      throw new Error('비대화형 환경(TTY 없음)에서는 추가할 이름이 필요합니다.');
+    }
+    const single = await input({ message: '컴포넌트 이름:' });
+    names.push(single);
+  }
 
+  const isMonorepo = await fs.pathExists(path.join(cwd, 'pnpm-workspace.yaml'));
   if (!isMonorepo) {
-    // Standalone: 현재 디렉토리에서 바로 실행
-    if (!componentName) {
-      componentName = await input({ message: '컴포넌트 이름:' });
-    }
-    console.log(`\n📦 sh-ui 컴포넌트 추가: ${componentName}`);
-    execSync(`npx sh-ui add ${componentName}`, { cwd, stdio: 'inherit' });
-    console.log(`\n✅ ${componentName} 추가 완료!`);
+    // Standalone: cwd 자체가 sh-ui.config.json 보유 — 그대로 add 호출.
+    await add({ cwd, names, skipInstall, diffMode, onConflict });
     return;
   }
 
-  // Monorepo (v0.65+): tokens 는 packages/ui/ui-apps/ui-{app} 으로, 그 외 컴포넌트/훅은
-  // packages/ui/ui-core 단일 SoT 로 라우팅. 컴포넌트 중복 emit 제거가 v0.65 의 핵심.
-  // v0.64.x 호환: ui-core/sh-ui.config.json 미존재 시 (구 모노레포 레이아웃) 기존 ui-apps
-  //   직접 라우팅 분기로 내려감.
   const uiCoreDir = path.join(cwd, 'packages', 'ui', 'ui-core');
   const uiAppsDir = path.join(cwd, 'packages', 'ui', 'ui-apps');
   const hasUiCore = await fs.pathExists(path.join(uiCoreDir, 'sh-ui.config.json'));
   const hasUiApps = await fs.pathExists(uiAppsDir);
 
   if (!hasUiCore && !hasUiApps) {
-    console.log('❌ packages/ui/ui-core 또는 packages/ui/ui-apps/ 디렉토리가 없습니다.');
-    return;
+    throw new Error('packages/ui/ui-core 또는 packages/ui/ui-apps/ 디렉토리가 없습니다.');
   }
 
-  if (!componentName) {
-    componentName = await input({ message: '컴포넌트 이름:' });
-  }
+  // 이름을 라우팅 그룹별로 분리: tokens → ui-app, 그 외 → ui-core.
+  const tokenNames = names.filter((n) => n === 'tokens');
+  const componentNames = names.filter((n) => n !== 'tokens');
 
-  const isTokens = componentName === 'tokens';
+  // ─── 비-tokens → ui-core (또는 v0.64.x fallback 시 ui-apps) ───
+  if (componentNames.length > 0) {
+    if (hasUiCore) {
+      if (app) {
+        console.log(
+          `ℹ️  v0.65+ 에서 컴포넌트는 packages/ui/ui-core 에 단일 emit (--app ${app} 무시).`,
+        );
+      }
+      console.log(`\n📦 packages/ui/ui-core ← ${componentNames.join(', ')}`);
+      await add({ cwd: uiCoreDir, names: componentNames, skipInstall, diffMode, onConflict });
+    } else {
+      // v0.64.x 호환: ui-core 없으니 모든 ui-app 에 컴포넌트 직접 emit (구 동작).
+      const targets = await pickUiAppTargets({ uiAppsDir, app, hintApp, kind: 'component' });
+      for (const pkg of targets) {
+        const pkgDir = path.join(uiAppsDir, pkg);
+        console.log(`\n📦 packages/ui/ui-apps/${pkg} ← ${componentNames.join(', ')}`);
+        await add({ cwd: pkgDir, names: componentNames, skipInstall, diffMode, onConflict });
+      }
+    }
+  }
 
-  // ─── 비-tokens (컴포넌트/훅/lib) → ui-core 단일 라우팅 ───
-  if (!isTokens && hasUiCore) {
-    if (appName) {
-      console.log(
-        `ℹ️  v0.65+ 에서 컴포넌트는 packages/ui/ui-core 에 단일 emit 됩니다 (--app ${appName} 무시).`,
-      );
+  // ─── tokens → ui-app(s) ───
+  if (tokenNames.length > 0) {
+    if (!hasUiApps) {
+      throw new Error('tokens 추가에는 packages/ui/ui-apps/ 가 필요합니다.');
     }
-    console.log(`\n📦 packages/ui/ui-core 에 ${componentName} 추가 중...`);
-    try {
-      execSync(`npx sh-ui add ${componentName}`, { cwd: uiCoreDir, stdio: 'inherit' });
-      console.log(`✅ packages/ui/ui-core 완료`);
-    } catch (error) {
-      console.log(`❌ packages/ui/ui-core 실패: ${error.message}`);
+    const targets = await pickUiAppTargets({ uiAppsDir, app, hintApp, kind: 'tokens' });
+    for (const pkg of targets) {
+      const pkgDir = path.join(uiAppsDir, pkg);
+      console.log(`\n📦 packages/ui/ui-apps/${pkg} ← tokens`);
+      await add({ cwd: pkgDir, names: tokenNames, skipInstall, diffMode, onConflict });
     }
-    return;
   }
 
-  // ─── tokens → ui-apps/ui-{app}(s), 또는 v0.64.x 호환 fallback (ui-core 없음) ───
-  if (!hasUiApps) {
-    console.log('❌ packages/ui/ui-apps/ 디렉토리가 없습니다.');
-    return;
-  }
+  console.log('\n✅ 추가 완료');
+}
 
+/**
+ * monorepo 의 ui-app 패키지 후보를 정해 1+ 개 반환.
+ *
+ * 우선순위:
+ *   1. 명시적 `--app` 플래그
+ *   2. walk-up 결과의 hintApp (apps/<name>/ 또는 ui-apps/ui-<name>/ 컨텍스트)
+ *   3. 단일 ui-app 만 존재 → 자동 선택
+ *   4. TTY → 사용자에게 select prompt
+ *   5. 비대화형 + 다중 ui-app → tokens 는 'all', 컴포넌트(v0.64.x fallback)는 throw
+ */
+async function pickUiAppTargets({ uiAppsDir, app, hintApp, kind }) {
   const entries = await fs.readdir(uiAppsDir, { withFileTypes: true });
   const uiPackages = entries
     .filter((e) => e.isDirectory() && e.name.startsWith('ui-') && e.name !== 'ui-app-template')
     .map((e) => e.name);
 
   if (uiPackages.length === 0) {
-    console.log('❌ ui-* 패키지가 없습니다.');
-    return;
+    throw new Error('packages/ui/ui-apps/ui-* 패키지가 없습니다.');
   }
 
-  let targets;
-  if (appName) {
-    const pkgName = `ui-${appName}`;
+  if (app) {
+    const pkgName = `ui-${app}`;
     if (!uiPackages.includes(pkgName)) {
-      console.log(`❌ packages/ui/ui-apps/${pkgName} 이 존재하지 않습니다.`);
-      console.log(`   사용 가능: ${uiPackages.join(', ')}`);
-      return;
+      throw new Error(
+        `packages/ui/ui-apps/${pkgName} 이 존재하지 않습니다. 사용 가능: ${uiPackages.join(', ')}`,
+      );
     }
-    targets = [pkgName];
-  } else if (uiPackages.length === 1) {
-    targets = uiPackages;
-  } else {
-    const choice = await select({
-      message: isTokens ? '어느 ui 패키지에 토큰을 추가할까요?' : '어디에 추가할까요?',
-      choices: [
-        { name: '모든 ui 패키지', value: 'all' },
-        ...uiPackages.map((name) => ({ name: `packages/ui/ui-apps/${name}`, value: name })),
-      ],
-    });
-    targets = choice === 'all' ? uiPackages : [choice];
+    return [pkgName];
   }
 
-  for (const pkg of targets) {
-    const pkgDir = path.join(uiAppsDir, pkg);
-    console.log(`\n📦 packages/ui/ui-apps/${pkg}에 ${componentName} 추가 중...`);
-    try {
-      execSync(`npx sh-ui add ${componentName}`, { cwd: pkgDir, stdio: 'inherit' });
-      console.log(`✅ packages/ui/ui-apps/${pkg} 완료`);
-    } catch (error) {
-      console.log(`❌ packages/ui/ui-apps/${pkg} 실패: ${error.message}`);
+  if (hintApp) {
+    const pkgName = `ui-${hintApp}`;
+    if (uiPackages.includes(pkgName)) {
+      return [pkgName];
+    }
+    // hintApp 이 가리키는 앱의 ui-패키지가 없으면 일반 흐름으로 떨어짐 (드문 케이스).
+  }
+
+  if (uiPackages.length === 1) {
+    return uiPackages;
+  }
+
+  if (!process.stdin.isTTY) {
+    if (kind === 'tokens') {
+      // 비대화형 + 다중 ui-app + tokens: 모든 앱에 적용 (가장 안전한 기본값).
+      return uiPackages;
     }
+    throw new Error(
+      `여러 ui-app 후보 (${uiPackages.join(', ')}) — 비대화형 환경에서는 --app 으로 명시하세요.`,
+    );
   }
 
-  console.log('\n✅ 컴포넌트 추가 완료!');
+  const choice = await select({
+    message: kind === 'tokens' ? '어느 ui 패키지에 토큰을 추가할까요?' : '어디에 추가할까요?',
+    choices: [
+      { name: '모든 ui 패키지', value: 'all' },
+      ...uiPackages.map((name) => ({ name: `packages/ui/ui-apps/${name}`, value: name })),
+    ],
+  });
+  return choice === 'all' ? uiPackages : [choice];
 }
 
 // ─── Generators ───

package/src/create/index.mjs

@@ -18,7 +18,7 @@ export const HELP_TEXT = `sh-ui create — sh-ui 프로젝트 스캐폴드 (Next
 
 사용법:
   sh-ui create [name] [options]
-  sh-ui create add-app
+  sh-ui create add-app [name] [--port <n>] [--plugins ..] [--theme ..] [--css ..]
   sh-ui create add-component <name> [--app <name>]
 
 옵션:
@@ -67,9 +67,19 @@ export async function runCreate(rest) {
   }
 
   if (command === 'add-app') {
-    await addApp();
+    await addApp({
+      name: positional[0],
+      port: flags.port,
+      plugins: flags.plugins,
+      theme: flags.theme,
+      css: flags.css,
+    });
   } else if (command === 'add-component') {
-    await addComponent(positional[0], flags.app);
+    // 호환 별칭 — 신규 진입점은 `sh-ui add <name>` (bin/sh-ui.mjs 가 walk-up 으로 라우팅).
+    await addComponent({
+      names: positional.filter(Boolean),
+      app: flags.app ?? null,
+    });
   } else {
     await createProject({
       name: positional[0],

package/src/mcp.mjs

@@ -7,6 +7,7 @@
 // 노출 툴:
 //   sh_ui_describe_init    - init 4개 축(platform/base/radius/mode) enum + 한글 설명
 //   sh_ui_create_project   - 빈 폴더에 Next.js/Flutter 프로젝트 스캐폴드
+//   sh_ui_add_app          - 기존 모노레포에 새 Next.js 앱 추가
 //   sh_ui_init             - sh-ui.config.json 생성 (비대화형)
 //   sh_ui_list_components  - 플랫폼 전체 컴포넌트 + 요약
 //   sh_ui_get_component    - 단일 컴포넌트의 메타·소스·deps
@@ -16,6 +17,7 @@
 //   sh_ui_encode_theme     - 토큰 객체 → base64 (사용자가 손본 톤을 영구 보관)
 //   sh_ui_decode_theme     - base64 → 토큰 객체 (기존 테마 일부만 수정 후 재인코딩)
 //   sh_ui_rename_app       - monorepo 의 앱 이름 일괄 변경 (디렉토리 + import/path)
+//   sh_ui_migrate_to_v065  - v0.64.x → v0.65 자동 마이그레이션 (컴포넌트 ui-core 단일화)
 
 import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -29,7 +31,8 @@ import { add } from "./add.mjs";
 import { list } from "./list.mjs";
 import { remove } from "./remove.mjs";
 import { renameApp } from "./rename-app.mjs";
-import { createProject } from "./create/generator.js";
+import { migrateToV065 } from "./migrate-v065.mjs";
+import { createProject, addApp } from "./create/generator.js";
 import {
   getRegistryRoot,
   getSummariesPath,
@@ -325,6 +328,44 @@ export async function startMcpServer() {
     },
   );
 
+  server.registerTool(
+    "sh_ui_add_app",
+    {
+      description:
+        "기존 모노레포에 새 Next.js 앱 추가 — apps/{name}/ + packages/ui/ui-apps/ui-{name}/ 동시 생성. " +
+        "사용자가 '앱 추가' / 'monorepo 에 새 앱' / 'add admin app' 류 요청을 하면 이 툴 사용 (Bash 로 npx " + cliName + " add-app 직접 호출보다 우선). " +
+        "v0.65+ 레이아웃 준수 — ui-{name} 은 tokens-only role, 컴포넌트는 sibling ui-core 가 SoT. " +
+        "theme/css 는 새 ui-app 에만 적용 (다른 앱 영향 없음). monorepo 가 아니면 (pnpm-workspace.yaml 없음) 에러.",
+      inputSchema: {
+        name: z.string().min(1)
+          .describe("앱 이름 — apps/{name}/ + packages/ui/ui-apps/ui-{name}/ 디렉토리명. 영숫자 + 하이픈."),
+        port: z.string().optional()
+          .describe("개발 서버 포트. 기본 3000. 다른 앱과 겹치면 사용자가 직접 다르게 지정."),
+        plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
+          .describe(`Next.js 플러그인 (${PLUGIN_NAMES.join(', ')}). 미지정시 빈 배열`),
+        theme: z.string().optional()
+          .describe(`프리셋 이름 (${THEME_PRESETS_LIST}) 또는 base64 테마 코드. 새 ui-app 의 tokens.css 에만 주입.`),
+        cssFramework: z.enum(CSS_FRAMEWORKS).optional()
+          .describe("CSS 프레임워크. 기본 plain. 새 앱의 컴포넌트 변종 결정 — 같은 모노레포 내 다른 앱과 다른 값 가능."),
+        cwd: z.string().optional()
+          .describe("모노레포 루트 (pnpm-workspace.yaml 있는 곳). 기본 process.cwd()"),
+      },
+    },
+    async (input) => {
+      const text = await captureConsole(() =>
+        addApp({
+          name: input.name,
+          port: input.port,
+          plugins: input.plugins,
+          theme: input.theme,
+          css: input.cssFramework,
+          cwd: resolveCwd(input),
+        }),
+      );
+      return textResult(text || "✓ 앱 추가 완료");
+    },
+  );
+
   server.registerTool(
     "sh_ui_init",
     {
@@ -607,6 +648,37 @@ export async function startMcpServer() {
     },
   );
 
+  // v0.64.x → v0.65 monorepo 자동 마이그레이션.
+  server.registerTool(
+    "sh_ui_migrate_to_v065",
+    {
+      description:
+        "v0.64.x → v0.65 monorepo 자동 마이그레이션 — 컴포넌트/훅/lib 를 ui-{app} 들에서 ui-core 단일 SoT 로 통합 + ui-app 을 tokens-only role 로 정리 + apps/* 의 import (`@workspace/ui-{app}/components/...` → `@workspace/ui-core/...`) 재작성. " +
+        "**dryRun 기본 — 안전 우선**. 컨텐츠 충돌(같은 logical path 의 파일이 ui-app 마다 다른 내용) 검출 시 abort + 충돌 목록 반환 (자동 병합 안 함, 사용자가 손본 컴포넌트 보호). " +
+        "monorepo 전용 (pnpm-workspace.yaml + packages/ui/ui-apps 필요). 적용 후 사용자에게 `pnpm install` 안내 필수.",
+      inputSchema: {
+        cwd: z.string().optional().describe("monorepo 루트. 기본 process.cwd()"),
+        dryRun: z.boolean().optional().describe("plan 만 반환, 실제 변경 X. 기본 true (안전)"),
+        skipImportRewrite: z.boolean().optional().describe("apps/* import 재작성 생략. 기본 false"),
+      },
+    },
+    async (input) => {
+      try {
+        const { summary } = await migrateToV065({
+          cwd: resolveCwd(input),
+          dryRun: input.dryRun !== false,
+          skipImportRewrite: input.skipImportRewrite === true,
+        });
+        return textResult(summary);
+      } catch (e) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: e.message }],
+        };
+      }
+    },
+  );
+
   // 변경 내역 조회 — 보너스: 사용자가 "최근 변경 알려줘" 류 요청 시
   server.registerTool(
     "sh_ui_get_changelog",

package/src/migrate-v065.mjs

@@ -0,0 +1,431 @@
+// v0.64.x → v0.65 monorepo 마이그레이션 도구.
+//
+// v0.64.x 레이아웃: 컴포넌트가 packages/ui/ui-apps/ui-{app}/src/components/ 에 emit.
+//                  같은 모노레포 내 N 개 앱이면 같은 컴포넌트가 N 번 복제됨.
+// v0.65 레이아웃:  컴포넌트는 packages/ui/ui-core/src/components/ 단일 SoT.
+//                  ui-{app} 은 tokens-only role (토큰/스타일만).
+//
+// 안전 원칙:
+//  - dryRun 기본 — 실제 파일 변경은 명시적 dryRun=false 시에만.
+//  - 컨텐츠 충돌 시 즉시 abort — 자동 병합 시도하지 않음 (사용자가 손본 컴포넌트 보호).
+//  - import 재작성은 정확한 패턴 (`@workspace/ui-{app}/{kind}/`) 만 — false-positive 차단.
+
+import * as fsp from "node:fs/promises";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+const COMPONENT_KINDS = ["components", "hooks", "lib"];
+
+async function fileExists(p) {
+  try {
+    await fsp.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function listFilesRecursive(dir) {
+  const out = [];
+  async function walk(d) {
+    const entries = await fsp.readdir(d, { withFileTypes: true });
+    for (const e of entries) {
+      const full = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (e.name === "node_modules" || e.name === ".next" || e.name === "dist") continue;
+        await walk(full);
+      } else if (e.isFile()) {
+        out.push(full);
+      }
+    }
+  }
+  await walk(dir);
+  return out;
+}
+
+function hashContent(s) {
+  return createHash("sha256").update(s).digest("hex").slice(0, 12);
+}
+
+/**
+ * 마이그레이션 plan 빌드 + (옵션) 적용.
+ *
+ * @param {Object} options
+ * @param {string} [options.cwd]                — monorepo 루트. 기본 process.cwd().
+ * @param {boolean} [options.dryRun=true]       — true 면 plan 텍스트 반환, false 면 실제 적용.
+ * @param {boolean} [options.skipImportRewrite] — apps/* 의 import 재작성 생략. 기본 false.
+ * @returns {Promise<{plan: object, summary: string}>}
+ */
+export async function migrateToV065(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const dryRun = options.dryRun !== false; // 기본 true (안전)
+  const skipImportRewrite = options.skipImportRewrite === true;
+
+  // ─── 1. 사전 검사 ───
+  if (!(await fileExists(path.join(cwd, "pnpm-workspace.yaml")))) {
+    throw new Error(
+      "pnpm-workspace.yaml 없음 — 모노레포가 아닙니다. v0.65 마이그레이션은 monorepo 변종에만 적용됩니다.",
+    );
+  }
+
+  const uiAppsDir = path.join(cwd, "packages", "ui", "ui-apps");
+  if (!(await fileExists(uiAppsDir))) {
+    throw new Error(
+      "packages/ui/ui-apps/ 없음 — v0.64.x monorepo 레이아웃이 아니거나 이미 마이그레이션됨.",
+    );
+  }
+
+  const uiPackages = (await fsp.readdir(uiAppsDir, { withFileTypes: true }))
+    .filter((e) => e.isDirectory() && e.name.startsWith("ui-") && e.name !== "ui-app-template")
+    .map((e) => e.name);
+
+  if (uiPackages.length === 0) {
+    throw new Error("packages/ui/ui-apps/ui-* 패키지 없음.");
+  }
+
+  const uiCoreDir = path.join(cwd, "packages", "ui", "ui-core");
+  const uiCoreCfgPath = path.join(uiCoreDir, "sh-ui.config.json");
+  const uiCoreAlreadyV065 = await fileExists(uiCoreCfgPath);
+
+  // ─── 2. 파일 수집 + 충돌 검출 ───
+  // logicalPath ('src/components/button/index.tsx') → [{app, srcPath, hash, content}]
+  const fileMap = new Map();
+  for (const pkg of uiPackages) {
+    const pkgDir = path.join(uiAppsDir, pkg);
+    for (const kind of COMPONENT_KINDS) {
+      const subDir = path.join(pkgDir, "src", kind);
+      if (!(await fileExists(subDir))) continue;
+      const files = await listFilesRecursive(subDir);
+      for (const file of files) {
+        const rel = path.relative(subDir, file);
+        if (rel === ".gitkeep" || rel.startsWith(".gitkeep")) continue;
+        const content = await fsp.readFile(file, "utf-8");
+        const hash = hashContent(content);
+        const logicalPath = path.posix.join("src", kind, ...rel.split(path.sep));
+        const list = fileMap.get(logicalPath) ?? [];
+        list.push({ app: pkg, srcPath: file, hash, content });
+        fileMap.set(logicalPath, list);
+      }
+    }
+  }
+
+  // ui-core 에 같은 logical path 의 기존 파일이 있으면 충돌 검출 대상에 포함.
+  for (const [logicalPath, entries] of fileMap) {
+    const uiCorePath = path.join(uiCoreDir, logicalPath);
+    if (await fileExists(uiCorePath)) {
+      const existing = await fsp.readFile(uiCorePath, "utf-8");
+      const hash = hashContent(existing);
+      entries.push({ app: "ui-core (existing)", srcPath: uiCorePath, hash, content: existing });
+    }
+  }
+
+  const moves = [];
+  const conflicts = [];
+  for (const [logicalPath, entries] of fileMap) {
+    const uniqueHashes = [...new Set(entries.map((e) => e.hash))];
+    if (uniqueHashes.length > 1) {
+      conflicts.push({
+        logicalPath,
+        variants: entries.map((e) => ({ app: e.app, hash: e.hash })),
+      });
+    } else {
+      moves.push({
+        logicalPath,
+        sourceApps: entries
+          .filter((e) => e.app !== "ui-core (existing)")
+          .map((e) => e.app),
+        canonicalSrc: entries[0].srcPath,
+        dest: path.join(uiCoreDir, logicalPath),
+        alreadyInUiCore: entries.some((e) => e.app === "ui-core (existing)"),
+      });
+    }
+  }
+
+  // ─── 3. ui-app config / package.json 패치 plan ───
+  const appConfigPatches = [];
+  const appPackageJsonPatches = [];
+  for (const pkg of uiPackages) {
+    const cfgPath = path.join(uiAppsDir, pkg, "sh-ui.config.json");
+    if (await fileExists(cfgPath)) {
+      const cfg = JSON.parse(await fsp.readFile(cfgPath, "utf-8"));
+      if (cfg.role !== "tokens-only") {
+        appConfigPatches.push({ pkg, cfgPath });
+      }
+    }
+    const pkgJsonPath = path.join(uiAppsDir, pkg, "package.json");
+    if (await fileExists(pkgJsonPath)) {
+      const pkgJson = JSON.parse(await fsp.readFile(pkgJsonPath, "utf-8"));
+      const removeExports = ["./components/*", "./hooks/*", "./lib/*"]
+        .filter((k) => pkgJson.exports?.[k]);
+      if (removeExports.length > 0) {
+        appPackageJsonPatches.push({ pkg, pkgJsonPath, removeExports });
+      }
+    }
+  }
+
+  // ─── 4. apps/* import 재작성 plan ───
+  const importRewrites = [];
+  if (!skipImportRewrite) {
+    const appsDir = path.join(cwd, "apps");
+    if (await fileExists(appsDir)) {
+      const apps = (await fsp.readdir(appsDir, { withFileTypes: true }))
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name);
+      const tsExt = /\.(ts|tsx|mjs|js|jsx)$/;
+      const re = /@workspace\/ui-([a-zA-Z0-9-]+)\/(components|hooks|lib)\//g;
+      for (const app of apps) {
+        const appDir = path.join(appsDir, app);
+        const files = await listFilesRecursive(appDir);
+        for (const file of files) {
+          if (!tsExt.test(file)) continue;
+          const content = await fsp.readFile(file, "utf-8");
+          if (!content.includes("@workspace/ui-")) continue;
+          let count = 0;
+          const rewritten = content.replace(re, (match, appName) => {
+            if (appName === "core") return match; // already core
+            count++;
+            return match.replace(`@workspace/ui-${appName}/`, "@workspace/ui-core/");
+          });
+          if (count > 0) {
+            importRewrites.push({ file, count, rewritten });
+          }
+        }
+      }
+    }
+  }
+
+  const plan = {
+    uiCoreAlreadyV065,
+    uiPackages,
+    moves,
+    conflicts,
+    appConfigPatches,
+    appPackageJsonPatches,
+    importRewrites,
+  };
+
+  // ─── 5. 충돌 발생 시 abort ───
+  if (conflicts.length > 0) {
+    const summary = renderConflicts(conflicts);
+    const err = new Error(
+      `자동 마이그레이션 abort — ${conflicts.length} 개 파일에 컨텐츠 충돌.\n` +
+        `같은 logical path 의 파일이 ui-app 마다 다른 내용을 가지고 있습니다 (사용자가 손본 결과 가능성).\n` +
+        `수동으로 해결한 뒤 재실행하거나, 충돌 파일은 수동 이전.\n\n${summary}`,
+    );
+    err.conflicts = conflicts;
+    throw err;
+  }
+
+  // ─── 6. dryRun: plan 텍스트 반환 ───
+  if (dryRun) {
+    const summary = renderPlan(plan, cwd);
+    return { plan, summary };
+  }
+
+  // ─── 7. apply ───
+  await applyPlan(plan, { cwd, uiAppsDir, uiCoreDir });
+  return {
+    plan,
+    summary:
+      `✓ v0.65 마이그레이션 완료\n` +
+      `  ${moves.length} 파일 ui-core 로 이동\n` +
+      `  ${appConfigPatches.length} ui-app sh-ui.config.json 패치\n` +
+      `  ${appPackageJsonPatches.length} ui-app package.json 패치\n` +
+      `  ${importRewrites.length} apps/* 파일 import 재작성`,
+  };
+}
+
+function renderPlan(plan, cwd) {
+  const lines = [];
+  lines.push("[DRY RUN] v0.65 마이그레이션 plan — 실제 적용은 dryRun: false");
+  lines.push("");
+
+  if (!plan.uiCoreAlreadyV065) {
+    lines.push("◇ ui-core sh-ui.config.json 신규 생성 + package.json exports 추가");
+  } else {
+    lines.push("◇ ui-core 는 이미 v0.65 레이아웃 — 컴포넌트만 이동");
+  }
+  lines.push("");
+
+  if (plan.moves.length > 0) {
+    lines.push(`◇ 파일 이동 (${plan.moves.length}개) — N 개 ui-app 의 동일 컨텐츠 → ui-core 단일 SoT:`);
+    for (const m of plan.moves.slice(0, 30)) {
+      const sources = m.sourceApps.length > 0 ? m.sourceApps.join(", ") : "(이미 ui-core)";
+      lines.push(`    ${m.logicalPath}  ←  ${sources}${m.alreadyInUiCore ? " (ui-core 동일)" : ""}`);
+    }
+    if (plan.moves.length > 30) lines.push(`    ... +${plan.moves.length - 30} more`);
+    lines.push("");
+  }
+
+  if (plan.appConfigPatches.length > 0) {
+    lines.push(`◇ ui-app sh-ui.config.json 패치 (${plan.appConfigPatches.length}개):`);
+    for (const p of plan.appConfigPatches) {
+      lines.push(`    ${p.pkg}: role: "tokens-only" 추가, components/utils paths/aliases 제거`);
+    }
+    lines.push("");
+  }
+
+  if (plan.appPackageJsonPatches.length > 0) {
+    lines.push(`◇ ui-app package.json exports 정리 (${plan.appPackageJsonPatches.length}개):`);
+    for (const p of plan.appPackageJsonPatches) {
+      lines.push(`    ${p.pkg}: ${p.removeExports.join(", ")} 제거`);
+    }
+    lines.push("");
+  }
+
+  if (plan.importRewrites.length > 0) {
+    lines.push(`◇ apps/* import 재작성 (${plan.importRewrites.length}개 파일):`);
+    for (const r of plan.importRewrites.slice(0, 20)) {
+      lines.push(`    ${path.relative(cwd, r.file)}  (${r.count} 곳)`);
+    }
+    if (plan.importRewrites.length > 20) {
+      lines.push(`    ... +${plan.importRewrites.length - 20} more files`);
+    }
+    lines.push("");
+  }
+
+  if (
+    plan.moves.length === 0 &&
+    plan.appConfigPatches.length === 0 &&
+    plan.appPackageJsonPatches.length === 0 &&
+    plan.importRewrites.length === 0
+  ) {
+    lines.push("✓ 변경 사항 없음 — 이미 v0.65 레이아웃.");
+  } else {
+    lines.push("실제 적용: dryRun: false 로 재호출.");
+  }
+  return lines.join("\n");
+}
+
+function renderConflicts(conflicts) {
+  const lines = [];
+  for (const c of conflicts.slice(0, 15)) {
+    lines.push(`  ${c.logicalPath}`);
+    for (const v of c.variants) {
+      lines.push(`    ${v.app}: ${v.hash}`);
+    }
+  }
+  if (conflicts.length > 15) {
+    lines.push(`  ... +${conflicts.length - 15} more`);
+  }
+  return lines.join("\n");
+}
+
+async function applyPlan(plan, ctx) {
+  const { uiAppsDir, uiCoreDir } = ctx;
+
+  // 1. ui-core 디렉토리/configs 보장
+  await fsp.mkdir(uiCoreDir, { recursive: true });
+  await fsp.mkdir(path.join(uiCoreDir, "src", "components"), { recursive: true });
+  await fsp.mkdir(path.join(uiCoreDir, "src", "hooks"), { recursive: true });
+  await fsp.mkdir(path.join(uiCoreDir, "src", "lib"), { recursive: true });
+
+  if (!plan.uiCoreAlreadyV065) {
+    await ensureUiCoreConfig(uiCoreDir);
+    await ensureUiCorePackageJsonExports(uiCoreDir);
+  }
+
+  // 2. 파일 이동 — copy 후 source 삭제
+  for (const m of plan.moves) {
+    if (!m.alreadyInUiCore) {
+      await fsp.mkdir(path.dirname(m.dest), { recursive: true });
+      await fsp.copyFile(m.canonicalSrc, m.dest);
+    }
+    for (const app of m.sourceApps) {
+      const appSrc = path.join(uiAppsDir, app, m.logicalPath);
+      if (await fileExists(appSrc)) {
+        await fsp.rm(appSrc, { force: true });
+      }
+    }
+  }
+
+  // 3. ui-app sh-ui.config.json 패치 — role 추가, components/utils paths/aliases 제거
+  for (const p of plan.appConfigPatches) {
+    const cfg = JSON.parse(await fsp.readFile(p.cfgPath, "utf-8"));
+    cfg.role = "tokens-only";
+    if (cfg.paths) {
+      delete cfg.paths.components;
+      delete cfg.paths.hooks;
+      delete cfg.paths.utils;
+    }
+    if (cfg.aliases) {
+      delete cfg.aliases.components;
+      delete cfg.aliases.hooks;
+      delete cfg.aliases.utils;
+      delete cfg.aliases.ui;
+      if (Object.keys(cfg.aliases).length === 0) delete cfg.aliases;
+    }
+    // role 을 platform/cssFramework 직후로 이동시키기 위해 재구성.
+    const ordered = {};
+    if (cfg.platform != null) ordered.platform = cfg.platform;
+    if (cfg.cssFramework != null) ordered.cssFramework = cfg.cssFramework;
+    ordered.role = "tokens-only";
+    for (const [k, v] of Object.entries(cfg)) {
+      if (k === "platform" || k === "cssFramework" || k === "role") continue;
+      ordered[k] = v;
+    }
+    await fsp.writeFile(p.cfgPath, JSON.stringify(ordered, null, 2) + "\n");
+  }
+
+  // 4. ui-app package.json exports 정리
+  for (const p of plan.appPackageJsonPatches) {
+    const pkgJson = JSON.parse(await fsp.readFile(p.pkgJsonPath, "utf-8"));
+    if (pkgJson.exports) {
+      for (const k of p.removeExports) delete pkgJson.exports[k];
+    }
+    await fsp.writeFile(p.pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n");
+  }
+
+  // 5. apps/* import 재작성
+  for (const r of plan.importRewrites) {
+    await fsp.writeFile(r.file, r.rewritten);
+  }
+
+  // 6. 비어진 ui-app 의 src/components/, src/hooks/, src/lib/ 디렉토리 정리.
+  //    .gitkeep 남기지 않고 디렉토리 자체 제거 (v0.65 ui-app 은 styles 만).
+  for (const pkg of plan.uiPackages) {
+    for (const kind of COMPONENT_KINDS) {
+      const subDir = path.join(uiAppsDir, pkg, "src", kind);
+      if (!(await fileExists(subDir))) continue;
+      const remaining = await listFilesRecursive(subDir);
+      const allGitkeep = remaining.every((f) => path.basename(f) === ".gitkeep");
+      if (remaining.length === 0 || allGitkeep) {
+        await fsp.rm(subDir, { recursive: true, force: true });
+      }
+    }
+  }
+}
+
+async function ensureUiCoreConfig(uiCoreDir) {
+  const cfgPath = path.join(uiCoreDir, "sh-ui.config.json");
+  if (await fileExists(cfgPath)) return;
+  const cfg = {
+    platform: "react",
+    cssFramework: "plain",
+    paths: {
+      components: "src/components",
+      hooks: "src/hooks",
+      utils: "src/lib/utils.ts",
+    },
+    aliases: {
+      components: "@workspace/ui-core/components",
+      hooks: "@workspace/ui-core/hooks",
+      utils: "@workspace/ui-core/lib/utils",
+      ui: "@workspace/ui-core/components",
+    },
+  };
+  await fsp.writeFile(cfgPath, JSON.stringify(cfg, null, 2) + "\n");
+}
+
+async function ensureUiCorePackageJsonExports(uiCoreDir) {
+  const pkgJsonPath = path.join(uiCoreDir, "package.json");
+  if (!(await fileExists(pkgJsonPath))) return;
+  const pkgJson = JSON.parse(await fsp.readFile(pkgJsonPath, "utf-8"));
+  pkgJson.exports = {
+    "./components/*": "./src/components/*.tsx",
+    "./hooks/*": "./src/hooks/*.ts",
+    "./lib/*": "./src/lib/*.ts",
+    ...(pkgJson.exports ?? {}),
+  };
+  await fsp.writeFile(pkgJsonPath, JSON.stringify(pkgJson, null, 2) + "\n");
+}

package/src/resolve-context.mjs

@@ -0,0 +1,56 @@
+// sh-ui 의 동작 컨텍스트 해석 — `sh-ui add` 등이 cwd 부터 부모 트리를 walk up 해
+// **standalone (sh-ui.config.json 발견)** 또는 **monorepo (pnpm-workspace.yaml 발견)** 컨텍스트 결정.
+//
+// monorepo 에서 사용자가 어디서 명령을 실행했는지 (apps/web, packages/ui/ui-apps/ui-admin 등)
+// 까지 추출해 hintApp 으로 넘김 — `sh-ui add tokens` 가 어느 ui-app 으로 라우팅될지의 기본값.
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * @param {string} startDir - 검색 시작점 (보통 process.cwd())
+ * @returns {{kind: 'config', root: string} | {kind: 'monorepo', root: string, hintApp: string|null} | null}
+ */
+export function findShUiContext(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    if (existsSync(path.join(dir, "sh-ui.config.json"))) {
+      return { kind: "config", root: dir };
+    }
+    if (existsSync(path.join(dir, "pnpm-workspace.yaml"))) {
+      const hintApp = extractHintApp(dir, startDir);
+      return { kind: "monorepo", root: dir, hintApp };
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * monorepo 루트가 정해진 뒤 startDir 의 상대 경로에서 어느 앱 컨텍스트인지 추출.
+ *
+ * 매칭 패턴 (모노레포 루트 기준):
+ *   - `apps/<name>/...`                            → <name>
+ *   - `packages/ui/ui-apps/ui-<name>/...`          → <name>
+ *
+ * 그 외(루트 자체, packages/ui/ui-core 등)는 null — 호출자가 prompt 또는 fallback.
+ */
+function extractHintApp(monorepoRoot, startDir) {
+  const rel = path.relative(monorepoRoot, path.resolve(startDir));
+  if (!rel || rel.startsWith("..")) return null;
+  const parts = rel.split(path.sep);
+  if (parts[0] === "apps" && parts[1]) {
+    return parts[1];
+  }
+  if (
+    parts[0] === "packages" &&
+    parts[1] === "ui" &&
+    parts[2] === "ui-apps" &&
+    parts[3] &&
+    parts[3].startsWith("ui-")
+  ) {
+    return parts[3].slice(3);
+  }
+  return null;
+}