@mandujs/cli 0.9.42 → 0.9.44

package/README.ko.md

@@ -223,7 +223,7 @@ bun test --watch   # 감시 모드
 ## 요구 사항
 
 - Bun >= 1.0.0
-- React >= 18.0.0
+- React >= 19.0.0
 
 ## 관련 패키지
 

package/README.md

@@ -43,7 +43,9 @@ bun run dev
 bunx mandu dev
 ```
 
-Your app is now running at `http://localhost:3000`.
+Your app is now running at `http://localhost:3333`.
+
+To change the port, set `PORT` or use `server.port` in `mandu.config`. If the port is in use, Mandu will pick the next available port.
 
 ### 3. Create Pages in `app/` Directory
 
@@ -254,7 +256,6 @@ bunx mandu guard --preset fsd
 
 | Option | Description |
 |--------|-------------|
-| `--port <n>` | Server port (default: 3000) |
 | `--guard` | Enable Guard watching |
 | `--guard-preset <p>` | Guard preset (default: mandu) |
 
@@ -307,7 +308,6 @@ bunx mandu guard --preset fsd
 bunx @mandujs/cli init my-app
 
 # Development
-bunx mandu dev --port 3000
 bunx mandu dev --guard
 
 # Routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/cli",
-  "version": "0.9.42",
+  "version": "0.9.44",
   "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
   "type": "module",
   "main": "./src/main.ts",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@mandujs/core": "0.9.39"
