@mandujs/cli 0.9.12 → 0.9.18

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.12",
+  "version": "0.9.18",
   "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.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 : success;
+}