@mandujs/cli 0.9.17 → 0.9.19

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Agent-Native Fullstack Framework CLI</strong><br/>
-  A development OS where architecture stays intact even when AI agents write your code
+  Architecture stays intact even when AI agents write your code
 </p>
 
 <p align="center">
@@ -16,47 +16,26 @@
 ## Installation
 
 ```bash
-# Bun required
 bun add -D @mandujs/cli
 ```
 
-## Quick Start
+Or use directly with `bunx`:
 
 ```bash
-# Create a new project
 bunx @mandujs/cli init my-app
-cd my-app
-
-# Start development server
-bun run dev
 ```
 
-## Commands
-
-### `mandu init <project-name>`
+## Quick Start
 
-Creates a new Mandu project.
+### 1. Create a New Project
 
 ```bash
 bunx @mandujs/cli init my-app
+cd my-app
+bun install
 ```
 
-Generated structure:
-```
-my-app/
-├── apps/
-│   ├── server/main.ts    # Server entry point
-│   └── web/entry.tsx     # Client entry point
-├── spec/
-│   └── routes.manifest.json  # SSOT - Route definitions
-├── tests/                # Test templates
-├── package.json
-└── tsconfig.json
-```
-
-### `mandu dev`
-
-Starts the development server (with HMR support).
+### 2. Start Development Server
 
 ```bash
 bun run dev
@@ -64,117 +43,264 @@ bun run dev
 bunx mandu dev
 ```
 
-### `mandu spec`
+Your app is now running at `http://localhost:3000`.
+
+### 3. Create Pages in `app/` Directory
+
+```
+app/
+├── page.tsx              → /
+├── about/page.tsx        → /about
+├── users/[id]/page.tsx   → /users/:id
+└── api/hello/route.ts    → /api/hello
+```
 
-Validates the spec file and updates the lock file.
+### 4. Build for Production
 
 ```bash
-bun run spec
+bunx mandu build
 ```
 
-### `mandu generate`
+That's it!
+
+---
+
+## Commands
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `mandu init [name]` | Create new project |
+| `mandu dev` | Start dev server (FS Routes + HMR) |
+| `mandu build` | Build for production |
+
+### FS Routes Commands
+
+| Command | Description |
+|---------|-------------|
+| `mandu routes list` | Show all routes |
+| `mandu routes generate` | Generate routes manifest |
+| `mandu routes watch` | Watch for route changes |
+
+### Guard Commands
+
+| Command | Description |
+|---------|-------------|
+| `mandu guard arch` | Run architecture check (default: mandu preset) |
+| `mandu guard arch --watch` | Watch mode |
+| `mandu guard arch --ci` | CI mode (exit 1 on errors) |
+| `mandu guard arch --preset fsd` | Use specific preset |
+| `mandu guard arch --output report.md` | Generate report |
+
+### Transaction Commands
+
+| Command | Description |
+|---------|-------------|
+| `mandu change begin` | Start transaction (creates snapshot) |
+| `mandu change commit` | Finalize changes |
+| `mandu change rollback` | Restore from snapshot |
+| `mandu change status` | Show current state |
+| `mandu change list` | View history |
+
+### Brain Commands
+
+| Command | Description |
+|---------|-------------|
+| `mandu doctor` | Analyze Guard failures + suggest patches |
+| `mandu watch` | Real-time file monitoring |
+| `mandu brain setup` | Configure sLLM (optional) |
+| `mandu brain status` | Check Brain status |
+
+### Contract & OpenAPI Commands
+
+| Command | Description |
+|---------|-------------|
+| `mandu contract create <routeId>` | Create contract for route |
+| `mandu contract validate` | Validate contract-slot consistency |
+| `mandu openapi generate` | Generate OpenAPI 3.0 spec |
+| `mandu openapi serve` | Start Swagger UI server |
+
+---
 
-Generates code based on the spec.
+## Workflow
+
+### Modern Workflow (Recommended)
 
 ```bash
-bun run generate
-```
+# 1. Create project
+bunx @mandujs/cli init my-app
+cd my-app && bun install
+
+# 2. Create pages
+# app/page.tsx        → /
+# app/users/page.tsx  → /users
+# app/api/users/route.ts → /api/users
 
