@mandujs/cli 0.9.22 → 0.9.23

package/README.ko.md

@@ -44,12 +44,35 @@ bunx @mandujs/cli init my-app
 생성되는 구조:
 ```
 my-app/
+├── app/                 # FS Routes
+│   └── page.tsx         # /
+├── src/                 # 아키텍처 레이어
+│   ├── client/          # 클라이언트 (FSD)
+│   │   ├── app/
+│   │   ├── pages/
+│   │   ├── widgets/
+│   │   ├── features/
+│   │   ├── entities/
+│   │   └── shared/
+│   ├── server/          # 서버 (Clean)
+│   │   ├── api/
+│   │   ├── application/
+│   │   ├── domain/
+│   │   ├── infra/
+│   │   └── core/
+│   └── shared/          # 공용
+│       ├── contracts/        # client-safe 계약
+│       ├── types/
+│       ├── utils/
+│       │   ├── client/       # 클라이언트 safe 유틸
+│       │   └── server/       # 서버 전용 유틸
+│       ├── schema/           # 서버 전용 스키마
+│       └── env/              # 서버 전용 환경
 ├── apps/
 │   ├── server/main.ts    # 서버 진입점
 │   └── web/entry.tsx     # 클라이언트 진입점
 ├── spec/
 │   └── routes.manifest.json  # SSOT - 라우트 정의
-├── tests/                # 테스트 템플릿
 ├── package.json
 └── tsconfig.json
 ```
@@ -82,20 +105,50 @@ bun run generate
 
 ### `mandu guard`
 
-아키텍처 규칙을 검사하고 위반 사항을 자동 수정합니다.
+아키텍처 규칙을 검사합니다. (기본: mandu 프리셋)
 
 ```bash
 bun run guard
 
+# 프리셋 변경
+bunx mandu guard --preset fsd
+
+# CI 모드 (warning도 실패 처리)
+bunx mandu guard --ci
+```
+
+### `mandu guard legacy`
+
+레거시 Spec Guard 검사 + 자동 수정입니다.
+
+```bash
+bunx mandu guard legacy
+
 # 자동 수정 비활성화
-bunx mandu guard --no-auto-correct
+bunx mandu guard legacy --no-auto-correct
 ```
 
-자동 수정 가능한 규칙:
+자동 수정 가능한 규칙(legacy):
 - `SPEC_HASH_MISMATCH` → lock 파일 갱신
 - `GENERATED_MANUAL_EDIT` → 코드 재생성
 - `SLOT_NOT_FOUND` → slot 파일 생성
 
+### `mandu contract build`
+
+계약 레지스트리(`.mandu/contracts.json`)를 생성합니다.
+
+```bash
+bunx mandu contract build
+```
+
+### `mandu contract diff`
+
+계약 변경사항(major/minor/patch)을 비교합니다.
+
+```bash
+bunx mandu contract diff
+```
+
 ## Spec 파일 작성
 
 `spec/routes.manifest.json`이 모든 라우트의 단일 진실 공급원(SSOT)입니다.

package/README.md

@@ -61,6 +61,34 @@ app/
 bunx mandu build
 ```
 
+### Default Architecture Layout
+
+```
+app/                     # FS Routes
+src/
+  client/                # Client (FSD)
+    app/
+    pages/
+    widgets/
+    features/
+    entities/
+    shared/
+  server/                # Server (Clean)
+    api/
+    application/
+    domain/
+    infra/
+    core/
+  shared/                # Universal shared
+    contracts/           # Client-safe contracts
+    types/
+    utils/
+      client/            # Client-safe utils
+      server/            # Server-only utils
+    schema/              # Server-only schema
+    env/                 # Server-only env
+```
+
 That's it!
 
 ---
@@ -87,11 +115,12 @@ That's it!
 
 | 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 |
+| `mandu guard` | Run architecture check (default: mandu preset) |
+| `mandu guard --watch` | Watch mode |
+| `mandu guard --ci` | CI mode (exit 1 on errors/warnings) |
+| `mandu guard --preset fsd` | Use specific preset |
+| `mandu guard --output report.md` | Generate report |
+| `mandu guard legacy` | Legacy Spec guard (auto-correct) |
 
 ### Transaction Commands
 
@@ -119,6 +148,8 @@ That's it!
 |---------|-------------|
 | `mandu contract create <routeId>` | Create contract for route |
 | `mandu contract validate` | Validate contract-slot consistency |
+| `mandu contract build` | Build contract registry |
+| `mandu contract diff` | Diff contracts against registry |
 | `mandu openapi generate` | Generate OpenAPI 3.0 spec |
 | `mandu openapi serve` | Start Swagger UI server |
 
@@ -149,7 +180,7 @@ bun run dev
 bunx mandu dev --guard
 
 # Or run Guard separately
-bunx mandu guard arch --watch
+bunx mandu guard --watch
 ```
 
 ### CI/CD Integration
