@mandujs/core 0.9.37 → 0.9.38

package/README.md

@@ -6,7 +6,7 @@
 
 <p align="center">
   <strong>Mandu Framework Core</strong><br/>
-  Spec, Generator, Guard, Runtime, Filling
+  Runtime, FS Routes, Guard, Bundler, Contract, Filling
 </p>
 
 <p align="center">
@@ -21,170 +21,456 @@ bun add @mandujs/core
 
 > Typically used through `@mandujs/cli`. Direct usage is for advanced use cases.
 
-## Module Structure
+## 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
-├── spec/      # Spec schema and loading
-├── generator/ # Code generation
-├── guard/     # Architecture checking and auto-correction
-├── runtime/   # Server and router
-└── report/    # Guard report generation
+├── router/      # FS Routes - file-system based routing
+├── guard/       # Mandu Guard - architecture enforcement
+├── runtime/     # Server, SSR, streaming
+├── filling/     # Handler chain API (Mandu.filling())
+├── contract/    # Type-safe API contracts
+├── bundler/     # Client bundling, HMR
+├── client/      # Island hydration, client router
+├── brain/       # Doctor, Watcher, Architecture analyzer
+├── change/      # Transaction & history
+└── spec/        # Manifest schema & validation
 ```
 
-## Spec Module
+---
+
+## FS Routes
 
-Route manifest schema definition and loading.
+File-system based routing system.
 
 ```typescript
-import { loadManifest, RoutesManifest, RouteSpec } from "@mandujs/core";
+import { scanRoutes, generateManifest, watchFSRoutes } from "@mandujs/core/router";
 
-// Load and validate manifest
-const result = await loadManifest("spec/routes.manifest.json");
+// Scan routes from app/ directory
+const result = await scanRoutes("/path/to/project");
+console.log(result.routes);
 
-if (result.success && result.data) {
-  const manifest: RoutesManifest = result.data;
-  manifest.routes.forEach((route: RouteSpec) => {
-    console.log(route.id, route.pattern, route.kind);
-  });
-}
+// 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)
+});
 ```
 
-### Lock File
+### Route Patterns
 
 ```typescript
-import { writeLock, readLock } from "@mandujs/core";
+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" }]
+```
+
+---
 
-// Write lock file
-const lock = await writeLock("spec/spec.lock.json", manifest);
-console.log(lock.routesHash);
+## Mandu Guard
 
-// Read lock file
-const existing = await readLock("spec/spec.lock.json");
+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));
 ```
 
-## Generator Module
+### Presets
+
+| Preset | Layers | Use Case |
+|--------|--------|----------|
+| `mandu` | app, pages, widgets, features, entities, api, application, domain, infra, core, shared | 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 |
 
-Spec-based code generation.
+### AST-based Analysis
 
 ```typescript
-import { generateRoutes, GenerateResult } from "@mandujs/core";
+import { extractImportsAST, analyzeModuleAST } from "@mandujs/core/guard";
 
-const result: GenerateResult = await generateRoutes(manifest, "./");
+// Extract imports with AST (more accurate than regex)
+const imports = extractImportsAST(code);
+// → [{ path: "./utils", type: "static", line: 1, namedImports: ["foo"] }]
 
-console.log("Created:", result.created);
-console.log("Skipped:", result.skipped);  // Existing slot files
+// Full module analysis
+const analysis = analyzeModuleAST(code, "src/features/user/api.ts");
 ```
 
-### Template Functions
+### Statistics & Trends
 
 ```typescript
 import {
-  generateApiHandler,
-  generateApiHandlerWithSlot,
-  generateSlotLogic,
-  generatePageComponent
-} from "@mandujs/core";
+  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);
+```
+
+---
 
