@mandujs/cli 0.9.12 → 0.9.18

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

@@ -1,9 +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 { 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";
@@ -19,19 +21,30 @@ 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
 
 Usage: bunx mandu <command> [options]
 
-Commands:
-  init           새 프로젝트 생성
-  spec-upsert    Spec 파일 검증 및 lock 갱신
-  generate       Spec에서 코드 생성
-  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)
-  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)
@@ -52,47 +65,58 @@ Commands:
   change list    변경 이력 조회
   change prune   오래된 스냅샷 정리
 
-Options:
-  --name <name>      init 시 프로젝트 이름 (기본: my-mandu-app)
-  --file <path>      spec-upsert 시 사용할 spec 파일 경로
-  --port <port>      dev/openapi serve 포트 (기본: 3000/8080)
-  --no-auto-correct  guard 시 자동 수정 비활성화
+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 트렌드 분석 표시
   --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/check 출력 형식: console, json, agent (기본: 자동)
   --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 spec-upsert
-  bunx mandu generate
+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 build --minify
-  bunx mandu build --watch
-  bunx mandu dev --port 3000
+  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:
@@ -170,15 +194,46 @@ async function main(): Promise<void> {
       success = await specUpsert({ file: options.file });
       break;
 
-    case "generate":
-      success = await generateApply();
-      break;
-
-    case "guard":
-      success = await guardCheck({
-        autoCorrect: options["no-auto-correct"] !== "true",
-      });
+    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",
+          });
+          break;
+        default:
+          // 기본값: 레거시 guard-check
+          success = await guardCheck({
+            autoCorrect: options["no-auto-correct"] !== "true",
+          });
+      }
       break;
+    }
 
     case "build":
       success = await build({
@@ -188,9 +243,50 @@ async function main(): Promise<void> {
       });
       break;
 
-    case "dev":
-      await dev({ port: parsePort(options.port) });
+    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];
+      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];

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";
+}