@mandujs/cli 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@mandujs/cli",
+  "version": "0.1.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.1.0"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/commands/dev.ts

@@ -0,0 +1,60 @@
+import { loadManifest, startServer, registerApiHandler, registerPageLoader } from "@mandu/core";
+import { resolveFromCwd } from "../util/fs";
+import path from "path";
+
+export interface DevOptions {
+  port?: number;
+}
+
+export async function dev(options: DevOptions = {}): Promise<void> {
+  const specPath = resolveFromCwd("spec/routes.manifest.json");
+  const rootDir = resolveFromCwd(".");
+
+  console.log(`🥟 Mandu Dev Server`);
+  console.log(`📄 Spec 파일: ${specPath}\n`);
+
+  const result = await loadManifest(specPath);
+
+  if (!result.success || !result.data) {
+    console.error("❌ Spec 로드 실패:");
+    result.errors?.forEach((e) => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+
+  console.log(`✅ Spec 로드 완료: ${result.data.routes.length}개 라우트`);
+
+  for (const route of result.data.routes) {
+    if (route.kind === "api") {
+      const modulePath = path.resolve(rootDir, route.module);
+      try {
+        const module = await import(modulePath);
+        registerApiHandler(route.id, module.default || module.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);
+      registerPageLoader(route.id, () => import(componentPath));
+      console.log(`  📄 Page: ${route.pattern} -> ${route.id}`);
+    }
+  }
+
+  console.log("");
+
+  const port = options.port || Number(process.env.PORT) || 3000;
+
+  const server = startServer(result.data, { port });
+
+  process.on("SIGINT", () => {
+    console.log("\n🛑 서버 종료 중...");
+    server.stop();
+    process.exit(0);
+  });
+
+  process.on("SIGTERM", () => {
+    console.log("\n🛑 서버 종료 중...");
+    server.stop();
+    process.exit(0);
+  });
+}

package/src/commands/generate-apply.ts

@@ -0,0 +1,40 @@
+import { loadManifest, generateRoutes, buildGenerateReport, printReportSummary, writeReport } from "@mandu/core";
+import { resolveFromCwd, getRootDir } from "../util/fs";
+
+export async function generateApply(): Promise<boolean> {
+  const specPath = resolveFromCwd("spec/routes.manifest.json");
+  const rootDir = getRootDir();
+
+  console.log(`🥟 Mandu Generate`);
+  console.log(`📄 Spec 파일: ${specPath}\n`);
+
+  const result = await loadManifest(specPath);
+
+  if (!result.success || !result.data) {
+    console.error("❌ Spec 로드 실패:");
+    result.errors?.forEach((e) => console.error(`  - ${e}`));
+    return false;
+  }
+
+  console.log(`✅ Spec 로드 완료 (${result.data.routes.length}개 라우트)`);
+  console.log(`🔄 코드 생성 중...\n`);
+
+  const generateResult = await generateRoutes(result.data, rootDir);
+
+  const report = buildGenerateReport(generateResult);
+  printReportSummary(report);
+
+  const reportPath = resolveFromCwd("mandu-report.json");
+  await writeReport(report, reportPath);
+  console.log(`📋 Report 저장: ${reportPath}`);
+
+  if (!generateResult.success) {
+    console.log(`\n❌ generate 실패`);
+    return false;
+  }
+
+  console.log(`\n✅ generate 완료`);
+  console.log(`💡 다음 단계: bunx mandu guard`);
+
+  return true;
+}

package/src/commands/guard-check.ts

@@ -0,0 +1,40 @@
+import { loadManifest, runGuardCheck, buildGuardReport, printReportSummary, writeReport } from "@mandu/core";
+import { resolveFromCwd, getRootDir } from "../util/fs";
+
+export async function guardCheck(): Promise<boolean> {
+  const specPath = resolveFromCwd("spec/routes.manifest.json");
+  const rootDir = getRootDir();
+
+  console.log(`🥟 Mandu Guard`);
+  console.log(`📄 Spec 파일: ${specPath}\n`);
+
+  const result = await loadManifest(specPath);
+
+  if (!result.success || !result.data) {
+    console.error("❌ Spec 로드 실패:");
+    result.errors?.forEach((e) => console.error(`  - ${e}`));
+    return false;
+  }
+
+  console.log(`✅ Spec 로드 완료`);
+  console.log(`🔍 Guard 검사 중...\n`);
+
+  const checkResult = await runGuardCheck(result.data, rootDir);
+
+  const report = buildGuardReport(checkResult);
+  printReportSummary(report);
+
+  const reportPath = resolveFromCwd("mandu-report.json");
+  await writeReport(report, reportPath);
+  console.log(`📋 Report 저장: ${reportPath}`);
+
+  if (!checkResult.passed) {
+    console.log(`\n❌ guard 실패: ${checkResult.violations.length}개 위반 발견`);
+    return false;
+  }
+
+  console.log(`\n✅ guard 통과`);
+  console.log(`💡 다음 단계: bunx mandu dev`);
+
+  return true;
+}

package/src/commands/init.ts

@@ -0,0 +1,88 @@
+import path from "path";
+import fs from "fs/promises";
+
+export interface InitOptions {
+  name?: string;
+  template?: string;
+}
+
+async function copyDir(src: string, dest: string, projectName: string): Promise<void> {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath, projectName);
+    } else {
+      let content = await fs.readFile(srcPath, "utf-8");
+      // Replace template variables
+      content = content.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+      await fs.writeFile(destPath, content);
+    }
+  }
+}
+
+function getTemplatesDir(): string {
+  // When installed via npm, templates are in the CLI package
+  const commandsDir = import.meta.dir;
+  // packages/cli/src/commands -> go up 2 levels to cli package root
+  return path.resolve(commandsDir, "../../templates");
+}
+
+export async function init(options: InitOptions = {}): Promise<boolean> {
+  const projectName = options.name || "my-mandu-app";
+  const template = options.template || "default";
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  console.log(`🥟 Mandu Init`);
+  console.log(`📁 프로젝트: ${projectName}`);
+  console.log(`📦 템플릿: ${template}\n`);
+
+  // Check if target directory exists
+  try {
+    await fs.access(targetDir);
+    console.error(`❌ 디렉토리가 이미 존재합니다: ${targetDir}`);
+    return false;
+  } catch {
+    // Directory doesn't exist, good to proceed
+  }
+
+  const templatesDir = getTemplatesDir();
+  const templateDir = path.join(templatesDir, template);
+
+  // Check if template exists
+  try {
+    await fs.access(templateDir);
+  } catch {
+    console.error(`❌ 템플릿을 찾을 수 없습니다: ${template}`);
+    console.error(`   사용 가능한 템플릿: default`);
+    return false;
+  }
+
+  console.log(`📋 템플릿 복사 중...`);
+
+  try {
+    await copyDir(templateDir, targetDir, projectName);
+  } catch (error) {
+    console.error(`❌ 템플릿 복사 실패:`, error);
+    return false;
+  }
+
+  // Create empty generated directories
+  await fs.mkdir(path.join(targetDir, "apps/server/generated/routes"), { recursive: true });
+  await fs.mkdir(path.join(targetDir, "apps/web/generated/routes"), { recursive: true });
+
+  console.log(`\n✅ 프로젝트 생성 완료!\n`);
+  console.log(`📍 위치: ${targetDir}`);
+  console.log(`\n🚀 시작하기:`);
+  console.log(`   cd ${projectName}`);
+  console.log(`   bun install`);
+  console.log(`   bun run spec`);
+  console.log(`   bun run generate`);
+  console.log(`   bun run dev`);
+
+  return true;
+}

