@mandujs/core 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mandujs/core",
+  "version": "0.1.0",
+  "description": "Mandu Framework Core - Spec, Generator, Guard, Runtime",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/**/*"
+  ],
+  "keywords": [
+    "mandu",
+    "framework",
+    "agent",
+    "ai",
+    "code-generation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/konamgil/mandu.git",
+    "directory": "packages/core"
+  },
+  "author": "konamgil",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "bun": ">=1.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "zod": ">=3.0.0"
+  }
+}

package/src/generator/generate.ts

@@ -0,0 +1,127 @@
+import type { RoutesManifest, RouteSpec } from "../spec/schema";
+import { generateApiHandler, generatePageComponent } from "./templates";
+import path from "path";
+import fs from "fs/promises";
+
+export interface GenerateResult {
+  success: boolean;
+  created: string[];
+  deleted: string[];
+  errors: string[];
+}
+
+export interface GeneratedMap {
+  version: number;
+  generatedAt: string;
+  files: Record<string, { routeId: string; kind: string }>;
+}
+
+async function ensureDir(dirPath: string): Promise<void> {
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+  } catch (error) {
+    // ignore if exists
+  }
+}
+
+async function getExistingFiles(dir: string): Promise<string[]> {
+  try {
+    const files = await fs.readdir(dir);
+    return files.filter((f) => f.endsWith(".route.ts") || f.endsWith(".route.tsx"));
+  } catch {
+    return [];
+  }
+}
+
+export async function generateRoutes(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<GenerateResult> {
+  const result: GenerateResult = {
+    success: true,
+    created: [],
+    deleted: [],
+    errors: [],
+  };
+
+  const serverRoutesDir = path.join(rootDir, "apps/server/generated/routes");
+  const webRoutesDir = path.join(rootDir, "apps/web/generated/routes");
+  const mapDir = path.join(rootDir, "packages/core/map");
+
+  await ensureDir(serverRoutesDir);
+  await ensureDir(webRoutesDir);
+  await ensureDir(mapDir);
+
+  const generatedMap: GeneratedMap = {
+    version: manifest.version,
+    generatedAt: new Date().toISOString(),
+    files: {},
+  };
+
+  const expectedServerFiles = new Set<string>();
+  const expectedWebFiles = new Set<string>();
+
+  for (const route of manifest.routes) {
+    try {
+      // Server handler
+      const serverFileName = `${route.id}.route.ts`;
+      const serverFilePath = path.join(serverRoutesDir, serverFileName);
+      expectedServerFiles.add(serverFileName);
+
+      const handlerContent = generateApiHandler(route);
+      await Bun.write(serverFilePath, handlerContent);
+      result.created.push(serverFilePath);
+
+      generatedMap.files[`apps/server/generated/routes/${serverFileName}`] = {
+        routeId: route.id,
+        kind: route.kind,
+      };
+
+      // Page component (only for page kind)
+      if (route.kind === "page") {
+        const webFileName = `${route.id}.route.tsx`;
+        const webFilePath = path.join(webRoutesDir, webFileName);
+        expectedWebFiles.add(webFileName);
+
+        const componentContent = generatePageComponent(route);
+        await Bun.write(webFilePath, componentContent);
+        result.created.push(webFilePath);
+
+        generatedMap.files[`apps/web/generated/routes/${webFileName}`] = {
+          routeId: route.id,
+          kind: route.kind,
+        };
+      }
+    } catch (error) {
+      result.success = false;
+      result.errors.push(
+        `Failed to generate ${route.id}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  // Clean up stale files
+  const existingServerFiles = await getExistingFiles(serverRoutesDir);
+  for (const file of existingServerFiles) {
+    if (!expectedServerFiles.has(file)) {
+      const filePath = path.join(serverRoutesDir, file);
+      await fs.unlink(filePath);
+      result.deleted.push(filePath);
+    }
+  }
+
+  const existingWebFiles = await getExistingFiles(webRoutesDir);
+  for (const file of existingWebFiles) {
+    if (!expectedWebFiles.has(file)) {
+      const filePath = path.join(webRoutesDir, file);
+      await fs.unlink(filePath);
+      result.deleted.push(filePath);
+    }
+  }
+
+  // Write generated map
+  const mapPath = path.join(mapDir, "generated.map.json");
+  await Bun.write(mapPath, JSON.stringify(generatedMap, null, 2));
+
+  return result;
+}

package/src/generator/index.ts

@@ -0,0 +1,2 @@
+export * from "./generate";
+export * from "./templates";

package/src/generator/templates.ts

@@ -0,0 +1,45 @@
+import type { RouteSpec } from "../spec/schema";
+
+export function generateApiHandler(route: RouteSpec): string {
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+
+import type { Request } from "bun";
+
+export default function handler(req: Request, params: Record<string, string>): Response {
+  return Response.json({
+    status: "ok",
+    routeId: "${route.id}",
+    pattern: "${route.pattern}",
+    timestamp: new Date().toISOString(),
+  });
+}
+`;
+}
+
+export function generatePageComponent(route: RouteSpec): string {
+  const pageName = capitalize(route.id);
+  return `// Generated by Mandu - DO NOT EDIT DIRECTLY
+// Route ID: ${route.id}
+// Pattern: ${route.pattern}
+
+import React from "react";
+
+interface Props {
+  params: Record<string, string>;
+}
+
+export default function ${pageName}Page({ params }: Props): React.ReactElement {
+  return React.createElement("div", null,
+    React.createElement("h1", null, "${pageName} Page"),
+    React.createElement("p", null, "Route ID: ${route.id}"),
+    React.createElement("p", null, "Pattern: ${route.pattern}")
+  );
+}
+`;
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/src/guard/check.ts

@@ -0,0 +1,225 @@
+import { GUARD_RULES, FORBIDDEN_IMPORTS, type GuardViolation } from "./rules";
+import { verifyLock, computeHash } from "../spec/lock";
+import type { RoutesManifest } from "../spec/schema";
+import type { GeneratedMap } from "../generator/generate";
+import path from "path";
+import fs from "fs/promises";
+
+export interface GuardCheckResult {
+  passed: boolean;
+  violations: GuardViolation[];
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readFileContent(filePath: string): Promise<string | null> {
+  try {
+    return await Bun.file(filePath).text();
+  } catch {
+    return null;
+  }
+}
+
+// Rule 1: Spec hash mismatch
+export async function checkSpecHashMismatch(
+  manifest: RoutesManifest,
+  lockPath: string
+): Promise<GuardViolation | null> {
+  const result = await verifyLock(lockPath, manifest);
+
+  if (!result.valid) {
+    return {
+      ruleId: GUARD_RULES.SPEC_HASH_MISMATCH.id,
+      file: lockPath,
+      message: result.lockHash
+        ? `Spec 해시 불일치: lock(${result.lockHash.slice(0, 8)}...) != current(${result.currentHash.slice(0, 8)}...)`
+        : "spec.lock.json 파일이 없습니다",
+      suggestion: "bunx mandu spec-upsert를 실행하여 변경사항을 반영하세요",
+    };
+  }
+
+  return null;
+}
+
+// Rule 2: Generated file manual edit detection
+export async function checkGeneratedManualEdit(
+  rootDir: string,
+  generatedMap: GeneratedMap
+): Promise<GuardViolation[]> {
+  const violations: GuardViolation[] = [];
+
+  for (const [filePath, meta] of Object.entries(generatedMap.files)) {
+    const fullPath = path.join(rootDir, filePath);
+    const content = await readFileContent(fullPath);
+
+    if (!content) continue;
+
+    // Check if the "DO NOT EDIT" comment was removed or modified
+    if (!content.includes("Generated by Mandu - DO NOT EDIT DIRECTLY")) {
+      violations.push({
+        ruleId: GUARD_RULES.GENERATED_MANUAL_EDIT.id,
+        file: filePath,
+        message: `generated 파일이 수동으로 변경된 것으로 보입니다 (routeId: ${meta.routeId})`,
+        suggestion: "bunx mandu generate를 실행하여 파일을 재생성하세요",
+      });
+    }
+  }
+
+  return violations;
+}
+
+// Rule 3: Non-generated importing generated
+export async function checkInvalidGeneratedImport(
+  rootDir: string
+): Promise<GuardViolation[]> {
+  const violations: GuardViolation[] = [];
+
+  // Scan non-generated source files
+  const sourceDirs = [
+    path.join(rootDir, "packages"),
+    path.join(rootDir, "apps/server"),
+    path.join(rootDir, "apps/web"),
+  ];
+
+  for (const sourceDir of sourceDirs) {
+    const files = await scanTsFiles(sourceDir);
+
+    for (const file of files) {
+      // Skip generated directories
+      if (file.includes("/generated/") || file.includes("\\generated\\")) {
+        continue;
+      }
+
+      const content = await readFileContent(file);
+      if (!content) continue;
+
+      // Check for imports from generated directories
+      const importRegex = /import\s+.*from\s+['"](.*generated.*)['"]/g;
+      let match;
+
+      while ((match = importRegex.exec(content)) !== null) {
+        const relativePath = path.relative(rootDir, file);
+        violations.push({
+          ruleId: GUARD_RULES.INVALID_GENERATED_IMPORT.id,
+          file: relativePath,
+          message: `generated 파일 직접 import 금지: ${match[1]}`,
+          suggestion:
+            "generated 파일을 직접 import하지 말고, 런타임 레지스트리를 통해 접근하세요",
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+// Rule 4: Forbidden imports in generated files
+export async function checkForbiddenImportsInGenerated(
+  rootDir: string,
+  generatedMap: GeneratedMap
+): Promise<GuardViolation[]> {
+  const violations: GuardViolation[] = [];
+
+  for (const [filePath] of Object.entries(generatedMap.files)) {
+    const fullPath = path.join(rootDir, filePath);
+    const content = await readFileContent(fullPath);
+
+    if (!content) continue;
+
+    for (const forbidden of FORBIDDEN_IMPORTS) {
+      const importRegex = new RegExp(
+        `import\\s+.*from\\s+['"]${forbidden}['"]|require\\s*\\(\\s*['"]${forbidden}['"]\\s*\\)`,
+        "g"
+      );
+
+      if (importRegex.test(content)) {
+        violations.push({
+          ruleId: GUARD_RULES.FORBIDDEN_IMPORT_IN_GENERATED.id,
+          file: filePath,
+          message: `generated 파일에서 금지된 모듈 '${forbidden}' import 감지`,
+          suggestion: `'${forbidden}' 모듈 사용이 필요하면 slot 로직에서 처리하세요`,
+        });
+      }
+    }
+  }
+
+  return violations;
+}
+
+async function scanTsFiles(dir: string): Promise<string[]> {
+  const files: string[] = [];
+
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules" && entry.name !== "dist") {
+          const subFiles = await scanTsFiles(fullPath);
+          files.push(...subFiles);
+        }
+      } else if (entry.isFile() && (entry.name.endsWith(".ts") || entry.name.endsWith(".tsx"))) {
+        files.push(fullPath);
+      }
+    }
+  } catch {
+    // Directory doesn't exist or can't be read
+  }
+
+  return files;
+}
+
+export async function runGuardCheck(
+  manifest: RoutesManifest,
+  rootDir: string
+): Promise<GuardCheckResult> {
+  const violations: GuardViolation[] = [];
+
+  const lockPath = path.join(rootDir, "spec/spec.lock.json");
+  const mapPath = path.join(rootDir, "packages/core/map/generated.map.json");
+
+  // Rule 1
+  const hashViolation = await checkSpecHashMismatch(manifest, lockPath);
+  if (hashViolation) {
+    violations.push(hashViolation);
+  }
+
+  // Load generated map for other checks
+  let generatedMap: GeneratedMap | null = null;
+  if (await fileExists(mapPath)) {
+    try {
+      const mapContent = await Bun.file(mapPath).text();
+      generatedMap = JSON.parse(mapContent);
+    } catch {
+      // Map file corrupted or missing
+    }
+  }
+
+  if (generatedMap) {
+    // Rule 2
+    const editViolations = await checkGeneratedManualEdit(rootDir, generatedMap);
+    violations.push(...editViolations);
+
+    // Rule 4
+    const forbiddenViolations = await checkForbiddenImportsInGenerated(rootDir, generatedMap);
+    violations.push(...forbiddenViolations);
+  }
+
+  // Rule 3
+  const importViolations = await checkInvalidGeneratedImport(rootDir);
+  violations.push(...importViolations);
+
+  return {
+    passed: violations.length === 0,
+    violations,
+  };
+}

package/src/guard/index.ts

@@ -0,0 +1,2 @@
+export * from "./rules";
+export * from "./check";

package/src/guard/rules.ts

@@ -0,0 +1,37 @@
+export interface GuardViolation {
+  ruleId: string;
+  file: string;
+  message: string;
+  suggestion: string;
+}
+
+export interface GuardRule {
+  id: string;
+  name: string;
+  description: string;
+}
+
+export const GUARD_RULES: Record<string, GuardRule> = {
+  SPEC_HASH_MISMATCH: {
+    id: "SPEC_HASH_MISMATCH",
+    name: "Spec Hash Mismatch",
+    description: "spec.lock.json의 해시와 현재 spec이 일치하지 않습니다",
+  },
+  GENERATED_MANUAL_EDIT: {
+    id: "GENERATED_MANUAL_EDIT",
+    name: "Generated File Manual Edit",
+    description: "generated 파일이 수동으로 변경되었습니다",
+  },
+  INVALID_GENERATED_IMPORT: {
+    id: "INVALID_GENERATED_IMPORT",
+    name: "Invalid Generated Import",
+    description: "non-generated 파일에서 generated 파일을 직접 import 했습니다",
+  },
+  FORBIDDEN_IMPORT_IN_GENERATED: {
+    id: "FORBIDDEN_IMPORT_IN_GENERATED",
+    name: "Forbidden Import in Generated",
+    description: "generated 파일에서 금지된 모듈을 import 했습니다",
+  },
+};
+
+export const FORBIDDEN_IMPORTS = ["fs", "child_process", "cluster", "worker_threads"];

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./spec";
+export * from "./runtime";
+export * from "./generator";
+export * from "./guard";
+export * from "./report";

package/src/report/build.ts

@@ -0,0 +1,127 @@
+import type { GuardViolation } from "../guard/rules";
+import type { GuardCheckResult } from "../guard/check";
+import type { GenerateResult } from "../generator/generate";
+
+export interface ManuduReport {
+  status: "pass" | "fail";
+  timestamp: string;
+  guardViolations: GuardViolation[];
+  generateResult?: {
+    created: string[];
+    deleted: string[];
+    errors: string[];
+  };
+  nextActions: string[];
+}
+
+export function buildGuardReport(checkResult: GuardCheckResult): ManuduReport {
+  const nextActions: string[] = [];
+
+  if (!checkResult.passed) {
+    const hasHashMismatch = checkResult.violations.some(
+      (v) => v.ruleId === "SPEC_HASH_MISMATCH"
+    );
+    const hasManualEdit = checkResult.violations.some(
+      (v) => v.ruleId === "GENERATED_MANUAL_EDIT"
+    );
+    const hasInvalidImport = checkResult.violations.some(
+      (v) => v.ruleId === "INVALID_GENERATED_IMPORT"
+    );
+    const hasForbiddenImport = checkResult.violations.some(
+      (v) => v.ruleId === "FORBIDDEN_IMPORT_IN_GENERATED"
+    );
+
+    if (hasHashMismatch) {
+      nextActions.push("bunx mandu spec-upsert --file spec/routes.manifest.json");
+    }
+    if (hasManualEdit) {
+      nextActions.push("bunx mandu generate");
+    }
+    if (hasInvalidImport) {
+      nextActions.push("generated 파일 직접 import를 제거하고 런타임 레지스트리 사용");
+    }
+    if (hasForbiddenImport) {
+      nextActions.push("generated 파일에서 금지된 import를 제거하고 slot에서 처리");
+    }
+  }
+
+  return {
+    status: checkResult.passed ? "pass" : "fail",
+    timestamp: new Date().toISOString(),
+    guardViolations: checkResult.violations,
+    nextActions,
+  };
+}
+
+export function buildGenerateReport(generateResult: GenerateResult): ManuduReport {
+  const nextActions: string[] = [];
+
+  if (!generateResult.success) {
+    nextActions.push("generate 오류를 수정하고 다시 실행하세요");
+  } else {
+    if (generateResult.created.length > 0) {
+      nextActions.push("bunx mandu guard로 검증 실행");
+    }
+  }
+
+  return {
+    status: generateResult.success ? "pass" : "fail",
+    timestamp: new Date().toISOString(),
+    guardViolations: [],
+    generateResult: {
+      created: generateResult.created,
+      deleted: generateResult.deleted,
+      errors: generateResult.errors,
+    },
+    nextActions,
+  };
+}
+
+export async function writeReport(report: ManuduReport, outputPath: string): Promise<void> {
+  await Bun.write(outputPath, JSON.stringify(report, null, 2));
+}
+
+export function printReportSummary(report: ManuduReport): void {
+  const statusIcon = report.status === "pass" ? "✅" : "❌";
+  console.log(`\n${statusIcon} Guard Status: ${report.status.toUpperCase()}`);
+  console.log(`📅 Timestamp: ${report.timestamp}`);
+
+  if (report.guardViolations.length > 0) {
+    console.log(`\n⚠️  Violations (${report.guardViolations.length}):`);
+    for (const violation of report.guardViolations) {
+      console.log(`  [${violation.ruleId}] ${violation.file}`);
+      console.log(`    └─ ${violation.message}`);
+      console.log(`    💡 ${violation.suggestion}`);
+    }
+  }
+
+  if (report.generateResult) {
+    if (report.generateResult.created.length > 0) {
+      console.log(`\n📁 Created (${report.generateResult.created.length}):`);
+      for (const file of report.generateResult.created) {
+        console.log(`  + ${file}`);
+      }
+    }
+    if (report.generateResult.deleted.length > 0) {
+      console.log(`\n🗑️  Deleted (${report.generateResult.deleted.length}):`);
+      for (const file of report.generateResult.deleted) {
+        console.log(`  - ${file}`);
+      }
+    }
+    if (report.generateResult.errors.length > 0) {
+      console.log(`\n❌ Errors (${report.generateResult.errors.length}):`);
+      for (const error of report.generateResult.errors) {
+        console.log(`  ! ${error}`);
+      }
+    }
+  }
+
+  if (report.nextActions.length > 0) {
+    console.log(`\n🎯 Next Actions:`);
+    for (const action of report.nextActions) {
+      console.log(`  → ${action}`);
+    }
+  }
+
+  console.log("");
+}

package/src/report/index.ts

@@ -0,0 +1 @@
+export * from "./build";

package/src/runtime/index.ts

@@ -0,0 +1,3 @@
+export * from "./ssr";
+export * from "./router";
+export * from "./server";

package/src/runtime/router.ts

@@ -0,0 +1,65 @@
+import type { RouteSpec } from "../spec/schema";
+
+export interface MatchResult {
+  route: RouteSpec;
+  params: Record<string, string>;
+}
+
+export class Router {
+  private routes: RouteSpec[] = [];
+  private compiledPatterns: Map<string, { regex: RegExp; paramNames: string[] }> = new Map();
+
+  constructor(routes: RouteSpec[] = []) {
+    this.setRoutes(routes);
+  }
+
+  setRoutes(routes: RouteSpec[]): void {
+    this.routes = routes;
+    this.compiledPatterns.clear();
+
+    for (const route of routes) {
+      this.compiledPatterns.set(route.id, this.compilePattern(route.pattern));
+    }
+  }
+
+  private compilePattern(pattern: string): { regex: RegExp; paramNames: string[] } {
+    const paramNames: string[] = [];
+
+    const regexStr = pattern
+      .replace(/\//g, "\\/")
+      .replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (_, paramName) => {
+        paramNames.push(paramName);
+        return "([^/]+)";
+      });
+
+    const regex = new RegExp(`^${regexStr}$`);
+    return { regex, paramNames };
+  }
+
+  match(pathname: string): MatchResult | null {
+    for (const route of this.routes) {
+      const compiled = this.compiledPatterns.get(route.id);
+      if (!compiled) continue;
+
+      const match = pathname.match(compiled.regex);
+      if (match) {
+        const params: Record<string, string> = {};
+        compiled.paramNames.forEach((name, index) => {
+          params[name] = match[index + 1];
+        });
+
+        return { route, params };
+      }
+    }
+
+    return null;
+  }
+
+  getRoutes(): RouteSpec[] {
+    return [...this.routes];
+  }
+}
+
+export function createRouter(routes: RouteSpec[] = []): Router {
+  return new Router(routes);
+}

package/src/runtime/server.ts

@@ -0,0 +1,139 @@
+import type { Server } from "bun";
+import type { RoutesManifest } from "../spec/schema";
+import { Router } from "./router";
+import { renderSSR } from "./ssr";
+import React from "react";
+
+export interface ServerOptions {
+  port?: number;
+  hostname?: string;
+}
+
+export interface ManduServer {
+  server: Server;
+  router: Router;
+  stop: () => void;
+}
+
+export type ApiHandler = (req: Request, params: Record<string, string>) => Response | Promise<Response>;
+export type PageLoader = () => Promise<{ default: React.ComponentType<{ params: Record<string, string> }> }>;
+
+export interface AppContext {
+  routeId: string;
+  url: string;
+  params: Record<string, string>;
+}
+
+type RouteComponent = (props: { params: Record<string, string> }) => React.ReactElement;
+type CreateAppFn = (context: AppContext) => React.ReactElement;
+
+// Registry
+const apiHandlers: Map<string, ApiHandler> = new Map();
+const pageLoaders: Map<string, PageLoader> = new Map();
+const routeComponents: Map<string, RouteComponent> = new Map();
+let createAppFn: CreateAppFn | null = null;
+
+export function registerApiHandler(routeId: string, handler: ApiHandler): void {
+  apiHandlers.set(routeId, handler);
+}
+
+export function registerPageLoader(routeId: string, loader: PageLoader): void {
+  pageLoaders.set(routeId, loader);
+}
+
+export function registerRouteComponent(routeId: string, component: RouteComponent): void {
+  routeComponents.set(routeId, component);
+}
+
+export function setCreateApp(fn: CreateAppFn): void {
+  createAppFn = fn;
+}
+
+// Default createApp implementation
+function defaultCreateApp(context: AppContext): React.ReactElement {
+  const Component = routeComponents.get(context.routeId);
+
+  if (!Component) {
+    return React.createElement("div", null,
+      React.createElement("h1", null, "404 - Route Not Found"),
+      React.createElement("p", null, `Route ID: ${context.routeId}`)
+    );
+  }
+
+  return React.createElement(Component, { params: context.params });
+}
+
+async function handleRequest(req: Request, router: Router): Promise<Response> {
+  const url = new URL(req.url);
+  const pathname = url.pathname;
+
+  const match = router.match(pathname);
+
+  if (!match) {
+    return new Response("Not Found", { status: 404 });
+  }
+
+  const { route, params } = match;
+
+  if (route.kind === "api") {
+    const handler = apiHandlers.get(route.id);
+    if (!handler) {
+      return Response.json({ error: "Handler not found" }, { status: 500 });
+    }
+    return handler(req, params);
+  }
+
+  if (route.kind === "page") {
+    const loader = pageLoaders.get(route.id);
+    if (loader) {
+      try {
+        const module = await loader();
+        registerRouteComponent(route.id, module.default);
+      } catch (error) {
+        console.error(`Failed to load page module for ${route.id}:`, error);
+        return new Response("Internal Server Error", { status: 500 });
+      }
+    }
+
+    const appCreator = createAppFn || defaultCreateApp;
+    const app = appCreator({
+      routeId: route.id,
+      url: req.url,
+      params,
+    });
+
+    return renderSSR(app, { title: `${route.id} - Mandu` });
+  }
+
+  return new Response("Unknown route kind", { status: 500 });
+}
+
+export function startServer(manifest: RoutesManifest, options: ServerOptions = {}): ManduServer {
+  const { port = 3000, hostname = "localhost" } = options;
+
+  const router = new Router(manifest.routes);
+
+  const server = Bun.serve({
+    port,
+    hostname,
+    fetch: (req) => handleRequest(req, router),
+  });
+
+  console.log(`🥟 Mandu server running at http://${hostname}:${port}`);
+
+  return {
+    server,
+    router,
+    stop: () => server.stop(),
+  };
+}
+
+// Clear registries (useful for testing)
+export function clearRegistry(): void {
+  apiHandlers.clear();
+  pageLoaders.clear();
+  routeComponents.clear();
+  createAppFn = null;
+}
+
+export { apiHandlers, pageLoaders, routeComponents };

package/src/runtime/ssr.ts

@@ -0,0 +1,38 @@
+import { renderToString } from "react-dom/server";
+import type { ReactElement } from "react";
+
+export interface SSROptions {
+  title?: string;
+  lang?: string;
+}
+
+export function renderToHTML(element: ReactElement, options: SSROptions = {}): string {
+  const { title = "Mandu App", lang = "ko" } = options;
+  const content = renderToString(element);
+
+  return `<!doctype html>
+<html lang="${lang}">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title}</title>
+</head>
+<body>
+  <div id="root">${content}</div>
+</body>
+</html>`;
+}
+
+export function createHTMLResponse(html: string, status: number = 200): Response {
+  return new Response(html, {
+    status,
+    headers: {
+      "Content-Type": "text/html; charset=utf-8",
+    },
+  });
+}
+
+export function renderSSR(element: ReactElement, options: SSROptions = {}): Response {
+  const html = renderToHTML(element, options);
+  return createHTMLResponse(html);
+}

package/src/spec/index.ts

@@ -0,0 +1,3 @@
+export * from "./schema";
+export * from "./load";
+export * from "./lock";

package/src/spec/load.ts

@@ -0,0 +1,76 @@
+import { RoutesManifest, type RoutesManifest as RoutesManifestType } from "./schema";
+import { ZodError } from "zod";
+
+export interface LoadResult {
+  success: boolean;
+  data?: RoutesManifestType;
+  errors?: string[];
+}
+
+export function formatZodError(error: ZodError): string[] {
+  return error.errors.map((e) => {
+    const path = e.path.length > 0 ? `[${e.path.join(".")}] ` : "";
+    return `${path}${e.message}`;
+  });
+}
+
+export async function loadManifest(filePath: string): Promise<LoadResult> {
+  try {
+    const file = Bun.file(filePath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      return {
+        success: false,
+        errors: [`파일을 찾을 수 없습니다: ${filePath}`],
+      };
+    }
+
+    const content = await file.text();
+    let json: unknown;
+
+    try {
+      json = JSON.parse(content);
+    } catch {
+      return {
+        success: false,
+        errors: ["JSON 파싱 실패: 올바른 JSON 형식이 아닙니다"],
+      };
+    }
+
+    const result = RoutesManifest.safeParse(json);
+
+    if (!result.success) {
+      return {
+        success: false,
+        errors: formatZodError(result.error),
+      };
+    }
+
+    return {
+      success: true,
+      data: result.data,
+    };
+  } catch (error) {
+    return {
+      success: false,
+      errors: [`예상치 못한 오류: ${error instanceof Error ? error.message : String(error)}`],
+    };
+  }
+}
+
+export function validateManifest(data: unknown): LoadResult {
+  const result = RoutesManifest.safeParse(data);
+
+  if (!result.success) {
+    return {
+      success: false,
+      errors: formatZodError(result.error),
+    };
+  }
+
+  return {
+    success: true,
+    data: result.data,
+  };
+}

package/src/spec/lock.ts

@@ -0,0 +1,56 @@
+import { createHash } from "crypto";
+import type { RoutesManifest } from "./schema";
+
+export interface SpecLock {
+  routesHash: string;
+  updatedAt: string;
+}
+
+export function computeHash(manifest: RoutesManifest): string {
+  const content = JSON.stringify(manifest, null, 2);
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export async function readLock(lockPath: string): Promise<SpecLock | null> {
+  try {
+    const file = Bun.file(lockPath);
+    const exists = await file.exists();
+
+    if (!exists) {
+      return null;
+    }
+
+    const content = await file.text();
+    return JSON.parse(content) as SpecLock;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeLock(lockPath: string, manifest: RoutesManifest): Promise<SpecLock> {
+  const lock: SpecLock = {
+    routesHash: computeHash(manifest),
+    updatedAt: new Date().toISOString(),
+  };
+
+  await Bun.write(lockPath, JSON.stringify(lock, null, 2));
+  return lock;
+}
+
+export async function verifyLock(
+  lockPath: string,
+  manifest: RoutesManifest
+): Promise<{ valid: boolean; currentHash: string; lockHash: string | null }> {
+  const currentHash = computeHash(manifest);
+  const lock = await readLock(lockPath);
+
+  if (!lock) {
+    return { valid: false, currentHash, lockHash: null };
+  }
+
+  return {
+    valid: lock.routesHash === currentHash,
+    currentHash,
+    lockHash: lock.routesHash,
+  };
+}

package/src/spec/schema.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+
+export const RouteKind = z.enum(["page", "api"]);
+export type RouteKind = z.infer<typeof RouteKind>;
+
+export const RouteSpec = z
+  .object({
+    id: z.string().min(1, "id는 필수입니다"),
+    pattern: z.string().startsWith("/", "pattern은 /로 시작해야 합니다"),
+    kind: RouteKind,
+    module: z.string().min(1, "module 경로는 필수입니다"),
+    componentModule: z.string().optional(),
+  })
+  .refine(
+    (route) => {
+      if (route.kind === "page" && !route.componentModule) {
+        return false;
+      }
+      return true;
+    },
+    {
+      message: "kind가 'page'인 경우 componentModule은 필수입니다",
+      path: ["componentModule"],
+    }
+  );
+
+export type RouteSpec = z.infer<typeof RouteSpec>;
+
+export const RoutesManifest = z
+  .object({
+    version: z.number().int().positive(),
+    routes: z.array(RouteSpec),
+  })
+  .refine(
+    (manifest) => {
+      const ids = manifest.routes.map((r) => r.id);
+      const uniqueIds = new Set(ids);
+      return ids.length === uniqueIds.size;
+    },
+    {
+      message: "route id는 중복될 수 없습니다",
+      path: ["routes"],
+    }
+  )
+  .refine(
+    (manifest) => {
+      const patterns = manifest.routes.map((r) => r.pattern);
+      const uniquePatterns = new Set(patterns);
+      return patterns.length === uniquePatterns.size;
+    },
+    {
+      message: "route pattern은 중복될 수 없습니다",
+      path: ["routes"],
+    }
+  );
+
+export type RoutesManifest = z.infer<typeof RoutesManifest>;