@mandujs/cli 0.18.0 → 0.18.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/cli",
-  "version": "0.18.0",
+  "version": "0.18.3",
   "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
   "type": "module",
   "main": "./src/main.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "0.18.0",
-    "@mandujs/ate": "0.17.0",
+    "@mandujs/core": "^0.18.4",
+    "@mandujs/ate": "^0.17.0",
     "cfonts": "^3.3.0"
   },
   "engines": {

package/src/commands/build.ts

@@ -120,7 +120,7 @@ export async function build(options: BuildOptions = {}): Promise<boolean> {
     console.log("\n👀 파일 감시 모드...");
     console.log("   Ctrl+C로 종료\n");
 
-    await watchAndRebuild(manifest, cwd, resolvedBuildOptions);
+    await watchAndRebuild(cwd, resolvedBuildOptions, { fsRoutes: config.fsRoutes });
   }
 
   return true;
@@ -128,49 +128,79 @@ export async function build(options: BuildOptions = {}): Promise<boolean> {
 
 /**
  * 파일 감시 및 재빌드
+ * FS Routes 프로젝트: app/ 디렉토리의 island 파일 감시
+ *
+ * 파일 변경 시마다 resolveManifest를 재호출하여 새로 추가/삭제된
+ * 라우트가 번들에 반영되도록 합니다.
  */
 async function watchAndRebuild(
-  manifest: RoutesManifest,
   rootDir: string,
-  options: BuildOptions
+  options: BuildOptions,
+  resolveOptions: Parameters<typeof resolveManifest>[1] = {}
 ): Promise<void> {
+  // FS Routes 프로젝트는 app/ 디렉토리를, 구버전은 spec/slots/ 감시
+  const fsRoutesDir = path.join(rootDir, "app");
   const slotsDir = path.join(rootDir, "spec", "slots");
 
-  // 디렉토리 존재 확인
+  let watchDir: string;
+  let watchMode: "fs-routes" | "slots";
+
   try {
-    await fs.access(slotsDir);
+    await fs.access(fsRoutesDir);
+    watchDir = fsRoutesDir;
+    watchMode = "fs-routes";
   } catch {
-    console.warn(`⚠️  슬롯 디렉토리가 없습니다: ${slotsDir}`);
-    return;
+    try {
+      await fs.access(slotsDir);
+      watchDir = slotsDir;
+      watchMode = "slots";
+    } catch {
+      console.warn(`⚠️  감시할 디렉토리가 없습니다 (app/ 또는 spec/slots/)`);
+      return;
+    }
   }
 
+  console.log(`👀 감시 중: ${watchDir}`);
+
   const { watch } = await import("fs");
 
-  const watcher = watch(slotsDir, { recursive: true }, async (event, filename) => {
+  const watcher = watch(watchDir, { recursive: true }, async (event, filename) => {
     if (!filename) return;
 
-    // .client.ts 파일만 감시
-    if (!filename.endsWith(".client.ts")) return;
-
-    const routeId = filename.replace(".client.ts", "").replace(/\\/g, "/").split("/").pop();
-    if (!routeId) return;
-
-    const route = manifest!.routes.find((r) => r.id === routeId);
-    if (!route || !route.clientModule) return;
+    const normalizedFilename = filename.replace(/\\/g, "/");
+
+    // FS Routes: island 파일 변경 감지
+    if (watchMode === "fs-routes") {
+      const isIslandFile =
+        normalizedFilename.endsWith(".island.tsx") ||
+        normalizedFilename.endsWith(".island.ts") ||
+        normalizedFilename.endsWith(".island.jsx") ||
+        normalizedFilename.endsWith(".island.js");
+      // 루트 레벨(page.tsx) 및 중첩 경로(/nested/page.tsx) 모두 감지, .js/.jsx 포함
+      const isPageFile = /(?:^|\/)page\.[jt]sx?$/.test(normalizedFilename);
+
+      if (!isIslandFile && !isPageFile) return;
+    } else {
+      // Slots: .client.ts 파일만 감시
+      if (!normalizedFilename.endsWith(".client.ts")) return;
+    }
 
-    console.log(`\n🔄 변경 감지: ${routeId}`);
+    console.log(`\n🔄 변경 감지: ${normalizedFilename}`);
 
     try {
-      const result = await buildClientBundles(manifest!, rootDir, {
+      // 파일 추가/삭제 반영을 위해 매 재빌드마다 매니페스트 재조회
+      const { manifest: freshManifest } = await resolveManifest(rootDir, resolveOptions);
+
+      const result = await buildClientBundles(freshManifest, rootDir, {
         minify: options.minify,
         sourcemap: options.sourcemap,
         outDir: options.outDir,
       });
 
       if (result.success) {
-        console.log(`✅ 재빌드 완료: ${routeId}`);
+        console.log(`✅ 재빌드 완료`);
       } else {
-        console.error(`❌ 재빌드 실패: ${routeId}`);
+        console.error(`❌ 재빌드 실패`);
         for (const error of result.errors) {
           console.error(`   ${error}`);
         }

package/src/commands/dev.ts

@@ -196,7 +196,9 @@ export async function dev(options: DevOptions = {}): Promise<void> {
   });
 
   if (port !== desiredPort) {
-    console.warn(`⚠️  Port ${desiredPort} is in use. Using ${port} instead.`);
+    console.warn(`⚠️  Port ${desiredPort} is in use.`);
+    console.warn(`    Dev server:    http://localhost:${port}`);
+    console.warn(`    HMR WebSocket: ws://localhost:${port + HMR_OFFSET}`);
   }
 
   // HMR 서버 시작 (클라이언트 슬롯이 있는 경우)

package/src/commands/lock.ts

@@ -284,24 +284,29 @@ async function showDiff(
     return false;
   }
 
-  // 스냅샷이 없으면 diff 불가
+  // 스냅샷이 없으면 전체 설정을 변경사항으로 표시
   if (!lockfile.snapshot) {
     if (json) {
       console.log(
         JSON.stringify({
-          success: false,
-          error: "SNAPSHOT_MISSING",
-          message:
-            "Lockfile에 스냅샷이 없습니다. '--include-snapshot' 옵션으로 다시 생성하세요.",
+          success: true,
+          warning: "SNAPSHOT_MISSING",
+          message: "스냅샷이 없어 전체 설정을 변경사항으로 표시",
+          hasChanges: true,
         })
       );
     } else {
-      console.error("❌ Lockfile에 스냅샷이 없습니다.");
-      console.error(
-        "   'mandu lock --include-snapshot' 옵션으로 다시 생성하세요."
-      );
+      console.log("⚠️  Lockfile에 스냅샷이 없습니다.");
+      console.log("   전체 설정을 변경사항으로 표시합니다.");
+      console.log("   정확한 diff를 보려면: mandu lock --include-snapshot\n");
     }
-    return false;
+
+    // Show entire config as additions
+    const { mcpServers } = resolveMcpSources(config, mcpConfig);
+    const configForDiff = mcpServers ? { ...config, mcpServers } : config;
+    const fullDiff = diffConfig({}, configForDiff);
+    console.log(formatConfigDiff(fullDiff, { color: true, verbose: true, showSecrets }));
+    return true;
   }
 
   // diff 계산

package/src/commands/start.ts

@@ -124,6 +124,11 @@ export async function start(options: StartOptions = {}): Promise<void> {
     console.warn(`⚠️  Port ${desiredPort} is in use. Using ${port} instead.`);
   }
 
+  // CSS 경로 결정 (빌드된 CSS 파일 존재 시 주입)
+  const cssFilePath = path.join(rootDir, ".mandu", "client", "globals.css");
+  const hasCss = fs.existsSync(cssFilePath);
+  const cssPath: string | false = hasCss ? "/.mandu/client/globals.css" : false;
+
   // 메인 서버 시작 (프로덕션 모드)
   const server = startServer(manifest, {
     port,
@@ -134,6 +139,7 @@ export async function start(options: StartOptions = {}): Promise<void> {
     cors: serverConfig.cors,
     streaming: serverConfig.streaming,
     rateLimit: serverConfig.rateLimit,
+    cssPath,
   });
 
   const actualPort = server.server.port ?? port;

package/src/commands/test-auto.ts

@@ -17,7 +17,7 @@ export async function testAuto(opts: { ci?: boolean; impact?: boolean; baseURL?:
     let onlyRoutes: string[] | undefined;
     let impactInfo: any = { mode: "full", changedFiles: [], selectedRoutes: [] };
     if (opts.impact) {
-      const impactRes = ateImpact({ repoRoot });
+      const impactRes = await ateImpact({ repoRoot });
       onlyRoutes = impactRes.selectedRoutes.length ? impactRes.selectedRoutes : undefined;
       impactInfo = {
         mode: onlyRoutes ? "subset" : "full",
@@ -27,7 +27,7 @@ export async function testAuto(opts: { ci?: boolean; impact?: boolean; baseURL?:
     }
 
     // 3) generate
-    const genRes = ateGenerate({ repoRoot, oracleLevel, onlyRoutes });
+    const genRes = await ateGenerate({ repoRoot, oracleLevel, onlyRoutes });
 
     // 4) run
     const runRes = await ateRun({ repoRoot, ci: opts.ci, headless: opts.ci, baseURL: opts.baseURL });

package/src/errors/messages.ts

@@ -1,143 +1,147 @@
-import { CLI_ERROR_CODES, type CLIErrorCode } from "./codes";
-
-interface ErrorInfo {
-  message: string;
-  suggestion?: string;
-  docLink?: string;
-}
-
-export const ERROR_MESSAGES: Record<CLIErrorCode, ErrorInfo> = {
-  [CLI_ERROR_CODES.INIT_DIR_EXISTS]: {
-    message: "Directory already exists: {path}",
-    suggestion: "Choose a different project name or remove the existing directory.",
-  },
-  [CLI_ERROR_CODES.INIT_BUN_NOT_FOUND]: {
-    message: "Bun runtime not found.",
-    suggestion: "Install Bun and ensure it is available in your PATH.",
-  },
-  [CLI_ERROR_CODES.INIT_TEMPLATE_NOT_FOUND]: {
-    message: "Template not found: {template}",
-    suggestion: "Use a valid template name (default).",
-  },
-  [CLI_ERROR_CODES.DEV_PORT_IN_USE]: {
-    message: "Port {port} is already in use.",
-    suggestion: "Set PORT or mandu.config server.port to pick a different port, or stop the process using this port.",
-  },
-  [CLI_ERROR_CODES.DEV_MANIFEST_NOT_FOUND]: {
-    message: "Routes manifest not found.",
-    suggestion: "Run `mandu routes generate` or create app/ routes before dev.",
-  },
-  [CLI_ERROR_CODES.DEV_NO_ROUTES]: {
-    message: "No routes were found in app/.",
-    suggestion: "Create app/page.tsx or app/api/*/route.ts to get started.",
-  },
-  [CLI_ERROR_CODES.GUARD_CONFIG_INVALID]: {
-    message: "Invalid guard configuration.",
-    suggestion: "Check your mandu.config and guard settings.",
-  },
-  [CLI_ERROR_CODES.GUARD_PRESET_NOT_FOUND]: {
-    message: "Unknown architecture preset: {preset}",
-    suggestion: "Available presets: mandu, fsd, clean, hexagonal, atomic.",
-  },
-  [CLI_ERROR_CODES.GUARD_VIOLATION_FOUND]: {
-    message: "{count} architecture violation(s) found.",
-    suggestion: "Fix violations above or set MANDU_OUTPUT=agent for AI-friendly output.",
-  },
-  [CLI_ERROR_CODES.BUILD_ENTRY_NOT_FOUND]: {
-    message: "Build entry not found: {entry}",
-    suggestion: "Check your routes manifest or build inputs.",
-  },
-  [CLI_ERROR_CODES.BUILD_BUNDLE_FAILED]: {
-    message: "Bundle build failed for '{target}'.",
-    suggestion: "Review build errors above for missing deps or syntax errors.",
-  },
-  [CLI_ERROR_CODES.BUILD_OUTDIR_NOT_WRITABLE]: {
-    message: "Output directory is not writable: {path}",
-    suggestion: "Ensure the directory exists and you have write permissions.",
-  },
-  [CLI_ERROR_CODES.CONFIG_PARSE_FAILED]: {
-    message: "Failed to parse mandu.config.",
-    suggestion: "Fix syntax errors in the config file.",
-  },
-  [CLI_ERROR_CODES.CONFIG_VALIDATION_FAILED]: {
-    message: "Configuration validation failed.",
-    suggestion: "Review validation errors above and fix your config.",
-  },
-  [CLI_ERROR_CODES.UNKNOWN_COMMAND]: {
-    message: "Unknown command: {command}",
-    suggestion: "Run with --help to see available commands.",
-  },
-  [CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND]: {
-    message: "Unknown subcommand '{subcommand}' for {command}.",
-    suggestion: "Run the command with --help to see available subcommands.",
-  },
-  [CLI_ERROR_CODES.MISSING_ARGUMENT]: {
-    message: "Missing required argument: {argument}",
-    suggestion: "Provide the required argument and try again.",
-  },
-};
-
-function interpolate(text: string, context?: Record<string, string | number>): string {
-  if (!context) return text;
-  let result = text;
-  for (const [key, value] of Object.entries(context)) {
-    result = result.replace(new RegExp(`\\{${key}\\}`, "g"), String(value));
-  }
-  return result;
-}
-
-export function formatCLIError(
-  code: CLIErrorCode,
-  context?: Record<string, string | number>
-): string {
-  const info = ERROR_MESSAGES[code];
-  const message = interpolate(info?.message ?? "Unknown error", context);
-  const suggestion = info?.suggestion ? interpolate(info.suggestion, context) : undefined;
-
-  const lines = ["", `❌ Error [${code}]`, `   ${message}`];
-  if (suggestion) {
-    lines.push("", `💡 ${suggestion}`);
-  }
-  if (info?.docLink) {
-    lines.push(`📖 ${info.docLink}`);
-  }
-  lines.push("");
-  return lines.join("\n");
-}
-
-export class CLIError extends Error {
-  readonly code: CLIErrorCode;
-  readonly context?: Record<string, string | number>;
-
-  constructor(code: CLIErrorCode, context?: Record<string, string | number>) {
-    super(formatCLIError(code, context));
-    this.code = code;
-    this.context = context;
-    this.name = "CLIError";
-  }
-}
-
-export function printCLIError(
-  code: CLIErrorCode,
-  context?: Record<string, string | number>
-): void {
-  console.error(formatCLIError(code, context));
-}
-
-export function handleCLIError(error: unknown): never {
-  if (error instanceof CLIError) {
-    console.error(error.message);
-    process.exit(1);
-  }
-
-  if (error instanceof Error) {
-    console.error(`\n❌ Unexpected error: ${error.message}\n`);
-    if (process.env.DEBUG) {
-      console.error(error.stack);
-    }
-    process.exit(1);
-  }
-
-  console.error("\n❌ Unknown error occurred\n");
-  process.exit(1);
-}
+import { CLI_ERROR_CODES, type CLIErrorCode } from "./codes";
+
+interface ErrorInfo {
+  message: string;
+  suggestion?: string;
+  docLink?: string;
+}
+
+export const ERROR_MESSAGES: Record<CLIErrorCode, ErrorInfo> = {
+  [CLI_ERROR_CODES.INIT_DIR_EXISTS]: {
+    message: "Directory already exists: {path}",
+    suggestion: "Choose a different project name or remove the existing directory.",
+  },
+  [CLI_ERROR_CODES.INIT_BUN_NOT_FOUND]: {
+    message: "Bun runtime not found.",
+    suggestion: "Install Bun and ensure it is available in your PATH.",
+  },
+  [CLI_ERROR_CODES.INIT_TEMPLATE_NOT_FOUND]: {
+    message: "Template not found: {template}",
+    suggestion: "Use a valid template name (default).",
+  },
+  [CLI_ERROR_CODES.DEV_PORT_IN_USE]: {
+    message: "Port {port} is already in use.",
+    suggestion: "Set PORT or mandu.config server.port to pick a different port, or stop the process using this port.",
+  },
+  [CLI_ERROR_CODES.DEV_MANIFEST_NOT_FOUND]: {
+    message: "Routes manifest not found.",
+    suggestion: "Run `mandu routes generate` or create app/ routes before dev.",
+  },
+  [CLI_ERROR_CODES.DEV_NO_ROUTES]: {
+    message: "No routes were found in app/.",
+    suggestion: "Create app/page.tsx or app/api/*/route.ts to get started.",
+  },
+  [CLI_ERROR_CODES.GUARD_CONFIG_INVALID]: {
+    message: "Invalid guard configuration.",
+    suggestion: "Check your mandu.config and guard settings.",
+  },
+  [CLI_ERROR_CODES.GUARD_PRESET_NOT_FOUND]: {
+    message: "Unknown architecture preset: {preset}",
+    suggestion: "Available presets: mandu, fsd, clean, hexagonal, atomic.",
+  },
+  [CLI_ERROR_CODES.GUARD_VIOLATION_FOUND]: {
+    message: "{count} architecture violation(s) found.",
+    suggestion: "Fix violations above or set MANDU_OUTPUT=agent for AI-friendly output.",
+  },
+  [CLI_ERROR_CODES.BUILD_ENTRY_NOT_FOUND]: {
+    message: "Build entry not found: {entry}",
+    suggestion: "Check your routes manifest or build inputs.",
+  },
+  [CLI_ERROR_CODES.BUILD_BUNDLE_FAILED]: {
+    message: "Bundle build failed for '{target}'.",
+    suggestion: "Review build errors above for missing deps or syntax errors.",
+  },
+  [CLI_ERROR_CODES.BUILD_OUTDIR_NOT_WRITABLE]: {
+    message: "Output directory is not writable: {path}",
+    suggestion: "Ensure the directory exists and you have write permissions.",
+  },
+  [CLI_ERROR_CODES.CONFIG_PARSE_FAILED]: {
+    message: "Failed to parse mandu.config.",
+    suggestion: "Fix syntax errors in the config file.",
+  },
+  [CLI_ERROR_CODES.CONFIG_VALIDATION_FAILED]: {
+    message: "Configuration validation failed.",
+    suggestion: "Review validation errors above and fix your config.",
+  },
+  [CLI_ERROR_CODES.UNKNOWN_COMMAND]: {
+    message: "Unknown command: {command}",
+    suggestion: "Run with --help to see available commands.",
+  },
+  [CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND]: {
+    message: "Unknown subcommand '{subcommand}' for {command}.",
+    suggestion: "Run the command with --help to see available subcommands.",
+  },
+  [CLI_ERROR_CODES.MISSING_ARGUMENT]: {
+    message: "Missing required argument: {argument}",
+    suggestion: "Provide the required argument and try again.",
+  },
+};
+
+function interpolate(text: string, context?: Record<string, string | number>): string {
+  if (!context) return text;
+  let result = text;
+  for (const [key, value] of Object.entries(context)) {
+    result = result.replace(new RegExp(`\\{${key}\\}`, "g"), String(value));
+  }
+  return result;
+}
+
+export function formatCLIError(
+  code: CLIErrorCode,
+  context?: Record<string, string | number>
+): string {
+  const info = ERROR_MESSAGES[code];
+  const message = interpolate(info?.message ?? "Unknown error", context);
+  const suggestion = info?.suggestion ? interpolate(info.suggestion, context) : undefined;
+
+  const lines = ["", `❌ Error [${code}]`, `   ${message}`];
+  if (suggestion) {
+    lines.push("", `💡 ${suggestion}`);
+  }
+  if (info?.docLink) {
+    lines.push(`📖 ${info.docLink}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+export class CLIError extends Error {
+  readonly code: CLIErrorCode;
+  readonly context?: Record<string, string | number>;
+
+  constructor(code: CLIErrorCode, context?: Record<string, string | number>) {
+    super(formatCLIError(code, context));
+    this.code = code;
+    this.context = context;
+    this.name = "CLIError";
+  }
+}
+
+export function printCLIError(
+  code: CLIErrorCode,
+  context?: Record<string, string | number>
+): void {
+  console.error(formatCLIError(code, context));
+}
+
+export function handleCLIError(error: unknown): never {
+  if (error instanceof CLIError) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  if (error instanceof Error) {
+    console.error(`\n❌ Unexpected error: ${error.message}\n`);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+
+  console.error("\n❌ Unknown error occurred (non-Error thrown)\n");
+  if (process.env.DEBUG) {
+    // eslint-disable-next-line no-console
+    console.error("Thrown value:", error);
+  }
+  process.exit(1);
+}

package/templates/default/AGENTS.md

@@ -1,96 +1,109 @@
-# AI Agent Instructions for Mandu Project
-
-이 프로젝트는 **Mandu Framework**로 구축되었습니다. AI 에이전트가 이 프로젝트를 다룰 때 아래 지침을 따라주세요.
-
-## 패키지 매니저: Bun (필수)
-
-**⚠️ 중요: 이 프로젝트는 Bun만 사용합니다. npm/yarn/pnpm을 사용하지 마세요.**
-
-```bash
-# ✅ 올바른 명령어
-bun install              # 의존성 설치
-bun add <package>        # 패키지 추가
-bun remove <package>     # 패키지 제거
-bun run dev              # 개발 서버 시작
-bun run build            # 프로덕션 빌드
-bun test                 # 테스트 실행
-
-# ❌ 사용 금지
-npm install / yarn install / pnpm install
-```
-
-## 프로젝트 구조
-
-```
-├── app/                  # FS 기반 라우팅 (페이지, API)
-│   ├── page.tsx         # / 라우트
-│   ├── layout.tsx       # 루트 레이아웃
-│   ├── globals.css      # Tailwind CSS (v4)
-│   └── api/             # API 라우트
-├── src/
-│   ├── client/          # 클라이언트 코드 (FSD 구조)
-│   │   ├── shared/      # 공용 UI, 유틸리티
-│   │   ├── entities/    # 엔티티 컴포넌트
-│   │   ├── features/    # 기능 컴포넌트
-│   │   └── widgets/     # 위젯/Island 컴포넌트
-│   ├── server/          # 서버 코드 (Clean Architecture)
-│   │   ├── domain/      # 도메인 모델
-│   │   ├── application/ # 비즈니스 로직
-│   │   └── infra/       # 인프라/DB
-│   └── shared/          # 클라이언트-서버 공유 코드
-│       ├── contracts/   # API 계약 타입
-│       └── types/       # 공용 타입
-└── mandu.config.ts      # Mandu 설정 (선택)
-```
-
-## 주요 규칙
-
-### 1. Island 컴포넌트
-클라이언트 상호작용이 필요한 컴포넌트는 `*.island.tsx`로 명명:
-```tsx
-// src/client/widgets/counter/Counter.island.tsx
-"use client";
-export function CounterIsland() { ... }
-```
-
-### 2. API 라우트
-`app/api/` 폴더에 `route.ts` 파일로 정의:
-```typescript
-// app/api/users/route.ts
-import { Mandu } from "@mandujs/core";
-export default Mandu.filling()
-  .get((ctx) => ctx.ok({ users: [] }))
-  .post(async (ctx) => { ... });
-```
-
-### 3. Tailwind CSS v4
-CSS-first 설정 사용 (`tailwind.config.ts` 없음):
-```css
-/* app/globals.css */
-@import "tailwindcss";
-@theme {
-  --color-primary: hsl(222.2 47.4% 11.2%);
-}
-```
-
-### 4. Import Alias
-`@/` = `src/` 경로:
-```typescript
-import { Button } from "@/client/shared/ui/button";
-```
-
-## 실행 방법
-
-```bash
-bun install     # 최초 설치
-bun run dev     # 개발 서버 (http://localhost:4000)
-bun run build   # 프로덕션 빌드
-bun run guard   # 아키텍처 검증
-```
-
-## 기술 스택
-
-- **Runtime**: Bun 1.x
-- **Framework**: Mandu (React 19 + Bun native)
-- **Styling**: Tailwind CSS v4
-- **Language**: TypeScript 5.x
+# AI Agent Instructions for Mandu Project
+
+이 프로젝트는 **Mandu Framework**로 구축되었습니다. AI 에이전트가 이 프로젝트를 다룰 때 아래 지침을 따라주세요.
+
+## 패키지 매니저: Bun (필수)
+
+**⚠️ 중요: 이 프로젝트는 Bun만 사용합니다. npm/yarn/pnpm을 사용하지 마세요.**
+
+```bash
+# ✅ 올바른 명령어
+bun install              # 의존성 설치
+bun add <package>        # 패키지 추가
+bun remove <package>     # 패키지 제거
+bun run dev              # 개발 서버 시작
+bun run build            # 프로덕션 빌드
+bun test                 # 테스트 실행
+
+# ❌ 사용 금지
+npm install / yarn install / pnpm install
+```
+
+## 프로젝트 구조
+
+```
+├── app/                  # FS 기반 라우팅 (페이지, API)
+│   ├── page.tsx         # / 라우트
+│   ├── layout.tsx       # 루트 레이아웃
+│   ├── globals.css      # Tailwind CSS (v4)
+│   └── api/             # API 라우트
+├── src/
+│   ├── client/          # 클라이언트 코드 (FSD 구조)
+│   │   ├── shared/      # 공용 UI, 유틸리티
+│   │   ├── entities/    # 엔티티 컴포넌트
+│   │   ├── features/    # 기능 컴포넌트
+│   │   └── widgets/     # 위젯/Island 컴포넌트
+│   ├── server/          # 서버 코드 (Clean Architecture)
+│   │   ├── domain/      # 도메인 모델
+│   │   ├── application/ # 비즈니스 로직
+│   │   └── infra/       # 인프라/DB
+│   └── shared/          # 클라이언트-서버 공유 코드
+│       ├── contracts/   # API 계약 타입
+│       └── types/       # 공용 타입
+└── mandu.config.ts      # Mandu 설정 (선택)
+```
+
+## 주요 규칙
+
+### 1. Layout 컴포넌트
+`html/head/body` 태그는 Mandu SSR이 자동으로 생성합니다. Layout은 body 내부 래퍼만 정의합니다:
+```tsx
+// app/layout.tsx
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-background font-sans antialiased">
+      {children}
+    </div>
+  );
+}
+```
+
+### 2. Island 컴포넌트
+클라이언트 상호작용이 필요한 컴포넌트는 `*.island.tsx`로 명명:
+```tsx
+// src/client/widgets/counter/Counter.island.tsx
+"use client";
+export function CounterIsland() { ... }
+```
+
+### 3. API 라우트
+`app/api/` 폴더에 `route.ts` 파일로 정의:
+```typescript
+// app/api/users/route.ts
+import { Mandu } from "@mandujs/core";
+export default Mandu.filling()
+  .get((ctx) => ctx.ok({ users: [] }))
+  .post(async (ctx) => { ... });
+```
+
+### 4. Tailwind CSS v4
+CSS-first 설정 사용 (`tailwind.config.ts` 없음):
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@theme {
+  --color-primary: hsl(222.2 47.4% 11.2%);
+}
+```
+
+### 5. Import Alias
+`@/` = `src/` 경로:
+```typescript
+import { Button } from "@/client/shared/ui/button";
+```
+
+## 실행 방법
+
+```bash
+bun install     # 최초 설치
+bun run dev     # 개발 서버 (http://localhost:3333)
+bun run build   # 프로덕션 빌드
+bun run guard   # 아키텍처 검증
+```
+
+## 기술 스택
+
+- **Runtime**: Bun 1.x
+- **Framework**: Mandu (React 19 + Bun native)
+- **Styling**: Tailwind CSS v4
+- **Language**: TypeScript 5.x

package/templates/default/app/layout.tsx

@@ -1,27 +1,20 @@
-/**
- * Root Layout
- *
- * 모든 페이지의 공통 레이아웃
- * globals.css를 여기서 임포트
- */
-
-import "./globals.css";
-
-interface RootLayoutProps {
-  children: React.ReactNode;
-}
-
-export default function RootLayout({ children }: RootLayoutProps) {
-  return (
-    <html lang="ko">
-      <head>
-        <meta charSet="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>{{PROJECT_NAME}}</title>
-      </head>
-      <body className="min-h-screen bg-background font-sans antialiased">
-        {children}
-      </body>
-    </html>
-  );
-}
+/**
+ * Root Layout
+ *
+ * 모든 페이지의 공통 레이아웃
+ * - html/head/body 태그는 Mandu SSR이 자동으로 생성합니다
+ * - 여기서는 body 내부의 공통 래퍼만 정의합니다
+ * - CSS는 Mandu가 자동으로 주입합니다: /.mandu/client/globals.css
+ */
+
+interface RootLayoutProps {
+  children: React.ReactNode;
+}
+
+export default function RootLayout({ children }: RootLayoutProps) {
+  return (
+    <div className="min-h-screen bg-background font-sans antialiased">
+      {children}
+    </div>
+  );
+}

package/templates/default/package.json

@@ -8,11 +8,14 @@
   },
   "scripts": {
     "dev": "mandu dev",
+    "dev:safe": "mandu lock && mandu dev",
     "build": "mandu build",
     "start": "mandu start",
     "check": "mandu check",
     "guard": "mandu guard",
-    "test": "bun test"
+    "test": "bun test",
+    "test:auto": "mandu test:auto",
+    "test:e2e:ci": "mandu test:auto --ci"
   },
   "dependencies": {
     "@mandujs/core": "{{CORE_VERSION}}",