@mandujs/cli 0.9.24 → 0.9.43

package/src/main.ts

@@ -23,6 +23,7 @@ import { watch } from "./commands/watch";
 import { brainSetup, brainStatus } from "./commands/brain";
 import { routesGenerate, routesList, routesWatch } from "./commands/routes";
 import { monitor } from "./commands/monitor";
+import { CLI_ERROR_CODES, handleCLIError, printCLIError } from "./errors";
 
 const HELP_TEXT = `
 🥟 Mandu CLI - Agent-Native Fullstack Framework
@@ -30,30 +31,25 @@ const HELP_TEXT = `
 Usage: bunx mandu <command> [options]
 
 Commands:
-  init           새 프로젝트 생성 (Tailwind + shadcn/ui 기본 포함)
-  check          FS Routes + Guard 통합 검사
-  routes generate  FS Routes 스캔 및 매니페스트 생성
-  routes list      현재 라우트 목록 출력
-  routes watch     실시간 라우트 감시
-  dev            개발 서버 실행 (FS Routes + Guard 기본)
-  dev --no-guard Guard 감시 비활성화
-  build          클라이언트 번들 빌드 (Hydration)
-  guard          아키텍처 위반 검사 (기본)
-  guard arch     아키텍처 위반 검사 (FSD/Clean/Hexagonal)
-  guard legacy   레거시 Spec Guard 검사
-  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)
-  monitor        MCP Activity Monitor 로그 스트림
-
-  brain setup    sLLM 설정 (선택)
-  brain status   Brain 상태 확인
+  init              새 프로젝트 생성 (Tailwind + shadcn/ui 기본 포함)
+  check             FS Routes + Guard 통합 검사
+  routes generate   FS Routes 스캔 및 매니페스트 생성
+  routes list       현재 라우트 목록 출력
+  routes watch      실시간 라우트 감시
+  dev               개발 서버 실행 (FS Routes + Guard 기본)
+  build             클라이언트 번들 빌드 (Hydration)
+  guard             아키텍처 위반 검사 (기본)
+  guard arch        아키텍처 위반 검사 (FSD/Clean/Hexagonal)
+  guard legacy      레거시 Spec Guard 검사
+  spec-upsert       Spec 파일 검증 및 lock 갱신 (레거시)
+  generate          Spec에서 코드 생성 (레거시)
+
+  doctor            Guard 실패 분석 + 패치 제안 (Brain)
+  watch             실시간 파일 감시 - 경고만 (Brain)
+  monitor           MCP Activity Monitor 로그 스트림
+
+  brain setup       sLLM 설정 (선택)
+  brain status      Brain 상태 확인
 
   contract create <routeId>  라우트에 대한 Contract 생성
   contract validate          Contract-Slot 일관성 검증
@@ -63,79 +59,68 @@ Commands:
   openapi generate           OpenAPI 3.0 스펙 생성
   openapi serve              Swagger UI 로컬 서버 실행
 
-  change begin   변경 트랜잭션 시작 (스냅샷 생성)
-  change commit  변경 확정
-  change rollback 스냅샷으로 복원
-  change status  현재 트랜잭션 상태
-  change list    변경 이력 조회
-  change prune   오래된 스냅샷 정리
+  change begin      변경 트랜잭션 시작 (스냅샷 생성)
+  change commit     변경 확정
+  change rollback   스냅샷으로 복원
+  change status     현재 트랜잭션 상태
+  change list       변경 이력 조회
+  change prune      오래된 스냅샷 정리
 
 Options:
