sh-ui-cli 0.65.0 → 0.66.0

package/bin/sh-ui.mjs

@@ -18,6 +18,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)
@@ -93,6 +95,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,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "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.66.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');

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,7 +67,13 @@ 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);
   } else {

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");
+}