@@ -157,7 +188,7 @@ bunx mandu guard arch --watch
 ```bash
 # Build and check
 bunx mandu build --minify
-bunx mandu guard arch --ci --format json
+bunx mandu guard --ci --format json
 ```
 
 ---
@@ -209,10 +240,10 @@ app/
 
 ```bash
 # List all presets
-bunx mandu guard arch --list-presets
+bunx mandu guard --list-presets
 
 # Use specific preset
-bunx mandu guard arch --preset fsd
+bunx mandu guard --preset fsd
 ```
 
 ---
@@ -235,13 +266,13 @@ bunx mandu guard arch --preset fsd
 | `--sourcemap` | Generate sourcemaps |
 | `--watch` | Watch mode |
 
-### `mandu guard arch`
+### `mandu guard`
 
 | Option | Description |
 |--------|-------------|
 | `--preset <p>` | Preset: fsd, clean, hexagonal, atomic, mandu |
 | `--watch` | Watch mode |
-| `--ci` | CI mode (exit 1 on errors) |
+| `--ci` | CI mode (exit 1 on errors/warnings) |
 | `--quiet` | Summary only |
 | `--format <f>` | Output: console, agent, json |
 | `--output <path>` | Report file path |
@@ -284,10 +315,11 @@ 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
+bunx mandu guard
+bunx mandu guard --watch
+bunx mandu guard --ci --format json
+bunx mandu guard --output report.md
+bunx mandu guard legacy
 
 # Transactions
 bunx mandu change begin --message "Add users API"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/cli",
-  "version": "0.9.22",
+  "version": "0.9.23",
   "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
   "type": "module",
   "main": "./src/main.ts",

package/src/commands/check.ts

@@ -34,6 +34,7 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
   const preset = options.preset ?? "mandu";
   const format = resolveOutputFormat(options.format);
   const quiet = options.quiet === true;
+  const strictWarnings = options.ci === true;
   const enableFsRoutes = !options.legacy && await isDirectory(path.resolve(rootDir, "app"));
   const specPath = resolveFromCwd("spec/routes.manifest.json");
   const hasSpec = await pathExists(specPath);
@@ -122,14 +123,45 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
     fsRoutes: enableFsRoutes
       ? {
           noPageToPage: true,
-          pageCanImport: ["widgets", "features", "entities", "shared"],
-          layoutCanImport: ["widgets", "shared"],
+          pageCanImport: [
+            "client/pages",
+            "client/widgets",
+            "client/features",
+            "client/entities",
+            "client/shared",
+            "shared/contracts",
+            "shared/types",
+            "shared/utils/client",
+          ],
+          layoutCanImport: [
+            "client/app",
+            "client/widgets",
+            "client/shared",
+            "shared/contracts",
+            "shared/types",
+            "shared/utils/client",
+          ],
+          routeCanImport: [
+            "server/api",
+            "server/application",
+            "server/domain",
+            "server/infra",
+            "server/core",
+            "shared/contracts",
+            "shared/schema",
+            "shared/types",
+            "shared/utils/client",
+            "shared/utils/server",
+            "shared/env",
+          ],
         }
       : undefined,
   };
 
   const report = await checkDirectory(guardConfig, rootDir);
-  if (report.bySeverity.error > 0) {
+  const hasArchErrors = report.bySeverity.error > 0;
+  const hasArchWarnings = report.bySeverity.warn > 0;
+  if (hasArchErrors || (strictWarnings && hasArchWarnings)) {
     success = false;
   }
 
@@ -166,7 +198,11 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
       const checkResult = await runGuardCheck(manifestResult.data, rootDir);
       legacySummary.passed = checkResult.passed;
       legacySummary.violations = checkResult.violations.length;
-      success = success && checkResult.passed;
+      if (strictWarnings && checkResult.violations.length > 0) {
+        success = false;
+      } else {
+        success = success && checkResult.passed;
+      }
 
       if (format === "console") {
         const legacyReport = buildGuardReport(checkResult);
@@ -200,5 +236,5 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
     console.log(JSON.stringify(summary, null, 2));
   }
 
-  return options.ci ? success : true;
+  return success;
 }

package/src/commands/contract.ts

@@ -3,17 +3,36 @@
  * Contract 생성 및 검증 명령어
  */
 
-import { loadManifest, runContractGuardCheck, generateContractTemplate } from "@mandujs/core";
-import path from "path";
-import fs from "fs/promises";
+import {
+  loadManifest,
+  runContractGuardCheck,
+  generateContractTemplate,
+  buildContractRegistry,
+  writeContractRegistry,
+  readContractRegistry,
+  diffContractRegistry,
+} from "@mandujs/core";
+import path from "path";
+import fs from "fs/promises";
 
 interface ContractCreateOptions {
   routeId: string;
 }
 