-// Generate API handler
-const code = generateApiHandler(route);
+## 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"));
+  });
+```
 
-// API handler with slot
-const codeWithSlot = generateApiHandlerWithSlot(route);
+### Middleware (Compose-style)
 
-// Slot logic file
-const slotCode = generateSlotLogic(route);
+```typescript
+export default Mandu.filling()
+  .middleware(async (ctx, next) => {
+    console.log("before");
+    await next();
+    console.log("after");
+  })
+  .get((ctx) => ctx.ok({ ok: true }));
 ```
 
-## Guard Module
+### 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<T>()` | Parse request body |
+| `ctx.params` | Route parameters |
+| `ctx.query` | Query parameters |
+| `ctx.set(key, value)` | Store in context |
+| `ctx.get<T>(key)` | Retrieve from context |
+
+---
+
+## Contract API
 
-Architecture rule checking and auto-correction.
+Type-safe API contracts with Zod.
 
 ```typescript
-import {
-  runGuardCheck,
-  runAutoCorrect,
-  GuardResult,
-  GuardViolation
-} from "@mandujs/core";
+import { Mandu } from "@mandujs/core";
+import { z } from "zod";
+
+// Define contract
+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() })
+  }
+});
 
-// Run check
-const result: GuardResult = await runGuardCheck(manifest, "./");
+// Create typed handlers
+const handlers = Mandu.handler(userContract, {
+  GET: (ctx) => ({ data: fetchUser(ctx.query.id) }),
+  POST: (ctx) => ({ data: createUser(ctx.body) })
+});
 
-if (!result.passed) {
-  result.violations.forEach((v: GuardViolation) => {
-    console.log(`${v.rule}: ${v.message}`);
-  });
+// Type-safe client
+const client = Mandu.client(userContract, { baseUrl: "/api/users" });
+const result = await client.GET({ query: { id: "123" } });
+```
 
-  // Run auto-correction
-  const corrected = await runAutoCorrect(result.violations, manifest, "./");
-  console.log("Fixed:", corrected.steps);
-  console.log("Remaining violations:", corrected.remainingViolations);
-}
+---
+
+## Runtime
+
+Server and SSR.
+
+```typescript
+import { startServer, registerApiHandler, registerPageLoader } from "@mandujs/core";
+
+// Register handlers
+registerApiHandler("getUsers", async (req) => ({ users: [] }));
+registerPageLoader("home", () => import("./pages/Home"));
+
+// Start server
+const server = startServer(manifest, { port: 3000 });
+```
+
+### Streaming SSR
+
+```typescript
+import { renderToStream } from "@mandujs/core";
+
+const stream = await renderToStream(<App />, {
+  bootstrapScripts: ["/client.js"],
+  onError: (err) => console.error(err)
+});
+```
+
+---
+
+## Client (Islands & Router)
+
+### Island Hydration
+
+```typescript
+import { createIsland, partial } from "@mandujs/core/client";
+
+// Define island
+const CounterIsland = createIsland({
+  name: "counter",
+  component: Counter,
+  priority: "visible"
+});
+
+// Partial (smaller than island)
+const ButtonPartial = partial("submit-btn", SubmitButton);
 ```
 
-### Guard Rules
+### Client Router
 
-| Rule ID | Description | Auto-correctable |
-|---------|-------------|------------------|
-| `SPEC_HASH_MISMATCH` | Spec and lock hash mismatch | ✅ |
-| `GENERATED_MANUAL_EDIT` | Manual edit to generated file | ✅ |
-| `HANDLER_NOT_FOUND` | Handler file not found | ❌ |
-| `COMPONENT_NOT_FOUND` | Component file not found | ❌ |
-| `SLOT_NOT_FOUND` | Slot file not found | ✅ |
+```typescript
+import { useRouter, useParams, Link, NavLink } from "@mandujs/core/client";
+
+function Navigation() {
+  const router = useRouter();
+  const params = useParams();
+
+  return (
+    <nav>
+      <NavLink href="/users" activeClass="active">Users</NavLink>
+      <button onClick={() => router.push("/settings")}>Settings</button>
+    </nav>
+  );
+}
+```
 
-## Runtime Module
+---
 
