sh-ui-cli 0.57.0 → 0.58.1

package/data/changelog/versions.json

@@ -2,6 +2,33 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$description": "sh-ui 릴리즈 노트 단일 소스. docs(React)와 showcase(Flutter)가 함께 읽는다. 새 릴리즈마다 맨 앞에 추가.",
   "versions": [
+    {
+      "version": "0.58.1",
+      "date": "2026-05-06",
+      "title": "fix — Sidebar focus trap 의 TS strict 위반 (firstEl/lastEl possibly undefined)",
+      "type": "patch",
+      "highlights": [
+        "**Sidebar `useFocusTrap` 의 TS strict 위반 해소** — `items.length === 0` 가드 후에도 `items[0]` / `items[items.length - 1]` 가 `possibly undefined` 로 잡혀 사용자 프로젝트 (strict tsconfig) 에서 typecheck 실패하던 문제. 가드를 `firstEl`/`lastEl` 직접 null-check 로 재구성 — 동작 동일, TS 만족. 사용자가 sh-ui Sidebar 컴포넌트를 add 후 본인 프로젝트에서 `tsc --noEmit` 돌릴 때 막히던 케이스 해소."
+      ],
+      "url": "https://github.com/sanghyeonKim0201/sh-ui/releases/tag/v0.58.1"
+    },
+    {
+      "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",

package/data/registry/react/components/sidebar/index.tsx

@@ -51,12 +51,12 @@ function useFocusTrap(
       }
       if (e.key !== "Tab") return;
       const items = focusables();
-      if (items.length === 0) {
+      const firstEl = items[0];
+      const lastEl = items[items.length - 1];
+      if (!firstEl || !lastEl) {
         e.preventDefault();
         return;
       }
-      const firstEl = items[0];
-      const lastEl = items[items.length - 1];
       if (e.shiftKey && document.activeElement === firstEl) {
         e.preventDefault();
         lastEl.focus();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh-ui-cli",
-  "version": "0.57.0",
+  "version": "0.58.1",
   "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)) {

package/src/create/generator.js

@@ -4,6 +4,11 @@ import fs from 'fs-extra';
 import os from 'node:os';
 import path from 'node:path';
 import { getPluginChoices, getPluginsByNames } from './plugins/index.js';
+import {
+  assertArchPlatformCompat,
+  getArchesForPlatform,
+  DEFAULT_ARCH,
+} from './architectures/index.js';
 import { resolveTheme } from './theme/decode.js';
 import { THEME_PRESETS, getThemePreset } from './theme/presets.js';
 import {
@@ -90,6 +95,19 @@ export async function createProject(options = {}) {
     ],
   });
 
+  // arch 결정 — platform 확정 후. 사용자가 --arch 미지정 시:
+  //   - next  → DEFAULT_ARCH ('fsd')
+  //   - flutter → 현재 Flutter arch 디스크립터 없음 → null. 미래에 flutter arch 추가되면
+  //     해당 platform 의 첫 번째 arch 또는 별도 default 로 변경.
+  // 명시한 경우 platform 호환성 검증 후 디스크립터 resolve. 잘못된 조합은 친절한 에러.
+  let arch = null;
+  if (platform === 'next') {
+    const archName = options.arch ?? DEFAULT_ARCH;
+    arch = assertArchPlatformCompat(archName, 'next');
+  } else if (platform === 'flutter' && options.arch) {
+    arch = assertArchPlatformCompat(options.arch, 'flutter');
+  }
+
   // CSS 프레임워크 — 현재는 plain 만 지원하지만, 곧 추가될 옵션을 disabled 로
   // 미리 노출해 사용자가 변종 시스템의 존재를 인지할 수 있게 한다.
   // Flutter 는 CSS 프레임워크 개념이 무의미하므로 자동 plain.
@@ -186,9 +204,9 @@ export async function createProject(options = {}) {
   plugins.sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
 
   if (projectType === 'standalone') {
-    await generateStandalone(targetDir, projectName, plugins, theme, cssFramework);
+    await generateStandalone(targetDir, projectName, plugins, theme, cssFramework, arch);
   } else {
-    await generateMonorepo(targetDir, projectName, plugins, { yes: options.yes, theme, css: cssFramework });
+    await generateMonorepo(targetDir, projectName, plugins, { yes: options.yes, theme, css: cssFramework, arch });
   }
 
   await finalizeProject(targetDir, { dryRun: options.dryRun });
@@ -267,7 +285,13 @@ export async function addApp() {
     return;
   }
 
-  await generateApp(appsDir, appName, port, plugins);
+  // addApp 은 기존 monorepo 의 새 앱 추가 — arch 는 일관성을 위해 모노레포가 처음
+  // 만들어질 때 정한 값과 같아야 한다. 현재는 root sh-ui.config.json 등에 별도 저장
+  // 안 해 두므로 일단 DEFAULT_ARCH (fsd) 로 fallback. 향후 root config 에 arch 박아두고
+  // 여기서 읽어오는 흐름으로 개선 가능.
+  const arch = assertArchPlatformCompat(DEFAULT_ARCH, 'next');
+
+  await generateApp(appsDir, appName, port, plugins, arch);
 
   console.log(`\n✅ apps/${appName} 이 추가되었습니다!`);
   console.log('\n  pnpm install');
@@ -355,8 +379,16 @@ async function generateFlutter(targetDir, projectName, theme, css) {
   await patchShUiConfig(path.join(targetDir, 'sh-ui.config.json'), css);
 }
 
-async function generateStandalone(targetDir, projectName, plugins, theme, css) {
-  await fs.copy(path.join(TEMPLATES_DIR, 'nextjs-standalone'), targetDir);
+async function generateStandalone(targetDir, projectName, plugins, theme, css, arch) {
+  // 베이스 (arch-neutral) + arch 오버레이 — generateApp 과 같은 패턴.
+  await fs.copy(path.join(TEMPLATES_DIR, 'nextjs-standalone'), targetDir, {
+    filter: (src) => !src.includes(`${path.sep}_arch${path.sep}`) && !src.endsWith(`${path.sep}_arch`),
+  });
+  await fs.copy(
+    path.join(TEMPLATES_DIR, 'nextjs-standalone', '_arch', arch.name),
+    targetDir,
+    { overwrite: true },
+  );
 
   // Update package.json
   const pkgPath = path.join(targetDir, 'package.json');
@@ -372,16 +404,16 @@ async function generateStandalone(targetDir, projectName, plugins, theme, css) {
   }
   await fs.writeJson(pkgPath, pkg, { spaces: 2 });
 
-  await writeNextConfig(targetDir, plugins, { isMonorepo: false });
+  await writeNextConfig(targetDir, plugins, { isMonorepo: false, arch });
   await appendEnvVars(path.join(targetDir, '.env.example'), plugins);
-  await writePluginFiles(targetDir, plugins);
-  await composeProviders(targetDir, plugins);
-  await applyTransforms(targetDir, plugins);
+  await writePluginFiles(targetDir, plugins, arch);
+  await composeProviders(targetDir, plugins, arch);
+  await applyTransforms(targetDir, plugins, arch);
   await injectCssTheme(targetDir, theme);
   await patchShUiConfig(path.join(targetDir, 'sh-ui.config.json'), css);
 }
 
-async function generateMonorepo(targetDir, projectName, plugins, { yes = false, theme, css } = {}) {
+async function generateMonorepo(targetDir, projectName, plugins, { yes = false, theme, css, arch } = {}) {
   await fs.copy(path.join(TEMPLATES_DIR, 'monorepo'), targetDir);
 
   // Update root package.json
@@ -412,14 +444,24 @@ async function generateMonorepo(targetDir, projectName, plugins, { yes = false,
   });
 
   const appsDir = path.join(targetDir, 'apps', appName);
-  await generateApp(appsDir, appName, port, plugins);
+  await generateApp(appsDir, appName, port, plugins, arch);
   const uiAppDir = path.join(targetDir, 'packages', 'ui', 'ui-apps', `ui-${appName}`);
   await injectCssTheme(uiAppDir, theme);
   await patchShUiConfig(path.join(uiAppDir, 'sh-ui.config.json'), css);
 }
 
-async function generateApp(targetDir, appName, port, plugins) {
-  await fs.copy(path.join(TEMPLATES_DIR, 'nextjs-app'), targetDir);
+async function generateApp(targetDir, appName, port, plugins, arch) {
+  // 베이스 템플릿 (arch-neutral 파일들) 만 카피 — _arch/ 디렉토리는 스킵.
+  // 그 후 선택된 arch 의 오버레이를 위에 머지해 arch-coupled 파일들 (layout.tsx,
+  // src/ 또는 lib+components/, tsconfig.json paths 블록 등) 을 떨어뜨린다.
+  await fs.copy(path.join(TEMPLATES_DIR, 'nextjs-app'), targetDir, {
+    filter: (src) => !src.includes(`${path.sep}_arch${path.sep}`) && !src.endsWith(`${path.sep}_arch`),
+  });
+  await fs.copy(
+    path.join(TEMPLATES_DIR, 'nextjs-app', '_arch', arch.name),
+    targetDir,
+    { overwrite: true },
+  );
 
   // Replace ui-app-name placeholder with actual app name in all files
   await replaceInAllFiles(targetDir, 'ui-app-name', `ui-${appName}`);
@@ -440,7 +482,7 @@ async function generateApp(targetDir, appName, port, plugins) {
   }
   await fs.writeJson(pkgPath, pkg, { spaces: 2 });
 
-  await writeNextConfig(targetDir, plugins, { isMonorepo: true, appName });
+  await writeNextConfig(targetDir, plugins, { isMonorepo: true, appName, arch });
 
   // Update Dockerfile
   const dockerPath = path.join(targetDir, 'Dockerfile');
@@ -461,9 +503,9 @@ async function generateApp(targetDir, appName, port, plugins) {
   }
 
   await appendEnvVars(path.join(targetDir, '.env.example'), plugins);
-  await writePluginFiles(targetDir, plugins);
-  await composeProviders(targetDir, plugins);
-  await applyTransforms(targetDir, plugins);
+  await writePluginFiles(targetDir, plugins, arch);
+  await composeProviders(targetDir, plugins, arch);
+  await applyTransforms(targetDir, plugins, arch);
 }
 
 // ─── Helpers ───
@@ -509,7 +551,7 @@ async function replaceInAllFiles(dir, search, replace) {
   }
 }
 
-async function writeNextConfig(targetDir, plugins, { isMonorepo, appName }) {
+async function writeNextConfig(targetDir, plugins, { isMonorepo, appName, arch }) {
   const imports = [`import type { NextConfig } from 'next';`];
   const preExport = [];
   let configBody;
@@ -535,7 +577,8 @@ async function writeNextConfig(targetDir, plugins, { isMonorepo, appName }) {
 
   for (const plugin of plugins) {
     if (plugin.imports) imports.push(...plugin.imports);
-    if (plugin.preExport) preExport.push(...plugin.preExport);
+    const pluginPreExport = resolveArchField(plugin.preExport, arch);
+    if (pluginPreExport) preExport.push(...pluginPreExport);
   }
 
   let exportExpr = 'nextConfig';
@@ -569,10 +612,25 @@ async function appendEnvVars(envPath, plugins) {
   }
 }
 
-async function writePluginFiles(targetDir, plugins) {
+/**
+ * 플러그인 manifest 의 함수형 필드를 arch 디스크립터로 평가해 정적 값으로 변환.
+ * Layer 1 에서는 모든 플러그인이 정적이라 사실상 no-op 분기. Layer 2 에서 플러그인이
+ * `files: (arch) => ({...})` 형태로 전환되면 이 헬퍼가 함수를 호출해 평가한다.
+ *
+ * arch 가 null (flutter 경로) 일 때는 함수형 필드는 빈 값으로 fallback —
+ * Flutter 에는 next-arch 가 없으므로 이런 플러그인이 호출되지 않아야 정상이지만
+ * 방어적 처리.
+ */
+function resolveArchField(field, arch) {
+  if (typeof field === 'function') return field(arch);
+  return field;
+}
+
+async function writePluginFiles(targetDir, plugins, arch) {
   for (const plugin of plugins) {
-    if (plugin.files) {
-      for (const [filePath, content] of Object.entries(plugin.files)) {
+    const files = resolveArchField(plugin.files, arch);
+    if (files) {
+      for (const [filePath, content] of Object.entries(files)) {
         const fullPath = path.join(targetDir, filePath);
         await fs.ensureDir(path.dirname(fullPath));
         await fs.writeFile(fullPath, content);
@@ -582,12 +640,15 @@ async function writePluginFiles(targetDir, plugins) {
 
   // auth-jwt + next-intl 동시 활성화 시 proxy.ts 병합
   // (각 플러그인이 단독으로 깐 proxy.ts 를 합친 버전으로 덮어쓴다)
+  // i18n routing import 는 arch.aliases.config 기준 — FSD 면 @/src/shared/config,
+  // flat 이면 @/lib/config 로 해석.
   const names = new Set(plugins.map((p) => p.name));
   if (names.has('auth-jwt') && names.has('next-intl')) {
+    const configAlias = arch ? arch.aliases.config : '@/src/shared/config';
     const mergedProxy = `import createIntlMiddleware from 'next-intl/middleware';
 import { NextRequest, NextResponse } from 'next/server';
 
-import { routing } from '@/src/shared/config/i18n/routing';
+import { routing } from '${configAlias}/i18n/routing';
 
 const AUTH_ROUTES = ['/sign-in', '/sign-up'];
 
@@ -635,18 +696,24 @@ export const config = {
   }
 }
 
-async function composeProviders(targetDir, plugins) {
+async function composeProviders(targetDir, plugins, arch) {
   const extraImports = [];
   const wrappers = [];
 
   for (const plugin of plugins) {
-    if (plugin.providerImports) extraImports.push(...plugin.providerImports);
-    if (plugin.providerWrappers) wrappers.push(...plugin.providerWrappers);
+    const providerImports = resolveArchField(plugin.providerImports, arch);
+    const providerWrappers = resolveArchField(plugin.providerWrappers, arch);
+    if (providerImports) extraImports.push(...providerImports);
+    if (providerWrappers) wrappers.push(...providerWrappers);
   }
 
   if (extraImports.length === 0 && wrappers.length === 0) return;
 
-  const globalProviderPath = path.join(targetDir, 'src/app/providers/GlobalProvider/index.tsx');
+  // GlobalProvider 위치는 arch.paths.providers 기준 — Layer 2 에서 플러그인이
+  // arch.aliases.providers 를 import 에 사용하게 되면 이 경로도 일관됨.
+  // arch 미지정 (legacy) 시 FSD 디폴트 fallback.
+  const providersDir = arch ? arch.paths.providers : 'src/app/providers';
+  const globalProviderPath = path.join(targetDir, providersDir, 'GlobalProvider', 'index.tsx');
   if (!(await fs.pathExists(globalProviderPath))) return;
 
   let content = await fs.readFile(globalProviderPath, 'utf-8');
@@ -674,11 +741,12 @@ async function composeProviders(targetDir, plugins) {
   await fs.writeFile(globalProviderPath, content);
 }
 
-async function applyTransforms(targetDir, plugins) {
+async function applyTransforms(targetDir, plugins, arch) {
   for (const plugin of plugins) {
-    if (!plugin.transforms) continue;
+    const transforms = resolveArchField(plugin.transforms, arch);
+    if (!transforms) continue;
 
-    for (const transform of plugin.transforms) {
+    for (const transform of transforms) {
       const { type } = transform;
 
       if (type === 'move') {
@@ -746,8 +814,9 @@ const OPTIONAL_DART_INJECTORS = [
 async function injectCssTheme(projectDir, theme) {
   if (!theme) return;
   const candidates = [
-    'src/shared/styles/tokens.css',
-    'src/styles/tokens.css',
+    'src/shared/styles/tokens.css',  // FSD standalone
+    'src/styles/tokens.css',          // monorepo ui-app-template (arch-neutral)
+    'lib/styles/tokens.css',          // flat standalone
   ];
   for (const rel of candidates) {
     const abs = path.join(projectDir, rel);