-interface ContractValidateOptions {
-  verbose?: boolean;
-}
+interface ContractValidateOptions {
+  verbose?: boolean;
+}
+
+interface ContractBuildOptions {
+  output?: string;
+}
+
+interface ContractDiffOptions {
+  from?: string;
+  to?: string;
+  output?: string;
+  json?: boolean;
+}
 
 /**
  * Create a new contract file for a route
@@ -85,7 +104,7 @@ export async function contractCreate(options: ContractCreateOptions): Promise<bo
 /**
  * Validate all contracts against their slot implementations
  */
-export async function contractValidate(options: ContractValidateOptions = {}): Promise<boolean> {
+export async function contractValidate(options: ContractValidateOptions = {}): Promise<boolean> {
   const rootDir = process.cwd();
   const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
 
@@ -148,5 +167,112 @@ export async function contractValidate(options: ContractValidateOptions = {}): P
     console.log(`💡 Use --verbose for fix suggestions\n`);
   }
 
-  return false;
-}
+  return false;
+}
+
+/**
+ * Build contract registry (.mandu/contracts.json)
+ */
+export async function contractBuild(options: ContractBuildOptions = {}): Promise<boolean> {
+  const rootDir = process.cwd();
+  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
+  const outputPath = options.output || path.join(rootDir, ".mandu", "contracts.json");
+
+  console.log(`\n📦 Building contract registry...\n`);
+
+  const manifestResult = await loadManifest(manifestPath);
+  if (!manifestResult.success) {
+    console.error("❌ Failed to load manifest:", manifestResult.errors);
+    return false;
+  }
+
+  const manifest = manifestResult.data!;
+  const { registry, warnings } = await buildContractRegistry(manifest, rootDir);
+
+  if (warnings.length > 0) {
+    console.log(`⚠️  ${warnings.length} warning(s):`);
+    for (const warning of warnings) {
+      console.log(`   - ${warning}`);
+    }
+    console.log();
+  }
+
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await writeContractRegistry(outputPath, registry);
+
+  console.log(`✅ Registry generated: ${path.relative(rootDir, outputPath)}`);
+  console.log(`📊 Contracts: ${registry.contracts.length}`);
+
+  return true;
+}
+
+/**
+ * Diff current contracts against a registry
+ */
+export async function contractDiff(options: ContractDiffOptions = {}): Promise<boolean> {
+  const rootDir = process.cwd();
+  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
+  const fromPath = options.from || path.join(rootDir, ".mandu", "contracts.json");
+
+  console.log(`\n🔍 Diffing contracts...\n`);
+
+  const fromRegistry = await readContractRegistry(fromPath);
+  if (!fromRegistry) {
+    console.error(`❌ Registry not found: ${path.relative(rootDir, fromPath)}`);
+    console.log(`💡 Run \`mandu contract build\` first.`);
+    return false;
+  }
+
+  let toRegistry = options.to ? await readContractRegistry(options.to) : null;
+
+  if (!toRegistry) {
+    const manifestResult = await loadManifest(manifestPath);
+    if (!manifestResult.success) {
+      console.error("❌ Failed to load manifest:", manifestResult.errors);
+      return false;
+    }
+    const { registry } = await buildContractRegistry(manifestResult.data!, rootDir);
+    toRegistry = registry;
+  }
+
+  const diff = diffContractRegistry(fromRegistry, toRegistry);
+
+  if (options.output) {
+    await fs.mkdir(path.dirname(options.output), { recursive: true });
+    await Bun.write(options.output, JSON.stringify(diff, null, 2));
+    console.log(`✅ Diff saved: ${path.relative(rootDir, options.output)}`);
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify(diff, null, 2));
+    return diff.summary.major === 0;
+  }
+
+  console.log(`📊 Summary: major ${diff.summary.major}, minor ${diff.summary.minor}, patch ${diff.summary.patch}`);
+
+  if (diff.added.length > 0) {
+    console.log(`\n🟢 Added (${diff.added.length})`);
+    for (const entry of diff.added) {
+      console.log(`  - ${entry.id} (${entry.routeId})`);
+    }
+  }
+
+  if (diff.removed.length > 0) {
+    console.log(`\n🔴 Removed (${diff.removed.length})`);
+    for (const entry of diff.removed) {
+      console.log(`  - ${entry.id} (${entry.routeId})`);
+    }
+  }
+
+  if (diff.changed.length > 0) {
+    console.log(`\n🟡 Changed (${diff.changed.length})`);
+    for (const change of diff.changed) {
+      console.log(`  - ${change.id} (${change.routeId}) [${change.severity}]`);
+      for (const detail of change.changes) {
+        console.log(`     • ${detail}`);
+      }
+    }
+  }
+
+  return diff.summary.major === 0;
+}