-Server startup and routing.
+## Brain (AI Assistant)
+
+Doctor and architecture analyzer.
 
 ```typescript
 import {
-  startServer,
-  registerApiHandler,
-  registerPageLoader
+  initializeBrain,
+  getBrain,
+  analyzeViolations,
+  initializeArchitectureAnalyzer
 } from "@mandujs/core";
 
-// Register API handler
-registerApiHandler("getUsers", async (req) => {
-  return { users: [] };
+// Initialize
+await initializeBrain();
+const brain = getBrain();
+
+// Analyze violations with suggestions
+const analysis = await analyzeViolations(violations, { useLLM: true });
+console.log(analysis.patches); // Suggested fixes
+
+// Architecture analyzer
+const analyzer = initializeArchitectureAnalyzer(rootDir);
+const locationResult = await analyzer.checkLocation({ path: "src/features/user.ts" });
+const importResult = await analyzer.checkImports({
+  sourceFile: "src/features/user.ts",
+  imports: ["../entities/product"]
 });
+```
 
-// Register page loader
-registerPageLoader("homePage", () => import("./pages/Home"));
+---
 
-// Start server
-const server = startServer(manifest, { port: 3000 });
+## Bundler
+
+Client bundling with HMR.
+
+```typescript
+import { buildClientBundle, createDevBundler } from "@mandujs/core/bundler";
 
-// Stop
-server.stop();
+// Production build
+const result = await buildClientBundle(manifest, {
+  outDir: ".mandu/client",
+  minify: true,
+  sourcemap: true
+});
+
+// Development with HMR
+const devBundler = await createDevBundler(manifest, {
+  rootDir: process.cwd(),
+  isDev: true
+});
 ```
 
-## Report Module
+---
 
-Guard result report generation.
+## Transaction API
+
+Atomic changes with rollback.
 
 ```typescript
-import { buildGuardReport } from "@mandujs/core";
+import { beginChange, commitChange, rollbackChange } from "@mandujs/core";
+
+// Start transaction
+const { changeId, snapshotId } = await beginChange(rootDir, "Add user API");
+
+// Make changes...
 
-const report = buildGuardReport(guardResult, lockPath);
-console.log(report);  // Formatted text report
+// Commit or rollback
+await commitChange(rootDir);
+// or
+await rollbackChange(rootDir);
 ```
 
+---
+
 ## Types
 
 ```typescript
 import type {
+  // Spec
   RoutesManifest,
   RouteSpec,
-  RouteKind,
-  SpecLock,
-  GuardResult,
-  GuardViolation,
-  GenerateResult,
-  AutoCorrectResult,
+
+  // Guard
+  GuardPreset,
+  GuardConfig,
+  Violation,
+  ViolationReport,
+
+  // Router
+  ScanResult,
+  FSRouteConfig,
+
+  // Contract
+  ContractDefinition,
+  ContractHandlers,
+
+  // Filling
+  ManduContext,
 } from "@mandujs/core";
 ```
 
+---
+
 ## Requirements
 
 - Bun >= 1.0.0