package/src/commands/spec-upsert.ts

@@ -0,0 +1,47 @@
+import { loadManifest, writeLock, readLock } from "@mandu/core";
+import { resolveFromCwd } from "../util/fs";
+import path from "path";
+
+export interface SpecUpsertOptions {
+  file?: string;
+}
+
+export async function specUpsert(options: SpecUpsertOptions): Promise<boolean> {
+  const specPath = options.file
+    ? resolveFromCwd(options.file)
+    : resolveFromCwd("spec/routes.manifest.json");
+
+  console.log(`🥟 Mandu Spec Upsert`);
+  console.log(`📄 Spec 파일: ${specPath}\n`);
+
+  const result = await loadManifest(specPath);
+
+  if (!result.success || !result.data) {
+    console.error("❌ Spec 검증 실패:");
+    result.errors?.forEach((e) => console.error(`  - ${e}`));
+    return false;
+  }
+
+  console.log(`✅ Spec 검증 통과`);
+  console.log(`   - 버전: ${result.data.version}`);
+  console.log(`   - 라우트 수: ${result.data.routes.length}`);
+
+  for (const route of result.data.routes) {
+    const kindIcon = route.kind === "api" ? "📡" : "📄";
+    console.log(`   ${kindIcon} ${route.id}: ${route.pattern} (${route.kind})`);
+  }
+
+  const lockPath = resolveFromCwd("spec/spec.lock.json");
+  const previousLock = await readLock(lockPath);
+  const newLock = await writeLock(lockPath, result.data);
+
+  console.log(`\n🔒 Lock 파일 갱신: ${lockPath}`);
+  console.log(`   - 이전 해시: ${previousLock?.routesHash?.slice(0, 12) || "(없음)"}...`);
+  console.log(`   - 새 해시: ${newLock.routesHash.slice(0, 12)}...`);
+  console.log(`   - 갱신 시간: ${newLock.updatedAt}`);
+
+  console.log(`\n✅ spec-upsert 완료`);
+  console.log(`💡 다음 단계: bunx mandu generate`);
+
+  return true;
+}