-### `mandu guard`
+# 3. Start development
+bun run dev
+```
 
-Checks architecture rules and auto-corrects violations.
+### With Architecture Guard
 
 ```bash
-bun run guard
+# Development with Guard watching
+bunx mandu dev --guard
 
-# Disable auto-correction
-bunx mandu guard --no-auto-correct
+# Or run Guard separately
+bunx mandu guard arch --watch
 ```
 
-Auto-correctable rules:
-- `SPEC_HASH_MISMATCH` → Updates lock file
-- `GENERATED_MANUAL_EDIT` → Regenerates code
-- `SLOT_NOT_FOUND` → Creates slot file
-
-## Writing Spec Files
-
-`spec/routes.manifest.json` is the Single Source of Truth (SSOT) for all routes.
-
-```json
-{
-  "version": "1.0.0",
-  "routes": [
-    {
-      "id": "getUsers",
-      "pattern": "/api/users",
-      "kind": "api",
-      "module": "apps/server/api/users.ts"
-    },
-    {
-      "id": "homePage",
-      "pattern": "/",
-      "kind": "page",
-      "module": "apps/server/pages/home.ts",
-      "componentModule": "apps/web/pages/Home.tsx"
-    }
-  ]
-}
+### CI/CD Integration
+
+```bash
+# Build and check
+bunx mandu build --minify
+bunx mandu guard arch --ci --format json
 ```
 
-### Slot System (v0.2.0+)
+---
 
-Add `slotModule` to separate business logic:
+## FS Routes
 
