@mandujs/cli 0.9.12 → 0.9.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/cli",
-  "version": "0.9.12",
+  "version": "0.9.17",
   "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
   "type": "module",
   "main": "./src/main.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "0.9.10"
+    "@mandujs/core": "0.9.37"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/commands/dev.ts

@@ -1,13 +1,21 @@
 import {
-  loadManifest,
   startServer,
   registerApiHandler,
   registerPageLoader,
   registerPageHandler,
+  registerLayoutLoader,
   startDevBundler,
   createHMRServer,
   needsHydration,
   loadEnv,
+  generateManifest,
+  watchFSRoutes,
+  clearDefaultRegistry,
+  createGuardWatcher,
+  getPreset,
+  type RoutesManifest,
+  type GuardConfig,
+  type GuardPreset,
 } from "@mandujs/core";
 import { resolveFromCwd } from "../util/fs";
 import path from "path";
@@ -16,13 +24,18 @@ export interface DevOptions {
   port?: number;
   /** HMR 비활성화 */
   noHmr?: boolean;
+  /** FS Routes 비활성화 (레거시 모드) */
+  legacy?: boolean;
+  /** Architecture Guard 활성화 */
+  guard?: boolean;
+  /** Guard 프리셋 */
+  guardPreset?: GuardPreset;
 }
 
 export async function dev(options: DevOptions = {}): Promise<void> {
-  const specPath = resolveFromCwd("spec/routes.manifest.json");
   const rootDir = resolveFromCwd(".");
 
-  console.log(`🥟 Mandu Dev Server`);
+  console.log(`🥟 Mandu Dev Server (FS Routes)`);
 
   // .env 파일 로드
   const envResult = await loadEnv({
@@ -34,50 +47,93 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     console.log(`🔐 환경 변수 로드: ${envResult.loaded.join(", ")}`);
   }
 
-  console.log(`📄 Spec 파일: ${specPath}\n`);
+  // FS Routes 스캔
+  console.log(`📂 app/ 폴더 스캔 중...`);
 
-  const result = await loadManifest(specPath);
+  const result = await generateManifest(rootDir, {
+    skipLegacy: true,
+  });
 
-  if (!result.success || !result.data) {
-    console.error("❌ Spec 로드 실패:");
-    result.errors?.forEach((e) => console.error(`  - ${e}`));
+  if (result.manifest.routes.length === 0) {
+    console.log("");
+    console.log("📭 라우트가 없습니다.");
+    console.log("");
+    console.log("💡 app/ 폴더에 page.tsx 파일을 생성하세요:");
+    console.log("");
+    console.log("  app/page.tsx        → /");
+    console.log("  app/blog/page.tsx   → /blog");
+    console.log("  app/api/users/route.ts → /api/users");
+    console.log("");
     process.exit(1);
   }
 
-  const manifest = result.data;
-  console.log(`✅ Spec 로드 완료: ${manifest.routes.length}개 라우트`);
-
-  // 핸들러 등록
-  for (const route of manifest.routes) {
-    if (route.kind === "api") {
-      const modulePath = path.resolve(rootDir, route.module);
-      try {
-        const module = await import(modulePath);
-        registerApiHandler(route.id, module.default || module.handler);
-        console.log(`  📡 API: ${route.pattern} -> ${route.id}`);
-      } catch (error) {
-        console.error(`  ❌ API 핸들러 로드 실패: ${route.id}`, error);
-      }
-    } else if (route.kind === "page" && route.componentModule) {
-      const componentPath = path.resolve(rootDir, route.componentModule);
-      const isIsland = needsHydration(route);
-
-      // slotModule이 있으면 PageHandler 사용 (filling.loader 지원)
-      if (route.slotModule) {
-        registerPageHandler(route.id, async () => {
-          const module = await import(componentPath);
-          // module.default = { component, filling }
-          return module.default;
-        });
-        console.log(`  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}`);
-      } else {
-        // slotModule이 없으면 기존 PageLoader 사용
-        registerPageLoader(route.id, () => import(componentPath));
-        console.log(`  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}`);
+  let manifest = result.manifest;
+  console.log(`✅ ${manifest.routes.length}개 라우트 발견\n`);
+
+  // Layout 경로 추적 (중복 등록 방지)
+  const registeredLayouts = new Set<string>();
+
+  // 핸들러 등록 함수
+  const registerHandlers = async (manifest: RoutesManifest, isReload = false) => {
+    // 리로드 시 레이아웃 캐시 클리어
+    if (isReload) {
+      registeredLayouts.clear();
+    }
+
+    for (const route of manifest.routes) {
+      if (route.kind === "api") {
+        const modulePath = path.resolve(rootDir, route.module);
+        try {
+          // 캐시 무효화 (HMR용)
+          delete require.cache[modulePath];
+          const module = await import(modulePath);
+          registerApiHandler(route.id, module.default || module.handler || module);
+          console.log(`  📡 API: ${route.pattern} -> ${route.id}`);
+        } catch (error) {
+          console.error(`  ❌ API 핸들러 로드 실패: ${route.id}`, error);
+        }
+      } else if (route.kind === "page" && route.componentModule) {
+        const componentPath = path.resolve(rootDir, route.componentModule);
+        const isIsland = needsHydration(route);
+        const hasLayout = route.layoutChain && route.layoutChain.length > 0;
+
+        // Layout 로더 등록
+        if (route.layoutChain) {
+          for (const layoutPath of route.layoutChain) {
+            if (!registeredLayouts.has(layoutPath)) {
+              const absLayoutPath = path.resolve(rootDir, layoutPath);
+              registerLayoutLoader(layoutPath, async () => {
+                // 캐시 무효화 (HMR용)
+                delete require.cache[absLayoutPath];
+                return import(absLayoutPath);
+              });
+              registeredLayouts.add(layoutPath);
+              console.log(`  🎨 Layout: ${layoutPath}`);
+            }
+          }
+        }
+
+        // slotModule이 있으면 PageHandler 사용 (filling.loader 지원)
+        if (route.slotModule) {
+          registerPageHandler(route.id, async () => {
+            delete require.cache[componentPath];
+            const module = await import(componentPath);
+            return module.default;
+          });
+          console.log(`  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`);
+        } else {
+          registerPageLoader(route.id, () => {
+            delete require.cache[componentPath];
+            return import(componentPath);
+          });
+          console.log(`  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`);
+        }
       }
     }
-  }
+  };
 
+  // 초기 핸들러 등록
+  await registerHandlers(manifest);
   console.log("");
 
   const port = options.port || Number(process.env.PORT) || 3000;
@@ -98,28 +154,28 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     devBundler = await startDevBundler({
       rootDir,
       manifest,
-      onRebuild: (result) => {
-        if (result.success) {
-          if (result.routeId === "*") {
-            hmrServer?.broadcast({
-              type: "reload",
-              data: {
-                timestamp: Date.now(),
-              },
-            });
-          } else {
-            hmrServer?.broadcast({
-              type: "island-update",
-              data: {
-                routeId: result.routeId,
-                timestamp: Date.now(),
-              },
-            });
-          }
-        } else {
-          hmrServer?.broadcast({
-            type: "error",
-            data: {
+      onRebuild: (result) => {
+        if (result.success) {
+          if (result.routeId === "*") {
+            hmrServer?.broadcast({
+              type: "reload",
+              data: {
+                timestamp: Date.now(),
+              },
+            });
+          } else {
+            hmrServer?.broadcast({
+              type: "island-update",
+              data: {
+                routeId: result.routeId,
+                timestamp: Date.now(),
+              },
+            });
+          }
+        } else {
+          hmrServer?.broadcast({
+            type: "error",
+            data: {
               routeId: result.routeId,
               message: result.error,
             },
@@ -147,12 +203,80 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     bundleManifest: devBundler?.initialBuild.manifest,
   });
 
+  // Architecture Guard 실시간 감시 (선택적)
+  let archGuardWatcher: ReturnType<typeof createGuardWatcher> | null = null;
+
+  if (options.guard) {
+    const guardPreset = options.guardPreset || "mandu";
+    const guardConfig: GuardConfig = {
+      preset: guardPreset,
+      srcDir: "src",
+      realtime: true,
+    };
+
+    console.log(`🛡️  Architecture Guard 활성화 (${guardPreset})`);
+
+    archGuardWatcher = createGuardWatcher({
+      config: guardConfig,
+      rootDir,
+      onViolation: (violation) => {
+        // 실시간 경고는 watcher 내부에서 처리
+      },
+      onFileAnalyzed: (analysis, violations) => {
+        if (violations.length > 0) {
+          // HMR 에러로 브로드캐스트
+          hmrServer?.broadcast({
+            type: "guard-violation",
+            data: {
+              file: analysis.filePath,
+              violations: violations.map((v) => ({
+                line: v.line,
+                message: `${v.fromLayer} → ${v.toLayer}: ${v.ruleDescription}`,
+              })),
+            },
+          });
+        }
+      },
+    });
+
+    archGuardWatcher.start();
+  }
+
+  // FS Routes 실시간 감시
+  const routesWatcher = await watchFSRoutes(rootDir, {
+    skipLegacy: true,
+    onChange: async (result) => {
+      const timestamp = new Date().toLocaleTimeString();
+      console.log(`\n🔄 [${timestamp}] 라우트 변경 감지`);
+
+      // 레지스트리 클리어 (layout 캐시 포함)
+      clearDefaultRegistry();
+
+      // 새 매니페스트로 서버 업데이트
+      manifest = result.manifest;
+      console.log(`   📋 라우트: ${manifest.routes.length}개`);
+
+      // 라우트 재등록 (isReload = true)
+      await registerHandlers(manifest, true);
+
+      // HMR 브로드캐스트 (전체 리로드)
+      if (hmrServer) {
+        hmrServer.broadcast({
+          type: "reload",
+          data: { timestamp: Date.now() },
+        });
+      }
+    },
+  });
+
   // 정리 함수
   const cleanup = () => {
     console.log("\n🛑 서버 종료 중...");
     server.stop();
     devBundler?.close();
     hmrServer?.close();
+    routesWatcher.close();
+    archGuardWatcher?.close();
     process.exit(0);
   };
 

package/src/commands/guard-arch.ts

@@ -0,0 +1,238 @@
+/**
+ * mandu guard arch - Architecture Guard Command
+ *
+ * 실시간 아키텍처 감시 및 일회성 검사
+ */
+
+import {
+  createGuardWatcher,
+  checkDirectory,
+  printReport,
+  formatReportForAgent,
+  formatReportAsAgentJSON,
+  getPreset,
+  listPresets,
+  createScanRecord,
+  addScanRecord,
+  loadStatistics,
+  analyzeTrend,
+  calculateLayerStatistics,
+  generateMarkdownReport,
+  generateHTMLReport,
+  type GuardConfig,
+  type GuardPreset,
+} from "@mandujs/core";
+import { writeFile } from "fs/promises";
+import { resolveFromCwd } from "../util/fs";
+
+export interface GuardArchOptions {
+  /** 프리셋 이름 */
+  preset?: GuardPreset;
+  /** 실시간 감시 모드 */
+  watch?: boolean;
+  /** CI 모드 (에러 시 exit 1) */
+  ci?: boolean;
+  /** 출력 형식: console, agent, json */
+  format?: "console" | "agent" | "json";
+  /** 조용히 (요약만 출력) */
+  quiet?: boolean;
+  /** 소스 디렉토리 */
+  srcDir?: string;
+  /** 프리셋 목록 출력 */
+  listPresets?: boolean;
+  /** 리포트 파일 출력 */
+  output?: string;
+  /** 리포트 형식: json, markdown, html */
+  reportFormat?: "json" | "markdown" | "html";
+  /** 통계 저장 (트렌드 분석용) */
+  saveStats?: boolean;
+  /** 트렌드 분석 표시 */
+  showTrend?: boolean;
+}
+
+export async function guardArch(options: GuardArchOptions = {}): Promise<boolean> {
+  const {
+    preset = "mandu",
+    watch = false,
+    ci = false,
+    format = "console",
+    quiet = false,
+    srcDir = "src",
+    listPresets: showPresets = false,
+    output,
+    reportFormat = "markdown",
+    saveStats = false,
+    showTrend = false,
+  } = options;
+
+  const rootDir = resolveFromCwd(".");
+
+  // 프리셋 목록 출력
+  if (showPresets) {
+    console.log("");
+    console.log("🛡️  Mandu Guard - Available Presets");
+    console.log("");
+
+    const presets = listPresets();
+    for (const p of presets) {
+      const presetDef = getPreset(p.name);
+      console.log(`  ${p.name === "fsd" ? "✨ " : "  "}${p.name}`);
+      console.log(`     ${p.description}`);
+      console.log(`     Layers: ${presetDef.hierarchy.join(" → ")}`);
+      console.log("");
+    }
+
+    console.log("Usage: bunx mandu guard arch --preset <name>");
+    return true;
+  }
+
+  console.log("");
+  console.log("🛡️  Mandu Guard - Architecture Checker");
+  console.log("");
+  console.log(`📋 Preset: ${preset}`);
+  console.log(`📂 Source: ${srcDir}/`);
+  console.log(`🔧 Mode: ${watch ? "Watch" : "Check"}`);
+  console.log("");
+
+  // Guard 설정
+  const config: GuardConfig = {
+    preset,
+    srcDir,
+    realtime: watch,
+  };
+
+  // 실시간 감시 모드
+  if (watch) {
+    console.log("👁️  Watching for architecture violations...");
+    console.log("   Press Ctrl+C to stop\n");
+
+    const watcher = createGuardWatcher({
+      config,
+      rootDir,
+      onViolation: (violation) => {
+        // 실시간 위반 출력은 watcher 내부에서 처리됨
+      },
+      onFileAnalyzed: (analysis, violations) => {
+        if (violations.length > 0 && !quiet) {
+          const timestamp = new Date().toLocaleTimeString();
+          console.log(`[${timestamp}] ${analysis.filePath}: ${violations.length} violation(s)`);
+        }
+      },
+    });
+
+    watcher.start();
+
+    // Ctrl+C 핸들링
+    process.on("SIGINT", () => {
+      console.log("\n🛑 Guard stopped");
+      watcher.close();
+      process.exit(0);
+    });
+
+    // 계속 실행
+    return new Promise(() => {});
+  }
+
+  // 일회성 검사 모드
+  console.log("🔍 Scanning for architecture violations...\n");
+
+  const report = await checkDirectory(config, rootDir);
+  const presetDef = getPreset(preset);
+
+  // 출력 형식에 따른 리포트 출력
+  switch (format) {
+    case "json":
+      console.log(formatReportAsAgentJSON(report, preset));
+      break;
+
+    case "agent":
+      console.log(formatReportForAgent(report, preset));
+      break;
+
+    case "console":
+    default:
+      if (quiet) {
+        // 요약만 출력
+        console.log(`Files analyzed: ${report.filesAnalyzed}`);
+        console.log(`Violations: ${report.totalViolations}`);
+        console.log(`  Errors: ${report.bySeverity.error}`);
+        console.log(`  Warnings: ${report.bySeverity.warn}`);
+        console.log(`  Info: ${report.bySeverity.info}`);
+      } else {
+        printReport(report, presetDef.hierarchy);
+      }
+      break;
+  }
+
+  // 통계 저장
+  if (saveStats) {
+    const scanRecord = createScanRecord(report, preset);
+    await addScanRecord(rootDir, scanRecord);
+    console.log("📊 Statistics saved to .mandu/guard-stats.json");
+  }
+
+  // 트렌드 분석
+  let trend = null;
+  let layerStats = null;
+
+  if (showTrend) {
+    const store = await loadStatistics(rootDir);
+    trend = analyzeTrend(store.records, 7);
+    layerStats = calculateLayerStatistics(report.violations, presetDef.hierarchy);
+
+    if (trend) {
+      console.log("");
+      console.log("📈 Trend Analysis (7 days):");
+      const trendEmoji = trend.trend === "improving" ? "📉" : trend.trend === "degrading" ? "📈" : "➡️";
+      console.log(`   Status: ${trendEmoji} ${trend.trend.toUpperCase()}`);
+      console.log(`   Change: ${trend.violationDelta >= 0 ? "+" : ""}${trend.violationDelta} (${trend.violationChangePercent >= 0 ? "+" : ""}${trend.violationChangePercent}%)`);
+
+      if (trend.recommendations.length > 0) {
+        console.log("   💡 Recommendations:");
+        for (const rec of trend.recommendations) {
+          console.log(`      - ${rec}`);
+        }
+      }
+    }
+  }
+
+  // 리포트 파일 출력
+  if (output) {
+    let reportContent: string;
+
+    switch (reportFormat) {
+      case "json":
+        reportContent = formatReportAsAgentJSON(report, preset);
+        break;
+      case "html":
+        reportContent = generateHTMLReport(report, trend, layerStats ?? undefined);
+        break;
+      case "markdown":
+      default:
+        reportContent = generateMarkdownReport(report, trend, layerStats ?? undefined);
+        break;
+    }
+
+    await writeFile(output, reportContent);
+    console.log(`\n📄 Report saved to ${output}`);
+  }
+
+  // CI 모드에서 에러가 있으면 실패
+  if (ci && report.bySeverity.error > 0) {
+    console.log("\n❌ Architecture check failed");
+    return false;
+  }
+
+  if (report.totalViolations === 0) {
+    console.log("\n✅ Architecture check passed");
+    return true;
+  }
+
+  if (report.bySeverity.error > 0) {
+    console.log(`\n⚠️  ${report.bySeverity.error} error(s) found - please fix before continuing`);
+    return !ci;
+  }
+
+  console.log(`\n⚠️  ${report.totalViolations} issue(s) found`);
+  return true;
+}

package/src/commands/routes.ts

@@ -0,0 +1,218 @@
+/**
+ * FS Routes CLI Commands
+ *
+ * 파일 시스템 기반 라우트 관리 명령어
+ */
+
+import {
+  scanRoutes,
+  generateManifest,
+  formatRoutesForCLI,
+  watchFSRoutes,
+  type GenerateOptions,
+  type FSScannerConfig,
+} from "@mandujs/core";
+import { resolveFromCwd } from "../util/fs";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface RoutesGenerateOptions {
+  /** 출력 파일 경로 */
+  output?: string;
+  /** 상세 출력 */
+  verbose?: boolean;
+}
+
+export interface RoutesListOptions {
+  /** 상세 출력 */
+  verbose?: boolean;
+}
+
+export interface RoutesWatchOptions {
+  /** 출력 파일 경로 */
+  output?: string;
+  /** 상세 출력 */
+  verbose?: boolean;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Commands
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * routes generate - FS Routes 스캔 및 매니페스트 생성
+ */
+export async function routesGenerate(options: RoutesGenerateOptions = {}): Promise<boolean> {
+  const rootDir = resolveFromCwd(".");
+
+  console.log("🥟 Mandu FS Routes Generate\n");
+
+  try {
+    const generateOptions: GenerateOptions = {
+      outputPath: options.output ?? ".mandu/routes.manifest.json",
+      skipLegacy: true, // 레거시 병합 비활성화
+    };
+
+    const result = await generateManifest(rootDir, generateOptions);
+
+    // 결과 출력
+    console.log(`✅ FS Routes 스캔 완료`);
+    console.log(`   📋 라우트: ${result.manifest.routes.length}개\n`);
+
+    // 경고 출력
+    if (result.warnings.length > 0) {
+      console.log("⚠️  경고:");
+      for (const warning of result.warnings) {
+        console.log(`   - ${warning}`);
+      }
+      console.log("");
+    }
+
+    // 라우트 목록 출력
+    if (options.verbose) {
+      console.log(formatRoutesForCLI(result.manifest));
+      console.log("");
+    }
+
+    // 출력 파일 경로
+    if (generateOptions.outputPath) {
+      console.log(`📁 매니페스트 저장: ${generateOptions.outputPath}`);
+    }
+
+    return true;
+  } catch (error) {
+    console.error("❌ FS Routes 생성 실패:", error instanceof Error ? error.message : error);
+    return false;
+  }
+}
+
+/**
+ * routes list - 현재 라우트 목록 출력
+ */
+export async function routesList(options: RoutesListOptions = {}): Promise<boolean> {
+  const rootDir = resolveFromCwd(".");
+
+  console.log("🥟 Mandu Routes List\n");
+
+  try {
+    const result = await scanRoutes(rootDir);
+
+    if (result.errors.length > 0) {
+      console.log("⚠️  스캔 경고:");
+      for (const error of result.errors) {
+        console.log(`   - ${error.type}: ${error.message}`);
+      }
+      console.log("");
+    }
+
+    if (result.routes.length === 0) {
+      console.log("📭 라우트가 없습니다.");
+      console.log("");
+      console.log("💡 app/ 폴더에 page.tsx 또는 route.ts 파일을 생성하세요.");
+      console.log("");
+      console.log("예시:");
+      console.log("  app/page.tsx        → /");
+      console.log("  app/blog/page.tsx   → /blog");
+      console.log("  app/api/users/route.ts → /api/users");
+      return true;
+    }
+
+    // 라우트 목록 출력
+    console.log(`📋 라우트 (${result.routes.length}개)`);
+    console.log("─".repeat(70));
+
+    for (const route of result.routes) {
+      const icon = route.kind === "page" ? "📄" : "📡";
+      const hydration = route.clientModule ? " 🏝️" : "";
+      const pattern = route.pattern.padEnd(35);
+      const id = route.id;
+
+      console.log(`${icon} ${pattern} → ${id}${hydration}`);
+
+      if (options.verbose) {
+        console.log(`   📁 ${route.sourceFile}`);
+        if (route.clientModule) {
+          console.log(`   🏝️  ${route.clientModule}`);
+        }
+        if (route.layoutChain.length > 0) {
+          console.log(`   📐 layouts: ${route.layoutChain.join(" → ")}`);
+        }
+      }
+    }
+
+    console.log("");
+
+    // 통계
+    console.log("📊 통계");
+    console.log(`   페이지: ${result.stats.pageCount}개`);
+    console.log(`   API: ${result.stats.apiCount}개`);
+    console.log(`   레이아웃: ${result.stats.layoutCount}개`);
+    console.log(`   Island: ${result.stats.islandCount}개`);
+    console.log(`   스캔 시간: ${result.stats.scanTime}ms`);
+
+    return true;
+  } catch (error) {
+    console.error("❌ 라우트 목록 조회 실패:", error instanceof Error ? error.message : error);
+    return false;
+  }
+}
+
+/**
+ * routes watch - 실시간 라우트 감시
+ */
+export async function routesWatch(options: RoutesWatchOptions = {}): Promise<boolean> {
+  const rootDir = resolveFromCwd(".");
+
+  console.log("🥟 Mandu FS Routes Watch\n");
+  console.log("👀 라우트 변경 감시 중... (Ctrl+C로 종료)\n");
+
+  try {
+    // 초기 스캔
+    const initialResult = await generateManifest(rootDir, {
+      outputPath: options.output ?? ".mandu/routes.manifest.json",
+    });
+
+    console.log(`✅ 초기 스캔: ${initialResult.manifest.routes.length}개 라우트\n`);
+
+    // 감시 시작
+    const watcher = await watchFSRoutes(rootDir, {
+      outputPath: options.output ?? ".mandu/routes.manifest.json",
+      onChange: (result) => {
+        const timestamp = new Date().toLocaleTimeString();
+        console.log(`\n🔄 [${timestamp}] 라우트 변경 감지`);
+        console.log(`   📋 총 라우트: ${result.manifest.routes.length}개`);
+
+        if (result.warnings.length > 0) {
+          for (const warning of result.warnings) {
+            console.log(`   ⚠️  ${warning}`);
+          }
+        }
+
+        if (options.verbose) {
+          console.log("");
+          console.log(formatRoutesForCLI(result.manifest));
+        }
+      },
+    });
+
+    // 종료 시그널 처리
+    const cleanup = () => {
+      console.log("\n\n🛑 감시 종료");
+      watcher.close();
+      process.exit(0);
+    };
+
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+
+    // 무한 대기
+    await new Promise(() => {});
+
+    return true;
+  } catch (error) {
+    console.error("❌ 라우트 감시 실패:", error instanceof Error ? error.message : error);
+    return false;
+  }
+}

package/src/main.ts

@@ -3,6 +3,7 @@
 import { specUpsert } from "./commands/spec-upsert";
 import { generateApply } from "./commands/generate-apply";
 import { guardCheck } from "./commands/guard-check";
+import { guardArch } from "./commands/guard-arch";
 import { dev } from "./commands/dev";
 import { init } from "./commands/init";
 import { build } from "./commands/build";
@@ -19,6 +20,7 @@ import {
 import { doctor } from "./commands/doctor";
 import { watch } from "./commands/watch";
 import { brainSetup, brainStatus } from "./commands/brain";
+import { routesGenerate, routesList, routesWatch } from "./commands/routes";
 
 const HELP_TEXT = `
 🥟 Mandu CLI - Agent-Native Fullstack Framework
@@ -27,11 +29,20 @@ Usage: bunx mandu <command> [options]
 
 Commands:
   init           새 프로젝트 생성
-  spec-upsert    Spec 파일 검증 및 lock 갱신
-  generate       Spec에서 코드 생성
-  guard          Guard 규칙 검사
+  routes generate  FS Routes 스캔 및 매니페스트 생성
+  routes list      현재 라우트 목록 출력
+  routes watch     실시간 라우트 감시
+  dev            개발 서버 실행 (FS Routes 자동 적용)
+  dev --guard    Guard 실시간 감시와 함께 개발 서버 실행
   build          클라이언트 번들 빌드 (Hydration)
-  dev            개발 서버 실행
+  guard          Guard 규칙 검사 (레거시 Spec 기반)
+  guard arch     아키텍처 위반 검사 (FSD/Clean/Hexagonal)
+  guard arch --watch  실시간 아키텍처 감시
+  guard arch --list-presets  사용 가능한 프리셋 목록
+  guard arch --output report.md  리포트 파일 생성
+  guard arch --show-trend  트렌드 분석 표시
+  spec-upsert    Spec 파일 검증 및 lock 갱신 (레거시)
+  generate       Spec에서 코드 생성 (레거시)
 
   doctor         Guard 실패 분석 + 패치 제안 (Brain)
   watch          실시간 파일 감시 - 경고만 (Brain)
@@ -56,15 +67,23 @@ Options:
   --name <name>      init 시 프로젝트 이름 (기본: my-mandu-app)
   --file <path>      spec-upsert 시 사용할 spec 파일 경로
   --port <port>      dev/openapi serve 포트 (기본: 3000/8080)
+  --guard            dev 시 Architecture Guard 실시간 감시 활성화
+  --guard-preset <p> dev --guard 시 프리셋 (기본: mandu)
   --no-auto-correct  guard 시 자동 수정 비활성화
+  --preset <name>    guard arch 프리셋 (기본: mandu) - fsd, clean, hexagonal, atomic 선택 가능
+  --ci               guard arch CI 모드 (에러 시 exit 1)
+  --quiet            guard arch 요약만 출력
+  --report-format    guard arch 리포트 형식: json, markdown, html
+  --save-stats       guard arch 통계 저장 (트렌드 분석용)
+  --show-trend       guard arch 트렌드 분석 표시
   --minify           build 시 코드 압축
   --sourcemap        build 시 소스맵 생성
-  --watch            build 시 파일 감시 모드
+  --watch            build/guard arch 파일 감시 모드
   --message <msg>    change begin 시 설명 메시지
   --id <id>          change rollback 시 특정 변경 ID
   --keep <n>         change prune 시 유지할 스냅샷 수 (기본: 5)
   --output <path>    openapi/doctor 출력 경로
-  --format <fmt>     doctor 출력 형식: console, json, markdown (기본: console)
+  --format <fmt>     doctor/guard 출력 형식: console, json, agent
   --no-llm           doctor에서 LLM 사용 안 함 (템플릿 모드)
   --model <name>     brain setup 시 모델 이름 (기본: llama3.2)
   --url <url>        brain setup 시 Ollama URL
@@ -73,26 +92,24 @@ Options:
 
 Examples:
   bunx mandu init --name my-app
-  bunx mandu spec-upsert
-  bunx mandu generate
-  bunx mandu guard
-  bunx mandu build --minify
-  bunx mandu build --watch
+  bunx mandu routes list
+  bunx mandu routes generate
   bunx mandu dev --port 3000
+  bunx mandu build --minify
+  bunx mandu guard
+  bunx mandu guard arch --preset fsd
+  bunx mandu guard arch --watch
+  bunx mandu guard arch --ci --format json
   bunx mandu doctor
-  bunx mandu doctor --format markdown --output report.md
-  bunx mandu watch
   bunx mandu brain setup --model codellama
-  bunx mandu brain status
   bunx mandu contract create users
-  bunx mandu contract validate --verbose
   bunx mandu openapi generate --output docs/api.json
-  bunx mandu openapi serve --port 8080
   bunx mandu change begin --message "Add new route"
-  bunx mandu change commit
-  bunx mandu change rollback
 
-Workflow:
+FS Routes Workflow (권장):
+  1. init → 2. app/ 폴더에 page.tsx 생성 → 3. dev → 4. build
+
+Legacy Workflow:
   1. init → 2. spec-upsert → 3. generate → 4. build → 5. guard → 6. dev
 
 Contract-first Workflow:
@@ -174,11 +191,32 @@ async function main(): Promise<void> {
       success = await generateApply();
       break;
 
-    case "guard":
-      success = await guardCheck({
-        autoCorrect: options["no-auto-correct"] !== "true",
-      });
+    case "guard": {
+      const subCommand = args[1];
+      switch (subCommand) {
+        case "arch":
+          success = await guardArch({
+            preset: (options.preset as any) || "fsd",
+            watch: options.watch === "true",
+            ci: options.ci === "true",
+            format: (options.format as any) || "console",
+            quiet: options.quiet === "true",
+            srcDir: options["src-dir"],
+            listPresets: options["list-presets"] === "true",
+            output: options.output,
+            reportFormat: (options["report-format"] as any) || "markdown",
+            saveStats: options["save-stats"] === "true",
+            showTrend: options["show-trend"] === "true",
+          });
+          break;
+        default:
+          // 기본값: 레거시 guard-check
+          success = await guardCheck({
+            autoCorrect: options["no-auto-correct"] !== "true",
+          });
+      }
       break;
+    }
 
     case "build":
       success = await build({
@@ -189,8 +227,47 @@ async function main(): Promise<void> {
       break;
 
     case "dev":
-      await dev({ port: parsePort(options.port) });
+      await dev({
+        port: parsePort(options.port),
+        guard: options.guard === "true",
+        guardPreset: options["guard-preset"] as any,
+      });
+      break;
+
+    case "routes": {
+      const subCommand = args[1];
+      switch (subCommand) {
+        case "generate":
+          success = await routesGenerate({
+            output: options.output,
+            verbose: options.verbose === "true",
+          });
+          break;
+        case "list":
+          success = await routesList({
+            verbose: options.verbose === "true",
+          });
+          break;
+        case "watch":
+          success = await routesWatch({
+            output: options.output,
+            verbose: options.verbose === "true",
+          });
+          break;
+        default:
+          // 기본값: list
+          if (!subCommand) {
+            success = await routesList({
+              verbose: options.verbose === "true",
+            });
+          } else {
+            console.error(`❌ Unknown routes subcommand: ${subCommand}`);
+            console.log("\nUsage: bunx mandu routes <generate|list|watch>");
+            process.exit(1);
+          }
+      }
       break;
+    }
 
     case "contract": {
       const subCommand = args[1];