@mandujs/cli 0.9.24 → 0.9.42

package/package.json

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

package/src/commands/build.ts

@@ -4,7 +4,7 @@
  * Hydration이 필요한 Island들을 번들링합니다.
  */
 
-import { loadManifest, buildClientBundles, printBundleStats } from "@mandujs/core";
+import { loadManifest, buildClientBundles, printBundleStats, validateAndReport } from "@mandujs/core";
 import path from "path";
 import fs from "fs/promises";
 
@@ -19,14 +19,20 @@ export interface BuildOptions {
   outDir?: string;
 }
 
-export async function build(options: BuildOptions = {}): Promise<boolean> {
-  const cwd = process.cwd();
-  const specPath = path.join(cwd, "spec", "routes.manifest.json");
-
-  console.log("📦 Mandu Build - Client Bundle Builder\n");
-
-  // 1. Spec 로드
-  const specResult = await loadManifest(specPath);
+export async function build(options: BuildOptions = {}): Promise<boolean> {
+  const cwd = process.cwd();
+  const specPath = path.join(cwd, "spec", "routes.manifest.json");
+
+  console.log("📦 Mandu Build - Client Bundle Builder\n");
+
+  const config = await validateAndReport(cwd);
+  if (!config) {
+    return false;
+  }
+  const buildConfig = config.build ?? {};
+
+  // 1. Spec 로드
+  const specResult = await loadManifest(specPath);
   if (!specResult.success) {
     console.error("❌ Spec 로드 실패:");
     for (const error of specResult.errors) {
@@ -58,13 +64,13 @@ export async function build(options: BuildOptions = {}): Promise<boolean> {
     console.log(`   - ${route.id} (${hydration.strategy}, ${hydration.priority || "visible"})`);
   }
 
-  // 3. 번들 빌드
-  const startTime = performance.now();
-  const result = await buildClientBundles(manifest, cwd, {
-    minify: options.minify,
-    sourcemap: options.sourcemap,
-    outDir: options.outDir,
-  });
+  // 3. 번들 빌드
+  const startTime = performance.now();
+  const result = await buildClientBundles(manifest, cwd, {
+    minify: options.minify ?? buildConfig.minify,
+    sourcemap: options.sourcemap ?? buildConfig.sourcemap,
+    outDir: options.outDir ?? buildConfig.outDir,
+  });
 
   // 4. 결과 출력
   console.log("");

package/src/commands/dev.ts

@@ -1,9 +1,9 @@
-import {
-  startServer,
-  registerApiHandler,
-  registerPageLoader,
-  registerPageHandler,
-  registerLayoutLoader,
+import {
+  startServer,
+  registerApiHandler,
+  registerPageLoader,
+  registerPageHandler,
+  registerLayoutLoader,
   startDevBundler,
   createHMRServer,
   needsHydration,
@@ -17,6 +17,7 @@ import {
   formatReportForAgent,
   formatReportAsAgentJSON,
   getPreset,
+  validateAndReport,
   type RoutesManifest,
   type GuardConfig,
   type GuardPreset,
@@ -24,8 +25,10 @@ import {
 } from "@mandujs/core";
 import { isDirectory, resolveFromCwd } from "../util/fs";
 import { resolveOutputFormat, type OutputFormat } from "../util/output";
-import path from "path";
-
+import { CLI_ERROR_CODES, printCLIError } from "../errors";
+import { importFresh } from "../util/bun";
+import path from "path";
+
 export interface DevOptions {
   port?: number;
   /** HMR 비활성화 */
@@ -39,55 +42,64 @@ export interface DevOptions {
   /** Guard 출력 형식 */
   guardFormat?: OutputFormat;
 }
-
+
 export async function dev(options: DevOptions = {}): Promise<void> {
   const rootDir = resolveFromCwd(".");
+  const config = await validateAndReport(rootDir);
+
+  if (!config) {
+    printCLIError(CLI_ERROR_CODES.CONFIG_VALIDATION_FAILED);
+    process.exit(1);
+  }
+
+  const serverConfig = config.server ?? {};
+  const devConfig = config.dev ?? {};
+  const guardConfigFromFile = config.guard ?? {};
 
   console.log(`🥟 Mandu Dev Server (FS Routes)`);
-
-  // .env 파일 로드
-  const envResult = await loadEnv({
-    rootDir,
-    env: "development",
-  });
-
-  if (envResult.loaded.length > 0) {
-    console.log(`🔐 환경 변수 로드: ${envResult.loaded.join(", ")}`);
-  }
-
-  // FS Routes 스캔
-  console.log(`📂 app/ 폴더 스캔 중...`);
-
-  const result = await generateManifest(rootDir, {
-    skipLegacy: true,
-  });
-
-  if (result.manifest.routes.length === 0) {
-    console.log("");
-    console.log("📭 라우트가 없습니다.");
-    console.log("");
-    console.log("💡 app/ 폴더에 page.tsx 파일을 생성하세요:");
-    console.log("");
-    console.log("  app/page.tsx        → /");
-    console.log("  app/blog/page.tsx   → /blog");
-    console.log("  app/api/users/route.ts → /api/users");
-    console.log("");
-    process.exit(1);
-  }
-
+
+  // .env 파일 로드
+  const envResult = await loadEnv({
+    rootDir,
+    env: "development",
+  });
+
+  if (envResult.loaded.length > 0) {
+    console.log(`🔐 환경 변수 로드: ${envResult.loaded.join(", ")}`);
+  }
+
+  // FS Routes 스캔
+  console.log(`📂 app/ 폴더 스캔 중...`);
+
+  const result = await generateManifest(rootDir, {
+    skipLegacy: true,
+  });
+
+  if (result.manifest.routes.length === 0) {
+    printCLIError(CLI_ERROR_CODES.DEV_NO_ROUTES);
+    console.log("💡 app/ 폴더에 page.tsx 파일을 생성하세요:");
+    console.log("");
+    console.log("  app/page.tsx        → /");
+    console.log("  app/blog/page.tsx   → /blog");
+    console.log("  app/api/users/route.ts → /api/users");
+    console.log("");
+    process.exit(1);
+  }
+
   let manifest = result.manifest;
   console.log(`✅ ${manifest.routes.length}개 라우트 발견\n`);
 
   const enableFsRoutes = !options.legacy && await isDirectory(path.resolve(rootDir, "app"));
-  const guardPreset = options.guardPreset || "mandu";
+  const guardPreset = options.guardPreset || guardConfigFromFile.preset || "mandu";
   const guardFormat = resolveOutputFormat(options.guardFormat);
   const guardConfig: GuardConfig | null =
     options.guard === false
       ? null
       : {
           preset: guardPreset,
-          srcDir: "src",
-          realtime: true,
+          srcDir: guardConfigFromFile.srcDir || "src",
+          realtime: guardConfigFromFile.realtime ?? true,
+          exclude: guardConfigFromFile.exclude,
           realtimeOutput: guardFormat,
           fsRoutes: enableFsRoutes
             ? {
@@ -144,161 +156,178 @@ export async function dev(options: DevOptions = {}): Promise<void> {
 
   // Layout 경로 추적 (중복 등록 방지)
   const registeredLayouts = new Set<string>();
-
-  // 핸들러 등록 함수
-  const registerHandlers = async (manifest: RoutesManifest, isReload = false) => {
-    // 리로드 시 레이아웃 캐시 클리어
-    if (isReload) {
-      registeredLayouts.clear();
-    }
-
-    for (const route of manifest.routes) {
-      if (route.kind === "api") {
-        const modulePath = path.resolve(rootDir, route.module);
-        try {
-          // 캐시 무효화 (HMR용)
-          delete require.cache[modulePath];
-          const module = await import(modulePath);
-          registerApiHandler(route.id, module.default || module.handler || module);
-          console.log(`  📡 API: ${route.pattern} -> ${route.id}`);
-        } catch (error) {
-          console.error(`  ❌ API 핸들러 로드 실패: ${route.id}`, error);
-        }
-      } else if (route.kind === "page" && route.componentModule) {
-        const componentPath = path.resolve(rootDir, route.componentModule);
-        const isIsland = needsHydration(route);
-        const hasLayout = route.layoutChain && route.layoutChain.length > 0;
-
-        // Layout 로더 등록
-        if (route.layoutChain) {
-          for (const layoutPath of route.layoutChain) {
-            if (!registeredLayouts.has(layoutPath)) {
-              const absLayoutPath = path.resolve(rootDir, layoutPath);
-              registerLayoutLoader(layoutPath, async () => {
-                // 캐시 무효화 (HMR용)
-                delete require.cache[absLayoutPath];
-                return import(absLayoutPath);
-              });
-              registeredLayouts.add(layoutPath);
-              console.log(`  🎨 Layout: ${layoutPath}`);
-            }
-          }
-        }
-
-        // slotModule이 있으면 PageHandler 사용 (filling.loader 지원)
-        if (route.slotModule) {
-          registerPageHandler(route.id, async () => {
-            delete require.cache[componentPath];
-            const module = await import(componentPath);
-            return module.default;
-          });
-          console.log(`  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`);
-        } else {
-          registerPageLoader(route.id, () => {
-            delete require.cache[componentPath];
-            return import(componentPath);
-          });
-          console.log(`  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`);
-        }
-      }
-    }
-  };
-
-  // 초기 핸들러 등록
-  await registerHandlers(manifest);
-  console.log("");
-
-  const port = options.port || Number(process.env.PORT) || 3000;
-
-  // HMR 서버 시작 (클라이언트 슬롯이 있는 경우)
-  let hmrServer: ReturnType<typeof createHMRServer> | null = null;
-  let devBundler: Awaited<ReturnType<typeof startDevBundler>> | null = null;
-
+
+  // 핸들러 등록 함수
+  const registerHandlers = async (manifest: RoutesManifest, isReload = false) => {
+    // 리로드 시 레이아웃 캐시 클리어
+    if (isReload) {
+      registeredLayouts.clear();
+    }
+
+    for (const route of manifest.routes) {
+      if (route.kind === "api") {
+        const modulePath = path.resolve(rootDir, route.module);
+        try {
+          // 캐시 무효화 (HMR용)
+          const module = await importFresh(modulePath);
+          let handler = module.default || module.handler || module;
+
+          // ManduFilling 인스턴스를 핸들러 함수로 래핑
+          if (handler && typeof handler.handle === 'function') {
+            console.log(`  🔄 ManduFilling 래핑: ${route.id}`);
+            const filling = handler;
+            handler = async (req: Request, params?: Record<string, string>) => {
+              return filling.handle(req, params);
+            };
+          } else {
+            console.log(`  ⚠️ 핸들러 타입: ${typeof handler}, handle: ${typeof handler?.handle}`);
+          }
+
+          registerApiHandler(route.id, handler);
+          console.log(`  📡 API: ${route.pattern} -> ${route.id}`);
+        } catch (error) {
+          console.error(`  ❌ API 핸들러 로드 실패: ${route.id}`, error);
+        }
+      } else if (route.kind === "page" && route.componentModule) {
+        const componentPath = path.resolve(rootDir, route.componentModule);
+        const isIsland = needsHydration(route);
+        const hasLayout = route.layoutChain && route.layoutChain.length > 0;
+
+        // Layout 로더 등록
+        if (route.layoutChain) {
+          for (const layoutPath of route.layoutChain) {
+            if (!registeredLayouts.has(layoutPath)) {
+              const absLayoutPath = path.resolve(rootDir, layoutPath);
+              registerLayoutLoader(layoutPath, async () => {
+                // 캐시 무효화 (HMR용)
+                return importFresh(absLayoutPath);
+              });
+              registeredLayouts.add(layoutPath);
+              console.log(`  🎨 Layout: ${layoutPath}`);
+            }
+          }
+        }
+
+        // slotModule이 있으면 PageHandler 사용 (filling.loader 지원)
+        if (route.slotModule) {
+          registerPageHandler(route.id, async () => {
+            const module = await importFresh(componentPath);
+            return module.default;
+          });
+          console.log(`  📄 Page: ${route.pattern} -> ${route.id} (with loader)${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`);
+        } else {
+          registerPageLoader(route.id, () => importFresh(componentPath));
+          console.log(`  📄 Page: ${route.pattern} -> ${route.id}${isIsland ? " 🏝️" : ""}${hasLayout ? " 🎨" : ""}`);
+        }
+      }
+    }
+  };
+
+  // 초기 핸들러 등록
+  await registerHandlers(manifest);
+  console.log("");
+
+  const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
+  const port =
+    options.port ??
+    (envPort && Number.isFinite(envPort) ? envPort : undefined) ??
+    serverConfig.port ??
+    3333;
+
+  // HMR 서버 시작 (클라이언트 슬롯이 있는 경우)
+  let hmrServer: ReturnType<typeof createHMRServer> | null = null;
+  let devBundler: Awaited<ReturnType<typeof startDevBundler>> | null = null;
+
   const hasIslands = manifest.routes.some(
     (r) => r.kind === "page" && r.clientModule && needsHydration(r)
   );
-
-  if (hasIslands && !options.noHmr) {
-    // HMR 서버 시작
-    hmrServer = createHMRServer(port);
-
-    // Dev 번들러 시작 (파일 감시)
-    devBundler = await startDevBundler({
-      rootDir,
-      manifest,
-      onRebuild: (result) => {
-        if (result.success) {
-          if (result.routeId === "*") {
-            hmrServer?.broadcast({
-              type: "reload",
-              data: {
-                timestamp: Date.now(),
-              },
-            });
-          } else {
-            hmrServer?.broadcast({
-              type: "island-update",
-              data: {
-                routeId: result.routeId,
-                timestamp: Date.now(),
-              },
-            });
-          }
-        } else {
-          hmrServer?.broadcast({
-            type: "error",
-            data: {
-              routeId: result.routeId,
-              message: result.error,
-            },
-          });
-        }
-      },
-      onError: (error, routeId) => {
-        hmrServer?.broadcast({
-          type: "error",
-          data: {
-            routeId,
-            message: error.message,
-          },
-        });
-      },
-    });
-  }
-
-  // 메인 서버 시작
-  const server = startServer(manifest, {
-    port,
-    rootDir,
-    isDev: true,
-    hmrPort: hmrServer ? port : undefined,
-    bundleManifest: devBundler?.initialBuild.manifest,
-  });
-
+
+  const hmrEnabled = options.noHmr ? false : (devConfig.hmr ?? true);
+  if (hasIslands && hmrEnabled) {
+    // HMR 서버 시작
+    hmrServer = createHMRServer(port);
+
+    // Dev 번들러 시작 (파일 감시)
+    devBundler = await startDevBundler({
+      rootDir,
+      manifest,
+      watchDirs: devConfig.watchDirs,
+      onRebuild: (result) => {
+        if (result.success) {
+          if (result.routeId === "*") {
+            hmrServer?.broadcast({
+              type: "reload",
+              data: {
+                timestamp: Date.now(),
+              },
+            });
+          } else {
+            hmrServer?.broadcast({
+              type: "island-update",
+              data: {
+                routeId: result.routeId,
+                timestamp: Date.now(),
+              },
+            });
+          }
+        } else {
+          hmrServer?.broadcast({
+            type: "error",
+            data: {
+              routeId: result.routeId,
+              message: result.error,
+            },
+          });
+        }
+      },
+      onError: (error, routeId) => {
+        hmrServer?.broadcast({
+          type: "error",
+          data: {
+            routeId,
+            message: error.message,
+          },
+        });
+      },
+    });
+  }
+
+  // 메인 서버 시작
+  const server = startServer(manifest, {
+    port,
+    hostname: serverConfig.hostname,
+    rootDir,
+    isDev: true,
+    hmrPort: hmrServer ? port : undefined,
+    bundleManifest: devBundler?.initialBuild.manifest,
+    cors: serverConfig.cors,
+    streaming: serverConfig.streaming,
+  });
+
   // FS Routes 실시간 감시
   const routesWatcher = await watchFSRoutes(rootDir, {
     skipLegacy: true,
     onChange: async (result) => {
-      const timestamp = new Date().toLocaleTimeString();
-      console.log(`\n🔄 [${timestamp}] 라우트 변경 감지`);
-
-      // 레지스트리 클리어 (layout 캐시 포함)
-      clearDefaultRegistry();
-
-      // 새 매니페스트로 서버 업데이트
-      manifest = result.manifest;
-      console.log(`   📋 라우트: ${manifest.routes.length}개`);
-
-      // 라우트 재등록 (isReload = true)
-      await registerHandlers(manifest, true);
-
-      // HMR 브로드캐스트 (전체 리로드)
-      if (hmrServer) {
-        hmrServer.broadcast({
-          type: "reload",
-          data: { timestamp: Date.now() },
-        });
-      }
+      const timestamp = new Date().toLocaleTimeString();
+      console.log(`\n🔄 [${timestamp}] 라우트 변경 감지`);
+
+      // 레지스트리 클리어 (layout 캐시 포함)
+      clearDefaultRegistry();
+
+      // 새 매니페스트로 서버 업데이트
+      manifest = result.manifest;
+      console.log(`   📋 라우트: ${manifest.routes.length}개`);
+
+      // 라우트 재등록 (isReload = true)
+      await registerHandlers(manifest, true);
+
+      // HMR 브로드캐스트 (전체 리로드)
+      if (hmrServer) {
+        hmrServer.broadcast({
+          type: "reload",
+          data: { timestamp: Date.now() },
+        });
+      }
     },
   });
 

package/src/commands/guard-arch.ts

@@ -19,6 +19,7 @@ import {
   calculateLayerStatistics,
   generateGuardMarkdownReport,
   generateHTMLReport,
+  validateAndReport,
   type GuardConfig,
   type GuardPreset,
 } from "@mandujs/core";
@@ -53,21 +54,18 @@ export interface GuardArchOptions {
 }
 
 export async function guardArch(options: GuardArchOptions = {}): Promise<boolean> {
+  const rootDir = resolveFromCwd(".");
   const {
-    preset = "mandu",
     watch = false,
     ci = false,
     format,
     quiet = false,
-    srcDir = "src",
     listPresets: showPresets = false,
     output,
     reportFormat = "markdown",
     saveStats = false,
     showTrend = false,
   } = options;
-
-  const rootDir = resolveFromCwd(".");
   const resolvedFormat = resolveOutputFormat(format);
   const enableFsRoutes = await isDirectory(path.resolve(rootDir, "app"));
 
@@ -90,6 +88,13 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
     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 +106,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 +158,7 @@ export async function guardArch(options: GuardArchOptions = {}): Promise<boolean
     }
 
     const watcher = createGuardWatcher({
-      config,
+      config: guardConfig,
       rootDir,
       onViolation: (violation) => {
         // 실시간 위반 출력은 watcher 내부에서 처리됨
@@ -185,7 +191,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/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: "Use --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 run with --format 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);
+}

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
@@ -265,7 +266,10 @@ async function main(): Promise<void> {
           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);
           }
@@ -320,7 +324,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 +341,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 +363,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);
       }
@@ -379,7 +389,10 @@ async function main(): Promise<void> {
           });
           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 +423,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);
       }
@@ -458,7 +474,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 +485,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 +495,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>;
+}