Mandu Framework Core
Runtime, FS Routes, Guard, Bundler, Contract, Filling
English | 한국어
## Installation ```bash bun add @mandujs/core ``` > Typically used through `@mandujs/cli`. Direct usage is for advanced use cases. ## Quick Start ### Basic API Handler (Filling) ```typescript import { Mandu } from "@mandujs/core"; export default Mandu.filling() .guard((ctx) => { if (!ctx.get("user")) return ctx.unauthorized("Login required"); }) .get(async (ctx) => { const users = await db.users.findMany(); return ctx.ok({ data: users }); }) .post(async (ctx) => { const body = await ctx.body<{ name: string }>(); const user = await db.users.create({ data: body }); return ctx.created({ data: user }); }); ``` ### Type-Safe Contract ```typescript import { Mandu } from "@mandujs/core"; import { z } from "zod"; const userContract = Mandu.contract({ request: { GET: { query: z.object({ id: z.string() }) }, POST: { body: z.object({ name: z.string() }) } }, response: { 200: z.object({ data: z.any() }), 400: z.object({ error: z.string() }) } }); const handlers = Mandu.handler(userContract, { GET: (ctx) => ({ data: fetchUser(ctx.query.id) }), POST: (ctx) => ({ data: createUser(ctx.body) }) }); ``` --- ## Module Overview ``` @mandujs/core ├── router/ # FS Routes - file-system based routing ├── guard/ # Mandu Guard - architecture enforcement │ ├── healing # Self-Healing Guard with auto-fix │ ├── decision-memory # ADR storage (RFC-001) │ ├── semantic-slots # Constraint validation (RFC-001) │ └── negotiation # AI-Framework dialog (RFC-001) ├── runtime/ # Server, SSR, streaming ├── filling/ # Handler chain API (Mandu.filling()) ├── contract/ # Type-safe API contracts ├── content/ # Content Layer - build-time content loading 🆕 │ └── loaders # file(), glob(), api() loaders ├── bundler/ # Client bundling, HMR ├── client/ # Island hydration, client router ├── brain/ # Doctor, Watcher, Architecture analyzer ├── change/ # Transaction & history └── spec/ # Manifest schema & validation ``` --- ## FS Routes File-system based routing system. ```typescript import { scanRoutes, generateManifest, watchFSRoutes } from "@mandujs/core/router"; // Scan routes from app/ directory const result = await scanRoutes("/path/to/project"); console.log(result.routes); // Generate manifest const { manifest } = await generateManifest("/path/to/project", { outputPath: ".mandu/manifest.json" }); // Watch for changes const watcher = await watchFSRoutes("/path/to/project", { onChange: (result) => console.log("Routes updated!", result.routes.length) }); ``` ### Route Patterns ```typescript import { pathToPattern, parseSegments } from "@mandujs/core/router"; // Convert path to URL pattern pathToPattern("users/[id]/posts"); // → "/users/:id/posts" pathToPattern("docs/[...slug]"); // → "/docs/:slug*" pathToPattern("(auth)/login"); // → "/login" (group ignored) // Parse segments parseSegments("[id]"); // → [{ type: "dynamic", name: "id" }] parseSegments("[...slug]"); // → [{ type: "catch-all", name: "slug" }] ``` --- ## Mandu Guard Real-time architecture enforcement with preset support. ```typescript import { createGuardWatcher, checkDirectory, getPreset, listPresets } from "@mandujs/core/guard"; // One-time check const report = await checkDirectory( { preset: "mandu" }, process.cwd() ); console.log(`Violations: ${report.totalViolations}`); // Real-time watching const watcher = createGuardWatcher({ config: { preset: "mandu", srcDir: "src" }, rootDir: process.cwd(), onViolation: (v) => console.log(`${v.filePath}: ${v.ruleDescription}`), }); watcher.start(); // List available presets listPresets().forEach(p => console.log(p.name, p.description)); ``` ### Presets (6) | Preset | Layers | Use Case | |--------|--------|----------| | `mandu` | client/*, shared/(contracts, types, utils/*, schema, env), server/* | Fullstack (default) | | `fsd` | app, pages, widgets, features, entities, shared | Frontend | | `clean` | api, application, domain, infra, shared | Backend | | `hexagonal` | adapters, ports, application, domain | DDD | | `atomic` | pages, templates, organisms, molecules, atoms | UI | | `cqrs` | commands, queries, events, dto, application, domain | Event-sourced apps | ### AST-based Analysis ```typescript import { extractImportsAST, analyzeModuleAST } from "@mandujs/core/guard"; // Extract imports with AST (more accurate than regex) const imports = extractImportsAST(code); // → [{ path: "./utils", type: "static", line: 1, namedImports: ["foo"] }] // Full module analysis const analysis = analyzeModuleAST(code, "src/features/user/api.ts"); ``` ### Statistics & Trends ```typescript import { createScanRecord, addScanRecord, analyzeTrend, generateGuardMarkdownReport } from "@mandujs/core/guard"; // Save scan for trend analysis const record = createScanRecord(report, "mandu"); await addScanRecord(rootDir, record); // Analyze improvement trend const trend = analyzeTrend(records, 7); // 7 days console.log(trend.trend); // "improving" | "stable" | "degrading" // Generate reports const markdown = generateGuardMarkdownReport(report, trend); ``` ### Self-Healing Guard (RFC-001) 🆕 ```typescript import { checkWithHealing, healAll, explainRule } from "@mandujs/core/guard"; // Detect violations with fix suggestions const result = await checkWithHealing({ preset: "mandu" }, process.cwd()); // Auto-fix all fixable violations if (result.items.length > 0) { const healResult = await healAll(result); console.log(`Fixed: ${healResult.fixed}, Failed: ${healResult.failed}`); } // Explain any rule const explanation = explainRule("layer-dependency"); console.log(explanation.description, explanation.examples); ``` ### Decision Memory (RFC-001) 🆕 ```typescript import { searchDecisions, saveDecision, checkConsistency, getCompactArchitecture } from "@mandujs/core/guard"; // Search past decisions const results = await searchDecisions(rootDir, ["auth", "jwt"]); // Save new decision (ADR) await saveDecision(rootDir, { id: "ADR-002", title: "Use PostgreSQL", status: "accepted", context: "Need relational database", decision: "Use PostgreSQL with Drizzle ORM", consequences: ["Need to manage migrations"], tags: ["database", "orm"] }); // Check implementation consistency const consistency = await checkConsistency(rootDir); ``` ### Architecture Negotiation (RFC-001) 🆕 ```typescript import { negotiate, generateScaffold } from "@mandujs/core/guard"; // AI negotiates with framework before implementation const plan = await negotiate({ intent: "Add user authentication", requirements: ["JWT based", "Refresh tokens"], constraints: ["Use existing User model"] }, projectRoot); if (plan.approved) { // Generate scaffold files await generateScaffold(plan.structure, projectRoot); } ``` --- ## Filling API Handler chain for business logic. ```typescript import { Mandu } from "@mandujs/core"; export default Mandu.filling() // Lifecycle hooks .onRequest((ctx) => { ctx.set("requestId", crypto.randomUUID()); }) // Guard (return Response to block) .guard((ctx) => { if (!ctx.get("user")) return ctx.unauthorized("Login required"); }) // Handlers .get(async (ctx) => { return ctx.ok({ users: await fetchUsers() }); }) .post(async (ctx) => { const body = await ctx.body(); return ctx.created({ user: await createUser(body) }); }) // After response .afterResponse((ctx) => { console.log("Request completed:", ctx.get("requestId")); }); ``` ### Middleware (Compose-style) ```typescript export default Mandu.filling() .middleware(async (ctx, next) => { console.log("before"); await next(); console.log("after"); }) .get((ctx) => ctx.ok({ ok: true })); ``` ### Context API | Method | Description | |--------|-------------| | `ctx.ok(data)` | 200 OK | | `ctx.created(data)` | 201 Created | | `ctx.noContent()` | 204 No Content | | `ctx.error(message)` | 400 Bad Request | | `ctx.unauthorized(message)` | 401 Unauthorized | | `ctx.forbidden(message)` | 403 Forbidden | | `ctx.notFound(message)` | 404 Not Found | | `ctx.fail(message)` | 500 Internal Server Error | | `ctx.body