sh-ui-cli 0.56.4 → 0.58.0

package/bin/sh-ui.mjs

@@ -15,17 +15,21 @@ const usage = `사용법:
                                    특수값: tokens → 설정 기반 토큰 파일 생성
   sh-ui list                       현재 설치된 컴포넌트 목록 표시
   sh-ui remove <component...>      설치된 컴포넌트 파일 삭제
+  sh-ui rename-app <old> <new>     monorepo 의 앱 이름 일괄 변경
+                                   (apps/<old>/, packages/ui/ui-apps/ui-<old>/
+                                   디렉토리 + 모든 import/path 패턴)
   sh-ui mcp                        MCP 서버(stdio) 시작 — IDE-내 AI용
   sh-ui mcp init --client <name>   IDE MCP 설정 파일에 sh-ui 엔트리 자동 추가
                                    (claude-code | cursor | claude-desktop)
   옵션:
-    --skip-install                 (add) 외부 패키지 자동 설치 생략
+    --skip-install                 (add, rename-app) 외부 패키지 자동 설치 생략
     --diff                         (add) 파일을 쓰지 않고 변경 내역만 출력
     --force                        (add) 기존 파일을 모두 덮어쓰기 (prompt 없음)
                                    (remove) 사용자가 수정한 파일도 삭제
     --keep                         (add) 기존 파일을 모두 유지 (prompt 없음)
     --all                          (list) 설치되지 않은 컴포넌트까지 표시
-    --dry-run                      (remove) 삭제 대상만 출력하고 실행 안 함
+    --dry-run                      (remove, rename-app) 변경 대상만 출력하고 실행 안 함
+    --yes                          (rename-app) 대화형 확인 생략
 `;
 
 try {
@@ -74,6 +78,21 @@ try {
       }
       break;
     }