-  --name <name>      init 시 프로젝트 이름 (기본: my-mandu-app)
-  --css <framework>  init 시 CSS 프레임워크: tailwind, panda, none (기본: tailwind)
-  --ui <library>     init 시 UI 라이브러리: shadcn, ark, none (기본: shadcn)
-  --theme            init 시 다크모드 테마 시스템 추가
-  --minimal          init 시 CSS/UI 없이 최소 템플릿 생성 (--css none --ui none)
-  --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 모드 (warning도 실패 처리)
-  --quiet            guard/check 요약만 출력
-  --report-format    guard arch 리포트 형식: json, markdown, html
-  --save-stats       guard arch 통계 저장 (트렌드 분석용)
-  --show-trend       guard arch 트렌드 분석 표시
-  --minify           build 시 코드 압축
-  --sourcemap        build 시 소스맵 생성
-  --watch            build/guard arch 파일 감시 모드
-  --summary          monitor 요약 출력 (JSON 로그에서만)
-  --since <duration> monitor 요약 기간 (예: 5m, 30s, 1h)
-  --follow <bool>    monitor follow 모드 (기본: true)
-  --file <path>      monitor 로그 파일 직접 지정
-  --message <msg>    change begin 시 설명 메시지
-  --id <id>          change rollback 시 특정 변경 ID
-  --keep <n>         change prune 시 유지할 스냅샷 수 (기본: 5)
-  --output <path>    openapi/doctor 출력 경로
-  --from <path>      contract diff 기준 레지스트리 경로
-  --to <path>        contract diff 대상 레지스트리 경로
-  --json             contract diff 결과 JSON 출력
-  --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         도움말 표시
+  --name <name>       init 시 프로젝트 이름 (기본: my-mandu-app)
+  --css <framework>   init 시 CSS 프레임워크: tailwind, panda, none (기본: tailwind)
+  --ui <library>      init 시 UI 라이브러리: shadcn, ark, none (기본: shadcn)
+  --theme             init 시 다크모드 테마 시스템 추가
+  --minimal           init 시 CSS/UI 없이 최소 템플릿 생성 (--css none --ui none)
+  --file <path>       spec-upsert spec 파일/monitor 로그 파일 경로
+  --watch             build/guard arch 파일 감시 모드
+  --output <path>     routes/openapi/doctor/contract/guard 출력 경로
+  --verbose           routes list/watch, contract validate, brain status 상세 출력
+  --from <path>       contract diff 기준 레지스트리 경로
+  --to <path>         contract diff 대상 레지스트리 경로
+  --json              contract diff 결과 JSON 출력
+  --title <title>     openapi generate title
+  --version <ver>     openapi generate version
+  --summary           monitor 요약 출력 (JSON 로그에서만)
+  --since <duration>  monitor 요약 기간 (예: 5m, 30s, 1h)
+  --follow <bool>     monitor follow 모드 (기본: true)
+  --message <msg>     change begin 시 설명 메시지
+  --id <id>           change rollback 시 특정 변경 ID
+  --keep <n>          change prune 시 유지할 스냅샷 수 (기본: 5)
+  --no-llm            doctor에서 LLM 사용 안 함 (템플릿 모드)
+  --status            watch 상태만 출력
+  --debounce <ms>     watch debounce (ms)
+  --model <name>      brain setup 시 모델 이름 (기본: llama3.2)
+  --url <url>         brain setup 시 Ollama URL
+  --skip-check        brain setup 시 모델/서버 체크 건너뜀
+  --help, -h          도움말 표시
+
+Notes:
+  - 출력 포맷은 환경에 따라 자동 결정됩니다 (TTY/CI/MANDU_OUTPUT).
+  - doctor 출력은 .json이면 JSON, 그 외는 markdown으로 저장됩니다.
+  - guard arch 리포트는 .json/.html/.md 확장자를 자동 추론합니다.
+  - 포트는 PORT 환경변수 또는 mandu.config의 server.port로 설정합니다.
+  - 포트 충돌 시 다음 사용 가능한 포트로 자동 변경됩니다.
 
 Examples:
   bunx mandu init --name my-app          # Tailwind + shadcn/ui 기본
   bunx mandu init my-app --minimal       # CSS/UI 없이 최소 템플릿
-  bunx mandu init my-app --theme         # 다크모드 테마 포함
-  bunx mandu init my-app --ui none       # UI 라이브러리 없이
-  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 dev
+  bunx mandu build --watch
   bunx mandu guard
-  bunx mandu guard arch --preset fsd
   bunx mandu guard arch --watch
-  bunx mandu guard arch --ci --format json
-  bunx mandu guard legacy
-  bunx mandu monitor
+  bunx mandu guard arch --output guard-report.md
+  bunx mandu check
+  bunx mandu routes list --verbose
+  bunx mandu contract create users
+  bunx mandu contract validate --verbose
+  bunx mandu contract build --output .mandu/contracts.json
+  bunx mandu contract diff --json
+  bunx mandu openapi generate --output docs/openapi.json
+  bunx mandu openapi serve
   bunx mandu monitor --summary --since 5m
-  bunx mandu doctor
+  bunx mandu doctor --output reports/doctor.json
   bunx mandu brain setup --model codellama
-  bunx mandu contract create users
-  bunx mandu contract build
-  bunx mandu contract diff
-  bunx mandu openapi generate --output docs/api.json
   bunx mandu change begin --message "Add new route"
 
 FS Routes Workflow (권장):
@@ -172,31 +157,6 @@ function parseArgs(args: string[]): { command: string; options: Record<string, s
   return { command, options };
 }
 
