@mandujs/cli 0.9.24 → 0.9.43

package/src/commands/guard-arch.ts

@@ -19,6 +19,7 @@ import {
   calculateLayerStatistics,
   generateGuardMarkdownReport,
   generateHTMLReport,
+  validateAndReport,
   type GuardConfig,
   type GuardPreset,
 } from "@mandujs/core";
@@ -52,22 +53,28 @@ export interface GuardArchOptions {
   showTrend?: boolean;
 }
 
+function inferReportFormat(output?: string): "json" | "markdown" | "html" | undefined {
+  if (!output) return undefined;
+  const ext = path.extname(output).toLowerCase();
+  if (ext === ".json") return "json";
+  if (ext === ".html" || ext === ".htm") return "html";
+  if (ext === ".md" || ext === ".markdown") return "markdown";
+  return undefined;
+}
+
 export async function guardArch(options: GuardArchOptions = {}): Promise<boolean> {
+  const rootDir = resolveFromCwd(".");
   const {
-    preset = "mandu",
     watch = false,
-    ci = false,
+    ci = process.env.CI === "true",
     format,
     quiet = false,
-    srcDir = "src",
     listPresets: showPresets = false,
     output,
-    reportFormat = "markdown",
+    reportFormat = inferReportFormat(options.output) ?? "markdown",
     saveStats = false,
     showTrend = false,
   } = options;
-
-  const rootDir = resolveFromCwd(".");
   const resolvedFormat = resolveOutputFormat(format);
   const enableFsRoutes = await isDirectory(path.resolve(rootDir, "app"));
 
@@ -86,10 +93,17 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
       console.log("");
     }
 
-    console.log("Usage: bunx mandu guard arch --preset <name>");
+    console.log("Usage: set guard.preset in mandu.config to choose a preset");
     return true;
   }
 
+  const fileConfig = await validateAndReport(rootDir);
+  if (!fileConfig) return false;
+  const guardConfigFromFile = fileConfig.guard ?? {};
+
+  const preset = options.preset ?? guardConfigFromFile.preset ?? "mandu";
+  const srcDir = options.srcDir ?? guardConfigFromFile.srcDir ?? "src";
+
   if (resolvedFormat === "console") {
     console.log("");
     console.log("🛡️  Mandu Guard - Architecture Checker");
@@ -101,11 +115,12 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
   }
 
   // Guard 설정