+    case "rename-app": {
+      const yes = rest.includes("--yes");
+      const dryRun = rest.includes("--dry-run");
+      const skipInstall = rest.includes("--skip-install");
+      const positional = rest.filter((a) => !a.startsWith("--"));
+      if (positional.length < 2) {
+        console.error("에러: rename-app 은 <old> <new> 두 인자가 필요합니다.\n");
+        console.error(usage);
+        process.exit(1);
+      }
+      const [oldName, newName] = positional;
+      const { renameApp } = await import("../src/rename-app.mjs");
+      await renameApp({ cwd: process.cwd(), oldName, newName, yes, dryRun, skipInstall });
+      break;
+    }
     case "remove":
     case "rm": {
       const force = rest.includes("--force");

package/data/changelog/versions.json

@@ -2,6 +2,38 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.58.0",
+      "date": "2026-05-05",
+      "title": "아키텍처 (arch) 1급 시민 도입 + flat 추가",
+      "type": "minor",
+      "highlights": [
+        "**`--arch` CLI 플래그 + MCP `arch` 파라미터 신설** — 프로젝트의 *모양* (폴더 구조, import alias 컨벤션, tsconfig paths) 을 1급 개념으로 분리. 플러그인과 직교하는 별도 축 — 사용자는 arch 한 개 + 플러그인 N 개를 동시에 선택. 미지정 시 기본 `fsd` (v0.57 까지의 동작과 동일).",
+        "**아키텍처 디스크립터 모델** — `src/create/architectures/{fsd,flat}.js` 가 8개 논리 키 (`layouts`, `providers`, `api`, `config`, `hooks`, `utils`, `ui`, `test`) 의 fs 경로 / import alias / tsconfig paths 를 선언. 플러그인은 하드코딩된 `src/shared/api/...` 대신 `arch.paths.api` / `arch.aliases.api` 를 조회해 산출물 emit — 한 번 작성된 플러그인이 모든 arch 에서 동작.",
+        "**`flat` 아키텍처 추가** — 슬라이스 (entities/features/widgets/views) 없는 vanilla Next 관용 구조 (`lib/api`, `lib/utils`, `components/layouts`, `components/providers`, `components/common`). 토이 프로젝트, 데모, 일회성 도구처럼 FSD 6 레이어가 과한 경우용. tsconfig paths 는 카테고리별 scoped (`@/lib/*`, `@/components/*`, `@/app/*`) — FSD 의 catch-all `@/*` 와 의도적으로 다른 컨벤션.",
+        "**플러그인 3개 (sentry/next-intl/auth-jwt) 모두 arch-aware 로 리팩토링** — files / transforms / preExport / providerImports 가 `(arch) => ...` 함수형으로 전환. 회귀 가드: FSD 디스크립터 값이 v0.57 까지의 하드코딩과 1:1 일치하므로 FSD 사용자 입장 변화 0.",
+        "**Cross-platform 대비** — 디스크립터에 `platforms: ['next' | 'flutter']` 필드 박힘. 현재 fsd/flat 둘 다 next 만 지원하지만, 향후 `flutter-clean` / `flutter-bloc` 같은 Flutter arch 추가 시 generator/CLI 수정 0 — 디스크립터만 추가하면 됨.",
+        "**베이스 템플릿 재구조화** — `templates/nextjs-app` / `templates/nextjs-standalone` 이 arch-neutral 베이스 + `_arch/{fsd,flat}/` 오버레이로 분리. generator 가 base 카피 후 선택된 arch 의 오버레이를 머지. 새 arch 추가 절차는 `packages/cli/ARCHITECTURE.md` 에 문서화.",
+        "**docs 사이드바에 Architectures 그룹 신설** — `/architectures` 허브 + `/architectures/fsd` + `/architectures/flat` 페이지. arch 선택 가이드 + 폴더 구조 시각화 + FSD ↔ flat 마이그레이션 절차.",
+        "**스모크 매트릭스 9개 시나리오 추가** — flat × {none, sentry, next-intl, auth-jwt, all 3} + flat monorepo 1개 + FSD 회귀 가드 2개. 핵심 검증: flat 에 src/ 부재, 어떤 .ts/.tsx 파일에도 `@/src/...` import 누수 없음, 플러그인 산출물이 arch-correct 경로로 떨어짐."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.58.0"
+    },
+    {
+      "version": "0.57.0",
+      "date": "2026-05-04",
+      "title": "rename-app — monorepo 앱 이름 일괄 변경 명령어 + MCP 툴",
+      "type": "minor",
+      "highlights": [
+        "**`sh-ui rename-app <old> <new>`** — monorepo 의 앱 이름을 한 번에 변경. `apps/<old>/`, `packages/ui/ui-apps/ui-<old>/` 두 디렉토리 이동 + `@workspace/ui-<old>` / `apps/<old>` / `--filter <old>` / `--app <old>` 같은 컨텍스트 묶인 패턴만 치환. 사용자 코드, package.json name, tsconfig paths, Dockerfile WORKDIR, next.config transpilePackages, sh-ui.config aliases, README, `.github/workflows/*.yml`, 루트 package.json scripts 까지 자동 갱신.",
+        "**MCP 툴 `sh_ui_rename_app`** — IDE-내 AI 가 \"apps/web 을 dashboard 로 바꿔줘\" 류 요청 받으면 자동 호출. `dryRun: true` 로 변경 매트릭스 미리보기 후 실행 권장. instructions 블록에도 가이드 추가.",
+        "**옵션** — `--dry-run` (변경 매트릭스만 출력) / `--yes` (대화형 확인 생략) / `--skip-install` (마지막 `pnpm install` 생략).",
+        "**false-positive 방지** — bare 단어(예: `web`)는 절대 치환하지 않음. 컨텍스트(슬래시, 따옴표, 백틱, 공백, 개행) 로 묶인 패턴만 매치 — `core-web-vitals` (ESLint) / `safari-web-extension` (Sentry) 같은 생태계 상수는 보존.",
+        "**lockfile 자동 재생성** — 마지막 단계에서 `pnpm install` 실행해 workspace 링크 갱신. 실패해도 friendly 안내 메시지로 사용자가 수동 실행 가능.",
+        "**fix — Next 16 호환: `app/layout.tsx` html/body 누락 에러 해소** — next-intl 플러그인이 `app/layout.tsx` 를 패스스루(`return children`) 로 남기던 방식이 Next 16 의 \"Missing <html> and <body> tags in the root layout\" 런타임 에러를 일으키던 문제 수정. 이제 `app/layout.tsx` 를 통째로 `app/[locale]/layout.tsx` 로 이동(globals.css side-effect import 보존)하고 본체만 locale-aware 버전으로 교체 — `app/layout.tsx` 가 사라지면서 `[locale]/layout.tsx` 가 Next 의 root layout 으로 인식되고 그 안의 `RootLayout` (html/body 보유) 이 정상 적용. smoke matrix 에 회귀 가드 추가."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.57.0"
+    },
     {
       "version": "0.56.4",
       "date": "2026-05-04",

package/package.json

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

package/src/api.d.ts

@@ -56,6 +56,40 @@ export type PluginManifest = {
 
 export const allPlugins: readonly PluginManifest[];
 
+/* ─────── 아키텍처 (arch) ─────── */
+
+/** 논리 키 셋 — 모든 arch 디스크립터가 동일하게 노출하는 카테고리. */
+export type ArchPathKey =
+  | 'layouts'
+  | 'providers'
+  | 'api'
+  | 'config'
+  | 'hooks'
+  | 'utils'
+  | 'ui'
+  | 'test';
+
+export type ArchManifest = {
+  /** kebab-case 식별자 (예: "fsd", "flat"). */
+  name: string;
+  label: string;
+  description: string;
+  /** 이 arch 가 적용 가능한 플랫폼들. */
+  platforms: readonly CreatePlatform[];
+  /** 논리 키 → 파일시스템 경로 (앱 루트 기준). */
+  paths: Record<ArchPathKey, string>;
+  /** 논리 키 → import alias prefix (TS 코드 emit 시). */
+  aliases: Record<ArchPathKey, string>;
+  /** tsconfig.json 의 paths 블록에 그대로 들어갈 객체. */
+  tsconfigPaths: Record<string, string[]>;
+};
+
+export const allArchitectures: readonly ArchManifest[];
+export const DEFAULT_ARCH: 'fsd';
+export function getArchByName(name: string): ArchManifest;
+export function getArchesForPlatform(platform: CreatePlatform): readonly ArchManifest[];
+export function isKnownArch(name: string): boolean;
+
 /* ─────── 테마 프리셋 ─────── */
 
 export type ThemePresetName = 'neutral' | 'slate' | 'rose' | 'emerald' | 'violet';

package/src/api.js

@@ -23,4 +23,11 @@ export {
 } from './constants.js';
 
 export { allPlugins } from './create/plugins/index.js';
+export {
+  allArchitectures,
+  DEFAULT_ARCH,
+  getArchByName,
+  getArchesForPlatform,
+  isKnownArch,
+} from './create/architectures/index.js';
 export { THEME_PRESETS, THEME_PRESET_NAMES } from './create/theme/presets.js';

package/src/create/architectures/archSchema.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+
+/**
+ * 아키텍처 디스크립터 스키마.
+ * architectures/index.js 로딩 시 모든 디스크립터를 이 스키마로 validate 한다.
+ *
+ * arch 는 플러그인과 별개의 1급 개념이다 — 프로젝트의 *모양* (폴더 구조,
+ * import alias 컨벤션) 을 정의하고, 플러그인은 이 디스크립터의 논리 키
+ * (`paths.api`, `aliases.providers` 등) 를 조회해 자신의 산출물을 emit 한다.
+ *
+ * 디자인 원칙:
+ * - 논리 키는 arch 중립적 — `layouts`, `providers`, `api`, `config`, `hooks`,
+ *   `utils`, `ui`, `test`. FSD 의 `shared/*` 같은 슬라이스 명칭이 키에 누수되지 않게.
+ * - 모든 arch 는 **동일한 키 셋** 을 노출해야 함 (플러그인이 안전하게 조회).
+ *   누락 시 스키마가 즉시 거부.
+ * - `paths` 는 fs 경로 (앱 루트 기준 상대), `aliases` 는 import 시 사용할 prefix.
+ *   둘은 1:1 대응 (paths.foo 디렉토리 = aliases.foo 가 가리키는 곳).
+ * - `tsconfigPaths` 는 tsconfig.json 의 paths 블록에 그대로 들어가는 객체.
+ *   arch 마다 `@/*` 한 줄일 수도, 더 세분화될 수도 있음.
+ */
+
+const PathKeys = z.object({
+  layouts:    z.string().min(1),
+  providers:  z.string().min(1),
+  api:        z.string().min(1),
+  config:     z.string().min(1),
+  hooks:      z.string().min(1),
+  utils:      z.string().min(1),
+  ui:         z.string().min(1),
+  test:       z.string().min(1),
+});
+
+export const ArchSchema = z.object({
+  name: z.string().regex(/^[a-z][a-z0-9-]*$/, {
+    message: 'Architecture name must be lowercase kebab-case (e.g., "fsd", "flat")',
+  }),
+  label: z.string().min(1),
+  description: z.string().min(1),
+
+  // 이 arch 가 적용 가능한 플랫폼들. CLI 에서 platform/arch 조합이 호환되는지 검증.
+  // 예: fsd/flat 은 ['next'], 미래에 추가될 flutter-clean 은 ['flutter'].
+  // 같은 이름의 arch 가 두 플랫폼 모두 지원하는 케이스도 가능 (예: 'flat' 가 양쪽).
+  platforms: z.array(z.enum(['next', 'flutter'])).min(1),
+
+  // 논리 키 → 파일시스템 경로 (앱 루트 기준 상대)
+  paths: PathKeys,
+
+  // 논리 키 → import alias prefix (TS 코드에서 emit 할 때 사용)
+  aliases: PathKeys,
+
+  // tsconfig.json 의 paths 필드에 그대로 들어가는 객체
+  // 예: FSD 는 { '@/*': ['./*'] }, flat 은 더 세분화
+  // Flutter arch 의 경우 이 필드는 사실상 무시됨 (Dart 는 tsconfig 가 없음).
+  tsconfigPaths: z.record(z.string(), z.array(z.string())),
+});
+
+export function validateArchitectures(architectures) {
+  for (const arch of architectures) {
+    const result = ArchSchema.safeParse(arch);
+    if (!result.success) {
+      const issues = result.error.issues
+        .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+        .join('\n');
+      throw new Error(
+        `Invalid architecture descriptor "${arch?.name ?? '(unknown)'}":\n${issues}`,
+      );
+    }
+  }
+}

package/src/create/architectures/flat.js

@@ -0,0 +1,51 @@
+/**
+ * Flat 아키텍처 디스크립터.
+ *
+ * 슬라이스 없이 vanilla Next.js 관용에 가까운 폴더 구조 — `lib/` (유틸/설정),
+ * `components/` (UI/레이아웃/프로바이더). 토이 프로젝트, 데모, 일회성 도구처럼
+ * FSD 의 6 레이어가 과한 경우에 적합.
+ *
+ * tsconfig 의 `paths` 는 FSD 의 전역 `@/*` 와 다르게 *카테고리별 scoped alias* 를
+ * 쓴다 (`@/lib/*`, `@/components/*`, `@/app/*`). 이유는 두 가지:
+ *
+ *   1. flat 은 import 가 짧은 게 강점 — `@/lib/api/x` 처럼 카테고리가 alias 에 박혀
+ *      있으면 한 번 보고 어디 파일인지 식별. 전역 `@/*` 보다 가독성 ↑.
+ *   2. 미래에 다른 arch 를 추가할 때 alias 컨벤션 차이가 arch 정체성의 일부가
+ *      될 수 있도록 — clean/MVC 등은 또 자기만의 alias 패턴을 가질 수 있다.
+ */
+export const flatArch = {
+  name: 'flat',
+  label: 'Flat',
+  description:
+    '슬라이스 없는 관용적 Next.js 구조 (lib/components/app). 작은 프로젝트, 데모, 일회성 도구에 적합.',
+  platforms: ['next'],
+
+  paths: {
+    layouts:    'components/layouts',
+    providers:  'components/providers',
+    api:        'lib/api',
+    config:     'lib/config',
+    hooks:      'lib/hooks',
+    utils:      'lib/utils',
+    ui:         'components/common',
+    test:       'lib/test',
+  },
+
+  aliases: {
+    layouts:    '@/components/layouts',
+    providers:  '@/components/providers',
+    api:        '@/lib/api',
+    config:     '@/lib/config',
+    hooks:      '@/lib/hooks',
+    utils:      '@/lib/utils',
+    ui:         '@/components/common',
+    test:       '@/lib/test',
+  },
+
+  // Scoped alias — 카테고리별로 명시. FSD 의 catch-all `@/*` 와 의도적으로 다름.
+  tsconfigPaths: {
+    '@/lib/*':        ['./lib/*'],
+    '@/components/*': ['./components/*'],
+    '@/app/*':        ['./app/*'],
+  },
+};

package/src/create/architectures/fsd.js

@@ -0,0 +1,42 @@
+/**
+ * Feature-Sliced Design 아키텍처 디스크립터.
+ *
+ * sh-ui 의 디폴트 arch — 슬라이스 (entities, features, widgets, views, shared, app) 기반.
+ * 플러그인이 emit 하는 산출물의 fs 경로/import alias 를 결정한다.
+ *
+ * 본 디스크립터의 값은 sh-ui v0.57 까지의 하드코딩된 경로와 1:1 일치 —
+ * 즉 v0.58 에서 FSD 사용자 입장 변화 0 이어야 한다 (회귀 가드는 smoke matrix 가).
+ */
+export const fsdArch = {
+  name: 'fsd',
+  label: 'Feature-Sliced Design',
+  description:
+    '슬라이스 기반 폴더 구조 (entities/features/widgets/views/shared/app). 도메인이 큰 프로젝트에 적합.',
+  platforms: ['next'],
+
+  paths: {
+    layouts:    'src/app/layouts',
+    providers:  'src/app/providers',
+    api:        'src/shared/api',
+    config:     'src/shared/config',
+    hooks:      'src/shared/hooks',
+    utils:      'src/shared/lib',
+    ui:         'src/shared/ui',
+    test:       'src/shared/test',
+  },
+
+  aliases: {
+    layouts:    '@/src/app/layouts',
+    providers:  '@/src/app/providers',
+    api:        '@/src/shared/api',
+    config:     '@/src/shared/config',
+    hooks:      '@/src/shared/hooks',
+    utils:      '@/src/shared/lib',
+    ui:         '@/src/shared/ui',
+    test:       '@/src/shared/test',
+  },
+
+  tsconfigPaths: {
+    '@/*': ['./*'],
+  },
+};

package/src/create/architectures/index.js

@@ -0,0 +1,55 @@
+import { fsdArch } from './fsd.js';
+import { flatArch } from './flat.js';
+import { validateArchitectures } from './archSchema.js';
+
+export const allArchitectures = [fsdArch, flatArch];
+
+// 모듈 로드 시점에 모든 arch 디스크립터를 schema 로 검증.
+// 누락된 키, 잘못된 형태가 있으면 즉시 에러.
+validateArchitectures(allArchitectures);
+
+export const DEFAULT_ARCH = 'fsd';
+
+export function getArchChoices() {
+  return allArchitectures.map((a) => ({
+    name: `${a.label} — ${a.description}`,
+    value: a.name,
+  }));
+}
+
+export function getArchByName(name) {
+  const arch = allArchitectures.find((a) => a.name === name);
+  if (!arch) {
+    const known = allArchitectures.map((a) => a.name).join(', ');
+    throw new Error(`Unknown architecture "${name}". Available: ${known}`);
+  }
+  return arch;
+}
+
+export function isKnownArch(name) {
+  return allArchitectures.some((a) => a.name === name);
+}
+
+/**
+ * platform 에서 사용 가능한 arch 만 필터링.
+ * 예: 'next' → fsd, flat / 'flutter' → (현재 없음, 향후 flutter-* 추가 시 노출).
+ */
+export function getArchesForPlatform(platform) {
+  return allArchitectures.filter((a) => a.platforms.includes(platform));
+}
+
+/**
+ * 주어진 arch 가 platform 과 호환되는지 검증. 호환 안 되면 친절한 에러.
+ * generator/cli-args 양쪽에서 호출.
+ */
+export function assertArchPlatformCompat(archName, platform) {
+  const arch = getArchByName(archName);
+  if (!arch.platforms.includes(platform)) {
+    const supported = getArchesForPlatform(platform).map((a) => a.name).join(', ') || '(없음)';
+    throw new Error(
+      `--arch=${archName} 는 platform=${platform} 와 호환되지 않습니다. ` +
+      `${platform} 에서 사용 가능: ${supported}`,
+    );
+  }
+  return arch;
+}

package/src/create/cli-args.js

@@ -5,12 +5,14 @@ import {
   CSS_FRAMEWORKS_PLANNED,
 } from '../constants.js';
 import { allPlugins } from './plugins/index.js';
+import { allArchitectures } from './architectures/index.js';
 
 const VALID_PLATFORMS = CREATE_PLATFORMS;
 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'];
+const VALUE_FLAGS = ['platform', 'structure', 'plugins', 'theme', 'app', 'css', 'arch'];
 const BOOL_FLAGS = ['yes', 'help', 'dry-run'];
 
 const SUBCOMMANDS = ['add-app', 'add-component'];
@@ -68,6 +70,11 @@ export const parseArgs = (argv) => {
     if (name === 'structure' && !VALID_STRUCTURES.includes(value)) {
       throw new Error(`--structure 는 ${VALID_STRUCTURES.join('/')} 중 하나여야 함 (받은 값: ${value})`);
     }
+    if (name === 'arch' && !VALID_ARCHES.includes(value)) {
+      throw new Error(
+        `--arch 는 ${VALID_ARCHES.join('/')} 중 하나여야 함 (받은 값: ${value})`,
+      );
+    }
     if (name === 'css' && !CSS_FRAMEWORKS_SUPPORTED.includes(value)) {
       // planned 값은 '곧 옵니다' 신호로 분기 — 사용자 의도가 더 명확히 전달.
       if (CSS_FRAMEWORKS_PLANNED.includes(value)) {