@mandujs/cli 0.4.4 → 0.5.0

package/package.json

@@ -1,40 +1,40 @@
-{
-  "name": "@mandujs/cli",
-  "version": "0.4.4",
-  "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
-  "type": "module",
-  "main": "./src/main.ts",
-  "bin": {
-    "mandu": "./src/main.ts"
-  },
-  "files": [
-    "src/**/*",
-    "templates/**/*"
-  ],
-  "keywords": [
-    "ai",
-    "agent",
-    "framework",
-    "fullstack",
-    "bun",
-    "typescript",
-    "react",
-    "ssr",
-    "code-generation"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/konamgil/mandu.git"
-  },
-  "author": "konamgil",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@mandujs/core": "^0.4.3"
-  },
-  "engines": {
-    "bun": ">=1.0.0"
-  }
-}
+{
+  "name": "@mandujs/cli",
+  "version": "0.5.0",
+  "description": "Agent-Native Fullstack Framework - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS",
+  "type": "module",
+  "main": "./src/main.ts",
+  "bin": {
+    "mandu": "./src/main.ts"
+  },
+  "files": [
+    "src/**/*",
+    "templates/**/*"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "framework",
+    "fullstack",
+    "bun",
+    "typescript",
+    "react",
+    "ssr",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git"
+  },
+  "author": "konamgil",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mandujs/core": "^0.5.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/commands/contract.ts

@@ -0,0 +1,152 @@
+/**
+ * Mandu CLI - Contract Commands
+ * Contract 생성 및 검증 명령어
+ */
+
+import { loadManifest, runContractGuardCheck, generateContractTemplate } from "@mandujs/core";
+import path from "path";
+import fs from "fs/promises";
+
+interface ContractCreateOptions {
+  routeId: string;
+}
+
+interface ContractValidateOptions {
+  verbose?: boolean;
+}
+
+/**
+ * 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!;
+
+  // Find the route
+  const route = manifest.routes.find((r) => r.id === options.routeId);
+  if (!route) {
+    console.error(`❌ Route not found: ${options.routeId}`);
+    console.log(`\nAvailable routes:`);
+    for (const r of manifest.routes) {
+      console.log(`  - ${r.id} (${r.pattern})`);
+    }
+    return false;
+  }
+
+  // Check if contract already exists
+  const contractPath = route.contractModule || `spec/contracts/${options.routeId}.contract.ts`;
+  const fullContractPath = path.join(rootDir, contractPath);
+
+  try {
+    await fs.access(fullContractPath);
+    console.error(`❌ Contract file already exists: ${contractPath}`);
+    console.log(`\nTo regenerate, delete the file first.`);
+    return false;
+  } catch {
+    // File doesn't exist, we can create it
+  }
+
+  // Create directory if needed
+  const contractDir = path.dirname(fullContractPath);
+  await fs.mkdir(contractDir, { recursive: true });
+
+  // Generate contract content
+  const contractContent = generateContractTemplate(route);
+
+  // Write contract file
+  await Bun.write(fullContractPath, contractContent);
+  console.log(`✅ Created: ${contractPath}`);
+
+  // Suggest updating manifest
+  if (!route.contractModule) {
+    console.log(`\n💡 Don't forget to add contractModule to your manifest:`);
+    console.log(`   "contractModule": "${contractPath}"`);
+  }
+
+  console.log(`\n📝 Next steps:`);
+  console.log(`   1. Edit ${contractPath} to define your API schema`);
+  console.log(`   2. Run \`mandu generate\` to regenerate handlers`);
+  console.log(`   3. Run \`mandu guard\` to validate contract-slot consistency`);
+
+  return true;
+}
+
+/**
+ * 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);
+
+  if (violations.length === 0) {
+    console.log(`✅ All contracts are valid!\n`);
+
+    // Show summary
+    const contractCount = manifest.routes.filter((r) => r.contractModule).length;
+    console.log(`📊 Summary:`);
+    console.log(`   Routes with contracts: ${contractCount}/${manifest.routes.length}`);
+
+    return true;
+  }
+
+  // Group violations by type
+  const byType: Record<string, typeof violations> = {};
+  for (const v of violations) {
+    byType[v.ruleId] = byType[v.ruleId] || [];
+    byType[v.ruleId].push(v);
+  }
+
+  // Display violations
+  console.log(`❌ Found ${violations.length} contract issues:\n`);
+
+  for (const [ruleId, ruleViolations] of Object.entries(byType)) {
+    const icon =
+      ruleId === "CONTRACT_METHOD_NOT_IMPLEMENTED"
+        ? "🔴"
+        : ruleId === "CONTRACT_METHOD_UNDOCUMENTED"
+          ? "🟡"
+          : "⚠️";
+
+    console.log(`${icon} ${ruleId} (${ruleViolations.length} issues)`);
+
+    for (const v of ruleViolations) {
+      console.log(`   📄 ${v.file}`);
+      console.log(`      ${v.message}`);
+      if (options.verbose) {
+        console.log(`      💡 ${v.suggestion}`);
+      }
+    }
+    console.log();
+  }
+
+  if (!options.verbose) {
+    console.log(`💡 Use --verbose for fix suggestions\n`);
+  }
+
+  return false;
+}

package/src/commands/openapi.ts

@@ -0,0 +1,183 @@
+/**
+ * Mandu CLI - OpenAPI Commands
+ * OpenAPI 스펙 생성 명령어
+ */
+
+import { loadManifest, generateOpenAPIDocument, openAPIToJSON } from "@mandujs/core";
+import path from "path";
+import fs from "fs/promises";
+
+interface OpenAPIGenerateOptions {
+  output?: string;
+  title?: string;
+  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!;
+
+  // Count routes with contracts
+  const contractRoutes = manifest.routes.filter((r) => r.contractModule);
+  if (contractRoutes.length === 0) {
+    console.log(`⚠️ No routes with contracts found.`);
+    console.log(`\nTo generate OpenAPI docs, add contractModule to your routes.`);
+    console.log(`Example:`);
+    console.log(`  {`);
+    console.log(`    "id": "users",`);
+    console.log(`    "pattern": "/api/users",`);
+    console.log(`    "contractModule": "spec/contracts/users.contract.ts"`);
+    console.log(`  }`);
+    return true;
+  }
+
+  console.log(`📝 Found ${contractRoutes.length} routes with contracts`);
+
+  // Generate OpenAPI document
+  try {
+    const doc = await generateOpenAPIDocument(manifest, rootDir, {
+      title: options.title,
+      version: options.version,
+    });
+
+    const json = openAPIToJSON(doc);
+
+    // Determine output path
+    const outputPath = options.output || path.join(rootDir, "openapi.json");
+    const outputDir = path.dirname(outputPath);
+
+    // Ensure directory exists
+    await fs.mkdir(outputDir, { recursive: true });
+
+    // Write file
+    await Bun.write(outputPath, json);
+
+    console.log(`\n✅ Generated: ${path.relative(rootDir, outputPath)}`);
+
+    // Show summary
+    const pathCount = Object.keys(doc.paths).length;
+    const tagCount = doc.tags?.length || 0;
+
+    console.log(`\n📊 Summary:`);
+    console.log(`   Paths: ${pathCount}`);
+    console.log(`   Tags: ${tagCount}`);
+    console.log(`   Version: ${doc.info.version}`);
+
+    console.log(`\n💡 View your API docs:`);
+    console.log(`   - Import into Swagger Editor: https://editor.swagger.io`);
+    console.log(`   - Import into Postman`);
+    console.log(`   - Run \`mandu openapi serve\` for local Swagger UI`);
+
+    return true;
+  } catch (error) {
+    console.error(`❌ Failed to generate OpenAPI:`, error);
+    return false;
+  }
+}
+
+/**
+ * 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");
+
+  console.log(`\n🌐 Starting OpenAPI documentation server...\n`);
+
+  // Check if openapi.json exists
+  try {
+    await fs.access(openAPIPath);
+  } catch {
+    console.log(`⚠️ openapi.json not found. Generating...`);
+    const generated = await openAPIGenerate({});
+    if (!generated) {
+      return false;
+    }
+  }
+
+  // Read OpenAPI spec
+  const specContent = await Bun.file(openAPIPath).text();
+
+  // Simple HTML for Swagger UI
+  const swaggerHTML = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Mandu API Documentation</title>
+  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui.css">
+  <style>
+    body { margin: 0; padding: 0; }
+    .swagger-ui .topbar { display: none; }
+    .swagger-ui .info .title { font-size: 28px; }
+    .swagger-ui .info { margin: 20px 0; }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://unpkg.com/swagger-ui-dist@5.9.0/swagger-ui-bundle.js"></script>
+  <script>
+    window.onload = () => {
+      SwaggerUIBundle({
+        spec: ${specContent},
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIBundle.SwaggerUIStandalonePreset
+        ],
+        layout: "BaseLayout"
+      });
+    };
+  </script>
+</body>
+</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`);
+  console.log(`\nPress Ctrl+C to stop.\n`);
+
+  // Keep server running
+  await new Promise(() => {});
+
+  return true;
+}

package/src/main.ts

@@ -6,6 +6,8 @@ import { guardCheck } from "./commands/guard-check";
 import { dev } from "./commands/dev";
 import { init } from "./commands/init";
 import { build } from "./commands/build";
+import { contractCreate, contractValidate } from "./commands/contract";
+import { openAPIGenerate, openAPIServe } from "./commands/openapi";
 import {
   changeBegin,
   changeCommit,
@@ -28,6 +30,12 @@ Commands:
   build          클라이언트 번들 빌드 (Hydration)
   dev            개발 서버 실행
 
+  contract create <routeId>  라우트에 대한 Contract 생성
+  contract validate          Contract-Slot 일관성 검증
+
+  openapi generate           OpenAPI 3.0 스펙 생성
+  openapi serve              Swagger UI 로컬 서버 실행
+
   change begin   변경 트랜잭션 시작 (스냅샷 생성)
   change commit  변경 확정
   change rollback 스냅샷으로 복원
@@ -38,7 +46,7 @@ Commands:
 Options:
   --name <name>      init 시 프로젝트 이름 (기본: my-mandu-app)
   --file <path>      spec-upsert 시 사용할 spec 파일 경로
-  --port <port>      dev 서버 포트 (기본: 3000)
+  --port <port>      dev/openapi serve 포트 (기본: 3000/8080)
   --no-auto-correct  guard 시 자동 수정 비활성화
   --minify           build 시 코드 압축
   --sourcemap        build 시 소스맵 생성
@@ -46,6 +54,8 @@ Options:
   --message <msg>    change begin 시 설명 메시지
   --id <id>          change rollback 시 특정 변경 ID
   --keep <n>         change prune 시 유지할 스냅샷 수 (기본: 5)
+  --output <path>    openapi generate 시 출력 경로 (기본: openapi.json)
+  --verbose          contract validate 시 상세 출력
   --help, -h         도움말 표시
 
 Examples:
@@ -56,12 +66,19 @@ Examples:
   bunx mandu build --minify
   bunx mandu build --watch
   bunx mandu dev --port 3000
+  bunx mandu contract create users
+  bunx mandu contract validate --verbose
+  bunx mandu openapi generate --output docs/api.json
+  bunx mandu openapi serve --port 8080
   bunx mandu change begin --message "Add new route"
   bunx mandu change commit
   bunx mandu change rollback
 
 Workflow:
   1. init → 2. spec-upsert → 3. generate → 4. build → 5. guard → 6. dev
+
+Contract-first Workflow:
+  1. contract create → 2. Edit contract → 3. generate → 4. Edit slot → 5. contract validate
 `;
 
 function parseArgs(args: string[]): { command: string; options: Record<string, string> } {
@@ -129,6 +146,53 @@ async function main(): Promise<void> {
       await dev({ port: options.port ? Number(options.port) : undefined });
       break;
 
+    case "contract": {
+      const subCommand = args[1];
+      switch (subCommand) {
+        case "create": {
+          const routeId = args[2] || options._positional;
+          if (!routeId) {
+            console.error("❌ Route ID is required");
+            console.log("\nUsage: bunx mandu contract create <routeId>");
+            process.exit(1);
+          }
+          success = await contractCreate({ routeId });
+          break;
+        }
+        case "validate":
+          success = await contractValidate({ verbose: options.verbose === "true" });
+          break;
+        default:
+          console.error(`❌ Unknown contract subcommand: ${subCommand}`);
+          console.log("\nUsage: bunx mandu contract <create|validate>");
+          process.exit(1);
+      }
+      break;
+    }
+
+    case "openapi": {
+      const subCommand = args[1];
+      switch (subCommand) {
+        case "generate":
+          success = await openAPIGenerate({
+            output: options.output,
+            title: options.title,
+            version: options.version,
+          });
+          break;
+        case "serve":
+          success = await openAPIServe({
+            port: options.port ? Number(options.port) : undefined,
+          });
+          break;
+        default:
+          console.error(`❌ Unknown openapi subcommand: ${subCommand}`);
+          console.log("\nUsage: bunx mandu openapi <generate|serve>");
+          process.exit(1);
+      }
+      break;
+    }
+
     case "change": {
       const subCommand = args[1];
       switch (subCommand) {