@mandujs/core 0.19.0 → 0.19.2

package/src/plugins/hooks.ts

@@ -0,0 +1,64 @@
+/**
+ * CLI Lifecycle Hook System
+ *
+ * Lightweight hook runner for build/dev/start lifecycle events.
+ * Hooks defined in mandu.config.ts run first, then plugin hooks
+ * in registration order. Each hook is isolated -- one failure
+ * does not block subsequent hooks.
+ */
+
+export interface ManduHooks {
+  onBeforeBuild?: () => void | Promise<void>;
+  onAfterBuild?: (result: { success: boolean; duration: number }) => void | Promise<void>;
+  onDevStart?: (info: { port: number; hostname: string }) => void | Promise<void>;
+  onDevStop?: () => void | Promise<void>;
+  onRouteChange?: (info: { routeId: string; pattern: string; kind: string }) => void | Promise<void>;
+  onBeforeStart?: () => void | Promise<void>;
+}
+
+export interface ManduPlugin {
+  name: string;
+  hooks?: Partial<ManduHooks>;
+  setup?: (config: Record<string, unknown>) => void | Promise<void>;
+}
+
+/**
+ * Run a named lifecycle hook across config-level hooks and plugins.
+ *
+ * Execution order:
+ *   1. Config hook (from mandu.config.ts `hooks` field)
+ *   2. Plugin hooks (from `plugins[].hooks`, in array order)
+ *
+ * Each invocation is wrapped in try/catch so a single failing hook
+ * does not prevent the remaining hooks from executing.
+ */
+export async function runHook<K extends keyof ManduHooks>(
+  hookName: K,
+  plugins: ManduPlugin[],
+  configHooks: Partial<ManduHooks> | undefined,
+  ...args: Parameters<NonNullable<ManduHooks[K]>>
+): Promise<void> {
+  const invoke = async (
+    label: string,
+    fn: ((...a: unknown[]) => void | Promise<void>) | undefined,
+  ) => {
+    if (!fn) return;
+    try {
+      await fn(...args);
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error(`[plugin] ${hookName} failed in ${label}: ${msg}`);
+    }
+  };
+
+  // Config-level hook runs first
+  await invoke("config", configHooks?.[hookName] as ((...a: unknown[]) => void | Promise<void>) | undefined);
+
+  // Plugin hooks run in registration order
+  for (const plugin of plugins) {
+    await invoke(
+      plugin.name,
+      plugin.hooks?.[hookName] as ((...a: unknown[]) => void | Promise<void>) | undefined,
+    );
+  }
+}

package/src/plugins/index.ts

@@ -36,3 +36,6 @@ export type {
   McpToolPlugin,
   MiddlewarePlugin,
 } from "./types";
+
+export { runHook } from "./hooks";
+export type { ManduPlugin, ManduHooks } from "./hooks";

package/src/plugins/types.ts

@@ -334,6 +334,11 @@ export interface McpToolPlugin {
    */
   inputSchema: Record<string, unknown>;
 
+  /**
+   * MCP tool annotations (hints for clients)
+   */
+  annotations?: Record<string, unknown>;
+
   /**
    * 도구 실행
    */

package/src/report/build.ts

@@ -18,9 +18,6 @@ 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"
     );
@@ -31,9 +28,6 @@ export function buildGuardReport(checkResult: GuardCheckResult): ManuduReport {
       (v) => v.ruleId === "FORBIDDEN_IMPORT_IN_GENERATED"
     );
 
-    if (hasHashMismatch) {
-      nextActions.push("bunx mandu routes generate");
-    }
     if (hasManualEdit) {
       nextActions.push("bunx mandu generate");
     }

package/src/resource/__tests__/backward-compat.test.ts