-```json
-{
-  "id": "getUsers",
-  "pattern": "/api/users",
-  "kind": "api",
-  "module": "apps/server/api/users.generated.ts",
-  "slotModule": "apps/server/api/users.slot.ts"
-}
+Create routes by adding files to `app/`:
+
+```
+app/
+├── page.tsx              → /
+├── layout.tsx            → Layout for all pages
+├── users/
+│   ├── page.tsx          → /users
+│   ├── [id]/
+│   │   └── page.tsx      → /users/:id
+│   └── [...slug]/
+│       └── page.tsx      → /users/*
+├── api/
+│   └── users/
+│       └── route.ts      → /api/users
+└── (auth)/               → Group (no URL segment)
+    └── login/page.tsx    → /login
 ```
 
-- `*.generated.ts` - Managed by framework (do not modify)
-- `*.slot.ts` - Business logic written by developers
+### Special Files
 
-## Development Workflow
+| File | Purpose |
+|------|---------|
+| `page.tsx` | Page component |
+| `layout.tsx` | Shared layout |
+| `route.ts` | API endpoint |
+| `loading.tsx` | Loading state |
+| `error.tsx` | Error boundary |
+| `slot.ts` | Business logic |
+| `client.tsx` | Interactive component (Island) |
 
-```bash
-# 1. Edit spec
-# 2. Validate spec and update lock
-bun run spec
+---
 
-# 3. Generate code
-bun run generate
+## Guard Presets
 
-# 4. Check architecture
-bun run guard
+| Preset | Description |
+|--------|-------------|
+| `mandu` | FSD + Clean Architecture (default) |
+| `fsd` | Feature-Sliced Design |
+| `clean` | Clean Architecture |
+| `hexagonal` | Hexagonal Architecture |
+| `atomic` | Atomic Design |
 
-# 5. Run tests
-bun test
+```bash
+# List all presets
+bunx mandu guard arch --list-presets
 
-# 6. Start dev server
-bun run dev
+# Use specific preset
+bunx mandu guard arch --preset fsd
 ```
 
-## Testing
+---
+
+## Options Reference
+
+### `mandu dev`
+
+| Option | Description |
+|--------|-------------|
+| `--port <n>` | Server port (default: 3000) |
+| `--guard` | Enable Guard watching |
+| `--guard-preset <p>` | Guard preset (default: mandu) |
+
+### `mandu build`
+
+| Option | Description |
+|--------|-------------|
+| `--minify` | Minify output |
+| `--sourcemap` | Generate sourcemaps |
+| `--watch` | Watch mode |
+
+### `mandu guard arch`
+
+| Option | Description |
+|--------|-------------|
+| `--preset <p>` | Preset: fsd, clean, hexagonal, atomic, mandu |
+| `--watch` | Watch mode |
+| `--ci` | CI mode (exit 1 on errors) |
+| `--quiet` | Summary only |
+| `--format <f>` | Output: console, agent, json |
+| `--output <path>` | Report file path |
+| `--report-format <f>` | Report: json, markdown, html |
+| `--save-stats` | Save for trend analysis |
+| `--show-trend` | Show trend analysis |
+
+### `mandu doctor`
+
+| Option | Description |
+|--------|-------------|
+| `--format <f>` | Output: console, json, markdown |
+| `--no-llm` | Template mode (no LLM) |
+| `--output <path>` | Output file path |
+
+---
 
-Built-in support for Bun test framework.
+## Examples
 
 ```bash
-bun test           # Run tests
-bun test --watch   # Watch mode
+# Initialize project
+bunx @mandujs/cli init my-app
+
+# Development
+bunx mandu dev --port 3000
+bunx mandu dev --guard
+
+# Routes
+bunx mandu routes list
+bunx mandu routes generate
+
+# Guard
+bunx mandu guard arch
+bunx mandu guard arch --watch
+bunx mandu guard arch --ci --format json
+bunx mandu guard arch --output report.md
+
+# Transactions
+bunx mandu change begin --message "Add users API"
+bunx mandu change commit
+bunx mandu change rollback
+
+# Doctor
+bunx mandu doctor
+bunx mandu doctor --format json
+
+# Build
+bunx mandu build --minify --sourcemap
 ```
 
+---
+
 ## Requirements
 
 - Bun >= 1.0.0
-- React >= 18.0.0
 
 ## Related Packages
 
 - [@mandujs/core](https://www.npmjs.com/package/@mandujs/core) - Core runtime
+- [@mandujs/mcp](https://www.npmjs.com/package/@mandujs/mcp) - MCP server
 
 ## License
 

package/package.json

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

package/src/commands/check.ts

@@ -0,0 +1,204 @@
+/**
+ * mandu check - Workflow Check Command
+ *
+ * FS Routes + Architecture Guard + Legacy Guard 통합 검사
+ */
+
+import {
+  generateManifest,
+  scanRoutes,
+  checkDirectory,
+  printReport,
+  getPreset,
+  loadManifest,
+  runGuardCheck,
+  buildGuardReport,
+  printReportSummary,
+  type GuardConfig,
+  type GuardPreset,
+} from "@mandujs/core";
+import path from "path";
+import { resolveFromCwd, isDirectory, pathExists } from "../util/fs";
+import { resolveOutputFormat, type OutputFormat } from "../util/output";
+
+export interface CheckOptions {
+  preset?: GuardPreset;
+  format?: OutputFormat;
+  ci?: boolean;
+  quiet?: boolean;
+  legacy?: boolean;
+}
+
+export async function check(options: CheckOptions = {}): Promise<boolean> {
+  const rootDir = resolveFromCwd(".");
+  const preset = options.preset ?? "mandu";
+  const format = resolveOutputFormat(options.format);
+  const quiet = options.quiet === true;
+  const enableFsRoutes = !options.legacy && await isDirectory(path.resolve(rootDir, "app"));
+  const specPath = resolveFromCwd("spec/routes.manifest.json");
+  const hasSpec = await pathExists(specPath);
+
+  let success = true;
+
+  const log = (message: string) => {
+    if (format === "console" && !quiet) {
+      console.log(message);
+    }
+  };
+
+  const print = (message: string) => {
+    if (format === "console") {
+      console.log(message);
+    }
+  };
+
+  if (format === "console") {
+    log("🥟 Mandu Check\n");
+  }
+
+  // 1) FS Routes 검사
+  let routesSummary: { enabled: boolean; count: number; warnings: string[] } = {
+    enabled: false,
+    count: 0,
+    warnings: [],
+  };
+
+  if (enableFsRoutes) {
+    routesSummary.enabled = true;
+
+    try {
+      if (format === "console") {
+        const result = await generateManifest(rootDir, {
+          outputPath: ".mandu/routes.manifest.json",
+          skipLegacy: true,
+        });
+        routesSummary.count = result.manifest.routes.length;
+        routesSummary.warnings = result.warnings;
+
+        if (quiet) {
+          print(`✅ FS Routes: ${routesSummary.count}개`);
+        } else {
+          log(`✅ FS Routes: ${routesSummary.count}개`);
+        }
+        if (routesSummary.warnings.length > 0) {
+          if (!quiet) {
+            log("⚠️  경고:");
+          }
+          for (const warning of routesSummary.warnings) {
+            if (!quiet) {
+              log(`   - ${warning}`);
+            }
+          }
+        }
+        if (!quiet) {
+          log("");
+        }
+      } else {
+        const scan = await scanRoutes(rootDir);
+        routesSummary.count = scan.routes.length;
+        routesSummary.warnings = scan.errors.map((e) => `${e.type}: ${e.message}`);
+      }
+    } catch (error) {
+      success = false;
+      routesSummary.warnings.push(
+        error instanceof Error ? error.message : String(error)
+      );
+      if (format === "console") {
+        console.error("❌ FS Routes 검사 실패:", error);
+      }
+    }
+  } else {
+    if (quiet) {
+      print("ℹ️  app/ 폴더 없음 - FS Routes 검사 스킵");
+    } else {
+      log("ℹ️  app/ 폴더 없음 - FS Routes 검사 스킵\n");
+    }
+  }
+
+  // 2) Architecture Guard 검사
+  const guardConfig: GuardConfig = {
+    preset,
+    srcDir: "src",
+    fsRoutes: enableFsRoutes
+      ? {
+          noPageToPage: true,
+          pageCanImport: ["widgets", "features", "entities", "shared"],
+          layoutCanImport: ["widgets", "shared"],
+        }
+      : undefined,
+  };
+
+  const report = await checkDirectory(guardConfig, rootDir);
+  if (report.bySeverity.error > 0) {
+    success = false;
+  }
+
+  if (format === "console") {
+    const presetDef = getPreset(preset);
+    if (quiet) {
+      print(`📊 Architecture: ${report.totalViolations}개 위반 (Errors: ${report.bySeverity.error})`);
+    } else {
+      printReport(report, presetDef.hierarchy);
+    }
+  }
+
+  // 3) Legacy Guard 검사 (spec 파일이 있을 때만)
+  let legacySummary: { enabled: boolean; passed: boolean; violations: number; errors?: string[] } = {
+    enabled: false,
+    passed: true,
+    violations: 0,
+  };
+
+  if (hasSpec) {
+    legacySummary.enabled = true;
+
+    const manifestResult = await loadManifest(specPath);
+    if (!manifestResult.success || !manifestResult.data) {
+      legacySummary.passed = false;
+      legacySummary.errors = manifestResult.errors ?? ["Spec 로드 실패"];
+      success = false;
+
+      if (format === "console") {
+        console.error("❌ Spec 로드 실패:");
+        manifestResult.errors?.forEach((e) => console.error(`  - ${e}`));
+      }
+    } else {
+      const checkResult = await runGuardCheck(manifestResult.data, rootDir);
+      legacySummary.passed = checkResult.passed;
+      legacySummary.violations = checkResult.violations.length;
+      success = success && checkResult.passed;
+
+      if (format === "console") {
+        const legacyReport = buildGuardReport(checkResult);
+        if (quiet) {
+          print(`📊 Legacy Guard: ${legacySummary.violations}개 위반`);
+        } else {
+          printReportSummary(legacyReport);
+        }
+      }
+    }
+  } else {
+    if (quiet) {
+      print("ℹ️  spec/routes.manifest.json 없음 - 레거시 Guard 스킵");
+    } else {
+      log("ℹ️  spec/routes.manifest.json 없음 - 레거시 Guard 스킵");
+    }
+  }
+
+  if (format !== "console") {
+    const summary = {
+      ok: success,
+      routes: routesSummary,
+      architecture: {
+        totalViolations: report.totalViolations,
+        bySeverity: report.bySeverity,
+        byType: report.byType,
+        report,
+      },
+      legacy: legacySummary,
+    };
+    console.log(JSON.stringify(summary, null, 2));
+  }
+
+  return options.ci ? success : true;
+}

