@mandujs/cli 0.9.42 → 0.9.44

package/src/commands/doctor.ts

@@ -15,20 +15,22 @@ import {
   getBrain,
 } from "../../../core/src/index";
 import { resolveFromCwd, getRootDir } from "../util/fs";
-import path from "path";
+import path from "path";
 import fs from "fs/promises";
 
-export interface DoctorOptions {
-  /** Output format: console, json, or markdown */
-  format?: "console" | "json" | "markdown";
+export interface DoctorOptions {
+  /** Output format: console, json, or markdown */
+  format?: "console" | "json" | "markdown";
   /** Whether to use LLM for enhanced analysis */
   useLLM?: boolean;
   /** Output file path (for json/markdown formats) */
-  output?: string;
-}
-
-export async function doctor(options: DoctorOptions = {}): Promise<boolean> {
-  const { format = "console", useLLM = true, output } = options;
+  output?: string;
+}
+
+export async function doctor(options: DoctorOptions = {}): Promise<boolean> {
+  const { format, useLLM = true, output } = options;
+  const inferredFormat = format ?? (output ? (path.extname(output).toLowerCase() === ".json" ? "json" : "markdown") : undefined);
+  const resolvedFormat = inferredFormat ?? "console";
 
   const specPath = resolveFromCwd("spec/routes.manifest.json");
   const rootDir = getRootDir();
@@ -80,12 +82,12 @@ export async function doctor(options: DoctorOptions = {}): Promise<boolean> {
   });
 
   // Output based on format
-  switch (format) {
-    case "console":
-      printDoctorReport(analysis);
-      break;
-
-    case "json": {
+  switch (resolvedFormat) {
+    case "console":
+      printDoctorReport(analysis);
+      break;
+
+    case "json": {
       const json = JSON.stringify(
         {
           summary: analysis.summary,
@@ -104,10 +106,10 @@ export async function doctor(options: DoctorOptions = {}): Promise<boolean> {
       } else {
         console.log(json);
       }
-      break;
-    }
-
-    case "markdown": {
+      break;
+    }
+
+    case "markdown": {
       const md = generateDoctorMarkdownReport(analysis);
 
       if (output) {
@@ -116,9 +118,9 @@ export async function doctor(options: DoctorOptions = {}): Promise<boolean> {
       } else {
         console.log(md);
       }
-      break;
-    }
-  }
-
-  return false;
-}
+      break;
+    }
+  }
+
+  return false;
+}

package/src/commands/guard-arch.ts

@@ -53,16 +53,25 @@ 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 {
     watch = false,
-    ci = false,
+    ci = process.env.CI === "true",
     format,
     quiet = false,
     listPresets: showPresets = false,
     output,
-    reportFormat = "markdown",
+    reportFormat = inferReportFormat(options.output) ?? "markdown",
     saveStats = false,
     showTrend = false,
   } = options;
@@ -84,7 +93,7 @@ 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;
   }
 

package/src/commands/init.ts

@@ -1,6 +1,6 @@
-import path from "path";
-import fs from "fs/promises";
-import { CLI_ERROR_CODES, printCLIError } from "../errors";
+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";
@@ -21,13 +21,13 @@ const CSS_FILES = [
   "app/globals.css",
 ];
 
-const UI_FILES = [
-  "src/client/shared/ui/button.tsx",
-  "src/client/shared/ui/card.tsx",
-  "src/client/shared/ui/input.tsx",
-  "src/client/shared/ui/index.ts",
-  "src/client/shared/lib/utils.ts",
-];
+const UI_FILES = [
+  "src/client/shared/ui/button.tsx",
+  "src/client/shared/ui/card.tsx",
+  "src/client/shared/ui/input.tsx",
+  "src/client/shared/ui/index.ts",
+  "src/client/shared/lib/utils.ts",
+];
 
 interface CopyOptions {
   projectName: string;
@@ -46,15 +46,15 @@ function shouldSkipFile(relativePath: string, options: CopyOptions): boolean {
     }
   }
 
-  // Skip UI files if ui is none
-  if (options.ui === "none") {
-    if (UI_FILES.some((f) => normalizedPath.endsWith(f))) {
-      return true;
-    }
-    // Skip UI/shared directories
-    if (normalizedPath.includes("src/client/shared/ui/")) return true;
-    if (normalizedPath.includes("src/client/shared/lib/")) return true;
-  }
+  // Skip UI files if ui is none
+  if (options.ui === "none") {
+    if (UI_FILES.some((f) => normalizedPath.endsWith(f))) {
+      return true;
+    }
+    // Skip UI/shared directories
+    if (normalizedPath.includes("src/client/shared/ui/")) return true;
+    if (normalizedPath.includes("src/client/shared/lib/")) return true;
+  }
 
   return false;
 }