package/src/main.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun
+
+import { specUpsert } from "./commands/spec-upsert";
+import { generateApply } from "./commands/generate-apply";
+import { guardCheck } from "./commands/guard-check";
+import { dev } from "./commands/dev";
+import { init } from "./commands/init";
+
+const HELP_TEXT = `
+🥟 Mandu CLI - Agent-Native Fullstack Framework
+
+Usage: bunx mandu <command> [options]
+
+Commands:
+  init           새 프로젝트 생성
+  spec-upsert    Spec 파일 검증 및 lock 갱신
+  generate       Spec에서 코드 생성
+  guard          Guard 규칙 검사
+  dev            개발 서버 실행
+
+Options:
+  --name <name>  init 시 프로젝트 이름 (기본: my-mandu-app)
+  --file <path>  spec-upsert 시 사용할 spec 파일 경로
+  --port <port>  dev 서버 포트 (기본: 3000)
+  --help, -h     도움말 표시
+
+Examples:
+  bunx mandu init --name my-app
+  bunx mandu spec-upsert
+  bunx mandu generate
+  bunx mandu guard
+  bunx mandu dev --port 3000
+
+Workflow:
+  1. init → 2. spec-upsert → 3. generate → 4. guard → 5. dev
+`;
+
+function parseArgs(args: string[]): { command: string; options: Record<string, string> } {
+  const command = args[0] || "";
+  const options: Record<string, string> = {};
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const value = args[i + 1] && !args[i + 1].startsWith("--") ? args[++i] : "true";
+      options[key] = value;
+    } else if (arg === "-h") {
+      options["help"] = "true";
+    } else if (!options._positional) {
+      // First non-flag argument after command is positional (e.g., project name)
+      options._positional = arg;
+    }
+  }
+
+  return { command, options };
+}
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const { command, options } = parseArgs(args);
+
+  if (options.help || command === "help" || !command) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+
+  let success = true;
+
+  switch (command) {
+    case "init":
+      success = await init({
+        name: options.name || options._positional
+      });
+      break;
+
+    case "spec-upsert":
+      success = await specUpsert({ file: options.file });
+      break;
+
+    case "generate":
+      success = await generateApply();
+      break;
+
+    case "guard":
+      success = await guardCheck();
+      break;
+
+    case "dev":
+      await dev({ port: options.port ? Number(options.port) : undefined });
+      break;
+
+    default:
+      console.error(`❌ Unknown command: ${command}`);
+      console.log(HELP_TEXT);
+      process.exit(1);
+  }
+
+  if (!success) {
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error("❌ 예상치 못한 오류:", error);
+  process.exit(1);
+});