+    "@mandujs/core": "workspace:*"
   },
   "engines": {
     "bun": ">=1.0.0"

package/src/commands/build.ts

@@ -2,11 +2,13 @@
  * mandu build - 클라이언트 번들 빌드
  *
  * Hydration이 필요한 Island들을 번들링합니다.
+ * Tailwind v4 프로젝트는 CSS도 함께 빌드합니다.
  */
 
-import { loadManifest, buildClientBundles, printBundleStats, validateAndReport } from "@mandujs/core";
+import { buildClientBundles, printBundleStats, validateAndReport, isTailwindProject, buildCSS, type RoutesManifest } from "@mandujs/core";
 import path from "path";
 import fs from "fs/promises";
+import { resolveManifest } from "../util/manifest";
 
 export interface BuildOptions {
   /** 코드 압축 (기본: production에서 true) */
@@ -19,30 +21,28 @@ 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");
-
-  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) {
-      console.error(`   ${error}`);
-    }
+export async function build(options: BuildOptions = {}): Promise<boolean> {
+  const cwd = process.cwd();
+
+  console.log("📦 Mandu Build - Client Bundle Builder\n");
+
+  const config = await validateAndReport(cwd);
+  if (!config) {
     return false;
   }
+  const buildConfig = config.build ?? {};
 
-  const manifest = specResult.data!;
-  console.log(`✅ Spec 로드 완료: ${manifest.routes.length}개 라우트`);
+  // 1. 라우트 매니페스트 로드 (FS Routes 우선)
+  let manifest: Awaited<ReturnType<typeof resolveManifest>>["manifest"];
+  try {
+    const resolved = await resolveManifest(cwd, { fsRoutes: config.fsRoutes });
+    manifest = resolved.manifest;
+    console.log(`✅ 라우트 로드 완료 (${resolved.source}): ${manifest.routes.length}개 라우트`);
+  } catch (error) {
+    console.error("❌ 라우트 로드 실패:");
+    console.error(`   ${error instanceof Error ? error.message : error}`);
+    return false;
+  }
 
   // 2. Hydration이 필요한 라우트 확인
   const hydratedRoutes = manifest.routes.filter(
@@ -64,15 +64,34 @@ 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 ?? buildConfig.minify,
-    sourcemap: options.sourcemap ?? buildConfig.sourcemap,
-    outDir: options.outDir ?? buildConfig.outDir,
-  });
+  // 3. Tailwind CSS 빌드 (감지 시에만)
+  const hasTailwind = await isTailwindProject(cwd);
+  if (hasTailwind) {
+    console.log(`\n🎨 Tailwind CSS v4 빌드 중...`);
+    const cssResult = await buildCSS({
+      rootDir: cwd,
+      minify: options.minify ?? true,
+    });
+
+    if (!cssResult.success) {
+      console.error(`\n❌ CSS 빌드 실패: ${cssResult.error}`);
+      return false;
+    }
+
+    console.log(`   ✅ CSS 빌드 완료 (${cssResult.buildTime?.toFixed(0)}ms)`);
+    console.log(`   출력: ${cssResult.outputPath}`);
+  }
 
-  // 4. 결과 출력
+  // 4. 번들 빌드
+  const startTime = performance.now();
+  const resolvedBuildOptions: BuildOptions = {
+    minify: options.minify ?? buildConfig.minify,
+    sourcemap: options.sourcemap ?? buildConfig.sourcemap,
+    outDir: options.outDir ?? buildConfig.outDir,
+  };
+  const result = await buildClientBundles(manifest, cwd, resolvedBuildOptions);
+
+  // 5. 결과 출력
   console.log("");
   printBundleStats(result);
 
@@ -84,13 +103,16 @@ export async function build(options: BuildOptions = {}): Promise<boolean> {
   const elapsed = (performance.now() - startTime).toFixed(0);
   console.log(`\n✅ 빌드 완료 (${elapsed}ms)`);
   console.log(`   출력: .mandu/client/`);
+  if (hasTailwind) {
+    console.log(`   CSS: .mandu/client/globals.css`);
+  }
 
-  // 5. 감시 모드
+  // 6. 감시 모드
   if (options.watch) {
     console.log("\n👀 파일 감시 모드...");
     console.log("   Ctrl+C로 종료\n");
 
-    await watchAndRebuild(manifest, cwd, options);
+    await watchAndRebuild(manifest, cwd, resolvedBuildOptions);
   }
 
   return true;
@@ -100,7 +122,7 @@ export async function build(options: BuildOptions = {}): Promise<boolean> {
  * 파일 감시 및 재빌드
  */
 async function watchAndRebuild(
-  manifest: Awaited<ReturnType<typeof loadManifest>>["manifest"],
+  manifest: RoutesManifest,
   rootDir: string,
   options: BuildOptions
 ): Promise<void> {

package/src/commands/check.ts

@@ -10,32 +10,28 @@ import {
   checkDirectory,
   printReport,
   getPreset,
+  validateAndReport,
   loadManifest,
   runGuardCheck,
   buildGuardReport,
   printReportSummary,
   type GuardConfig,
-  type GuardPreset,
 } from "@mandujs/core";
 import path from "path";
 import { resolveFromCwd, isDirectory, pathExists } from "../util/fs";
-import { resolveOutputFormat, type OutputFormat } from "../util/output";
-
-export interface CheckOptions {
-  preset?: GuardPreset;
-  format?: OutputFormat;
-  ci?: boolean;
-  quiet?: boolean;
-  legacy?: boolean;
-}
+import { resolveOutputFormat } from "../util/output";
 
-export async function check(options: CheckOptions = {}): Promise<boolean> {
+export async function check(): Promise<boolean> {
   const rootDir = resolveFromCwd(".");
-  const preset = options.preset ?? "mandu";
-  const format = resolveOutputFormat(options.format);
-  const quiet = options.quiet === true;
-  const strictWarnings = options.ci === true;
-  const enableFsRoutes = !options.legacy && await isDirectory(path.resolve(rootDir, "app"));
+  const config = await validateAndReport(rootDir);
+  if (!config) return false;
+
+  const guardConfigFromFile = config.guard ?? {};
+  const preset = guardConfigFromFile.preset ?? "mandu";
+  const format = resolveOutputFormat();
+  const quiet = false;
+  const strictWarnings = process.env.CI === "true";
+  const enableFsRoutes = await isDirectory(path.resolve(rootDir, "app"));
   const specPath = resolveFromCwd("spec/routes.manifest.json");
   const hasSpec = await pathExists(specPath);
 
@@ -70,6 +66,7 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
     try {
       if (format === "console") {
         const result = await generateManifest(rootDir, {
+          scanner: config.fsRoutes,
           outputPath: ".mandu/routes.manifest.json",
           skipLegacy: true,
         });
@@ -95,7 +92,7 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
           log("");
         }
       } else {
-        const scan = await scanRoutes(rootDir);
+        const scan = await scanRoutes(rootDir, config.fsRoutes);
         routesSummary.count = scan.routes.length;
         routesSummary.warnings = scan.errors.map((e) => `${e.type}: ${e.message}`);
       }
@@ -119,7 +116,8 @@ export async function check(options: CheckOptions = {}): Promise<boolean> {
   // 2) Architecture Guard 검사
   const guardConfig: GuardConfig = {
     preset,
-    srcDir: "src",
+    srcDir: guardConfigFromFile.srcDir ?? "src",
+    exclude: guardConfigFromFile.exclude,
     fsRoutes: enableFsRoutes
       ? {
           noPageToPage: true,

package/src/commands/contract.ts

@@ -4,16 +4,17 @@
  */
 
 import {
-  loadManifest,
   runContractGuardCheck,
   generateContractTemplate,
   buildContractRegistry,
   writeContractRegistry,
   readContractRegistry,
   diffContractRegistry,
+  validateAndReport,
 } from "@mandujs/core";
 import path from "path";
 import fs from "fs/promises";
+import { resolveManifest } from "../util/manifest";
 
 interface ContractCreateOptions {
   routeId: string;
@@ -33,24 +34,32 @@ interface ContractDiffOptions {
   output?: string;
   json?: boolean;
 }
+
+async function loadRoutesManifest(rootDir: string) {
+  const config = await validateAndReport(rootDir);
+  if (!config) {
+    throw new Error("Invalid mandu.config");
+  }
+  const resolved = await resolveManifest(rootDir, { fsRoutes: config.fsRoutes });
+  return resolved.manifest;
+}
 
 /**
  * Create a new contract file for a route
  */
-export async function contractCreate(options: ContractCreateOptions): Promise<boolean> {
-  const rootDir = process.cwd();
-  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
-
-  console.log(`\n📜 Creating contract for route: ${options.routeId}\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!;
+export async function contractCreate(options: ContractCreateOptions): Promise<boolean> {
+  const rootDir = process.cwd();
+
+  console.log(`\n📜 Creating contract for route: ${options.routeId}\n`);
+
+  // Load manifest
+  let manifest;
+  try {
+    manifest = await loadRoutesManifest(rootDir);
+  } catch (error) {
+    console.error("❌ Failed to load manifest:", error instanceof Error ? error.message : error);
+    return false;
+  }
 
   // Find the route
   const route = manifest.routes.find((r) => r.id === options.routeId);
@@ -105,22 +114,21 @@ export async function contractCreate(options: ContractCreateOptions): Promise<bo
  * Validate all contracts against their slot implementations
  */
 export async function contractValidate(options: ContractValidateOptions = {}): Promise<boolean> {
-  const rootDir = process.cwd();
-  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
-
-  console.log(`\n🔍 Validating contracts...\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!;
-
-  // Run contract guard check
-  const violations = await runContractGuardCheck(manifest, rootDir);
+  const rootDir = process.cwd();
+
+  console.log(`\n🔍 Validating contracts...\n`);
+
+  // Load manifest
+  let manifest;
+  try {
+    manifest = await loadRoutesManifest(rootDir);
+  } catch (error) {
+    console.error("❌ Failed to load manifest:", error instanceof Error ? error.message : error);
+    return false;
+  }
+
+  // Run contract guard check
+  const violations = await runContractGuardCheck(manifest, rootDir);
 
   if (violations.length === 0) {
     console.log(`✅ All contracts are valid!\n`);
@@ -175,18 +183,17 @@ export async function contractValidate(options: ContractValidateOptions = {}): P
  */
 export async function contractBuild(options: ContractBuildOptions = {}): Promise<boolean> {
   const rootDir = process.cwd();
-  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
   const outputPath = options.output || path.join(rootDir, ".mandu", "contracts.json");
 
   console.log(`\n📦 Building contract registry...\n`);
 
-  const manifestResult = await loadManifest(manifestPath);
-  if (!manifestResult.success) {
-    console.error("❌ Failed to load manifest:", manifestResult.errors);
+  let manifest;
+  try {
+    manifest = await loadRoutesManifest(rootDir);
+  } catch (error) {
+    console.error("❌ Failed to load manifest:", error instanceof Error ? error.message : error);
     return false;
   }
-
-  const manifest = manifestResult.data!;
   const { registry, warnings } = await buildContractRegistry(manifest, rootDir);
 
   if (warnings.length > 0) {
@@ -211,7 +218,6 @@ export async function contractBuild(options: ContractBuildOptions = {}): Promise
  */
 export async function contractDiff(options: ContractDiffOptions = {}): Promise<boolean> {
   const rootDir = process.cwd();
-  const manifestPath = path.join(rootDir, "spec/routes.manifest.json");
   const fromPath = options.from || path.join(rootDir, ".mandu", "contracts.json");
 
   console.log(`\n🔍 Diffing contracts...\n`);
@@ -226,12 +232,14 @@ export async function contractDiff(options: ContractDiffOptions = {}): Promise<b
   let toRegistry = options.to ? await readContractRegistry(options.to) : null;
 
   if (!toRegistry) {
-    const manifestResult = await loadManifest(manifestPath);
-    if (!manifestResult.success) {
-      console.error("❌ Failed to load manifest:", manifestResult.errors);
+    let manifest;
+    try {
+      manifest = await loadRoutesManifest(rootDir);
+    } catch (error) {
+      console.error("❌ Failed to load manifest:", error instanceof Error ? error.message : error);
       return false;
     }
-    const { registry } = await buildContractRegistry(manifestResult.data!, rootDir);
+    const { registry } = await buildContractRegistry(manifest, rootDir);
     toRegistry = registry;
   }
 

package/src/commands/dev.ts

@@ -8,7 +8,6 @@ import {
   createHMRServer,
   needsHydration,
   loadEnv,
-  generateManifest,
   watchFSRoutes,
   clearDefaultRegistry,
   createGuardWatcher,
@@ -18,29 +17,23 @@ import {
   formatReportAsAgentJSON,
   getPreset,
   validateAndReport,
+  isTailwindProject,
+  startCSSWatch,
   type RoutesManifest,
   type GuardConfig,
-  type GuardPreset,
   type Violation,
+  type CSSWatcher,
 } from "@mandujs/core";
-import { isDirectory, resolveFromCwd } from "../util/fs";
-import { resolveOutputFormat, type OutputFormat } from "../util/output";
+import { resolveFromCwd } from "../util/fs";
+import { resolveOutputFormat } from "../util/output";
 import { CLI_ERROR_CODES, printCLIError } from "../errors";
 import { importFresh } from "../util/bun";
+import { resolveManifest } from "../util/manifest";
+import { resolveAvailablePort } from "../util/port";
 import path from "path";
 
 export interface DevOptions {
   port?: number;
-  /** HMR 비활성화 */
-  noHmr?: boolean;
-  /** FS Routes 비활성화 (레거시 모드) */
-  legacy?: boolean;
-  /** Architecture Guard 활성화 */
-  guard?: boolean;
-  /** Guard 프리셋 */
-  guardPreset?: GuardPreset;
-  /** Guard 출력 형식 */
-  guardFormat?: OutputFormat;
 }
 
 export async function dev(options: DevOptions = {}): Promise<void> {
@@ -55,8 +48,9 @@ export async function dev(options: DevOptions = {}): Promise<void> {
   const serverConfig = config.server ?? {};
   const devConfig = config.dev ?? {};
   const guardConfigFromFile = config.guard ?? {};
+  const HMR_OFFSET = 1;
 
-  console.log(`🥟 Mandu Dev Server (FS Routes)`);
+  console.log(`🥟 Mandu Dev Server`);
 
   // .env 파일 로드
   const envResult = await loadEnv({
@@ -68,32 +62,37 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     console.log(`🔐 환경 변수 로드: ${envResult.loaded.join(", ")}`);
   }
 
-  // FS Routes 스캔
-  console.log(`📂 app/ 폴더 스캔 중...`);
-
-  const result = await generateManifest(rootDir, {
-    skipLegacy: true,
-  });
+  // 라우트 스캔 (FS Routes 우선, 없으면 spec manifest)
+  console.log(`📂 라우트 스캔 중...`);
+  let manifest: RoutesManifest;
+  let enableFsRoutes = false;
+
+  try {
+    const resolved = await resolveManifest(rootDir, { fsRoutes: config.fsRoutes });
+    manifest = resolved.manifest;
+    enableFsRoutes = resolved.source === "fs";
+
+    if (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);
+    }
 
-  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("");
+    console.log(`✅ ${manifest.routes.length}개 라우트 발견\n`);
+  } catch (error) {
+    printCLIError(CLI_ERROR_CODES.DEV_MANIFEST_NOT_FOUND);
+    console.error(error instanceof Error ? error.message : error);
     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 || guardConfigFromFile.preset || "mandu";
-  const guardFormat = resolveOutputFormat(options.guardFormat);
+  const guardPreset = guardConfigFromFile.preset || "mandu";
+  const guardFormat = resolveOutputFormat();
   const guardConfig: GuardConfig | null =
-    options.guard === false
+    guardConfigFromFile.realtime === false
       ? null
       : {
           preset: guardPreset,
@@ -228,21 +227,62 @@ export async function dev(options: DevOptions = {}): Promise<void> {
   console.log("");
 
   const envPort = process.env.PORT ? Number(process.env.PORT) : undefined;
-  const port =
+  const desiredPort =
     options.port ??
     (envPort && Number.isFinite(envPort) ? envPort : undefined) ??
     serverConfig.port ??
     3333;
 
+  const hasIslands = manifest.routes.some(
+    (r) => r.kind === "page" && r.clientModule && needsHydration(r)
+  );
+  const hmrEnabled = devConfig.hmr ?? true;
+
+  const { port } = await resolveAvailablePort(desiredPort, {
+    hostname: serverConfig.hostname,
+    offsets: hasIslands && hmrEnabled ? [0, HMR_OFFSET] : [0],
+  });
+
+  if (port !== desiredPort) {
+    console.warn(`⚠️  Port ${desiredPort} is in use. Using ${port} instead.`);
+  }
+
   // HMR 서버 시작 (클라이언트 슬롯이 있는 경우)
   let hmrServer: ReturnType<typeof createHMRServer> | null = null;
   let devBundler: Awaited<ReturnType<typeof startDevBundler>> | null = null;
+  let cssWatcher: CSSWatcher | null = null;
 
-  const hasIslands = manifest.routes.some(
-    (r) => r.kind === "page" && r.clientModule && needsHydration(r)
-  );
+  // CSS 빌드 시작 (Tailwind v4 감지 시에만)
+  const hasTailwind = await isTailwindProject(rootDir);
+  if (hasTailwind) {
+    cssWatcher = await startCSSWatch({
+      rootDir,
+      watch: true,
+      onBuild: (result) => {
+        if (result.success && hmrServer) {
+          // cssWatcher.serverPath 사용 (경로 일관성)
+          hmrServer.broadcast({
+            type: "css-update",
+            data: {
+              cssPath: cssWatcher?.serverPath || "/.mandu/client/globals.css",
+              timestamp: Date.now(),
+            },
+          });
+        }
+      },
+      onError: (error) => {
+        if (hmrServer) {
+          hmrServer.broadcast({
+            type: "error",
+            data: {
+              message: `CSS Error: ${error.message}`,
+            },
+          });
+        }
+      },
+    });
+  }
 
-  const hmrEnabled = options.noHmr ? false : (devConfig.hmr ?? true);
   if (hasIslands && hmrEnabled) {
     // HMR 서버 시작
     hmrServer = createHMRServer(port);
@@ -302,8 +342,20 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     bundleManifest: devBundler?.initialBuild.manifest,
     cors: serverConfig.cors,
     streaming: serverConfig.streaming,
+    // Tailwind 감지 시에만 CSS 링크 주입
+    cssPath: hasTailwind ? cssWatcher?.serverPath : false,
   });
 
+  const actualPort = server.server.port ?? port;
+  if (actualPort !== port) {
+    if (hmrServer) {
+      hmrServer.close();
+      hmrServer = createHMRServer(actualPort);
+      server.registry.settings.hmrPort = actualPort;
+      console.log(`🔁 HMR port updated: ${actualPort + HMR_OFFSET}`);
+    }
+  }
+
   // FS Routes 실시간 감시
   const routesWatcher = await watchFSRoutes(rootDir, {
     skipLegacy: true,
@@ -341,6 +393,7 @@ export async function dev(options: DevOptions = {}): Promise<void> {
     server.stop();
     devBundler?.close();
     hmrServer?.close();
+    cssWatcher?.close();
     routesWatcher.close();
     archGuardWatcher?.close();
     process.exit(0);