@@ -76,13 +76,13 @@ async function copyDir(
       : entry.name;
 
     if (entry.isDirectory()) {
-      // Skip directories that would be empty when ui=none
-      if (options.ui === "none") {
-        if (entry.name === "ui" && relativePath === "src/client/shared") continue;
-        if (entry.name === "lib" && relativePath === "src/client/shared") continue;
-      }
-      await copyDir(srcPath, destPath, options, currentRelativePath);
-    } else {
+      // Skip directories that would be empty when ui=none
+      if (options.ui === "none") {
+        if (entry.name === "ui" && relativePath === "src/client/shared") continue;
+        if (entry.name === "lib" && relativePath === "src/client/shared") continue;
+      }
+      await copyDir(srcPath, destPath, options, currentRelativePath);
+    } else {
       // Check if file should be skipped
       if (shouldSkipFile(currentRelativePath, options)) {
         continue;
@@ -163,8 +163,8 @@ export async function init(options: InitOptions = {}): Promise<boolean> {
   // Check if target directory exists
   try {
     await fs.access(targetDir);
-    printCLIError(CLI_ERROR_CODES.INIT_DIR_EXISTS, { path: targetDir });
-    return false;
+    printCLIError(CLI_ERROR_CODES.INIT_DIR_EXISTS, { path: targetDir });
+    return false;
   } catch {
     // Directory doesn't exist, good to proceed
   }
@@ -176,9 +176,9 @@ export async function init(options: InitOptions = {}): Promise<boolean> {
   try {
     await fs.access(templateDir);
   } catch {
-    printCLIError(CLI_ERROR_CODES.INIT_TEMPLATE_NOT_FOUND, { template });
-    console.error(`   사용 가능한 템플릿: default`);
-    return false;
+    printCLIError(CLI_ERROR_CODES.INIT_TEMPLATE_NOT_FOUND, { template });
+    console.error(`   사용 가능한 템플릿: default`);
+    return false;
   }
 
   console.log(`📋 템플릿 복사 중...`);
@@ -221,26 +221,25 @@ export async function init(options: InitOptions = {}): Promise<boolean> {
   console.log(`   cd ${projectName}`);
   console.log(`   bun install`);
   console.log(`   bun run dev`);
-  console.log(`\n📂 파일 구조:`);
-  console.log(`   app/layout.tsx    → 루트 레이아웃`);
-  console.log(`   app/page.tsx      → http://localhost:3000/`);
-  console.log(`   app/api/*/route.ts → API endpoints`);
-  console.log(`   src/client/*      → 클라이언트 레이어`);
-  console.log(`   src/server/*      → 서버 레이어`);
-  console.log(`   src/shared/contracts → 계약 (client-safe)`);
-  console.log(`   src/shared/types     → 공용 타입`);
-  console.log(`   src/shared/utils/client → 클라이언트 safe 유틸`);
-  console.log(`   src/shared/utils/server → 서버 전용 유틸`);
-  console.log(`   src/shared/schema    → 서버 전용 스키마`);
-  console.log(`   src/shared/env       → 서버 전용 환경`);
-  if (css !== "none") {
-    console.log(`   app/globals.css   → 전역 CSS (Tailwind)`);
-    console.log(`   tailwind.config.ts → Tailwind 설정`);
-  }
-  if (ui !== "none") {
-    console.log(`   src/client/shared/ui/ → UI 컴포넌트 (shadcn)`);
-    console.log(`   src/client/shared/lib/utils.ts → 유틸리티 (cn 함수)`);
-  }
+  console.log(`\n📂 파일 구조:`);
+  console.log(`   app/layout.tsx    → 루트 레이아웃`);
+  console.log(`   app/page.tsx      → http://localhost:3000/`);
+  console.log(`   app/api/*/route.ts → API endpoints`);
+  console.log(`   src/client/*      → 클라이언트 레이어`);
+  console.log(`   src/server/*      → 서버 레이어`);
+  console.log(`   src/shared/contracts → 계약 (client-safe)`);
+  console.log(`   src/shared/types     → 공용 타입`);
+  console.log(`   src/shared/utils/client → 클라이언트 safe 유틸`);
+  console.log(`   src/shared/utils/server → 서버 전용 유틸`);
+  console.log(`   src/shared/schema    → 서버 전용 스키마`);
+  console.log(`   src/shared/env       → 서버 전용 환경`);
+  if (css !== "none") {
+    console.log(`   app/globals.css   → 전역 CSS (Tailwind v4)`);
+  }
+  if (ui !== "none") {
+    console.log(`   src/client/shared/ui/ → UI 컴포넌트 (shadcn)`);
+    console.log(`   src/client/shared/lib/utils.ts → 유틸리티 (cn 함수)`);
+  }
 
   return true;
 }
@@ -326,8 +325,10 @@ async function updatePackageJson(
   const pkg = JSON.parse(content);
 
   if (css === "none") {
-    // Remove Tailwind dependencies
+    // Remove Tailwind dependencies (v4)
     delete pkg.devDependencies?.tailwindcss;
+    delete pkg.devDependencies?.["@tailwindcss/cli"];
+    // Legacy v3 (just in case)
     delete pkg.devDependencies?.postcss;
     delete pkg.devDependencies?.autoprefixer;
   }

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/errors/messages.ts

@@ -21,7 +21,7 @@ export const ERROR_MESSAGES: Record<CLIErrorCode, ErrorInfo> = {
   },
   [CLI_ERROR_CODES.DEV_PORT_IN_USE]: {
     message: "Port {port} is already in use.",
-    suggestion: "Use --port to pick a different port or stop the process using this port.",
+    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.",
@@ -41,7 +41,7 @@ export const ERROR_MESSAGES: Record<CLIErrorCode, ErrorInfo> = {
   },
   [CLI_ERROR_CODES.GUARD_VIOLATION_FOUND]: {
     message: "{count} architecture violation(s) found.",
-    suggestion: "Fix violations above or run with --format agent for AI-friendly output.",
+    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}",