@mandujs/cli 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,170 @@
+# @mandujs/cli
+
+Agent-Native Fullstack Framework CLI - 에이전트가 코딩해도 아키텍처가 무너지지 않는 개발 OS
+
+## 설치
+
+```bash
+# Bun 필수
+bun add -D @mandujs/cli
+```
+
+## 빠른 시작
+
+```bash
+# 새 프로젝트 생성
+bunx @mandujs/cli init my-app
+cd my-app
+
+# 개발 서버 시작
+bun run dev
+```
+
+## 명령어
+
+### `mandu init <project-name>`
+
+새 Mandu 프로젝트를 생성합니다.
+
+```bash
+bunx @mandujs/cli init my-app
+```
+
+생성되는 구조:
+```
+my-app/
+├── apps/
+│   ├── server/main.ts    # 서버 진입점
+│   └── web/entry.tsx     # 클라이언트 진입점
+├── spec/
+│   └── routes.manifest.json  # SSOT - 라우트 정의
+├── tests/                # 테스트 템플릿
+├── package.json
+└── tsconfig.json
+```
+
+### `mandu dev`
+
+개발 서버를 시작합니다 (HMR 지원).
+
+```bash
+bun run dev
+# 또는
+bunx mandu dev
+```
+
+### `mandu spec`
+
+spec 파일을 검증하고 lock 파일을 갱신합니다.
+
+```bash
+bun run spec
+```
+
+### `mandu generate`
+
+spec 기반으로 코드를 생성합니다.
+
+```bash
+bun run generate
+```
+
+### `mandu guard`
+
+아키텍처 규칙을 검사하고 위반 사항을 자동 수정합니다.
+
+```bash
+bun run guard
+
+# 자동 수정 비활성화
+bunx mandu guard --no-auto-correct
+```
+
+자동 수정 가능한 규칙:
+- `SPEC_HASH_MISMATCH` → lock 파일 갱신
+- `GENERATED_MANUAL_EDIT` → 코드 재생성
+- `SLOT_NOT_FOUND` → slot 파일 생성
+
+## Spec 파일 작성
+
+`spec/routes.manifest.json`이 모든 라우트의 단일 진실 공급원(SSOT)입니다.
+
+```json
+{
+  "version": "1.0.0",
+  "routes": [
+    {
+      "id": "getUsers",
+      "pattern": "/api/users",
+      "kind": "api",
+      "module": "apps/server/api/users.ts"
+    },
+    {
+      "id": "homePage",
+      "pattern": "/",
+      "kind": "page",
+      "module": "apps/server/pages/home.ts",
+      "componentModule": "apps/web/pages/Home.tsx"
+    }
+  ]
+}
+```
+
+### Slot 시스템 (v0.2.0+)
+
+비즈니스 로직을 분리하려면 `slotModule`을 추가합니다:
+
+```json
+{
+  "id": "getUsers",
+  "pattern": "/api/users",
+  "kind": "api",
+  "module": "apps/server/api/users.generated.ts",
+  "slotModule": "apps/server/api/users.slot.ts"
+}
+```
+
+- `*.generated.ts` - 프레임워크가 관리 (수정 금지)
+- `*.slot.ts` - 개발자가 작성하는 비즈니스 로직
+
+## 개발 워크플로우
+
+```bash
+# 1. spec 수정
+# 2. spec 검증 및 lock 갱신
+bun run spec
+
+# 3. 코드 생성
+bun run generate
+
+# 4. 아키텍처 검사
+bun run guard
+
+# 5. 테스트
+bun test
+
+# 6. 개발 서버
+bun run dev
+```
+
+## 테스트
+
+Bun 테스트 프레임워크를 기본 지원합니다.
+
+```bash
+bun test           # 테스트 실행
+bun test --watch   # 감시 모드
+```
+
+## 요구 사항
+
+- Bun >= 1.0.0
+- React >= 18.0.0
+
+## 관련 패키지
+
+- [@mandujs/core](https://www.npmjs.com/package/@mandujs/core) - 핵심 런타임
+
+## 라이선스
+
+MIT

package/package.json

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

package/src/commands/dev.ts

@@ -1,4 +1,4 @@
-import { loadManifest, startServer, registerApiHandler, registerPageLoader } from "@mandu/core";
+import { loadManifest, startServer, registerApiHandler, registerPageLoader } from "@mandujs/core";
 import { resolveFromCwd } from "../util/fs";
 import path from "path";
 

package/src/commands/generate-apply.ts

@@ -1,4 +1,4 @@
-import { loadManifest, generateRoutes, buildGenerateReport, printReportSummary, writeReport } from "@mandu/core";
+import { loadManifest, generateRoutes, buildGenerateReport, printReportSummary, writeReport } from "@mandujs/core";
 import { resolveFromCwd, getRootDir } from "../util/fs";
 
 export async function generateApply(): Promise<boolean> {

package/src/commands/guard-check.ts

@@ -1,12 +1,27 @@
-import { loadManifest, runGuardCheck, buildGuardReport, printReportSummary, writeReport } from "@mandu/core";
+import {
+  loadManifest,
+  runGuardCheck,
+  buildGuardReport,
+  printReportSummary,
+  writeReport,
+  runAutoCorrect,
+  isAutoCorrectableViolation,
+} from "@mandujs/core";
 import { resolveFromCwd, getRootDir } from "../util/fs";
 
-export async function guardCheck(): Promise<boolean> {
+export interface GuardCheckOptions {
+  autoCorrect?: boolean;
+}
+
+export async function guardCheck(options: GuardCheckOptions = {}): Promise<boolean> {
+  const { autoCorrect = true } = options;
+
   const specPath = resolveFromCwd("spec/routes.manifest.json");
   const rootDir = getRootDir();
 
   console.log(`🥟 Mandu Guard`);
-  console.log(`📄 Spec 파일: ${specPath}\n`);
+  console.log(`📄 Spec 파일: ${specPath}`);
+  console.log(`🔧 Auto-correct: ${autoCorrect ? "ON" : "OFF"}\n`);
 
   const result = await loadManifest(specPath);
 
@@ -19,7 +34,55 @@ export async function guardCheck(): Promise<boolean> {
   console.log(`✅ Spec 로드 완료`);
   console.log(`🔍 Guard 검사 중...\n`);
 
-  const checkResult = await runGuardCheck(result.data, rootDir);
+  let checkResult = await runGuardCheck(result.data, rootDir);
+
+  // Auto-correct 시도
+  if (!checkResult.passed && autoCorrect) {
+    const autoCorrectableCount = checkResult.violations.filter(isAutoCorrectableViolation).length;
+
+    if (autoCorrectableCount > 0) {
+      console.log(`⚠️  ${checkResult.violations.length}개 위반 감지 (자동 수정 가능: ${autoCorrectableCount}개)`);
+      console.log(`🔄 Auto-correct 실행 중...\n`);
+
+      const autoCorrectResult = await runAutoCorrect(
+        checkResult.violations,
+        result.data,
+        rootDir
+      );
+
+      // 수행된 단계 출력
+      for (const step of autoCorrectResult.steps) {
+        const icon = step.success ? "✅" : "❌";
+        console.log(`  ${icon} [${step.action}] ${step.message}`);
+      }
+
+      if (autoCorrectResult.fixed) {
+        console.log(`\n✅ Auto-correct 완료 (${autoCorrectResult.retriedCount}회 재시도)`);
+
+        // 최종 Guard 재검사
+        checkResult = await runGuardCheck(result.data, rootDir);
+      } else {
+        console.log(`\n⚠️  일부 위반은 수동 수정이 필요합니다:`);
+
+        const manualViolations = autoCorrectResult.remainingViolations.filter(
+          (v) => !isAutoCorrectableViolation(v)
+        );
+
+        for (const v of manualViolations) {
+          console.log(`  - [${v.ruleId}] ${v.file}`);
+          console.log(`    💡 ${v.suggestion}`);
+        }
+
+        // 남은 위반으로 업데이트
+        checkResult = {
+          passed: autoCorrectResult.remainingViolations.length === 0,
+          violations: autoCorrectResult.remainingViolations,
+        };
+      }
+
+      console.log("");
+    }
+  }
 
   const report = buildGuardReport(checkResult);
   printReportSummary(report);
@@ -29,11 +92,11 @@ export async function guardCheck(): Promise<boolean> {
   console.log(`📋 Report 저장: ${reportPath}`);
 
   if (!checkResult.passed) {
-    console.log(`\n❌ guard 실패: ${checkResult.violations.length}개 위반 발견`);
+    console.log(`\n❌ Guard 실패: ${checkResult.violations.length}개 위반 발견`);
     return false;
   }
 
-  console.log(`\n✅ guard 통과`);
+  console.log(`\n✅ Guard 통과`);
   console.log(`💡 다음 단계: bunx mandu dev`);
 
   return true;

package/src/commands/spec-upsert.ts

@@ -1,4 +1,4 @@
-import { loadManifest, writeLock, readLock } from "@mandu/core";
+import { loadManifest, writeLock, readLock } from "@mandujs/core";
 import { resolveFromCwd } from "../util/fs";
 import path from "path";
 

package/src/main.ts

@@ -19,10 +19,11 @@ Commands:
   dev            개발 서버 실행
 
 Options:
-  --name <name>  init 시 프로젝트 이름 (기본: my-mandu-app)
-  --file <path>  spec-upsert 시 사용할 spec 파일 경로
-  --port <port>  dev 서버 포트 (기본: 3000)
-  --help, -h     도움말 표시
+  --name <name>      init 시 프로젝트 이름 (기본: my-mandu-app)
+  --file <path>      spec-upsert 시 사용할 spec 파일 경로
+  --port <port>      dev 서버 포트 (기본: 3000)
+  --no-auto-correct  guard 시 자동 수정 비활성화
+  --help, -h         도움말 표시
 
 Examples:
   bunx mandu init --name my-app
@@ -83,7 +84,9 @@ async function main(): Promise<void> {
       break;
 
     case "guard":
-      success = await guardCheck();
+      success = await guardCheck({
+        autoCorrect: options["no-auto-correct"] !== "true",
+      });
       break;
 
     case "dev":

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

@@ -1,4 +1,4 @@
-import { loadManifest, startServer, registerApiHandler, registerPageLoader } from "@mandu/core";
+import { loadManifest, startServer, registerApiHandler, registerPageLoader } from "@mandujs/core";
 import path from "path";
 
 const SPEC_PATH = path.resolve(import.meta.dir, "../../spec/routes.manifest.json");

package/templates/default/package.json

@@ -6,15 +6,17 @@
     "dev": "mandu dev",
     "generate": "mandu generate",
     "guard": "mandu guard",
-    "spec": "mandu spec-upsert"
+    "spec": "mandu spec-upsert",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
   },
   "dependencies": {
-    "@mandujs/core": "^0.1.0",
+    "@mandujs/core": "^0.2.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },
   "devDependencies": {
-    "@mandujs/cli": "^0.1.0",
+    "@mandujs/cli": "^0.2.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
     "typescript": "^5.0.0"

package/templates/default/tests/example.test.ts

@@ -0,0 +1,58 @@
+// Mandu Example Test
+// 이 파일은 테스트 작성 방법을 보여주는 예제입니다.
+
+import { describe, it, expect } from "bun:test";
+import { createTestRequest, parseJsonResponse, assertStatus } from "./helpers";
+
+describe("Example Tests", () => {
+  describe("Basic Assertions", () => {
+    it("should pass basic equality test", () => {
+      expect(1 + 1).toBe(2);
+    });
+
+    it("should pass object equality test", () => {
+      const obj = { status: "ok", data: { message: "hello" } };
+      expect(obj).toEqual({
+        status: "ok",
+        data: { message: "hello" },
+      });
+    });
+  });
+
+  describe("Test Helpers", () => {
+    it("should create test request", () => {
+      const req = createTestRequest("http://localhost:3000/api/test", {
+        method: "POST",
+        body: { name: "test" },
+      });
+
+      expect(req.method).toBe("POST");
+      expect(req.url).toBe("http://localhost:3000/api/test");
+    });
+
+    it("should parse JSON response", async () => {
+      const mockResponse = new Response(
+        JSON.stringify({ status: "ok" }),
+        { status: 200 }
+      );
+
+      const data = await parseJsonResponse<{ status: string }>(mockResponse);
+      expect(data.status).toBe("ok");
+    });
+  });
+});
+
+// API 핸들러 테스트 예제 (실제 핸들러 import 후 사용)
+// import handler from "../apps/server/generated/routes/health.route";
+//
+// describe("API: GET /api/health", () => {
+//   it("should return 200 with status ok", async () => {
+//     const req = createTestRequest("http://localhost:3000/api/health");
+//     const response = handler(req, {});
+//
+//     assertStatus(response, 200);
+//
+//     const data = await parseJsonResponse<{ status: string }>(response);
+//     expect(data.status).toBe("ok");
+//   });
+// });

package/templates/default/tests/helpers.ts

@@ -0,0 +1,52 @@
+// Mandu Test Helpers
+// 테스트에서 사용할 유틸리티 함수들
+
+import type { Request } from "bun";
+
+/**
+ * API 핸들러 테스트용 Request 생성
+ */
+export function createTestRequest(
+  url: string,
+  options?: {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+  }
+): Request {
+  const { method = "GET", body, headers = {} } = options || {};
+
+  return new Request(url, {
+    method,
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+}
+
+/**
+ * Response를 JSON으로 파싱
+ */
+export async function parseJsonResponse<T = unknown>(response: Response): Promise<T> {
+  return response.json() as Promise<T>;
+}
+
+/**
+ * Response 상태 검증
+ */
+export function assertStatus(response: Response, expectedStatus: number): void {
+  if (response.status !== expectedStatus) {
+    throw new Error(
+      `Expected status ${expectedStatus}, got ${response.status}`
+    );
+  }
+}
+
+/**
+ * 테스트용 라우트 파라미터 생성
+ */
+export function createParams(params: Record<string, string>): Record<string, string> {
+  return params;
+}

package/templates/default/tests/setup.ts

@@ -0,0 +1,9 @@
+// Mandu Test Setup
+// Bun 테스트 환경 설정
+
+// 테스트 타임아웃 설정 (필요 시)
+// import { setDefaultTimeout } from "bun:test";
+// setDefaultTimeout(10000);
+
+// 환경 변수 설정
+process.env.NODE_ENV = "test";