@@ -43,7 +43,6 @@ describe("Backward Compatibility - Path Structure", () => {
     expect(paths.typesDir).toBeDefined();
     expect(paths.mapDir).toBeDefined();
     expect(paths.manifestPath).toBeDefined();
-    expect(paths.lockPath).toBeDefined();
   });
 
   test("should not conflict with existing generated directories", async () => {

package/src/router/fs-patterns.ts

@@ -62,6 +62,15 @@ export function parseSegment(segment: string): RouteSegment {
     };
   }
 
+  // Slot / Parallel route: @name
+  if (segment.startsWith("@")) {
+    return {
+      raw: segment,
+      type: "slot",
+      paramName: segment.slice(1), // @modal → "modal"
+    };
+  }
+
   // Static segment
   return {
     raw: segment,
@@ -123,7 +132,7 @@ export function segmentsToPattern(segments: RouteSegment[]): string {
   }
 
   const parts = segments
-    .filter((seg) => seg.type !== "group") // 그룹은 URL에 포함 안 됨
+    .filter((seg) => seg.type !== "group" && seg.type !== "slot") // 그룹과 slot(@name)은 URL에 포함 안 됨
     .map((seg) => segmentToPatternPart(seg));
 
   return "/" + parts.join("/");
@@ -272,6 +281,7 @@ export function generateRouteId(relativePath: string): string {
 const SEGMENT_PRIORITY: Record<SegmentType, number> = {
   static: 0,
   group: 1, // 그룹은 URL에 영향 없으므로 static과 동일
+  slot: 1, // slot(@name)도 URL에 영향 없음 — layout named prop으로 전달
   dynamic: 2,
   catchAll: 3,
   optionalCatchAll: 4,

package/src/router/fs-routes.ts

@@ -6,7 +6,7 @@
  * @module router/fs-routes
  */
 
-import { writeFile, mkdir } from "fs/promises";
+import { writeFile, readFile, mkdir } from "fs/promises";
 import { join, dirname } from "path";
 import type { RoutesManifest, RouteSpec } from "../spec/schema";
 import type { FSRouteConfig, FSScannerConfig, ScanResult } from "./fs-types";
@@ -50,33 +50,38 @@ export interface GenerateOptions {
 /**
  * FSRouteConfig를 RouteSpec으로 변환
  */
+/** Normalize path separators to forward slashes for cross-platform consistency */
+function normalizePath(p: string): string {
+  return p.replace(/\\/g, "/");
+}
+
 export function fsRouteToRouteSpec(fsRoute: FSRouteConfig): RouteSpec {
   const base = {
     id: fsRoute.id,
     pattern: fsRoute.pattern,
-    module: fsRoute.module,
+    module: normalizePath(fsRoute.module),
   };
 
   if (fsRoute.kind === "page") {
     const pageRoute: RouteSpec = {
       ...base,
       kind: "page" as const,
-      componentModule: fsRoute.componentModule ?? "",
+      componentModule: normalizePath(fsRoute.componentModule ?? ""),
       ...(fsRoute.clientModule
         ? {
-            clientModule: fsRoute.clientModule,
+            clientModule: normalizePath(fsRoute.clientModule),
             hydration: fsRoute.hydration ?? {
               strategy: "island" as const,
-              priority: "visible" as const,
+              priority: "immediate" as const,
               preload: false,
             },
           }
         : {}),
       ...(fsRoute.layoutChain && fsRoute.layoutChain.length > 0
-        ? { layoutChain: fsRoute.layoutChain }
+        ? { layoutChain: fsRoute.layoutChain.map(normalizePath) }
         : {}),
-      ...(fsRoute.loadingModule ? { loadingModule: fsRoute.loadingModule } : {}),
-      ...(fsRoute.errorModule ? { errorModule: fsRoute.errorModule } : {}),
+      ...(fsRoute.loadingModule ? { loadingModule: normalizePath(fsRoute.loadingModule) } : {}),
+      ...(fsRoute.errorModule ? { errorModule: normalizePath(fsRoute.errorModule) } : {}),
     };
     return pageRoute;
   }
@@ -115,19 +120,54 @@ export async function resolveAutoLinks(
   manifest: RoutesManifest,
   rootDir: string
 ): Promise<void> {
+  // Slot = server-side data loader (.slot.ts/.tsx)
+  // Client = client-side island module (.client.ts/.tsx) — sets clientModule, NOT slotModule
+  const slotExtensions = [".slot.ts", ".slot.tsx"];
+  const clientExtensions = [".client.ts", ".client.tsx"];
+
   await Promise.all(
     manifest.routes.map(async (route) => {
-      const slotPath = join(rootDir, "spec", "slots", `${route.id}.slot.ts`);
       const contractPath = join(rootDir, "spec", "contracts", `${route.id}.contract.ts`);
 
-      const [slotExists, contractExists] = await Promise.all([
-        Bun.file(slotPath).exists(),
+      // Check all extensions in parallel
+      const slotChecks = slotExtensions.map(async (ext) => {
+        const path = join(rootDir, "spec", "slots", `${route.id}${ext}`);
+        return (await Bun.file(path).exists()) ? ext : null;
+      });
+      const clientChecks = clientExtensions.map(async (ext) => {
+        const path = join(rootDir, "spec", "slots", `${route.id}${ext}`);
+        return (await Bun.file(path).exists()) ? ext : null;
+      });
+
+      const [contractExists, ...allResults] = await Promise.all([
         Bun.file(contractPath).exists(),
+        ...slotChecks,
+        ...clientChecks,
       ]);
 
-      if (slotExists) {
-        route.slotModule = `spec/slots/${route.id}.slot.ts`;
+      const slotResults = allResults.slice(0, slotExtensions.length);
+      const clientResults = allResults.slice(slotExtensions.length);
+
+      // Set slotModule for .slot.ts(x) files (server data loaders)
+      const matchedSlotExt = slotResults.find((ext) => ext !== null);
+      if (matchedSlotExt) {
+        route.slotModule = `spec/slots/${route.id}${matchedSlotExt}`;
+      }
+
+      // Set clientModule for .client.ts(x) files (island hydration) — only if not already set
+      const matchedClientExt = clientResults.find((ext) => ext !== null);
+      if (matchedClientExt && !route.clientModule) {
+        route.clientModule = `spec/slots/${route.id}${matchedClientExt}`;
+        // Also set default hydration config if not present
+        if (!route.hydration) {
+          route.hydration = {
+            strategy: "island" as const,
+            priority: "immediate" as const,
+            preload: false,
+          };
+        }
       }
+
       if (contractExists) {
         route.contractModule = `spec/contracts/${route.id}.contract.ts`;
       }
@@ -189,10 +229,34 @@ export async function generateManifest(
   // Auto-linking: spec/slots/, spec/contracts/ 자동 연결
   await resolveAutoLinks(manifest, rootDir);
 
-  // .mandu/ 디렉토리에 매니페스트 저장
+  // 기존 매니페스트에서 사용자 설정 필드 보존 (clientModule, hydration 등)
   const outputPath = options.outputPath ?? ".mandu/routes.manifest.json";
   const outputFullPath = join(rootDir, outputPath);
   await mkdir(dirname(outputFullPath), { recursive: true });
+
+  try {
+    const existingRaw = await readFile(outputFullPath, "utf-8");
+    const existingManifest = JSON.parse(existingRaw) as RoutesManifest;
+    if (existingManifest.routes) {
+      const existingMap = new Map(
+        existingManifest.routes.map((r) => [r.id, r])
+      );
+      for (const route of manifest.routes) {
+        const prev = existingMap.get(route.id);
+        if (!prev) continue;
+        // 사용자가 설정한 clientModule/hydration 보존
+        if (prev.clientModule && !route.clientModule) {
+          route.clientModule = prev.clientModule;
+        }
+        if (prev.hydration && !route.hydration) {
+          route.hydration = prev.hydration;
+        }
+      }
+    }
+  } catch {
+    // 기존 매니페스트가 없으면 무시
+  }
+
   await writeFile(outputFullPath, JSON.stringify(manifest, null, 2), "utf-8");
 
   return {

package/src/router/fs-scanner.ts

@@ -241,7 +241,7 @@ export class FSScanner {
       const pattern = segmentsToPattern(file.segments);
       const patternShape = getPatternShape(pattern);
       const routeId = generateRouteId(file.relativePath);
-      const modulePath = join(this.config.routesDir, file.relativePath);
+      const modulePath = join(this.config.routesDir, file.relativePath).replace(/\\/g, "/");
 
       // 중복 패턴 체크
       const existingRoute = patternMap.get(pattern);
@@ -288,7 +288,7 @@ export class FSScanner {
 
       if (islands?.[0]) {
         // 우선순위: 명시적 island 파일
-        clientModule = join(this.config.routesDir, islands[0].relativePath);
+        clientModule = join(this.config.routesDir, islands[0].relativePath).replace(/\\/g, "/");
 
         // SSR shell + island placeholder 패턴은 hydration mismatch 위험이 매우 높으므로 에러로 처리
         if (pageFileContent && this.hasHydrationShellMismatchRisk(pageFileContent, islands[0].relativePath)) {

package/src/router/fs-types.ts

@@ -20,7 +20,8 @@ export type SegmentType =
   | "dynamic" // 동적 세그먼트 (예: "[slug]")
   | "catchAll" // Catch-all 세그먼트 (예: "[...path]")
   | "optionalCatchAll" // Optional catch-all (예: "[[...path]]")
-  | "group"; // 라우트 그룹 (예: "(marketing)")
+  | "group" // 라우트 그룹 (예: "(marketing)")
+  | "slot"; // Named slot / Parallel route (예: "@modal")
 
 /**
  * 파싱된 라우트 세그먼트

package/src/runtime/adapter-bun.ts

@@ -0,0 +1,62 @@
+/**
+ * Mandu Bun Adapter (기본 어댑터)
+ * Bun.serve() 기반 서버 생성
+ */
+
+import type { ManduAdapter, AdapterOptions, AdapterServer } from "./adapter";
+import { startServer, type ManduServer } from "./server";
+
+/**
+ * Bun 어댑터 (기본)
+ *
+ * @example
+ * ```typescript
+ * // mandu.config.ts
+ * import { adapterBun } from "@mandujs/core";
+ *
+ * export default {
+ *   adapter: adapterBun(),
+ * };
+ * ```
+ */
+export function adapterBun(): ManduAdapter {
+  return {
+    name: "adapter-bun",
+
+    createServer(options: AdapterOptions): AdapterServer {
+      let manduServer: ManduServer | null = null;
+
+      return {
+        async fetch(req: Request): Promise<Response> {
+          if (!manduServer) {
+            return new Response("Server not started", { status: 503 });
+          }
+          // 내부 서버로 프록시
+          const url = new URL(req.url);
+          const targetUrl = `http://localhost:${manduServer.server.port}${url.pathname}${url.search}`;
+          return globalThis.fetch(new Request(targetUrl, req));
+        },
+
+        async listen(port: number, hostname?: string) {
+          manduServer = startServer(options.manifest, {
+            ...options.serverOptions,
+            port,
+            hostname,
+            rootDir: options.rootDir,
+            bundleManifest: options.bundleManifest,
+          });
+
+          return {
+            port: manduServer.server.port ?? port,
+            hostname: hostname ?? "localhost",
+          };
+        },
+
+        async close() {
+          manduServer?.stop();
+          manduServer = null;
+        },
+      };
+    },
+  };
+}

package/src/runtime/adapter.ts

@@ -0,0 +1,47 @@
+/**
+ * Mandu Adapter Interface
+ * 런타임 중립적 서버 어댑터 추상화
+ */
+
+import type { RoutesManifest } from "../spec/schema";
+import type { BundleManifest } from "../bundler/types";
+import type { ServerOptions } from "./server";
+
+// ========== Types ==========
+
+export interface AdapterOptions {
+  manifest: RoutesManifest;
+  bundleManifest?: BundleManifest;
+  rootDir: string;
+  serverOptions: ServerOptions;
+}
+
+export interface AdapterServer {
+  /** fetch handler (Web Fetch API — 런타임 중립) */
+  fetch: (request: Request) => Promise<Response>;
+  /** 서버 시작 */
+  listen(port: number, hostname?: string): Promise<{ port: number; hostname: string }>;
+  /** 서버 중지 */
+  close(): Promise<void>;
+}
+
+/**
+ * Mandu Adapter 인터페이스
+ *
+ * @example
+ * ```typescript
+ * // mandu.config.ts
+ * import adapterBun from "@mandujs/adapter-bun";
+ *
+ * export default {
+ *   adapter: adapterBun(),
+ * };
+ * ```
+ */
+export interface ManduAdapter {
+  name: string;
+  /** 빌드 타임: 배포 산출물 생성 (SSG, 서버리스 번들 등) */
+  build?(options: AdapterOptions): Promise<void>;
+  /** 런타임: 서버 인스턴스 생성 */
+  createServer(options: AdapterOptions): AdapterServer;
+}