-/**
- * 포트 옵션 안전하게 파싱
- * - 숫자가 아니면 undefined 반환 (기본값 사용)
- * - 유효 범위: 1-65535
- */
-function parsePort(value: string | undefined, optionName = "port"): number | undefined {
-  if (!value || value === "true") {
-    return undefined; // 기본값 사용
-  }
-
-  const port = Number(value);
-
-  if (Number.isNaN(port)) {
-    console.warn(`⚠️  Invalid --${optionName} value: "${value}" (using default)`);
-    return undefined;
-  }
-
-  if (!Number.isInteger(port) || port < 1 || port > 65535) {
-    console.warn(`⚠️  Invalid --${optionName} range: ${port} (must be 1-65535, using default)`);
-    return undefined;
-  }
-
-  return port;
-}
-
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
   const { command, options } = parseArgs(args);
@@ -228,30 +188,15 @@ async function main(): Promise<void> {
       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",
-      });
+      success = await check();
       break;
 
     case "guard": {
       const subCommand = args[1];
       const hasSubCommand = subCommand && !subCommand.startsWith("--");
       const guardArchOptions = {
-        preset: options.preset as any,
         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",
       };
       switch (subCommand) {
         case "arch":
@@ -259,13 +204,14 @@ async function main(): Promise<void> {
           break;
         case "legacy":
         case "spec":
-          success = await guardCheck({
-            autoCorrect: options["no-auto-correct"] !== "true",
-          });
+          success = await guardCheck();
           break;
         default:
           if (hasSubCommand) {
-            console.error(`❌ Unknown guard subcommand: ${subCommand}`);
+            printCLIError(CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND, {
+              command: "guard",
+              subcommand,
+            });
             console.log("\nUsage: bunx mandu guard <arch|legacy>");
             process.exit(1);
           }
@@ -277,20 +223,12 @@ async function main(): Promise<void> {
 
     case "build":
       success = await build({
-        minify: options.minify === "true",
-        sourcemap: options.sourcemap === "true",
         watch: options.watch === "true",
       });
       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",
-      });
+      await dev();
       break;
 
     case "routes": {
@@ -320,7 +258,10 @@ async function main(): Promise<void> {
               verbose: options.verbose === "true",
             });
           } else {
-            console.error(`❌ Unknown routes subcommand: ${subCommand}`);
+            printCLIError(CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND, {
+              command: "routes",
+              subcommand,
+            });
             console.log("\nUsage: bunx mandu routes <generate|list|watch>");
             process.exit(1);
           }
@@ -334,7 +275,7 @@ async function main(): Promise<void> {
         case "create": {
           const routeId = args[2] || options._positional;
           if (!routeId) {
-            console.error("❌ Route ID is required");
+            printCLIError(CLI_ERROR_CODES.MISSING_ARGUMENT, { argument: "routeId" });
             console.log("\nUsage: bunx mandu contract create <routeId>");
             process.exit(1);
           }
@@ -356,7 +297,10 @@ async function main(): Promise<void> {
           });
           break;
         default:
-          console.error(`❌ Unknown contract subcommand: ${subCommand}`);
+          printCLIError(CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND, {
+            command: "contract",
+            subcommand,
+          });
           console.log("\nUsage: bunx mandu contract <create|validate|build|diff>");
           process.exit(1);
       }
@@ -374,12 +318,13 @@ async function main(): Promise<void> {
           });
           break;
         case "serve":
-          success = await openAPIServe({
-            port: parsePort(options.port),
-          });
+          success = await openAPIServe();
           break;
         default:
-          console.error(`❌ Unknown openapi subcommand: ${subCommand}`);
+          printCLIError(CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND, {
+            command: "openapi",
+            subcommand,
+          });
           console.log("\nUsage: bunx mandu openapi <generate|serve>");
           process.exit(1);
       }
@@ -410,7 +355,10 @@ async function main(): Promise<void> {
           });
           break;
         default:
-          console.error(`❌ Unknown change subcommand: ${subCommand}`);
+          printCLIError(CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND, {
+            command: "change",
+            subcommand,
+          });
           console.log(`\nUsage: bunx mandu change <begin|commit|rollback|status|list|prune>`);
           process.exit(1);
       }
