sh-ui-cli 0.78.0 → 0.80.0

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.80.0",
+      "date": "2026-05-12",
+      "title": "describeTemplate — 프로젝트 생성 전 파일 트리 미리보기",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui-cli/api` 에 `describeTemplate()` 추가** — 옵션 조합(platform/structure/arch/plugins/cssFramework/appName) 으로 실제 생성 없이 emit 될 파일 경로 트리를 사전 계산. 베이스 템플릿 + arch 오버레이 + `plugin.files` + cssFramework 분기 + `plugin.transforms` (이동/삭제) 까지 정확히 반영. fs 접근 없는 순수 함수라 브라우저 번들 가능.",
+        "**`/create` 페이지 헤더에 파일 미리보기 별도 다이얼로그** — `FolderSearch` 아이콘 + 별도 진입. 옵션 picker(`ProjectOptionsForm` 으로 추출) + 요약/상세 토글 + 출처별 lucide 아이콘 분류(base=Package, arch=Layers, sentry=ShieldAlert, intl=Languages, …) + hover/진행막대 시각화. 상세 트리는 폴더/파일 lucide 아이콘 + 컴팩트 indent.",
+        "**상세 트리에서 파일 클릭 → 내용 viewer** — `/api/template-content` route 가 lazy fetch. 베이스/arch 오버레이 디스크 파일은 readFile, plugin.files 는 plugin 모듈 호출 결과, cssFramework 동적 변종은 placeholder. 출처 라벨 표시.",
+        "**MCP `sh_ui_describe_template` 툴 노출** — \"플러그인 켜면 어떤 파일 추가돼?\" 류 질문에 IDE-내 에이전트가 실제 스캐폴드 없이 답할 수 있게.",
+        "**docs UI raw 컴포넌트 일소** — `/create` 헤더 / TokenEditor / ShowcasePicker / ShowcaseCanvas / ExportBlock / ShadowBuilder / GradientBuilder / 검색 다이얼로그 / examples 갤러리의 raw `<button>`·`<input>` 을 sh-ui `Button`/`Input` 으로 통일. 풀 커스텀 className 영역도 `Button + className` 조합으로 base 동작(hover/focus/active) 받으면서 디자인 유지.",
+        "**빌드 인프라** — `scripts/build-template-manifest.mjs` 가 `packages/cli/templates/` 를 스캔해 `src/create/templateManifest.js` 로 emit (pretest / prepublishOnly 에서 자동 실행). 템플릿 변경 시 drift 없음."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.80.0"
+    },
+    {
+      "version": "0.79.0",
+      "date": "2026-05-12",
+      "title": "no-restricted toLocaleDateString — SSR hydration mismatch 회귀 가드",
+      "type": "minor",
+      "highlights": [
+        "**ESLint `no-restricted-syntax` 룰 추가** — 인자 0개의 `.toLocaleDateString()` / `.toLocaleString()` / `.toLocaleTimeString()` 호출을 error 로 차단. Node 기본 로케일(en-US) 과 브라우저 로케일(ko-KR) 이 달라 SSR 출력이 hydrate 시 mismatch 나던 함정의 회귀 가드.",
+        "**대체 경로 안내가 에러 메시지에 박힘** — `@/src/shared/lib/formatDate` 의 `formatDate` / `formatDateTime` (default `ko-KR`), next-intl locale 추종이면 `useFormatDate` 훅, 숫자는 `formatPrice`. AST selector 가 `arguments.length === 0` 만 매칭하므로 의도된 locale 명시 호출 (`toLocaleDateString('ko-KR', { ... })`) 은 통과.",
+        "**적용 범위** — monorepo `@workspace/eslint-config/base` (next.js · react-internal 등 모든 워크스페이스 config 가 상속) + `nextjs-standalone` 의 fsd / flat / mes arch 오버레이 3종.",
+        "**템플릿 CLAUDE.md 추가** — `nextjs-standalone` / `monorepo` 시작 템플릿에 `CLAUDE.md` 신규. 날짜·숫자 포맷 컨벤션 + sh-ui 컴포넌트 우선 + 토큰 사용 원칙 명시. AI 에이전트가 코드 작성 시점에 컨텍스트로 읽고 미리 피할 수 있게."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.79.0"
+    },
     {
       "version": "0.78.0",
       "date": "2026-05-12",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "description": "sh-ui CLI — 프로젝트 스캐폴드(create) + 컴포넌트 추가(add/list/remove) + IDE-내 AI용 MCP 서버",
   "license": "MIT",
   "repository": {
@@ -44,13 +44,15 @@
     "./api": {
       "types": "./src/api.d.ts",
       "default": "./src/api.js"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "scripts": {
     "bundle-data": "node scripts/copy-data.mjs",
-    "pretest": "node scripts/copy-data.mjs",
+    "build:manifest": "node scripts/build-template-manifest.mjs",
+    "pretest": "node scripts/build-template-manifest.mjs && node scripts/copy-data.mjs",
     "test": "vitest run",
-    "prepublishOnly": "node scripts/copy-data.mjs && node --check bin/sh-ui.mjs"
+    "prepublishOnly": "node scripts/build-template-manifest.mjs && node scripts/copy-data.mjs && node --check bin/sh-ui.mjs"
   },
   "files": [
     "bin",

package/src/api.d.ts

@@ -120,3 +120,51 @@ export interface ThemePreset {
 
 export const THEME_PRESETS: Record<ThemePresetName, ThemePreset>;
 export const THEME_PRESET_NAMES: readonly ThemePresetName[];
+
+/* ─────── 템플릿 트리 미리보기 ─────── */
+
+/**
+ * 옵션 조합으로 프로젝트 생성 시 어떤 파일이 emit 되는지 사전 계산.
+ * fs 접근 없는 순수 함수 — 브라우저 사용 가능.
+ */
+export interface DescribeTemplateOptions {
+  platform?: CreatePlatform;
+  /** next 일 때만 의미. */
+  structure?: CreateStructure;
+  /** next 일 때 'fsd' | 'flat' | 'mes'. */
+  arch?: string;
+  /** 플러그인 name 배열. */
+  plugins?: string[];
+  cssFramework?: CssFrameworkSupported;
+  projectName?: string;
+  /** monorepo 첫 앱 이름. 기본 'web'. */
+  appName?: string;
+}
+
+export interface DescribeTemplateGroup {
+  /** 'base' | 'arch' | `plugin-${name}` | 'css' | 'transform' | 'monorepo' | 'ui-app' | `app-${id}` */
+  id: string;
+  label: string;
+  paths: string[];
+}
+
+export interface DescribeTemplateResult {
+  /** 모든 파일 경로 (POSIX, 정렬). */
+  files: string[];
+  /** 출처별 분류 — 빈 그룹은 제외. */
+  groups: DescribeTemplateGroup[];
+}
+
+export function describeTemplate(
+  options?: DescribeTemplateOptions,
+): DescribeTemplateResult;
+
+/**
+ * 빌드 타임에 emit 되는 raw 템플릿 인덱스. describeTemplate() 가 내부적으로 사용.
+ * 외부 노출은 디버깅 / 마이그레이션 도구용.
+ */
+export interface TemplateManifestEntry {
+  base: string[];
+  arches?: Record<string, string[]>;
+}
+export const TEMPLATE_MANIFEST: Record<string, TemplateManifestEntry>;

package/src/api.js

@@ -31,3 +31,5 @@ export {
   isKnownArch,
 } from './create/architectures/index.js';
 export { THEME_PRESETS, THEME_PRESET_NAMES } from './create/theme/presets.js';
+export { describeTemplate } from './create/describeTemplate.js';
+export { TEMPLATE_MANIFEST } from './create/templateManifest.js';

package/src/create/describeTemplate.js

@@ -0,0 +1,274 @@
+/**
+ * describeTemplate — "옵션 조합으로 프로젝트 만들면 어떤 파일이 생기는가" 를
+ * 실제 생성 없이 계산. apps/docs 의 CreateProjectDialog 가 옵션 토글 시 트리
+ * 미리보기를 그리는 데 사용. MCP 툴 `sh_ui_describe_template` 도 동일 함수.
+ *
+ * 입력: createProject() 가 받는 옵션의 부분집합 + appName(monorepo).
+ * 출력: { files: string[], groups: Group[] }
+ *   - files: 모든 파일 경로(POSIX) 정렬
+ *   - groups: 출처별 분류 — 'base'/'arch'/'plugin-*'/'css'/'transform' 등
+ *
+ * 정확도 계약:
+ * - 베이스 템플릿 + arch 오버레이 + plugin.files + cssFramework 분기 + plugin.transforms
+ *   (move/delete) 까지 반영. plugin.transforms 의 replace 는 내용만 바꾸므로 트리 영향 X.
+ * - generator.js 가 emit 하는 *파일 경로* 와 1:1 일치하는 것을 목표. content 차이는 무시.
+ *
+ * 순수성: fs 접근 없음. templateManifest.js (build-template-manifest.mjs 가 emit) 와
+ * plugins/architectures 디스크립터만 사용. 브라우저 번들 가능.
+ */
+
+import { TEMPLATE_MANIFEST } from './templateManifest.js';
+import {
+  getArchByName,
+  DEFAULT_ARCH,
+  isKnownArch,
+} from './architectures/index.js';
+import { getPluginsByNames } from './plugins/index.js';
+import { CSS_FRAMEWORK_DEFAULT } from '../constants.js';
+
+/**
+ * @typedef {Object} DescribeOptions
+ * @property {'next'|'flutter'} [platform]
+ * @property {'standalone'|'monorepo'} [structure]   next 일 때만 의미
+ * @property {string} [arch]                          next 일 때 'fsd'|'flat'|'mes'
+ * @property {string[]} [plugins]                     ['sentry', 'next-intl', 'auth-jwt']
+ * @property {'tailwind'|'plain'|'css-modules'} [cssFramework]
+ * @property {string} [projectName]
+ * @property {string} [appName]                       monorepo 첫 앱 이름. 기본 'web'
+ */
+
+/**
+ * @typedef {Object} Group
+ * @property {string} id          'base' | 'arch' | `plugin-${name}` | 'css' | 'transform' | 'monorepo' | 'ui-app' | `app-${id}`
+ * @property {string} label       사용자가 보는 한국어 라벨
+ * @property {string[]} paths     이 그룹에 귀속된 파일 경로 (정렬)
+ */
+
+/**
+ * @typedef {Object} DescribeResult
+ * @property {string[]} files                전체 파일 경로 정렬
+ * @property {Group[]} groups
+ */
+
+/**
+ * @param {DescribeOptions} [opts]
+ * @returns {DescribeResult}
+ */
+export function describeTemplate(opts = {}) {
+  const {
+    platform = 'next',
+    structure = 'standalone',
+    arch: archName = DEFAULT_ARCH,
+    plugins: pluginNames = [],
+    cssFramework = CSS_FRAMEWORK_DEFAULT,
+    appName: rawAppName = 'web',
+  } = opts;
+
+  if (platform === 'flutter') {
+    const base = TEMPLATE_MANIFEST['flutter-standalone'].base;
+    return finalize([
+      makeGroup('base', 'Flutter 베이스', base),
+    ]);
+  }
+
+  // platform === 'next'
+  const safeArchName = isKnownArch(archName) ? archName : DEFAULT_ARCH;
+  const archObj = getArchByName(safeArchName);
+  const plugins = getPluginsByNames(pluginNames).sort(
+    (a, b) => (a.priority ?? 0) - (b.priority ?? 0),
+  );
+
+  if (structure === 'standalone') {
+    const groups = buildNextGroups({
+      prefix: '',
+      templateKey: 'nextjs-standalone',
+      arch: archObj,
+      plugins,
+      cssFramework,
+    });
+    return finalize(groups);
+  }
+
+  // monorepo
+  const appName = rawAppName || 'web';
+  const groups = [];
+
+  groups.push(makeGroup(
+    'monorepo',
+    '모노레포 루트',
+    TEMPLATE_MANIFEST['monorepo'].base.slice(),
+  ));
+
+  const appGroups = buildNextGroups({
+    prefix: `apps/${appName}/`,
+    templateKey: 'nextjs-app',
+    arch: archObj,
+    plugins,
+    cssFramework,
+  });
+  for (const g of appGroups) {
+    g.id = `app-${g.id}`;
+    g.label = `apps/${appName} — ${g.label}`;
+    groups.push(g);
+  }
+
+  groups.push(makeGroup(
+    'ui-app',
+    `packages/ui/ui-apps/ui-${appName}`,
+    TEMPLATE_MANIFEST['ui-app-template'].base.map(
+      (p) => `packages/ui/ui-apps/ui-${appName}/${p}`,
+    ),
+  ));
+
+  return finalize(groups);
+}
+
+/** next 베이스 + arch + plugin.files + css 분기 + plugin.transforms 적용. */
+function buildNextGroups({ prefix, templateKey, arch, plugins, cssFramework }) {
+  const tpl = TEMPLATE_MANIFEST[templateKey];
+  if (!tpl) {
+    throw new Error(`describeTemplate: 알 수 없는 템플릿 키 '${templateKey}'`);
+  }
+
+  const groups = [];
+
+  groups.push(makeGroup(
+    'base',
+    `${templateKey} 베이스`,
+    tpl.base.map((p) => prefix + p),
+  ));
+
+  const archFiles = tpl.arches?.[arch.name] ?? [];
+  groups.push(makeGroup(
+    'arch',
+    `${arch.label} 오버레이`,
+    archFiles.map((p) => prefix + p),
+  ));
+
+  // plugin.files — arch-aware. 정적이면 그대로, 함수면 호출.
+  for (const plugin of plugins) {
+    const filesField = resolveArchField(plugin.files, arch);
+    if (!filesField) continue;
+    const paths = Object.keys(filesField).map((p) => prefix + p);
+    if (paths.length === 0) continue;
+    groups.push(makeGroup(
+      `plugin-${plugin.name}`,
+      `+ ${plugin.label}`,
+      paths,
+    ));
+  }
+
+  // cssFramework: css-modules 면 page.module.css / error.module.css 추가.
+  // generator.js applyCssFrameworkVariant 와 동일한 분기 — intl 활성 시 [locale]/, 아니면 app/.
+  if (cssFramework === 'css-modules') {
+    const intlActive = plugins.some((p) => p.name === 'next-intl');
+    const sentryActive = plugins.some((p) => p.name === 'sentry');
+    const cssPaths = [];
+    const pageDir = intlActive ? 'app/[locale]' : 'app';
+    cssPaths.push(`${prefix}${pageDir}/page.module.css`);
+    if (sentryActive) {
+      cssPaths.push(`${prefix}${pageDir}/error.module.css`);
+    }
+    groups.push(makeGroup(
+      'css',
+      'CSS: css-modules 변종',
+      cssPaths,
+    ));
+  }
+
+  // plugin.transforms — move/delete 만 트리에 영향. replace 는 content-only.
+  const moves = [];
+  const deletes = [];
+  for (const plugin of plugins) {
+    const tr = resolveArchField(plugin.transforms, arch);
+    if (!tr) continue;
+    for (const t of tr) {
+      if (t.type === 'move') moves.push({ from: prefix + t.from, to: prefix + t.to });
+      if (t.type === 'delete') deletes.push(prefix + t.path);
+    }
+  }
+
+  if (moves.length || deletes.length) {
+    const added = applyMovesAndDeletes(groups, moves, deletes);
+    if (added.length) {
+      groups.push(makeGroup(
+        'transform',
+        '플러그인 transform (이동/생성)',
+        added,
+      ));
+    }
+  }
+
+  return groups;
+}
+
+/** arch-aware 필드 resolve. 함수면 (arch) => value, 정적이면 그대로. */
+function resolveArchField(field, arch) {
+  if (field == null) return null;
+  return typeof field === 'function' ? field(arch) : field;
+}
+
+/**
+ * 그룹 배열에서 moves/deletes 적용:
+ *   - move from→to: 모든 그룹에서 from 제거, to 는 transform 그룹용으로 반환.
+ *   - delete path: 모든 그룹에서 path 제거.
+ *
+ * @returns {string[]} transform 그룹에 추가될 새 경로
+ */
+function applyMovesAndDeletes(groups, moves, deletes) {
+  const added = [];
+  for (const { from, to } of moves) {
+    const removed = removeFromAllGroups(groups, from);
+    // 원본이 어디에도 없었다면 (예: sentry 비활성 상태에서 error.tsx 이동) — 새로
+    // 추가하지 않는다. generator.js 의 `if (await fs.pathExists(fromPath))` 시맨틱.
+    if (removed) added.push(to);
+  }
+  for (const p of deletes) {
+    removeFromAllGroups(groups, p);
+  }
+  return added;
+}
+
+function removeFromAllGroups(groups, path) {
+  let removed = false;
+  for (const g of groups) {
+    const idx = g.paths.indexOf(path);
+    if (idx !== -1) {
+      g.paths.splice(idx, 1);
+      removed = true;
+    }
+  }
+  return removed;
+}
+
+function makeGroup(id, label, paths) {
+  return { id, label, paths: paths.slice() };
+}
+
+/**
+ * 후처리: 그룹 간 dedupe (같은 path 가 여러 그룹에 있으면 마지막 그룹이 소유),
+ * 그룹 안에서 path 정렬, 빈 그룹 제거, 전체 파일 목록 계산.
+ */
+function finalize(groups) {
+  const seen = new Set();
+  // 뒤에서 앞으로 — 후순위 그룹(plugins/css/transform) 이 dedup 우선권.
+  for (let i = groups.length - 1; i >= 0; i--) {
+    const kept = [];
+    for (const p of groups[i].paths) {
+      if (!seen.has(p)) {
+        seen.add(p);
+        kept.push(p);
+      }
+    }
+    groups[i] = {
+      id: groups[i].id,
+      label: groups[i].label,
+      paths: kept.sort(),
+    };
+  }
+  const cleaned = groups.filter((g) => g.paths.length > 0);
+  const files = [];
+  for (const g of cleaned) files.push(...g.paths);
+  files.sort();
+  return { files, groups: cleaned };
+}

package/src/create/templateManifest.js

@@ -0,0 +1,327 @@
+// AUTO-GENERATED by scripts/build-template-manifest.mjs — do not edit by hand.
+// 템플릿 디렉토리(`packages/cli/templates/`) 의 파일 경로 인덱스.
+// describeTemplate() 의 입력. 템플릿 변경 후에는 빌드 스크립트 재실행 필요.
+
+export const TEMPLATE_MANIFEST = {
+  "flutter-standalone": {
+    "base": [
+      "README.md",
+      "analysis_options.yaml",
+      "gitignore",
+      "lib/main.dart",
+      "lib/sh_ui/foundation/sh_ui_tokens.dart",
+      "pubspec.yaml",
+      "sh-ui.config.json"
+    ]
+  },
+  "monorepo": {
+    "base": [
+      ".dockerignore",
+      ".npmrc",
+      ".prettierrc",
+      "CLAUDE.md",
+      "README.md",
+      "gitignore",
+      "package.json",
+      "packages/eslint-config/base.js",
+      "packages/eslint-config/flat.js",
+      "packages/eslint-config/fsd.js",
+      "packages/eslint-config/mes.js",
+      "packages/eslint-config/next.js",
+      "packages/eslint-config/package.json",
+      "packages/eslint-config/react-internal.js",
+      "packages/typescript-config/base.json",
+      "packages/typescript-config/nextjs.json",
+      "packages/typescript-config/package.json",
+      "packages/typescript-config/react-library.json",
+      "packages/ui/ui-apps/.gitkeep",
+      "packages/ui/ui-core/eslint.config.js",
+      "packages/ui/ui-core/package.json",
+      "packages/ui/ui-core/sh-ui.config.json",
+      "packages/ui/ui-core/src/components/.gitkeep",
+      "packages/ui/ui-core/src/hooks/.gitkeep",
+      "packages/ui/ui-core/src/lib/utils.ts",
+      "packages/ui/ui-core/tsconfig.json",
+      "pnpm-workspace.yaml",
+      "tsconfig.json",
+      "turbo.json"
+    ]
+  },
+  "nextjs-app": {
+    "base": [
+      ".env.example",
+      "README.md",
+      "app/page.tsx",
+      "eslint.config.js",
+      "next.config.ts",
+      "package.json",
+      "postcss.config.mjs",
+      "vitest.config.ts",
+      "vitest.setup.ts"
+    ],
+    "arches": {
+      "flat": [
+        "app/api/proxy/[...path]/route.ts",
+        "app/layout.tsx",
+        "components/common/.gitkeep",
+        "components/common/FallbackBoundary/index.tsx",
+        "components/common/PrefetchBoundary/index.tsx",
+        "components/layouts/RootLayout.tsx",
+        "components/providers/GlobalProvider/index.tsx",
+        "components/providers/index.tsx",
+        "components/providers/tanstack/QueryClientProvider.tsx",
+        "components/providers/tanstack/TanstackDevtoolsProvider.tsx",
+        "components/providers/theme/ThemeProvider.tsx",
+        "eslint.config.js",
+        "lib/api/.gitkeep",
+        "lib/api/apiTypes.ts",
+        "lib/api/clientFetch.ts",
+        "lib/api/error.ts",
+        "lib/api/errorMessages.ts",
+        "lib/api/http.ts",
+        "lib/api/observability.ts",
+        "lib/api/queryClient.ts",
+        "lib/api/serverFetch.ts",
+        "lib/config/.gitkeep",
+        "lib/hooks/.gitkeep",
+        "lib/hooks/useAppMutation.ts",
+        "lib/test/createTestQueryClient.ts",
+        "lib/test/index.ts",
+        "lib/test/renderWithProviders.tsx",
+        "lib/utils/.gitkeep",
+        "lib/utils/formatDate.ts",
+        "lib/utils/formatPrice.ts",
+        "lib/utils/getQueryClient.ts",
+        "tsconfig.json"
+      ],
+      "fsd": [
+        "app/api/proxy/[...path]/route.ts",
+        "app/layout.tsx",
+        "src/app/layouts/RootLayout.tsx",
+        "src/app/providers/GlobalProvider/index.tsx",
+        "src/app/providers/index.tsx",
+        "src/app/providers/tanstack/QueryClientProvider.tsx",
+        "src/app/providers/tanstack/TanstackDevtoolsProvider.tsx",
+        "src/app/providers/theme/ThemeProvider.tsx",
+        "src/entities/.gitkeep",
+        "src/features/.gitkeep",
+        "src/shared/api/.gitkeep",
+        "src/shared/api/apiTypes.ts",
+        "src/shared/api/clientFetch.ts",
+        "src/shared/api/error.ts",
+        "src/shared/api/errorMessages.ts",
+        "src/shared/api/http.ts",
+        "src/shared/api/observability.ts",
+        "src/shared/api/queryClient.ts",
+        "src/shared/api/serverFetch.ts",
+        "src/shared/config/.gitkeep",
+        "src/shared/hooks/.gitkeep",
+        "src/shared/hooks/useAppMutation.ts",
+        "src/shared/lib/.gitkeep",
+        "src/shared/lib/formatDate.ts",
+        "src/shared/lib/formatPrice.ts",
+        "src/shared/lib/getQueryClient.ts",
+        "src/shared/model/.gitkeep",
+        "src/shared/test/createTestQueryClient.ts",
+        "src/shared/test/index.ts",
+        "src/shared/test/renderWithProviders.tsx",
+        "src/shared/ui/.gitkeep",
+        "src/shared/ui/FallbackBoundary/index.tsx",
+        "src/shared/ui/PrefetchBoundary/index.tsx",
+        "src/views/.gitkeep",
+        "src/widgets/.gitkeep",
+        "tsconfig.json"
+      ],
+      "mes": [
+        "app/api/proxy/[...path]/route.ts",
+        "app/layout.tsx",
+        "app/sign-in/page.tsx",
+        "eslint.config.js",
+        "src/components/common/.gitkeep",
+        "src/components/common/FallbackBoundary/index.tsx",
+        "src/components/common/PrefetchBoundary/index.tsx",
+        "src/components/layouts/RootLayout.tsx",
+        "src/components/providers/GlobalProvider/index.tsx",
+        "src/components/providers/index.tsx",
+        "src/components/providers/tanstack/QueryClientProvider.tsx",
+        "src/components/providers/tanstack/TanstackDevtoolsProvider.tsx",
+        "src/components/providers/theme/ThemeProvider.tsx",
+        "src/hooks/.gitkeep",
+        "src/hooks/useAppMutation.ts",
+        "src/lib/api/.gitkeep",
+        "src/lib/api/apiTypes.ts",
+        "src/lib/api/clientFetch.ts",
+        "src/lib/api/error.ts",
+        "src/lib/api/errorMessages.ts",
+        "src/lib/api/http.ts",
+        "src/lib/api/observability.ts",
+        "src/lib/api/queryClient.ts",
+        "src/lib/api/serverFetch.ts",
+        "src/lib/config/.gitkeep",
+        "src/lib/test/createTestQueryClient.ts",
+        "src/lib/test/index.ts",
+        "src/lib/test/renderWithProviders.tsx",
+        "src/lib/utils/.gitkeep",
+        "src/lib/utils/formatDate.ts",
+        "src/lib/utils/formatPrice.ts",
+        "src/lib/utils/getQueryClient.ts",
+        "src/pages/sign-in/api.ts",
+        "src/pages/sign-in/components/.gitkeep",
+        "src/pages/sign-in/hooks.ts",
+        "src/pages/sign-in/index.tsx",
+        "src/pages/sign-in/schema.ts",
+        "tsconfig.json"
+      ]
+    }
+  },
+  "nextjs-standalone": {
+    "base": [
+      ".env.example",
+      ".prettierrc",
+      "CLAUDE.md",
+      "README.md",
+      "app/globals.css",
+      "app/page.tsx",
+      "eslint.config.js",
+      "gitignore",
+      "next.config.ts",
+      "package.json",
+      "postcss.config.mjs",
+      "vitest.config.ts",
+      "vitest.setup.ts"
+    ],
+    "arches": {
+      "flat": [
+        "app/api/proxy/[...path]/route.ts",
+        "app/globals.css",
+        "app/layout.tsx",
+        "components/common/.gitkeep",
+        "components/common/FallbackBoundary/index.tsx",
+        "components/common/PrefetchBoundary/index.tsx",
+        "components/layouts/RootLayout.tsx",
+        "components/providers/GlobalProvider/index.tsx",
+        "components/providers/index.tsx",
+        "components/providers/tanstack/QueryClientProvider.tsx",
+        "components/providers/tanstack/TanstackDevtoolsProvider.tsx",
+        "components/providers/theme/ThemeProvider.tsx",
+        "eslint.config.js",
+        "lib/api/.gitkeep",
+        "lib/api/apiTypes.ts",
+        "lib/api/clientFetch.ts",
+        "lib/api/error.ts",
+        "lib/api/errorMessages.ts",
+        "lib/api/http.ts",
+        "lib/api/observability.ts",
+        "lib/api/queryClient.ts",
+        "lib/api/serverFetch.ts",
+        "lib/config/.gitkeep",
+        "lib/hooks/.gitkeep",
+        "lib/hooks/useAppMutation.ts",
+        "lib/styles/tokens.css",
+        "lib/test/createTestQueryClient.ts",
+        "lib/test/index.ts",
+        "lib/test/renderWithProviders.tsx",
+        "lib/utils/formatDate.ts",
+        "lib/utils/formatPrice.ts",
+        "lib/utils/getQueryClient.ts",
+        "lib/utils/utils.ts",
+        "sh-ui.config.json",
+        "tsconfig.json"
+      ],
+      "fsd": [
+        "app/api/proxy/[...path]/route.ts",
+        "app/layout.tsx",
+        "sh-ui.config.json",
+        "src/app/layouts/RootLayout.tsx",
+        "src/app/providers/GlobalProvider/index.tsx",
+        "src/app/providers/index.tsx",
+        "src/app/providers/tanstack/QueryClientProvider.tsx",
+        "src/app/providers/tanstack/TanstackDevtoolsProvider.tsx",
+        "src/app/providers/theme/ThemeProvider.tsx",
+        "src/entities/.gitkeep",
+        "src/features/.gitkeep",
+        "src/shared/api/.gitkeep",
+        "src/shared/api/apiTypes.ts",
+        "src/shared/api/clientFetch.ts",
+        "src/shared/api/error.ts",
+        "src/shared/api/errorMessages.ts",
+        "src/shared/api/http.ts",
+        "src/shared/api/observability.ts",
+        "src/shared/api/queryClient.ts",
+        "src/shared/api/serverFetch.ts",
+        "src/shared/config/.gitkeep",
+        "src/shared/hooks/.gitkeep",
+        "src/shared/hooks/useAppMutation.ts",
+        "src/shared/lib/formatDate.ts",
+        "src/shared/lib/formatPrice.ts",
+        "src/shared/lib/getQueryClient.ts",
+        "src/shared/lib/utils.ts",
+        "src/shared/model/.gitkeep",
+        "src/shared/styles/tokens.css",
+        "src/shared/test/createTestQueryClient.ts",
+        "src/shared/test/index.ts",
+        "src/shared/test/renderWithProviders.tsx",
+        "src/shared/ui/.gitkeep",
+        "src/shared/ui/FallbackBoundary/index.tsx",
+        "src/shared/ui/PrefetchBoundary/index.tsx",
+        "src/views/.gitkeep",
+        "src/widgets/.gitkeep",
+        "tsconfig.json"
+      ],
+      "mes": [
+        "app/api/proxy/[...path]/route.ts",
+        "app/globals.css",
+        "app/layout.tsx",
+        "app/sign-in/page.tsx",
+        "eslint.config.js",
+        "sh-ui.config.json",
+        "src/components/common/.gitkeep",
+        "src/components/common/FallbackBoundary/index.tsx",
+        "src/components/common/PrefetchBoundary/index.tsx",
+        "src/components/layouts/RootLayout.tsx",
+        "src/components/providers/GlobalProvider/index.tsx",
+        "src/components/providers/index.tsx",
+        "src/components/providers/tanstack/QueryClientProvider.tsx",
+        "src/components/providers/tanstack/TanstackDevtoolsProvider.tsx",
+        "src/components/providers/theme/ThemeProvider.tsx",
+        "src/hooks/.gitkeep",
+        "src/hooks/useAppMutation.ts",
+        "src/lib/api/.gitkeep",
+        "src/lib/api/apiTypes.ts",
+        "src/lib/api/clientFetch.ts",
+        "src/lib/api/error.ts",
+        "src/lib/api/errorMessages.ts",
+        "src/lib/api/http.ts",
+        "src/lib/api/observability.ts",
+        "src/lib/api/queryClient.ts",
+        "src/lib/api/serverFetch.ts",
+        "src/lib/config/.gitkeep",
+        "src/lib/styles/tokens.css",
+        "src/lib/test/createTestQueryClient.ts",
+        "src/lib/test/index.ts",
+        "src/lib/test/renderWithProviders.tsx",
+        "src/lib/utils/formatDate.ts",
+        "src/lib/utils/formatPrice.ts",
+        "src/lib/utils/getQueryClient.ts",
+        "src/lib/utils/utils.ts",
+        "src/pages/sign-in/api.ts",
+        "src/pages/sign-in/components/.gitkeep",
+        "src/pages/sign-in/hooks.ts",
+        "src/pages/sign-in/index.tsx",
+        "src/pages/sign-in/schema.ts",
+        "tsconfig.json"
+      ]
+    }
+  },
+  "ui-app-template": {
+    "base": [
+      "eslint.config.js",
+      "package.json",
+      "postcss.config.mjs",
+      "sh-ui.config.json",
+      "src/styles/globals.css",
+      "src/styles/tokens.css",
+      "tsconfig.json"
+    ]
+  }
+};

package/src/mcp.mjs

@@ -49,6 +49,7 @@ import {
 } from "./constants.js";
 import { allPlugins } from "./create/plugins/index.js";
 import { allArchitectures } from "./create/architectures/index.js";
+import { describeTemplate } from "./create/describeTemplate.js";
 import { THEME_PRESET_NAMES } from "./create/theme/presets.js";
 import { decodeTheme } from "./create/theme/decode.js";
 import { encodeTheme } from "./create/theme/encode.js";
@@ -805,6 +806,51 @@ export async function startMcpServer() {
     },
   );
 
+  // 템플릿 트리 사전 미리보기 — 실제 생성 없이 옵션 조합으로 어떤 파일이 emit 되는지.
+  // apps/docs 의 CreateProjectDialog 와 같은 출력 (sh-ui-cli/api 의 describeTemplate).
+  server.registerTool(
+    "sh_ui_describe_template",
+    {
+      description:
+        "sh-ui create 호출 시 어떤 파일이 생기는지 사전 계산 — 실제 fs 변경 없음. " +
+        "사용자가 '미리 보고 싶다' / '어떤 파일 생기는지' / '플러그인 켜면 뭐가 추가돼?' 류 질문을 하면 이 툴 사용 (sh_ui_create_project 의 dry-run 대용). " +
+        "베이스 템플릿 + arch 오버레이 + plugin.files + cssFramework 분기 + plugin.transforms (이동/삭제) 까지 정확히 반영. " +
+        "반환: { files: 정렬된 전체 경로, groups: 출처별 분류 (base/arch/plugin-*/css/transform) }.",
+      inputSchema: {
+        platform: z.enum(CREATE_PLATFORMS)
+          .describe("타겟 플랫폼"),
+        structure: z.enum(CREATE_STRUCTURES).optional()
+          .describe("Next.js 구조. platform=next 일 때 의미. 기본 standalone"),
+        arch: z.enum(ARCH_NAMES).optional()
+          .describe("아키텍처. platform=next 일 때 의미. 기본 fsd"),
+        plugins: z.array(z.enum(PLUGIN_NAMES)).optional()
+          .describe(`Next.js 플러그인 배열 (${PLUGIN_NAMES.join(', ')}). 미지정 빈 배열`),
+        cssFramework: z.enum(CSS_FRAMEWORKS).optional()
+          .describe("CSS 프레임워크. 기본 plain. css-modules 면 page.module.css 등 추가"),
+        appName: z.string().optional()
+          .describe("monorepo 첫 앱 이름. 기본 web"),
+      },
+    },
+    async (input) => {
+      try {
+        const result = describeTemplate({
+          platform: input.platform,
+          structure: input.structure,
+          arch: input.arch,
+          plugins: input.plugins,
+          cssFramework: input.cssFramework,
+          appName: input.appName,
+        });
+        return jsonResult(result);
+      } catch (e) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: e.message }],
+        };
+      }
+    },
+  );
+
   // 변경 내역 조회 — 보너스: 사용자가 "최근 변경 알려줘" 류 요청 시
   server.registerTool(
     "sh_ui_get_changelog",

package/templates/monorepo/CLAUDE.md

@@ -0,0 +1,40 @@
+# 프로젝트 작업 규칙
+
+sh-ui CLI 가 스캐폴드한 monorepo (Turborepo + pnpm workspace). AI 에이전트
+(Claude / Cursor / Codex 등) 가 이 파일을 컨텍스트로 읽고 아래 규칙을 따른다.
+
+## 구조
+
+- `apps/<name>/` — Next.js 앱. 라우트 + 비즈니스 로직.
+- `packages/ui/ui-core/` — 모든 앱이 공유하는 sh-ui 컴포넌트 / 훅 / 유틸 SoT.
+  컴포넌트 추가는 여기에 한 번만.
+- `packages/ui/ui-apps/ui-<name>/` — 앱별 토큰 (color/spacing/font) 만 보관.
+  컴포넌트는 두지 않음 (v0.65+ `tokens-only` 마커).
+- `packages/eslint-config/` · `packages/typescript-config/` — 공용 설정.
+
+## 날짜 / 숫자 포맷
+
+- raw `Date.prototype.toLocaleDateString()` / `toLocaleString()` / `toLocaleTimeString()`
+  호출 **금지** — SSR(Node) 와 브라우저의 기본 로케일이 달라 hydration mismatch 의
+  원인. ESLint `no-restricted-syntax` 룰이 인자 0개의 호출을 막는다
+  (`@workspace/eslint-config/base` 에 정의).
+- 대신 `@/src/shared/lib/formatDate` 의 `formatDate(date)` / `formatDateTime(date)`
+  사용 (default locale `ko-KR`, 서버·클라이언트 동일 출력 보장).
+- next-intl locale 추종이 필요하면 `@/src/shared/hooks/useFormatDate` 훅 사용.
+- 동일 원칙이 숫자에도 적용 — raw `Number.prototype.toLocaleString()` 금지,
+  `formatPrice` 사용.
+- 인자가 명시된 호출 (`toLocaleDateString('ko-KR', { ... })`) 은 의도된 사용이므로
+  허용. 다만 SSR 출력 결정성을 위해서는 util 경유가 안전.
+
+## 새 앱 추가
+
+`sh_ui_add_app` MCP 툴 또는 `npx sh-ui-cli add app <name>` — `apps/<name>/` +
+`packages/ui/ui-apps/ui-<name>/` 를 한 번에 만든다. 앱별로 다른 톤 가능 (예:
+marketing = rose, admin = emerald). 컴포넌트는 `ui-core` 단일 SoT 라 두 앱이
+자동 공유.
+
+## 토큰 사용
+
+- 색상 / 간격 / 폰트 크기는 항상 토큰 변수 경유 (`var(--space-3)`, `bg-fg`,
+  `text-fg-muted` 등). 매직 px / hex 직접 하드코딩 금지.
+- 토큰 정의부는 `packages/ui/ui-apps/ui-<name>/src/styles/tokens.css`.

package/templates/monorepo/packages/eslint-config/base.js

@@ -18,6 +18,15 @@ export const config = [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `@/src/shared/lib/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
   {

package/templates/nextjs-standalone/CLAUDE.md

@@ -0,0 +1,30 @@
+# 프로젝트 작업 규칙
+
+sh-ui CLI 가 스캐폴드한 Next.js standalone 프로젝트. AI 에이전트 (Claude / Cursor /
+Codex 등) 가 이 파일을 컨텍스트로 읽고 아래 규칙을 따른다.
+
+## 날짜 / 숫자 포맷
+
+- raw `Date.prototype.toLocaleDateString()` / `toLocaleString()` / `toLocaleTimeString()`
+  호출 **금지** — SSR(Node) 와 브라우저의 기본 로케일이 달라 hydration mismatch 의
+  원인. ESLint `no-restricted-syntax` 룰이 인자 0개의 호출을 막는다.
+- 대신 `@/src/shared/lib/formatDate` 의 `formatDate(date)` / `formatDateTime(date)`
+  사용 (default locale `ko-KR`, 서버·클라이언트 동일 출력 보장).
+- next-intl locale 추종이 필요하면 `@/src/shared/hooks/useFormatDate` 훅 사용.
+- 동일 원칙이 숫자에도 적용 — raw `Number.prototype.toLocaleString()` 금지,
+  `@/src/shared/lib/formatPrice` 의 `formatPrice` 사용.
+- 인자가 명시된 호출 (`toLocaleDateString('ko-KR', { ... })`) 은 의도된 사용이므로
+  허용. 다만 SSR 출력 결정성을 위해서는 util 경유가 안전.
+
+## sh-ui 컴포넌트 우선
+
+- shadcn/ui 류 외부 라이브러리 대신 이 프로젝트의 `components/ui/*` (sh-ui 레지스트리)
+  사용. Base UI (`@base-ui-components/react`) 위에 빌드되어 있음.
+- 새 컴포넌트가 필요하면 `npx sh-ui-cli add <name>` 또는 sh-ui MCP 의
+  `sh_ui_add_component` 사용.
+
+## 토큰 사용
+
+- 색상 / 간격 / 폰트 크기는 항상 토큰 변수 경유 (`var(--space-3)`, `bg-fg`,
+  `text-fg-muted` 등). 매직 px / hex 직접 하드코딩 금지.
+- 토큰 정의부는 `app/globals.css` 또는 `src/shared/styles/tokens.css`.

package/templates/nextjs-standalone/_arch/flat/eslint.config.js

@@ -27,6 +27,15 @@ export default [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `lib/utils/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
 

package/templates/nextjs-standalone/_arch/mes/eslint.config.js

@@ -27,6 +27,15 @@ export default [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `src/lib/utils/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },
 

package/templates/nextjs-standalone/eslint.config.js

@@ -27,6 +27,15 @@ export default [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector:
+            "CallExpression[arguments.length=0][callee.type='MemberExpression'][callee.property.name=/^toLocale(Date|Time)?String$/]",
+          message:
+            "Argument-less .toLocaleDateString() / .toLocaleString() / .toLocaleTimeString() causes SSR hydration mismatch (Node default locale ≠ browser locale). Use `formatDate` from `@/src/shared/lib/formatDate`, or the `useFormatDate` hook for i18n-aware locale (numbers: `formatPrice`).",
+        },
+      ],
     },
   },