package/src/commands/dev.ts

@@ -17,20 +17,23 @@ import {
   type GuardConfig,
   type GuardPreset,
 } from "@mandujs/core";
-import { resolveFromCwd } from "../util/fs";
+import { isDirectory, resolveFromCwd } from "../util/fs";
+import { resolveOutputFormat, type OutputFormat } from "../util/output";
 import path from "path";
 
-export interface DevOptions {
-  port?: number;
-  /** HMR 비활성화 */
-  noHmr?: boolean;
-  /** FS Routes 비활성화 (레거시 모드) */
-  legacy?: boolean;
-  /** Architecture Guard 활성화 */
-  guard?: boolean;
-  /** Guard 프리셋 */
-  guardPreset?: GuardPreset;
-}
+export interface DevOptions {
+  port?: number;
+  /** HMR 비활성화 */
+  noHmr?: boolean;
+  /** FS Routes 비활성화 (레거시 모드) */
+  legacy?: boolean;
+  /** Architecture Guard 활성화 */
+  guard?: boolean;
+  /** Guard 프리셋 */
+  guardPreset?: GuardPreset;
+  /** Guard 출력 형식 */
+  guardFormat?: OutputFormat;
+}
 
 export async function dev(options: DevOptions = {}): Promise<void> {
   const rootDir = resolveFromCwd(".");
@@ -203,16 +206,26 @@ 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,
-    };
+  // Architecture Guard 실시간 감시 (선택적)
+  let archGuardWatcher: ReturnType<typeof createGuardWatcher> | null = null;
+
+  if (options.guard !== false) {
+    const guardPreset = options.guardPreset || "mandu";
+    const guardFormat = resolveOutputFormat(options.guardFormat);
+    const enableFsRoutes = !options.legacy && await isDirectory(path.resolve(rootDir, "app"));
+    const guardConfig: GuardConfig = {
+      preset: guardPreset,
+      srcDir: "src",
+      realtime: true,
+      realtimeOutput: guardFormat,
+      fsRoutes: enableFsRoutes
+        ? {
+            noPageToPage: true,
+            pageCanImport: ["widgets", "features", "entities", "shared"],
+            layoutCanImport: ["widgets", "shared"],
+          }
+        : undefined,
+    };
 
     console.log(`🛡️  Architecture Guard 활성화 (${guardPreset})`);
 

package/src/commands/doctor.ts

@@ -10,7 +10,7 @@ import {
   runGuardCheck,
   analyzeViolations,
   printDoctorReport,
-  generateMarkdownReport,
+  generateDoctorMarkdownReport,
   initializeBrain,
   getBrain,
 } from "../../../core/src/index";
@@ -108,7 +108,7 @@ export async function doctor(options: DoctorOptions = {}): Promise<boolean> {
     }
 
     case "markdown": {
-      const md = generateMarkdownReport(analysis);
+      const md = generateDoctorMarkdownReport(analysis);
 
       if (output) {
         await fs.writeFile(output, md, "utf-8");

package/src/commands/guard-arch.ts

@@ -17,13 +17,15 @@ import {
   loadStatistics,
   analyzeTrend,
   calculateLayerStatistics,
-  generateMarkdownReport,
+  generateGuardMarkdownReport,
   generateHTMLReport,
   type GuardConfig,
   type GuardPreset,
 } from "@mandujs/core";
 import { writeFile } from "fs/promises";
-import { resolveFromCwd } from "../util/fs";
+import { isDirectory, resolveFromCwd } from "../util/fs";
+import { resolveOutputFormat, type OutputFormat } from "../util/output";
+import path from "path";
 
 export interface GuardArchOptions {
   /** 프리셋 이름 */
@@ -33,7 +35,7 @@ export interface GuardArchOptions {
   /** CI 모드 (에러 시 exit 1) */
   ci?: boolean;
   /** 출력 형식: console, agent, json */
-  format?: "console" | "agent" | "json";
+  format?: OutputFormat;
   /** 조용히 (요약만 출력) */
   quiet?: boolean;
   /** 소스 디렉토리 */
@@ -55,7 +57,7 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
     preset = "mandu",
     watch = false,
     ci = false,
-    format = "console",
+    format,
     quiet = false,
     srcDir = "src",
     listPresets: showPresets = false,
@@ -66,6 +68,8 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
   } = options;
 
   const rootDir = resolveFromCwd(".");
+  const resolvedFormat = resolveOutputFormat(format);
+  const enableFsRoutes = await isDirectory(path.resolve(rootDir, "app"));
 
   // 프리셋 목록 출력
   if (showPresets) {
@@ -86,25 +90,37 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
     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("");
+  if (resolvedFormat === "console") {
+    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,
+    realtimeOutput: resolvedFormat,
+    fsRoutes: enableFsRoutes
+      ? {
+          noPageToPage: true,
+          pageCanImport: ["widgets", "features", "entities", "shared"],
+          layoutCanImport: ["widgets", "shared"],
+        }
+      : undefined,
   };
 
   // 실시간 감시 모드
   if (watch) {
-    console.log("👁️  Watching for architecture violations...");
-    console.log("   Press Ctrl+C to stop\n");
+    if (resolvedFormat === "console") {
+      console.log("👁️  Watching for architecture violations...");
+      console.log("   Press Ctrl+C to stop\n");
+    }
 
     const watcher = createGuardWatcher({
       config,
@@ -113,7 +129,7 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
         // 실시간 위반 출력은 watcher 내부에서 처리됨
       },
       onFileAnalyzed: (analysis, violations) => {
-        if (violations.length > 0 && !quiet) {
+        if (resolvedFormat === "console" && violations.length > 0 && !quiet) {
           const timestamp = new Date().toLocaleTimeString();
           console.log(`[${timestamp}] ${analysis.filePath}: ${violations.length} violation(s)`);
         }
@@ -124,7 +140,9 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
 
     // Ctrl+C 핸들링
     process.on("SIGINT", () => {
-      console.log("\n🛑 Guard stopped");
+      if (resolvedFormat === "console") {
+        console.log("\n🛑 Guard stopped");
+      }
       watcher.close();
       process.exit(0);
     });
@@ -134,13 +152,15 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
   }
 
   // 일회성 검사 모드
-  console.log("🔍 Scanning for architecture violations...\n");
+  if (resolvedFormat === "console" && !quiet) {
+    console.log("🔍 Scanning for architecture violations...\n");
+  }
 
   const report = await checkDirectory(config, rootDir);
   const presetDef = getPreset(preset);
 
   // 출력 형식에 따른 리포트 출력
-  switch (format) {
+  switch (resolvedFormat) {
     case "json":
       console.log(formatReportAsAgentJSON(report, preset));
       break;
@@ -209,7 +229,7 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
         break;
       case "markdown":
       default:
-        reportContent = generateMarkdownReport(report, trend, layerStats ?? undefined);
+        reportContent = generateGuardMarkdownReport(report, trend, layerStats ?? undefined);
         break;
     }
 

package/src/main.ts

@@ -1,10 +1,11 @@
 #!/usr/bin/env bun
 
-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 { specUpsert } from "./commands/spec-upsert";
+import { generateApply } from "./commands/generate-apply";
+import { guardCheck } from "./commands/guard-check";
+import { guardArch } from "./commands/guard-arch";
+import { check } from "./commands/check";
+import { dev } from "./commands/dev";
 import { init } from "./commands/init";
 import { build } from "./commands/build";
 import { contractCreate, contractValidate } from "./commands/contract";
@@ -27,13 +28,14 @@ const HELP_TEXT = `
 
 Usage: bunx mandu <command> [options]
 
-Commands:
-  init           새 프로젝트 생성
-  routes generate  FS Routes 스캔 및 매니페스트 생성
-  routes list      현재 라우트 목록 출력
-  routes watch     실시간 라우트 감시
-  dev            개발 서버 실행 (FS Routes 자동 적용)
-  dev --guard    Guard 실시간 감시와 함께 개발 서버 실행
+Commands:
+  init           새 프로젝트 생성
+  check          FS Routes + Guard 통합 검사
+  routes generate  FS Routes 스캔 및 매니페스트 생성
+  routes list      현재 라우트 목록 출력
+  routes watch     실시간 라우트 감시
+  dev            개발 서버 실행 (FS Routes + Guard 기본)
+  dev --no-guard Guard 감시 비활성화
   build          클라이언트 번들 빌드 (Hydration)
   guard          Guard 규칙 검사 (레거시 Spec 기반)
   guard arch     아키텍처 위반 검사 (FSD/Clean/Hexagonal)
@@ -63,16 +65,19 @@ Commands:
   change list    변경 이력 조회
   change prune   오래된 스냅샷 정리
 
-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 요약만 출력
+Options:
+  --name <name>      init 시 프로젝트 이름 (기본: my-mandu-app)
+  --file <path>      spec-upsert 시 사용할 spec 파일 경로
+  --port <port>      dev/openapi serve 포트 (기본: 3000/8080)
+  --guard            dev 시 Architecture Guard 실시간 감시 활성화 (기본: ON)
+  --no-guard         dev 시 Guard 비활성화
+  --guard-preset <p> dev --guard 시 프리셋 (기본: mandu)
+  --guard-format <f> dev --guard 출력 형식: console, json, agent (기본: 자동)
+  --legacy           FS Routes 비활성화 (레거시 모드)
+  --no-auto-correct  guard 시 자동 수정 비활성화
+  --preset <name>    guard/check 프리셋 (기본: mandu) - fsd, clean, hexagonal, atomic 선택 가능
+  --ci               guard/check CI 모드 (에러 시 exit 1)
+  --quiet            guard/check 요약만 출력
   --report-format    guard arch 리포트 형식: json, markdown, html
   --save-stats       guard arch 통계 저장 (트렌드 분석용)
   --show-trend       guard arch 트렌드 분석 표시
@@ -83,19 +88,22 @@ Options:
   --id <id>          change rollback 시 특정 변경 ID
   --keep <n>         change prune 시 유지할 스냅샷 수 (기본: 5)
   --output <path>    openapi/doctor 출력 경로
-  --format <fmt>     doctor/guard 출력 형식: console, json, agent
+  --format <fmt>     guard/check 출력 형식: console, json, agent (기본: 자동)
+  --format <fmt>     doctor 출력 형식: console, json, markdown (기본: console)
   --no-llm           doctor에서 LLM 사용 안 함 (템플릿 모드)
   --model <name>     brain setup 시 모델 이름 (기본: llama3.2)
   --url <url>        brain setup 시 Ollama URL
   --verbose          상세 출력
   --help, -h         도움말 표시
 
-Examples:
-  bunx mandu init --name my-app
-  bunx mandu routes list
-  bunx mandu routes generate
-  bunx mandu dev --port 3000
-  bunx mandu build --minify
+Examples:
+  bunx mandu init --name my-app
+  bunx mandu check
+  bunx mandu routes list
+  bunx mandu routes generate
+  bunx mandu dev --port 3000
+  bunx mandu dev --no-guard
+  bunx mandu build --minify
   bunx mandu guard
   bunx mandu guard arch --preset fsd
   bunx mandu guard arch --watch
@@ -187,23 +195,33 @@ async function main(): Promise<void> {
       success = await specUpsert({ file: options.file });
       break;
 
-    case "generate":
-      success = await generateApply();
-      break;
-
-    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,
+    case "generate":
+      success = await generateApply();
+      break;
+
+    case "check":
+      success = await check({
+        preset: options.preset as any,
+        format: options.format as any,
+        ci: options.ci === "true",
+        quiet: options.quiet === "true",
+        legacy: options.legacy === "true",
+      });
+      break;
+
+    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,
+            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",
@@ -226,13 +244,15 @@ async function main(): Promise<void> {
       });
       break;
 
-    case "dev":
-      await dev({
-        port: parsePort(options.port),
-        guard: options.guard === "true",
-        guardPreset: options["guard-preset"] as any,
-      });
-      break;
+    case "dev":
+      await dev({
+        port: parsePort(options.port),
+        guard: options["no-guard"] === "true" ? false : options.guard !== "false",
+        guardPreset: options["guard-preset"] as any,
+        guardFormat: options["guard-format"] as any,
+        legacy: options.legacy === "true",
+      });
+      break;
 
     case "routes": {
       const subCommand = args[1];

package/src/util/fs.ts

@@ -1,9 +1,28 @@
-import path from "path";
+import path from "path";
+import fs from "fs/promises";
 
 export function resolveFromCwd(...paths: string[]): string {
   return path.resolve(process.cwd(), ...paths);
 }
 
-export function getRootDir(): string {
-  return process.cwd();
-}
+export function getRootDir(): string {
+  return process.cwd();
+}
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function isDirectory(targetPath: string): Promise<boolean> {
+  try {
+    const stat = await fs.stat(targetPath);
+    return stat.isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/util/output.ts

@@ -0,0 +1,41 @@
+export type OutputFormat = "console" | "agent" | "json";
+
+function normalizeFormat(value?: string): OutputFormat | undefined {
+  if (!value) return undefined;
+  if (value === "console" || value === "agent" || value === "json") {
+    return value;
+  }
+  return undefined;
+}
+
+export function resolveOutputFormat(explicit?: OutputFormat): OutputFormat {
+  const env = process.env;
+
+  const direct = normalizeFormat(explicit) ?? normalizeFormat(env.MANDU_OUTPUT);
+  if (direct) return direct;
+
+  const agentSignals = [
+    "MANDU_AGENT",
+    "CODEX_AGENT",
+    "CODEX",
+    "CLAUDE_CODE",
+    "ANTHROPIC_CLAUDE_CODE",
+  ];
+
+  for (const key of agentSignals) {
+    const value = env[key];
+    if (value === "1" || value === "true") {
+      return "json";
+    }
+  }
+
+  if (env.CI === "true") {
+    return "json";
+  }
+
+  if (process.stdout && !process.stdout.isTTY) {
+    return "json";
+  }
+
+  return "console";
+}

package/templates/default/app/api/health/route.ts

@@ -0,0 +1,13 @@
+/**
+ * Health Check API
+ *
+ * GET /api/health
+ */
+
+export function GET() {
+  return Response.json({
+    status: "ok",
+    timestamp: new Date().toISOString(),
+    framework: "Mandu",
+  });
+}

package/templates/default/app/page.tsx

@@ -0,0 +1,60 @@
+/**
+ * Home Page
+ *
+ * Edit this file and see changes at http://localhost:3000
+ */
+
+export default function HomePage() {
+  return (
+    <html lang="ko">
+      <head>
+        <meta charSet="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Mandu App</title>
+        <style>{`
+          body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            display: flex;
+            justify-content: center;
+            align-items: center;
+            min-height: 100vh;
+            margin: 0;
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+          }
+          .container {
+            text-align: center;
+            padding: 2rem;
+          }
+          h1 {
+            font-size: 3rem;
+            margin-bottom: 1rem;
+          }
+          p {
+            font-size: 1.2rem;
+            opacity: 0.9;
+          }
+          code {
+            background: rgba(255,255,255,0.2);
+            padding: 0.2rem 0.5rem;
+            border-radius: 4px;
+          }
+          a {
+            color: white;
+            text-decoration: underline;
+          }
+        `}</style>
+      </head>
+      <body>
+        <div className="container">
+          <h1>🥟 Mandu</h1>
+          <p>Welcome to your new Mandu project!</p>
+          <p>Edit <code>app/page.tsx</code> to get started.</p>
+          <p>
+            <a href="/api/health">Check API Health →</a>
+          </p>
+        </div>
+      </body>
+    </html>
+  );
+}

package/templates/default/package.json

@@ -5,19 +5,15 @@
   "scripts": {
     "dev": "mandu dev",
     "build": "mandu build",
-    "generate": "mandu generate",
-    "guard": "mandu guard",
-    "spec": "mandu spec-upsert",
-    "test": "bun test",
-    "test:watch": "bun test --watch"
+    "test": "bun test"
   },
   "dependencies": {
-    "@mandujs/core": "^0.4.0",
+    "@mandujs/core": "^0.9.38",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@mandujs/cli": "^0.4.0",
+    "@mandujs/cli": "^0.9.18",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "typescript": "^5.0.0"

package/templates/default/spec/routes.manifest.json

@@ -1,18 +1,4 @@
 {
-  "version": 1,
-  "routes": [
-    {
-      "id": "home",
-      "pattern": "/",
-      "kind": "page",
-      "module": "apps/server/generated/routes/home.route.ts",
-      "componentModule": "apps/web/generated/routes/home.route.tsx"
-    },
-    {
-      "id": "health",
-      "pattern": "/api/health",
-      "kind": "api",
-      "module": "apps/server/generated/routes/health.route.ts"
-    }
-  ]
+  "version": 2,
+  "routes": []
 }