package/src/util/fs.ts

@@ -0,0 +1,9 @@
+import path from "path";
+
+export function resolveFromCwd(...paths: string[]): string {
+  return path.resolve(process.cwd(), ...paths);
+}
+
+export function getRootDir(): string {
+  return process.cwd();
+}

package/templates/default/apps/server/main.ts

@@ -0,0 +1,49 @@
+import { loadManifest, startServer, registerApiHandler, registerPageLoader } from "@mandu/core";
+import path from "path";
+
+const SPEC_PATH = path.resolve(import.meta.dir, "../../spec/routes.manifest.json");
+
+async function main() {
+  console.log("🥟 Mandu Server Starting...\n");
+
+  const result = await loadManifest(SPEC_PATH);
+
+  if (!result.success || !result.data) {
+    console.error("❌ Spec 로드 실패:");
+    result.errors?.forEach((e) => console.error(`  - ${e}`));
+    process.exit(1);
+  }
+
+  console.log(`✅ Spec 로드 완료: ${result.data.routes.length}개 라우트`);
+
+  for (const route of result.data.routes) {
+    if (route.kind === "api") {
+      const modulePath = path.resolve(import.meta.dir, "../../", route.module);
+      try {
+        const module = await import(modulePath);
+        registerApiHandler(route.id, module.default || module.handler);
+        console.log(`  📡 API: ${route.pattern} -> ${route.id}`);
+      } catch (error) {
+        console.error(`  ❌ API 핸들러 로드 실패: ${route.id}`, error);
+      }
+    } else if (route.kind === "page") {
+      const componentPath = path.resolve(import.meta.dir, "../../", route.componentModule!);
+      registerPageLoader(route.id, () => import(componentPath));
+      console.log(`  📄 Page: ${route.pattern} -> ${route.id}`);
+    }
+  }
+
+  console.log("");
+
+  const server = startServer(result.data, {
+    port: Number(process.env.PORT) || 3000,
+  });
+
+  process.on("SIGINT", () => {
+    console.log("\n🛑 서버 종료 중...");
+    server.stop();
+    process.exit(0);
+  });
+}
+
+main().catch(console.error);

package/templates/default/apps/web/entry.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import type { ReactElement } from "react";
+
+export interface AppContext {
+  routeId: string;
+  url: string;
+  params: Record<string, string>;
+}
+
+type RouteComponent = (props: { params: Record<string, string> }) => ReactElement;
+
+const routeComponents: Record<string, RouteComponent> = {};
+
+export function registerRoute(routeId: string, component: RouteComponent): void {
+  routeComponents[routeId] = component;
+}
+
+export function createApp(context: AppContext): ReactElement {
+  const Component = routeComponents[context.routeId];
+
+  if (!Component) {
+    return (
+      <div>
+        <h1>404 - Route Not Found</h1>
+        <p>Route ID: {context.routeId}</p>
+      </div>
+    );
+  }
+
+  return <Component params={context.params} />;
+}
+
+export function getRegisteredRoutes(): string[] {
+  return Object.keys(routeComponents);
+}

package/templates/default/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "mandu dev",
+    "generate": "mandu generate",
+    "guard": "mandu guard",
+    "spec": "mandu spec-upsert"
+  },
+  "dependencies": {
+    "@mandujs/core": "^0.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "devDependencies": {
+    "@mandujs/cli": "^0.1.0",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "typescript": "^5.0.0"
+  }
+}

package/templates/default/spec/routes.manifest.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "routes": [
+    {
+      "id": "home",
+      "pattern": "/",
+      "kind": "page",
+      "module": "apps/server/generated/routes/home.route.ts",
+      "componentModule": "apps/web/generated/routes/home.route.tsx"
+    },
+    {
+      "id": "health",
+      "pattern": "/api/health",
+      "kind": "api",
+      "module": "apps/server/generated/routes/health.route.ts"
+    }
+  ]
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "jsx": "react-jsx",
+    "types": ["bun-types"]
+  },
+  "include": ["apps/**/*.ts", "apps/**/*.tsx"],
+  "exclude": ["node_modules"]
+}