@mandujs/core 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,189 @@
+# @mandujs/core
+
+Mandu Framework Core - Spec, Generator, Guard, Runtime
+
+## 설치
+
+```bash
+bun add @mandujs/core
+```
+
+> 일반적으로 `@mandujs/cli`를 통해 사용합니다. 직접 사용은 고급 사용 사례입니다.
+
+## 모듈 구조
+
+```
+@mandujs/core
+├── spec/      # Spec 스키마 및 로딩
+├── generator/ # 코드 생성
+├── guard/     # 아키텍처 검사 및 자동 수정
+├── runtime/   # 서버 및 라우터
+└── report/    # Guard 리포트 생성
+```
+
+## Spec 모듈
+
+라우트 manifest 스키마 정의 및 로딩.
+
+```typescript
+import { loadManifest, RoutesManifest, RouteSpec } from "@mandujs/core";
+
+// manifest 로드 및 검증
+const result = await loadManifest("spec/routes.manifest.json");
+
+if (result.success && result.data) {
+  const manifest: RoutesManifest = result.data;
+  manifest.routes.forEach((route: RouteSpec) => {
+    console.log(route.id, route.pattern, route.kind);
+  });
+}
+```
+
+### Lock 파일
+
+```typescript
+import { writeLock, readLock } from "@mandujs/core";
+
+// lock 파일 쓰기
+const lock = await writeLock("spec/spec.lock.json", manifest);
+console.log(lock.routesHash);
+
+// lock 파일 읽기
+const existing = await readLock("spec/spec.lock.json");
+```
+
+## Generator 모듈
+
+Spec 기반 코드 생성.
+
+```typescript
+import { generateRoutes, GenerateResult } from "@mandujs/core";
+
+const result: GenerateResult = await generateRoutes(manifest, "./");
+
+console.log("생성됨:", result.created);
+console.log("건너뜀:", result.skipped);  // 이미 존재하는 slot 파일
+```
+
+### 템플릿 함수
+
+```typescript
+import {
+  generateApiHandler,
+  generateApiHandlerWithSlot,
+  generateSlotLogic,
+  generatePageComponent
+} from "@mandujs/core";
+
+// API 핸들러 생성
+const code = generateApiHandler(route);
+
+// Slot이 있는 API 핸들러
+const codeWithSlot = generateApiHandlerWithSlot(route);
+
+// Slot 로직 파일
+const slotCode = generateSlotLogic(route);
+```
+
+## Guard 모듈
+
+아키텍처 규칙 검사 및 자동 수정.
+
+```typescript
+import {
+  runGuardCheck,
+  runAutoCorrect,
+  GuardResult,
+  GuardViolation
+} from "@mandujs/core";
+
+// 검사 실행
+const result: GuardResult = await runGuardCheck(manifest, "./");
+
+if (!result.passed) {
+  result.violations.forEach((v: GuardViolation) => {
+    console.log(`${v.rule}: ${v.message}`);
+  });
+
+  // 자동 수정 실행
+  const corrected = await runAutoCorrect(result.violations, manifest, "./");
+  console.log("수정됨:", corrected.steps);
+  console.log("남은 위반:", corrected.remainingViolations);
+}
+```
+
+### Guard 규칙
+
+| 규칙 ID | 설명 | 자동 수정 |
+|---------|------|----------|
+| `SPEC_HASH_MISMATCH` | spec과 lock 해시 불일치 | ✅ |
+| `GENERATED_MANUAL_EDIT` | generated 파일 수동 수정 | ✅ |
+| `HANDLER_NOT_FOUND` | 핸들러 파일 없음 | ❌ |
+| `COMPONENT_NOT_FOUND` | 컴포넌트 파일 없음 | ❌ |
+| `SLOT_NOT_FOUND` | slot 파일 없음 | ✅ |
+
+## Runtime 모듈
+
+서버 시작 및 라우팅.
+
+```typescript
+import {
+  startServer,
+  registerApiHandler,
+  registerPageLoader
+} from "@mandujs/core";
+
+// API 핸들러 등록
+registerApiHandler("getUsers", async (req) => {
+  return { users: [] };
+});
+
+// 페이지 로더 등록
+registerPageLoader("homePage", () => import("./pages/Home"));
+
+// 서버 시작
+const server = startServer(manifest, { port: 3000 });
+
+// 종료
+server.stop();
+```
+
+## Report 모듈
+
+Guard 결과 리포트 생성.
+
+```typescript
+import { buildGuardReport } from "@mandujs/core";
+
+const report = buildGuardReport(guardResult, lockPath);
+console.log(report);  // 포맷된 텍스트 리포트
+```
+
+## 타입
+
+```typescript
+import type {
+  RoutesManifest,
+  RouteSpec,
+  RouteKind,
+  SpecLock,
+  GuardResult,
+  GuardViolation,
+  GenerateResult,
+  AutoCorrectResult,
+} from "@mandujs/core";
+```
+
+## 요구 사항
+
+- Bun >= 1.0.0
+- React >= 18.0.0
+- Zod >= 3.0.0
+
+## 관련 패키지
+
+- [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI 도구
+
+## 라이선스
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mandujs/core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
   "type": "module",
   "main": "./src/index.ts",

package/src/generator/generate.ts

@@ -1,12 +1,22 @@
 import type { RoutesManifest, RouteSpec } from "../spec/schema";
-import { generateApiHandler, generatePageComponent } from "./templates";
+import { generateApiHandler, generatePageComponent, generateSlotLogic } from "./templates";
 import path from "path";
 import fs from "fs/promises";
 
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export interface GenerateResult {
   success: boolean;
   created: string[];
   deleted: string[];
+  skipped: string[];
   errors: string[];
 }
 
@@ -41,6 +51,7 @@ export async function generateRoutes(
     success: true,
     created: [],
     deleted: [],
+    skipped: [],
     errors: [],
   };
 
@@ -77,6 +88,24 @@ export async function generateRoutes(
         kind: route.kind,
       };
 
+      // Slot file (only if slotModule is specified)
+      if (route.slotModule) {
+        const slotFilePath = path.join(rootDir, route.slotModule);
+        const slotDir = path.dirname(slotFilePath);
+
+        await ensureDir(slotDir);
+
+        // slot 파일이 이미 존재하면 덮어쓰지 않음 (사용자 코드 보존)
+        const slotExists = await fileExists(slotFilePath);
+        if (!slotExists) {
+          const slotContent = generateSlotLogic(route);
+          await Bun.write(slotFilePath, slotContent);
+          result.created.push(slotFilePath);
+        } else {
+          result.skipped.push(slotFilePath);
+        }
+      }
+
       // Page component (only for page kind)
       if (route.kind === "page") {
         const webFileName = `${route.id}.route.tsx`;

package/src/generator/templates.ts

@@ -1,6 +1,11 @@
 import type { RouteSpec } from "../spec/schema";
 
 export function generateApiHandler(route: RouteSpec): string {
+  // slotModule이 있으면 slot을 호출하는 버전 생성
+  if (route.slotModule) {
+    return generateApiHandlerWithSlot(route);
+  }
+
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY
 // Route ID: ${route.id}
 // Pattern: ${route.pattern}
@@ -18,6 +23,113 @@ export default function handler(req: Request, params: Record<string, string>): R
 `;
 }
 
+export function generateApiHandlerWithSlot(route: RouteSpec): string {
+  const slotImportPath = computeSlotImportPath(route.slotModule!, "apps/server/generated/routes");
+  const logicFunctionName = `${route.id}Logic`;
+
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+// Slot Module: ${route.slotModule}
+
+import type { Request } from "bun";
+import { ${logicFunctionName} } from "${slotImportPath}";
+
+export default async function handler(
+  req: Request,
+  params: Record<string, string>
+): Promise<Response> {
+  try {
+    const result = await ${logicFunctionName}(req, params);
+    return Response.json(result);
+  } catch (error) {
+    console.error(\`[${route.id}] Handler error:\`, error);
+    return Response.json(
+      { status: "error", message: "Internal server error" },
+      { status: 500 }
+    );
+  }
+}
+`;
+}
+
+export function generateSlotLogic(route: RouteSpec): string {
+  const logicFunctionName = `${route.id}Logic`;
+  const resultTypeName = `${capitalize(route.id)}Result`;
+
+  return `// Slot logic for route: ${route.id}
+// Pattern: ${route.pattern}
+// 이 파일에서 비즈니스 로직을 구현하세요.
+
+import type { Request } from "bun";
+
+export interface ${resultTypeName} {
+  status: "ok" | "error";
+  data?: unknown;
+  message?: string;
+}
+
+export async function ${logicFunctionName}(
+  req: Request,
+  params: Record<string, string>
+): Promise<${resultTypeName}> {
+  const method = req.method;
+
+  // TODO: 비즈니스 로직 구현
+  switch (method) {
+    case "GET":
+      return {
+        status: "ok",
+        data: { routeId: "${route.id}", message: "GET 로직 미구현" },
+      };
+
+    case "POST":
+      return {
+        status: "ok",
+        data: { routeId: "${route.id}", message: "POST 로직 미구현" },
+      };
+
+    default:
+      return {
+        status: "error",
+        message: \`Method \${method} not allowed\`,
+      };
+  }
+}
+`;
+}
+
+function computeSlotImportPath(slotModule: string, fromDir: string): string {
+  // slotModule: "apps/server/slots/users.logic.ts"
+  // fromDir: "apps/server/generated/routes"
+  // result: "../../slots/users.logic"
+
+  const slotParts = slotModule.replace(/\\/g, "/").split("/");
+  const fromParts = fromDir.replace(/\\/g, "/").split("/");
+
+  // Find common prefix length
+  let commonLength = 0;
+  while (
+    commonLength < slotParts.length &&
+    commonLength < fromParts.length &&
+    slotParts[commonLength] === fromParts[commonLength]
+  ) {
+    commonLength++;
+  }
+
+  // Calculate relative path
+  const upCount = fromParts.length - commonLength;
+  const relativeParts = slotParts.slice(commonLength);
+  const ups = Array(upCount).fill("..");
+
+  let result = [...ups, ...relativeParts].join("/");
+
+  // Remove .ts extension
+  result = result.replace(/\.ts$/, "");
+
+  return result;
+}
+
 export function generatePageComponent(route: RouteSpec): string {
   const pageName = capitalize(route.id);
   return `// Generated by Mandu - DO NOT EDIT DIRECTLY

package/src/guard/auto-correct.ts

@@ -0,0 +1,203 @@
+import type { RoutesManifest } from "../spec/schema";
+import type { GuardViolation } from "./rules";
+import { GUARD_RULES } from "./rules";
+import { runGuardCheck } from "./check";
+import { writeLock } from "../spec/lock";
+import { generateRoutes } from "../generator/generate";
+import path from "path";
+
+export interface AutoCorrectStep {
+  ruleId: string;
+  action: string;
+  success: boolean;
+  message: string;
+}
+
+export interface AutoCorrectResult {
+  fixed: boolean;
+  steps: AutoCorrectStep[];
+  remainingViolations: GuardViolation[];
+  retriedCount: number;
+}
+
+// 자동 수정 가능한 규칙들
+const AUTO_CORRECTABLE_RULES = new Set([
+  GUARD_RULES.SPEC_HASH_MISMATCH.id,
+  GUARD_RULES.GENERATED_MANUAL_EDIT.id,
+  GUARD_RULES.SLOT_NOT_FOUND.id,
+]);
+
+export function isAutoCorrectableViolation(violation: GuardViolation): boolean {
+  return AUTO_CORRECTABLE_RULES.has(violation.ruleId);
+}
+
+export async function runAutoCorrect(
+  violations: GuardViolation[],
+  manifest: RoutesManifest,
+  rootDir: string,
+  maxRetries: number = 3
+): Promise<AutoCorrectResult> {
+  const steps: AutoCorrectStep[] = [];
+  let currentViolations = violations;
+  let retriedCount = 0;
+
+  while (retriedCount < maxRetries) {
+    const autoCorrectableViolations = currentViolations.filter(isAutoCorrectableViolation);
+
+    if (autoCorrectableViolations.length === 0) {
+      break;
+    }
+
+    // 각 위반에 대해 수정 시도
+    let anyFixed = false;
+
+    for (const violation of autoCorrectableViolations) {
+      const step = await correctViolation(violation, manifest, rootDir);
+      steps.push(step);
+
+      if (step.success) {
+        anyFixed = true;
+      }
+    }
+
+    if (!anyFixed) {
+      // 아무것도 수정하지 못했으면 루프 종료
+      break;
+    }
+
+    // Guard 재검사
+    retriedCount++;
+    const recheckResult = await runGuardCheck(manifest, rootDir);
+    currentViolations = recheckResult.violations;
+
+    if (recheckResult.passed) {
+      return {
+        fixed: true,
+        steps,
+        remainingViolations: [],
+        retriedCount,
+      };
+    }
+  }
+
+  return {
+    fixed: currentViolations.length === 0,
+    steps,
+    remainingViolations: currentViolations,
+    retriedCount,
+  };
+}
+
+async function correctViolation(
+  violation: GuardViolation,
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<AutoCorrectStep> {
+  switch (violation.ruleId) {
+    case GUARD_RULES.SPEC_HASH_MISMATCH.id:
+      return await correctSpecHashMismatch(manifest, rootDir);
+
+    case GUARD_RULES.GENERATED_MANUAL_EDIT.id:
+      return await correctGeneratedManualEdit(manifest, rootDir);
+
+    case GUARD_RULES.SLOT_NOT_FOUND.id:
+      return await correctSlotNotFound(manifest, rootDir);
+
+    default:
+      return {
+        ruleId: violation.ruleId,
+        action: "skip",
+        success: false,
+        message: `자동 수정 불가능한 규칙: ${violation.ruleId}`,
+      };
+  }
+}
+
+async function correctSpecHashMismatch(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<AutoCorrectStep> {
+  try {
+    const lockPath = path.join(rootDir, "spec/spec.lock.json");
+    await writeLock(lockPath, manifest);
+
+    return {
+      ruleId: GUARD_RULES.SPEC_HASH_MISMATCH.id,
+      action: "spec-upsert",
+      success: true,
+      message: "spec.lock.json 업데이트 완료",
+    };
+  } catch (error) {
+    return {
+      ruleId: GUARD_RULES.SPEC_HASH_MISMATCH.id,
+      action: "spec-upsert",
+      success: false,
+      message: `spec.lock.json 업데이트 실패: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+async function correctGeneratedManualEdit(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<AutoCorrectStep> {
+  try {
+    const result = await generateRoutes(manifest, rootDir);
+
+    if (result.success) {
+      return {
+        ruleId: GUARD_RULES.GENERATED_MANUAL_EDIT.id,
+        action: "generate",
+        success: true,
+        message: `코드 재생성 완료 (${result.created.length}개 파일)`,
+      };
+    } else {
+      return {
+        ruleId: GUARD_RULES.GENERATED_MANUAL_EDIT.id,
+        action: "generate",
+        success: false,
+        message: `코드 재생성 실패: ${result.errors.join(", ")}`,
+      };
+    }
+  } catch (error) {
+    return {
+      ruleId: GUARD_RULES.GENERATED_MANUAL_EDIT.id,
+      action: "generate",
+      success: false,
+      message: `코드 재생성 실패: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+async function correctSlotNotFound(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<AutoCorrectStep> {
+  try {
+    const result = await generateRoutes(manifest, rootDir);
+
+    if (result.success) {
+      const slotCount = result.created.filter((f) => f.includes("slots")).length;
+      return {
+        ruleId: GUARD_RULES.SLOT_NOT_FOUND.id,
+        action: "generate-slot",
+        success: true,
+        message: `Slot 파일 생성 완료 (${slotCount}개 파일)`,
+      };
+    } else {
+      return {
+        ruleId: GUARD_RULES.SLOT_NOT_FOUND.id,
+        action: "generate-slot",
+        success: false,
+        message: `Slot 파일 생성 실패: ${result.errors.join(", ")}`,
+      };
+    }
+  } catch (error) {
+    return {
+      ruleId: GUARD_RULES.SLOT_NOT_FOUND.id,
+      action: "generate-slot",
+      success: false,
+      message: `Slot 파일 생성 실패: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}

package/src/guard/check.ts

@@ -120,6 +120,32 @@ export async function checkInvalidGeneratedImport(
   return violations;
 }
 
+// Rule 5: Slot file existence check
+export async function checkSlotFileExists(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<GuardViolation[]> {
+  const violations: GuardViolation[] = [];
+
+  for (const route of manifest.routes) {
+    if (route.slotModule) {
+      const slotPath = path.join(rootDir, route.slotModule);
+      const exists = await fileExists(slotPath);
+
+      if (!exists) {
+        violations.push({
+          ruleId: GUARD_RULES.SLOT_NOT_FOUND.id,
+          file: route.slotModule,
+          message: `Slot 파일을 찾을 수 없습니다 (routeId: ${route.id})`,
+          suggestion: "bunx mandu generate를 실행하여 slot 파일을 생성하세요",
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
 // Rule 4: Forbidden imports in generated files
 export async function checkForbiddenImportsInGenerated(
   rootDir: string,
@@ -218,6 +244,10 @@ export async function runGuardCheck(
   const importViolations = await checkInvalidGeneratedImport(rootDir);
   violations.push(...importViolations);
 
+  // Rule 5: Slot file existence
+  const slotViolations = await checkSlotFileExists(manifest, rootDir);
+  violations.push(...slotViolations);
+
   return {
     passed: violations.length === 0,
     violations,

package/src/guard/index.ts

@@ -1,2 +1,3 @@
 export * from "./rules";
 export * from "./check";
+export * from "./auto-correct";

package/src/guard/rules.ts

@@ -32,6 +32,11 @@ export const GUARD_RULES: Record<string, GuardRule> = {
     name: "Forbidden Import in Generated",
     description: "generated 파일에서 금지된 모듈을 import 했습니다",
   },
+  SLOT_NOT_FOUND: {
+    id: "SLOT_NOT_FOUND",
+    name: "Slot File Not Found",
+    description: "spec에 명시된 slotModule 파일을 찾을 수 없습니다",
+  },
 };
 
 export const FORBIDDEN_IMPORTS = ["fs", "child_process", "cluster", "worker_threads"];

package/src/spec/schema.ts

@@ -10,6 +10,7 @@ export const RouteSpec = z
     kind: RouteKind,
     module: z.string().min(1, "module 경로는 필수입니다"),
     componentModule: z.string().optional(),
+    slotModule: z.string().optional(),
   })
   .refine(
     (route) => {