@@ -419,7 +367,6 @@ async function main(): Promise<void> {
 
     case "doctor":
       success = await doctor({
-        format: (options.format as "console" | "json" | "markdown") || "console",
         useLLM: options["no-llm"] !== "true",
         output: options.output,
       });
@@ -434,7 +381,6 @@ async function main(): Promise<void> {
 
     case "monitor":
       success = await monitor({
-        format: options.format as any,
         summary: options.summary === "true",
         since: options.since,
         follow: options.follow === "false" ? false : true,
@@ -458,7 +404,10 @@ async function main(): Promise<void> {
           });
           break;
         default:
-          console.error(`❌ Unknown brain subcommand: ${subCommand}`);
+          printCLIError(CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND, {
+            command: "brain",
+            subcommand,
+          });
           console.log("\nUsage: bunx mandu brain <setup|status>");
           process.exit(1);
       }
@@ -466,7 +415,7 @@ async function main(): Promise<void> {
     }
 
     default:
-      console.error(`❌ Unknown command: ${command}`);
+      printCLIError(CLI_ERROR_CODES.UNKNOWN_COMMAND, { command });
       console.log(HELP_TEXT);
       process.exit(1);
   }
@@ -476,7 +425,4 @@ async function main(): Promise<void> {
   }
 }
 
-main().catch((error) => {
-  console.error("❌ 예상치 못한 오류:", error);
-  process.exit(1);
-});
+main().catch((error) => handleCLIError(error));

package/src/util/bun.ts

@@ -0,0 +1,6 @@
+export function importFresh<T = unknown>(modulePath: string): Promise<T> {
+  const url = Bun.pathToFileURL(modulePath);
+  const cacheBusted = new URL(url.href);
+  cacheBusted.searchParams.set("t", Date.now().toString());
+  return import(cacheBusted.href) as Promise<T>;
+}

package/src/util/manifest.ts

@@ -0,0 +1,52 @@
+import path from "path";
+import {
+  generateManifest,
+  loadManifest,
+  type RoutesManifest,
+  type FSScannerConfig,
+} from "@mandujs/core";
+import { isDirectory } from "./fs";
+
+export type ManifestSource = "fs" | "spec";
+
+export interface ResolvedManifest {
+  manifest: RoutesManifest;
+  source: ManifestSource;
+  warnings: string[];
+}
+
+export async function resolveManifest(
+  rootDir: string,
+  options: { fsRoutes?: FSScannerConfig; outputPath?: string } = {}
+): Promise<ResolvedManifest> {
+  const appDir = path.resolve(rootDir, "app");
+  const hasApp = await isDirectory(appDir);
+
+  if (hasApp) {
+    const result = await generateManifest(rootDir, {
+      scanner: options.fsRoutes,
+      outputPath: options.outputPath,
+      skipLegacy: true,
+    });
+    return {
+      manifest: result.manifest,
+      source: "fs",
+      warnings: result.warnings,
+    };
+  }
+
+  const specPath = path.join(rootDir, "spec", "routes.manifest.json");
+  if (await Bun.file(specPath).exists()) {
+    const result = await loadManifest(specPath);
+    if (!result.success) {
+      throw new Error(result.errors?.join(", ") || "Failed to load routes manifest");
+    }
+    return {
+      manifest: result.data!,
+      source: "spec",
+      warnings: [],
+    };
+  }
+
+  throw new Error("No routes found. Create app/ routes or spec/routes.manifest.json");
+}

package/src/util/port.ts

@@ -0,0 +1,71 @@
+import { createServer } from "net";
+
+const DEFAULT_MAX_ATTEMPTS = 10;
+
+function isPortUsable(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as { code?: string }).code;
+  return code === "EADDRINUSE" || code === "EACCES";
+}
+
+async function isPortAvailable(port: number, hostname?: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    const server = createServer();
+
+    server.once("error", (error) => {
+      if (isPortUsable(error)) {
+        resolve(false);
+      } else {
+        resolve(false);
+      }
+    });
+
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+
+    try {
+      server.listen(port, hostname);
+      server.unref();
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+export async function resolveAvailablePort(
+  startPort: number,
+  options: {
+    hostname?: string;
+    offsets?: number[];
+    maxAttempts?: number;
+  } = {}
+): Promise<{ port: number; attempts: number }> {
+  const offsets = options.offsets && options.offsets.length > 0 ? options.offsets : [0];
+  const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const candidate = startPort + attempt;
+    if (candidate < 1 || candidate > 65535) {
+      continue;
+    }
+
+    const targets = offsets
+      .map((offset) => candidate + offset)
+      .filter((port) => port >= 1 && port <= 65535);
+
+    if (targets.length !== offsets.length) {
+      continue;
+    }
+
+    const results = await Promise.all(
+      targets.map((port) => isPortAvailable(port, options.hostname))
+    );
+
+    if (results.every(Boolean)) {
+      return { port: candidate, attempts: attempt };
+    }
+  }
+
+  throw new Error(`No available port found starting at ${startPort}`);
+}

package/templates/default/AGENTS.md

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