-  const config: GuardConfig = {
+  const guardConfig: GuardConfig = {
     preset,
     srcDir,
     realtime: watch,
     realtimeOutput: resolvedFormat,
+    exclude: guardConfigFromFile.exclude,
     fsRoutes: enableFsRoutes
       ? {
           noPageToPage: true,
@@ -152,7 +167,7 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
     }
 
     const watcher = createGuardWatcher({
-      config,
+      config: guardConfig,
       rootDir,
       onViolation: (violation) => {
         // 실시간 위반 출력은 watcher 내부에서 처리됨
@@ -185,7 +200,7 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
     console.log("🔍 Scanning for architecture violations...\n");
   }
 
-  const report = await checkDirectory(config, rootDir);
+  const report = await checkDirectory(guardConfig, rootDir);
   const presetDef = getPreset(preset);
 
   // 출력 형식에 따른 리포트 출력

package/src/commands/init.ts

@@ -1,5 +1,6 @@
-import path from "path";
-import fs from "fs/promises";
+import path from "path";
+import fs from "fs/promises";
+import { CLI_ERROR_CODES, printCLIError } from "../errors";
 
 export type CSSFramework = "tailwind" | "panda" | "none";
 export type UILibrary = "shadcn" | "ark" | "none";
@@ -162,8 +163,8 @@ export async function init(options: InitOptions = {}): Promise<boolean> {
   // Check if target directory exists
   try {
     await fs.access(targetDir);
-    console.error(`❌ 디렉토리가 이미 존재합니다: ${targetDir}`);
-    return false;
+    printCLIError(CLI_ERROR_CODES.INIT_DIR_EXISTS, { path: targetDir });
+    return false;
   } catch {
     // Directory doesn't exist, good to proceed
   }
@@ -175,9 +176,9 @@ export async function init(options: InitOptions = {}): Promise<boolean> {
   try {
     await fs.access(templateDir);
   } catch {
-    console.error(`❌ 템플릿을 찾을 수 없습니다: ${template}`);
-    console.error(`   사용 가능한 템플릿: default`);
-    return false;
+    printCLIError(CLI_ERROR_CODES.INIT_TEMPLATE_NOT_FOUND, { template });
+    console.error(`   사용 가능한 템플릿: default`);
+    return false;
   }
 
   console.log(`📋 템플릿 복사 중...`);

package/src/commands/monitor.ts

@@ -2,12 +2,11 @@ import fs from "fs/promises";
 import fsSync from "fs";
 import path from "path";
 import { resolveFromCwd, pathExists } from "../util/fs";
-import { resolveOutputFormat, type OutputFormat } from "../util/output";
+import { resolveOutputFormat } from "../util/output";
 
 type MonitorOutput = "console" | "json";
 
 export interface MonitorOptions {
-  format?: OutputFormat;
   follow?: boolean;
   summary?: boolean;
   since?: string;
@@ -263,7 +262,7 @@ async function followFile(
 
 export async function monitor(options: MonitorOptions = {}): Promise<boolean> {
   const rootDir = resolveFromCwd(".");
-  const resolved = resolveOutputFormat(options.format);
+  const resolved = resolveOutputFormat();
   const output: MonitorOutput = resolved === "json" || resolved === "agent" ? "json" : "console";
   const filePath = await resolveLogFile(rootDir, output, options.file);
 

package/src/commands/openapi.ts

@@ -3,9 +3,10 @@
  * OpenAPI 스펙 생성 명령어
  */
 
-import { loadManifest, generateOpenAPIDocument, openAPIToJSON } from "@mandujs/core";
-import path from "path";
-import fs from "fs/promises";
+import { generateOpenAPIDocument, openAPIToJSON, validateAndReport } from "@mandujs/core";
+import path from "path";
+import fs from "fs/promises";
+import { resolveManifest } from "../util/manifest";
 
 interface OpenAPIGenerateOptions {
   output?: string;
@@ -13,27 +14,78 @@ interface OpenAPIGenerateOptions {
   version?: string;
 }
 
-interface OpenAPIServeOptions {
-  port?: number;
-}
-
-/**
- * Generate OpenAPI specification from contracts
- */
-export async function openAPIGenerate(options: OpenAPIGenerateOptions = {}): Promise<boolean> {
-  const rootDir = process.cwd();
-  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
-
-  console.log(`\n📄 Generating OpenAPI specification...\n`);
-
-  // Load manifest
-  const manifestResult = await loadManifest(manifestPath);
-  if (!manifestResult.success) {
-    console.error("❌ Failed to load manifest:", manifestResult.errors);
-    return false;
-  }
-
-  const manifest = manifestResult.data!;
+interface OpenAPIServeOptions {
+  port?: number;
+}
+
+function normalizePort(value: string | number | undefined, label: string): number | undefined {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  const port = typeof value === "string" ? Number(value) : value;
+  if (!Number.isFinite(port) || !Number.isInteger(port)) {
+    console.warn(`⚠️  Invalid ${label} value: "${value}" (using default)`);
+    return undefined;
+  }
+  if (port < 1 || port > 65535) {
+    console.warn(`⚠️  Invalid ${label} range: ${port} (must be 1-65535, using default)`);
+    return undefined;
+  }
+  return port;
+}
+
+function isPortInUse(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false;
+  const code = (error as { code?: string }).code;
+  const message = (error as { message?: string }).message ?? "";
+  return code === "EADDRINUSE" || message.includes("EADDRINUSE") || message.includes("address already in use");
+}
+
+function serveWithAutoPort(
+  startPort: number,
+  fetch: (req: Request) => Response
+): { server: ReturnType<typeof Bun.serve>; port: number; attempts: number } {
+  const maxAttempts = 10;
+  let lastError: unknown = null;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const candidate = startPort + attempt;
+    if (candidate < 1 || candidate > 65535) {
+      continue;
+    }
+    try {
+      const server = Bun.serve({ port: candidate, fetch });
+      return { server, port: server.port ?? candidate, attempts: attempt };
+    } catch (error) {
+      if (!isPortInUse(error)) {
+        throw error;
+      }
+      lastError = error;
+    }
+  }
+
+  throw lastError ?? new Error(`No available port found starting at ${startPort}`);
+}
+
+/**
+ * Generate OpenAPI specification from contracts
+ */
+export async function openAPIGenerate(options: OpenAPIGenerateOptions = {}): Promise<boolean> {
+  const rootDir = process.cwd();
+
+  console.log(`\n📄 Generating OpenAPI specification...\n`);
+
+  // Load manifest (FS Routes 우선)
+  let manifest: Awaited<ReturnType<typeof resolveManifest>>["manifest"];
+  try {
+    const config = await validateAndReport(rootDir);
+    if (!config) return false;
+    const resolved = await resolveManifest(rootDir, { fsRoutes: config.fsRoutes });
+    manifest = resolved.manifest;
+  } catch (error) {
+    console.error("❌ Failed to load manifest:", error instanceof Error ? error.message : error);
+    return false;
+  }
 
   // Count routes with contracts
   const contractRoutes = manifest.routes.filter((r) => r.contractModule);
@@ -96,10 +148,16 @@ export async function openAPIGenerate(options: OpenAPIGenerateOptions = {}): Pro
 /**
  * Serve Swagger UI for OpenAPI documentation
  */
-export async function openAPIServe(options: OpenAPIServeOptions = {}): Promise<boolean> {
-  const rootDir = process.cwd();
-  const port = options.port || 8080;
-  const openAPIPath = path.join(rootDir, "openapi.json");
+export async function openAPIServe(options: OpenAPIServeOptions = {}): Promise<boolean> {
+  const rootDir = process.cwd();
+  const config = await validateAndReport(rootDir);
+  if (!config) return false;
+
+  const optionPort = normalizePort(options.port, "openapi.port");
+  const envPort = normalizePort(process.env.PORT, "PORT");
+  const configPort = normalizePort(config.server?.port, "mandu.config server.port");
+  const desiredPort = optionPort ?? envPort ?? configPort ?? 8080;
+  const openAPIPath = path.join(rootDir, "openapi.json");
 
   console.log(`\n🌐 Starting OpenAPI documentation server...\n`);
 
@@ -154,26 +212,27 @@ export async function openAPIServe(options: OpenAPIServeOptions = {}): Promise<b
 </html>
   `.trim();
 
-  // Start server
-  const server = Bun.serve({
-    port,
-    fetch(req) {
-      const url = new URL(req.url);
-
-      if (url.pathname === "/openapi.json") {
-        return new Response(specContent, {
-          headers: { "Content-Type": "application/json" },
-        });
-      }
-
-      return new Response(swaggerHTML, {
-        headers: { "Content-Type": "text/html" },
-      });
-    },
-  });
-
-  console.log(`✅ Swagger UI is running at http://localhost:${port}`);
-  console.log(`   OpenAPI spec: http://localhost:${port}/openapi.json`);
+  // Start server (auto port fallback)
+  const { port, attempts } = serveWithAutoPort(desiredPort, (req) => {
+      const url = new URL(req.url);
+
+      if (url.pathname === "/openapi.json") {
+        return new Response(specContent, {
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+
+      return new Response(swaggerHTML, {
+        headers: { "Content-Type": "text/html" },
+      });
+  });
+
+  if (attempts > 0) {
+    console.warn(`⚠️  Port ${desiredPort} is in use. Using ${port} instead.`);
+  }
+
+  console.log(`✅ Swagger UI is running at http://localhost:${port}`);
+  console.log(`   OpenAPI spec: http://localhost:${port}/openapi.json`);
   console.log(`\nPress Ctrl+C to stop.\n`);
 
   // Keep server running

package/src/commands/routes.ts

@@ -9,6 +9,7 @@ import {
   generateManifest,
   formatRoutesForCLI,
   watchFSRoutes,
+  validateAndReport,
   type GenerateOptions,
   type FSScannerConfig,
 } from "@mandujs/core";
@@ -46,11 +47,14 @@ export interface RoutesWatchOptions {
  */
 export async function routesGenerate(options: RoutesGenerateOptions = {}): Promise<boolean> {
   const rootDir = resolveFromCwd(".");
+  const config = await validateAndReport(rootDir);
+  if (!config) return false;
 
   console.log("🥟 Mandu FS Routes Generate\n");
 
   try {
     const generateOptions: GenerateOptions = {
+      scanner: config.fsRoutes,
       outputPath: options.output ?? ".mandu/routes.manifest.json",
       skipLegacy: true, // 레거시 병합 비활성화
     };
@@ -93,11 +97,13 @@ export async function routesGenerate(options: RoutesGenerateOptions = {}): Promi
  */
 export async function routesList(options: RoutesListOptions = {}): Promise<boolean> {
   const rootDir = resolveFromCwd(".");
+  const config = await validateAndReport(rootDir);
+  if (!config) return false;
 
   console.log("🥟 Mandu Routes List\n");
 
   try {
-    const result = await scanRoutes(rootDir);
+    const result = await scanRoutes(rootDir, config.fsRoutes);
 
     if (result.errors.length > 0) {
       console.log("⚠️  스캔 경고:");
@@ -164,6 +170,8 @@ export async function routesList(options: RoutesListOptions = {}): Promise<boole
  */
 export async function routesWatch(options: RoutesWatchOptions = {}): Promise<boolean> {
   const rootDir = resolveFromCwd(".");
+  const config = await validateAndReport(rootDir);
+  if (!config) return false;
 
   console.log("🥟 Mandu FS Routes Watch\n");
   console.log("👀 라우트 변경 감시 중... (Ctrl+C로 종료)\n");
@@ -171,6 +179,7 @@ export async function routesWatch(options: RoutesWatchOptions = {}): Promise<boo
   try {
     // 초기 스캔
     const initialResult = await generateManifest(rootDir, {
+      scanner: config.fsRoutes,
       outputPath: options.output ?? ".mandu/routes.manifest.json",
     });
 
@@ -178,6 +187,7 @@ export async function routesWatch(options: RoutesWatchOptions = {}): Promise<boo
 
     // 감시 시작
     const watcher = await watchFSRoutes(rootDir, {
+      scanner: config.fsRoutes,
       outputPath: options.output ?? ".mandu/routes.manifest.json",
       onChange: (result) => {
         const timestamp = new Date().toLocaleTimeString();

package/src/errors/codes.ts

@@ -0,0 +1,35 @@
+/**
+ * CLI error codes
+ */
+export const CLI_ERROR_CODES = {
+  // Init errors (E001-E009)
+  INIT_DIR_EXISTS: "CLI_E001",
+  INIT_BUN_NOT_FOUND: "CLI_E002",
+  INIT_TEMPLATE_NOT_FOUND: "CLI_E003",
+
+  // Dev errors (E010-E019)
+  DEV_PORT_IN_USE: "CLI_E010",
+  DEV_MANIFEST_NOT_FOUND: "CLI_E011",
+  DEV_NO_ROUTES: "CLI_E012",
+
+  // Guard errors (E020-E029)
+  GUARD_CONFIG_INVALID: "CLI_E020",
+  GUARD_PRESET_NOT_FOUND: "CLI_E021",
+  GUARD_VIOLATION_FOUND: "CLI_E022",
+
+  // Build errors (E030-E039)
+  BUILD_ENTRY_NOT_FOUND: "CLI_E030",
+  BUILD_BUNDLE_FAILED: "CLI_E031",
+  BUILD_OUTDIR_NOT_WRITABLE: "CLI_E032",
+
+  // Config errors (E040-E049)
+  CONFIG_PARSE_FAILED: "CLI_E040",
+  CONFIG_VALIDATION_FAILED: "CLI_E041",
+
+  // CLI usage errors (E100+)
+  UNKNOWN_COMMAND: "CLI_E100",
+  UNKNOWN_SUBCOMMAND: "CLI_E101",
+  MISSING_ARGUMENT: "CLI_E102",
+} as const;
+
+export type CLIErrorCode = typeof CLI_ERROR_CODES[keyof typeof CLI_ERROR_CODES];

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export { CLI_ERROR_CODES, type CLIErrorCode } from "./codes";
+export { CLIError, formatCLIError, handleCLIError, printCLIError } from "./messages";

package/src/errors/messages.ts

@@ -0,0 +1,143 @@
+import { CLI_ERROR_CODES, type CLIErrorCode } from "./codes";
+
+interface ErrorInfo {
+  message: string;
+  suggestion?: string;
+  docLink?: string;
+}
+
+export const ERROR_MESSAGES: Record<CLIErrorCode, ErrorInfo> = {
+  [CLI_ERROR_CODES.INIT_DIR_EXISTS]: {
+    message: "Directory already exists: {path}",
+    suggestion: "Choose a different project name or remove the existing directory.",
+  },
+  [CLI_ERROR_CODES.INIT_BUN_NOT_FOUND]: {
+    message: "Bun runtime not found.",
+    suggestion: "Install Bun and ensure it is available in your PATH.",
+  },
+  [CLI_ERROR_CODES.INIT_TEMPLATE_NOT_FOUND]: {
+    message: "Template not found: {template}",
+    suggestion: "Use a valid template name (default).",
+  },
+  [CLI_ERROR_CODES.DEV_PORT_IN_USE]: {
+    message: "Port {port} is already in use.",
+    suggestion: "Set PORT or mandu.config server.port to pick a different port, or stop the process using this port.",
+  },
+  [CLI_ERROR_CODES.DEV_MANIFEST_NOT_FOUND]: {
+    message: "Routes manifest not found.",
+    suggestion: "Run `mandu routes generate` or create app/ routes before dev.",
+  },
+  [CLI_ERROR_CODES.DEV_NO_ROUTES]: {
+    message: "No routes were found in app/.",
+    suggestion: "Create app/page.tsx or app/api/*/route.ts to get started.",
+  },
+  [CLI_ERROR_CODES.GUARD_CONFIG_INVALID]: {
+    message: "Invalid guard configuration.",
+    suggestion: "Check your mandu.config and guard settings.",
+  },
+  [CLI_ERROR_CODES.GUARD_PRESET_NOT_FOUND]: {
+    message: "Unknown architecture preset: {preset}",
+    suggestion: "Available presets: mandu, fsd, clean, hexagonal, atomic.",
+  },
+  [CLI_ERROR_CODES.GUARD_VIOLATION_FOUND]: {
+    message: "{count} architecture violation(s) found.",
+    suggestion: "Fix violations above or set MANDU_OUTPUT=agent for AI-friendly output.",
+  },
+  [CLI_ERROR_CODES.BUILD_ENTRY_NOT_FOUND]: {
+    message: "Build entry not found: {entry}",
+    suggestion: "Check your routes manifest or build inputs.",
+  },
+  [CLI_ERROR_CODES.BUILD_BUNDLE_FAILED]: {
+    message: "Bundle build failed for '{target}'.",
+    suggestion: "Review build errors above for missing deps or syntax errors.",
+  },
+  [CLI_ERROR_CODES.BUILD_OUTDIR_NOT_WRITABLE]: {
+    message: "Output directory is not writable: {path}",
+    suggestion: "Ensure the directory exists and you have write permissions.",
+  },
+  [CLI_ERROR_CODES.CONFIG_PARSE_FAILED]: {
+    message: "Failed to parse mandu.config.",
+    suggestion: "Fix syntax errors in the config file.",
+  },
+  [CLI_ERROR_CODES.CONFIG_VALIDATION_FAILED]: {
+    message: "Configuration validation failed.",
+    suggestion: "Review validation errors above and fix your config.",
+  },
+  [CLI_ERROR_CODES.UNKNOWN_COMMAND]: {
+    message: "Unknown command: {command}",
+    suggestion: "Run with --help to see available commands.",
+  },
+  [CLI_ERROR_CODES.UNKNOWN_SUBCOMMAND]: {
+    message: "Unknown subcommand '{subcommand}' for {command}.",
+    suggestion: "Run the command with --help to see available subcommands.",
+  },
+  [CLI_ERROR_CODES.MISSING_ARGUMENT]: {
+    message: "Missing required argument: {argument}",
+    suggestion: "Provide the required argument and try again.",
+  },
+};
+
+function interpolate(text: string, context?: Record<string, string | number>): string {
+  if (!context) return text;
+  let result = text;
+  for (const [key, value] of Object.entries(context)) {
+    result = result.replace(new RegExp(`\\{${key}\\}`, "g"), String(value));
+  }
+  return result;
+}
+
+export function formatCLIError(
+  code: CLIErrorCode,
+  context?: Record<string, string | number>
+): string {
+  const info = ERROR_MESSAGES[code];
+  const message = interpolate(info?.message ?? "Unknown error", context);
+  const suggestion = info?.suggestion ? interpolate(info.suggestion, context) : undefined;
+
+  const lines = ["", `❌ Error [${code}]`, `   ${message}`];
+  if (suggestion) {
+    lines.push("", `💡 ${suggestion}`);
+  }
+  if (info?.docLink) {
+    lines.push(`📖 ${info.docLink}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+export class CLIError extends Error {
+  readonly code: CLIErrorCode;
+  readonly context?: Record<string, string | number>;
+
+  constructor(code: CLIErrorCode, context?: Record<string, string | number>) {
+    super(formatCLIError(code, context));
+    this.code = code;
+    this.context = context;
+    this.name = "CLIError";
+  }
+}
+
+export function printCLIError(
+  code: CLIErrorCode,
+  context?: Record<string, string | number>
+): void {
+  console.error(formatCLIError(code, context));
+}
+
+export function handleCLIError(error: unknown): never {
+  if (error instanceof CLIError) {
+    console.error(error.message);
+    process.exit(1);
+  }
+
+  if (error instanceof Error) {
+    console.error(`\n❌ Unexpected error: ${error.message}\n`);
+    if (process.env.DEBUG) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+
+  console.error("\n❌ Unknown error occurred\n");
+  process.exit(1);
+}