@@ -194,6 +480,7 @@ import type {
 ## Related Packages
 
 - [@mandujs/cli](https://www.npmjs.com/package/@mandujs/cli) - CLI tool
+- [@mandujs/mcp](https://www.npmjs.com/package/@mandujs/mcp) - MCP server for AI agents
 
 ## License
 

package/package.json

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

package/src/brain/doctor/index.ts

@@ -34,7 +34,7 @@ export {
   formatPatch,
   printDoctorReport,
   generateJsonReport,
-  generateMarkdownReport,
+  generateDoctorMarkdownReport,
   formatDoctorReport,
   type ReportFormat,
 } from "./reporter";

package/src/brain/doctor/reporter.ts

@@ -222,9 +222,9 @@ export function generateJsonReport(analysis: DoctorAnalysis): string {
 }
 
 /**
- * Generate a Markdown report
+ * Generate a Markdown report (Doctor Analysis)
  */
-export function generateMarkdownReport(analysis: DoctorAnalysis): string {
+export function generateDoctorMarkdownReport(analysis: DoctorAnalysis): string {
   const lines: string[] = [];
 
   lines.push("# 🩺 Mandu Doctor Report");
@@ -328,7 +328,7 @@ export function formatDoctorReport(
       return generateJsonReport(analysis);
 
     case "markdown":
-      return generateMarkdownReport(analysis);
+      return generateDoctorMarkdownReport(analysis);
 
     default:
       printDoctorReport(analysis);

package/src/guard/index.ts

@@ -169,7 +169,7 @@ export {
   loadStatistics,
   saveStatistics,
   addScanRecord,
-  generateMarkdownReport,
+  generateGuardMarkdownReport,
   generateHTMLReport,
   type ScanRecord,
   type StatisticsStore,

package/src/guard/statistics.ts

@@ -360,9 +360,9 @@ export async function addScanRecord(
 // ═══════════════════════════════════════════════════════════════════════════
 
 /**
- * 마크다운 리포트 생성
+ * 마크다운 리포트 생성 (Guard Report)
  */
-export function generateMarkdownReport(
+export function generateGuardMarkdownReport(
   report: ViolationReport,
   trend?: TrendAnalysis | null,
   layerStats?: LayerStatistics[]
@@ -499,7 +499,7 @@ export function generateHTMLReport(
   trend?: TrendAnalysis | null,
   layerStats?: LayerStatistics[]
 ): string {
-  const markdown = generateMarkdownReport(report, trend, layerStats);
+  const markdown = generateGuardMarkdownReport(report, trend, layerStats);
 
   // 간단한 마크다운 → HTML 변환
   let html = markdown

package/src/guard/types.ts

@@ -84,6 +84,9 @@ export interface GuardConfig {
   /** FS Routes 통합 */
   fsRoutes?: FSRoutesGuardConfig;
 
+  /** 실시간 출력 형식 */
+  realtimeOutput?: "console" | "agent" | "json";
+
   /** 캐시 사용 여부 (기본값: true) */
   cache?: boolean;
 
@@ -320,6 +323,7 @@ export const DEFAULT_GUARD_CONFIG: Required<Omit<GuardConfig, "preset" | "layers
     deepNesting: "info",
     crossSliceDependency: "warn",
   },
+  realtimeOutput: "console",
   cache: true,
   incremental: true,
   debounceMs: 100,

package/src/guard/watcher.ts

@@ -20,7 +20,11 @@ import type {
 import { WATCH_EXTENSIONS, DEFAULT_GUARD_CONFIG } from "./types";
 import { analyzeFile, shouldAnalyzeFile } from "./analyzer";
 import { validateFileAnalysis, detectCircularDependencies } from "./validator";
-import { printRealtimeViolation } from "./reporter";
+import {
+  printRealtimeViolation,
+  formatViolationForAgent,
+  formatViolationAsAgentJSON,
+} from "./reporter";
 import { getPreset } from "./presets";
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -119,12 +123,24 @@ export function createGuardWatcher(options: WatcherOptions): GuardWatcher {
       // 콜백 호출
       onFileAnalyzed?.(analysis, violations);
 
+      const realtimeOutput = config.realtimeOutput ?? DEFAULT_GUARD_CONFIG.realtimeOutput;
+
       // 위반 처리
       for (const violation of violations) {
         onViolation?.(violation);
 
         if (!silent) {
-          printRealtimeViolation(violation);
+          switch (realtimeOutput) {
+            case "agent":
+              console.log(formatViolationForAgent(violation, config.preset));
+              break;
+            case "json":
+              console.log(formatViolationAsAgentJSON(violation, config.preset));
+              break;
+            case "console":
+            default:
+              printRealtimeViolation(violation);
+          }
         }
       }
     } catch (error) {
@@ -239,7 +255,8 @@ export function createGuardWatcher(options: WatcherOptions): GuardWatcher {
       watcher.on("change", (path) => handleFileChange("change", resolve(rootDir, path)));
       watcher.on("unlink", (path) => handleFileChange("unlink", resolve(rootDir, path)));
 
-      if (!silent) {
+      const realtimeOutput = config.realtimeOutput ?? DEFAULT_GUARD_CONFIG.realtimeOutput;
+      if (!silent && realtimeOutput === "console") {
         console.log(`[Guard] 🛡️  Watching ${Array.from(scanRoots).join(", ")} for architecture violations...`);
       }
     },