@mandujs/core 0.54.1 → 0.54.2

package/src/resource/generators/slot.ts

@@ -19,7 +19,7 @@ export function generateResourceSlot(definition: ResourceDefinition): string {
   const endpoints = getEnabledEndpoints(definition);
 
   // Generate endpoint handlers
-  const handlers = generateHandlers(definition, endpoints, pascalName);
+  const handlers = generateHandlers(definition, endpoints, pascalName, pluralName);
 
   return `// 🥟 Mandu Filling - ${resourceName} Resource
 // Pattern: /api/${pluralName}
@@ -46,32 +46,33 @@ ${handlers}
 /**
  * Generate handlers for enabled endpoints
  */
-function generateHandlers(
-  definition: ResourceDefinition,
-  endpoints: string[],
-  pascalName: string
-): string {
-  const handlers: string[] = [];
-
-  if (endpoints.includes("list")) {
-    handlers.push(generateListHandler(definition, pascalName));
-  }
-
-  if (endpoints.includes("get")) {
-    handlers.push(generateGetHandler(definition, pascalName));
-  }
-
-  if (endpoints.includes("create")) {
-    handlers.push(generateCreateHandler(definition, pascalName));
-  }
-
-  if (endpoints.includes("update")) {
-    handlers.push(generateUpdateHandler(definition, pascalName));
-  }
-
-  if (endpoints.includes("delete")) {
-    handlers.push(generateDeleteHandler(definition, pascalName));
-  }
+function generateHandlers(
+  definition: ResourceDefinition,
+  endpoints: string[],
+  pascalName: string,
+  pluralName: string
+): string {
+  const handlers: string[] = [];
+
+  if (endpoints.includes("list")) {
+    handlers.push(generateListHandler(pascalName, pluralName));
+  }
+
+  if (endpoints.includes("get")) {
+    handlers.push(generateGetHandler(pascalName, pluralName));
+  }
+
+  if (endpoints.includes("create")) {
+    handlers.push(generateCreateHandler(pascalName, pluralName));
+  }
+
+  if (endpoints.includes("update")) {
+    handlers.push(generateUpdateHandler(pascalName, pluralName));
+  }
+
+  if (endpoints.includes("delete")) {
+    handlers.push(generateDeleteHandler(pascalName, pluralName));
+  }
 
   return handlers.join("\n\n");
 }
@@ -79,16 +80,16 @@ function generateHandlers(
 /**
  * Generate LIST handler (GET /api/resources)
  */
-function generateListHandler(definition: ResourceDefinition, pascalName: string): string {
-  return `  // 📋 List ${pascalName}s
-  .get(async (ctx) => {
-    const input = await ctx.input(contract, "GET", ctx.params);
-    const { page, limit } = input;
-
-    // TODO: Implement database query
-    // const offset = (page - 1) * limit;
-    // const items = await db.select().from(${definition.name}s).limit(limit).offset(offset);
-    // const total = await db.select({ count: count() }).from(${definition.name}s);
+function generateListHandler(pascalName: string, pluralName: string): string {
+  return `  // 📋 List ${pascalName}s
+  .get(async (ctx) => {
+    const input = await ctx.input(contract, "GET", ctx.params);
+    const { page, limit } = input;
+
+    // TODO: Implement database query
+    // const offset = (page - 1) * limit;
+    // const items = await db.select().from(${pluralName}).limit(limit).offset(offset);
+    // const total = await db.select({ count: count() }).from(${pluralName});
 
     const mockData = {
       data: [], // Replace with actual data
@@ -106,14 +107,14 @@ function generateListHandler(definition: ResourceDefinition, pascalName: string)
 /**
  * Generate GET handler (GET /api/resources/:id)
  */
-function generateGetHandler(definition: ResourceDefinition, pascalName: string): string {
-  return `  // 📄 Get Single ${pascalName}
-  .get(async (ctx) => {
-    const { id } = ctx.params;
-
-    // TODO: Implement database query
-    // const item = await db.select().from(${definition.name}s).where(eq(${definition.name}s.id, id)).limit(1);
-    // if (!item) return ctx.notFound("${pascalName} not found");
+function generateGetHandler(pascalName: string, pluralName: string): string {
+  return `  // 📄 Get Single ${pascalName}
+  .get(async (ctx) => {
+    const { id } = ctx.params;
+
+    // TODO: Implement database query
+    // const item = await db.select().from(${pluralName}).where(eq(${pluralName}.id, id)).limit(1);
+    // if (!item) return ctx.notFound("${pascalName} not found");
 
     const mockData = {
       data: { id, message: "${pascalName} details" }, // Replace with actual data
@@ -126,13 +127,13 @@ function generateGetHandler(definition: ResourceDefinition, pascalName: string):
 /**
  * Generate CREATE handler (POST /api/resources)
  */
-function generateCreateHandler(definition: ResourceDefinition, pascalName: string): string {
-  return `  // ➕ Create ${pascalName}
-  .post(async (ctx) => {
-    const input = await ctx.input(contract, "POST", ctx.params);
-
-    // TODO: Implement database insertion
-    // const [created] = await db.insert(${definition.name}s).values(input).returning();
+function generateCreateHandler(pascalName: string, pluralName: string): string {
+  return `  // ➕ Create ${pascalName}
+  .post(async (ctx) => {
+    const input = await ctx.input(contract, "POST", ctx.params);
+
+    // TODO: Implement database insertion
+    // const [created] = await db.insert(${pluralName}).values(input).returning();
 
     const mockData = {
       data: { id: "new-id", ...input }, // Replace with actual created data
@@ -145,17 +146,17 @@ function generateCreateHandler(definition: ResourceDefinition, pascalName: strin
 /**
  * Generate UPDATE handler (PUT /api/resources/:id)
  */
-function generateUpdateHandler(definition: ResourceDefinition, pascalName: string): string {
-  return `  // ✏️ Update ${pascalName}
-  .put(async (ctx) => {
-    const { id } = ctx.params;
-    const input = await ctx.input(contract, "PUT", ctx.params);
-
-    // TODO: Implement database update
-    // const [updated] = await db.update(${definition.name}s)
-    //   .set(input)
-    //   .where(eq(${definition.name}s.id, id))
-    //   .returning();
+function generateUpdateHandler(pascalName: string, pluralName: string): string {
+  return `  // ✏️ Update ${pascalName}
+  .put(async (ctx) => {
+    const { id } = ctx.params;
+    const input = await ctx.input(contract, "PUT", ctx.params);
+
+    // TODO: Implement database update
+    // const [updated] = await db.update(${pluralName})
+    //   .set(input)
+    //   .where(eq(${pluralName}.id, id))
+    //   .returning();
     // if (!updated) return ctx.notFound("${pascalName} not found");
 
     const mockData = {
@@ -169,14 +170,14 @@ function generateUpdateHandler(definition: ResourceDefinition, pascalName: strin
 /**
  * Generate DELETE handler (DELETE /api/resources/:id)
  */
-function generateDeleteHandler(definition: ResourceDefinition, pascalName: string): string {
-  return `  // 🗑️ Delete ${pascalName}
-  .delete(async (ctx) => {
-    const { id } = ctx.params;
-
-    // TODO: Implement database deletion
-    // const deleted = await db.delete(${definition.name}s).where(eq(${definition.name}s.id, id));
-    // if (!deleted) return ctx.notFound("${pascalName} not found");
+function generateDeleteHandler(pascalName: string, pluralName: string): string {
+  return `  // 🗑️ Delete ${pascalName}
+  .delete(async (ctx) => {
+    const { id } = ctx.params;
+
+    // TODO: Implement database deletion
+    // const deleted = await db.delete(${pluralName}).where(eq(${pluralName}.id, id));
+    // if (!deleted) return ctx.notFound("${pascalName} not found");
 
     return ctx.output(contract, 200, { data: { message: "${pascalName} deleted" } });
   })`;

package/src/resource/schema.ts

@@ -237,19 +237,27 @@ function validateField(resourceName: string, fieldName: string, field: ResourceF
 /**
  * Get plural name for resource
  */
-export function getPluralName(definition: ResourceDefinition): string {
-  if (definition.options?.pluralName) {
-    return definition.options.pluralName;
-  }
-
-  if (definition.options?.autoPlural === false) {
-    return definition.name;
-  }
-
-  // Simple pluralization: add 's'
-  // TODO: Add more sophisticated pluralization rules if needed
-  return `${definition.name}s`;
-}
+export function getPluralName(definition: ResourceDefinition): string {
+  if (definition.options?.pluralName) {
+    return definition.options.pluralName;
+  }
+
+  if (definition.options?.autoPlural === false) {
+    return definition.name;
+  }
+
+  return pluralize(definition.name);
+}
+
+function pluralize(singular: string): string {
+  if (/[^aeiou]y$/i.test(singular)) {
+    return singular.slice(0, -1) + "ies";
+  }
+  if (/(?:s|x|z|ch|sh)$/i.test(singular)) {
+    return singular + "es";
+  }
+  return singular + "s";
+}
 
 /**
  * Get enabled endpoints

package/src/runtime/__tests__/devtools-adapter.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import type { RoutesManifest } from "../../spec/schema";
+import {
+  createRuntimeDevtoolsAdapter,
+  shouldRecordRuntimeRequest,
+  type RuntimeDevtoolsAdapter,
+} from "../devtools-adapter";
+
+const manifest: RoutesManifest = {
+  version: 1,
+  routes: [],
+};
+
+describe("runtime devtools adapter", () => {
+  let adapter: RuntimeDevtoolsAdapter | null = null;
+
+  afterEach(() => {
+    adapter?.stop();
+    adapter = null;
+  });
+
+  it("stays disabled outside dev mode", async () => {
+    adapter = createRuntimeDevtoolsAdapter({
+      isDev: false,
+      rootDir: process.cwd(),
+      manifest,
+      guardConfig: null,
+    });
+
+    expect(adapter.kitchen).toBeNull();
+    expect(adapter.dashboardPath).toBeNull();
+    const response = await adapter.handleRequest(
+      new Request("http://localhost:3000/__kitchen"),
+      "/__kitchen"
+    );
+    expect(response).toBeNull();
+  });
+
+  it("dispatches Kitchen requests in dev mode", async () => {
+    adapter = createRuntimeDevtoolsAdapter({
+      isDev: true,
+      rootDir: process.cwd(),
+      manifest,
+      guardConfig: null,
+    });
+
+    expect(adapter.kitchen).not.toBeNull();
+    expect(adapter.dashboardPath).toBe("/__kitchen");
+    await expect(
+      adapter.handleRequest(new Request("http://localhost:3000/api/ping"), "/api/ping")
+    ).resolves.toBeNull();
+
+    const response = await adapter.handleRequest(
+      new Request("http://localhost:3000/__kitchen"),
+      "/__kitchen"
+    );
+    expect(response?.status).toBe(200);
+    expect(await response?.text()).toContain("Mandu Kitchen");
+  });
+
+  it("keeps framework-internal request paths out of the Kitchen request log", () => {
+    expect(shouldRecordRuntimeRequest("/api/ping")).toBe(true);
+    expect(shouldRecordRuntimeRequest("/_mandu/heap")).toBe(true);
+    expect(shouldRecordRuntimeRequest("/.mandu/client/runtime.js")).toBe(false);
+    expect(shouldRecordRuntimeRequest("/__kitchen/api/events")).toBe(false);
+    expect(shouldRecordRuntimeRequest("/__mandu/events/recent")).toBe(false);
+  });
+});

package/src/runtime/__tests__/observability-lifecycle.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  INTERNAL_EVENTS_ENDPOINT,
+  createRuntimeObservabilityLifecycle,
+} from "../observability-lifecycle";
+import { eventBus } from "../../observability/event-bus";
+import {
+  resetTracer,
+  type Span,
+  type SpanExporter,
+} from "../../observability/tracing";
+
+class CaptureExporter implements SpanExporter {
+  readonly spans: Span[] = [];
+  export(spans: Span[]): void {
+    this.spans.push(...spans);
+  }
+}
+
+afterEach(() => {
+  resetTracer();
+});
+
+describe("runtime observability lifecycle", () => {
+  test("serves heap snapshots with perf data when exposed", async () => {
+    const lifecycle = createRuntimeObservabilityLifecycle({ isDev: true });
+    const response = lifecycle.handleEndpoint(
+      new Request("http://localhost/_mandu/heap"),
+      "/_mandu/heap"
+    );
+
+    expect(response?.status).toBe(200);
+    const body = await response!.json() as {
+      process: { heapUsed: number };
+      perf: unknown;
+    };
+    expect(body.process.heapUsed).toBeGreaterThan(0);
+    expect(body.perf).toBeDefined();
+  });
+
+  test("keeps metrics hidden in production unless explicitly enabled", () => {
+    const hidden = createRuntimeObservabilityLifecycle({ isDev: false });
+    const shown = createRuntimeObservabilityLifecycle({
+      isDev: false,
+      metricsEndpoint: true,
+    });
+
+    expect(hidden.handleEndpoint(new Request("http://localhost/_mandu/metrics"), "/_mandu/metrics")).toBeNull();
+    expect(shown.handleEndpoint(new Request("http://localhost/_mandu/metrics"), "/_mandu/metrics")?.status).toBe(200);
+  });
+
+  test("serves recent EventBus snapshots from the lifecycle endpoint", async () => {
+    const lifecycle = createRuntimeObservabilityLifecycle({ isDev: true });
+    const source = `observability-lifecycle-${Date.now()}`;
+    eventBus.emit({
+      type: "http",
+      severity: "info",
+      source,
+      message: "GET /observed 200",
+    });
+
+    const response = lifecycle.handleEndpoint(
+      new Request(`http://localhost${INTERNAL_EVENTS_ENDPOINT}/recent?source=${source}`),
+      `${INTERNAL_EVENTS_ENDPOINT}/recent`
+    );
+
+    expect(response?.status).toBe(200);
+    const body = await response!.json() as {
+      events: Array<{ source: string; message: string }>;
+    };
+    expect(body.events.some((event) => event.source === source)).toBe(true);
+  });
+
+  test("wraps requests in a root tracing span", async () => {
+    const exporter = new CaptureExporter();
+    const lifecycle = createRuntimeObservabilityLifecycle({
+      isDev: false,
+      tracing: {
+        enabled: true,
+        customExporter: exporter,
+      },
+    });
+    const incomingTraceId = "4bf92f3577b34da6a3ce929d0e0e4736";
+    const incomingSpanId = "00f067aa0ba902b7";
+    const response = await lifecycle.runRequest(
+      new Request("https://example.test/users", {
+        headers: {
+          traceparent: `00-${incomingTraceId}-${incomingSpanId}-01`,
+        },
+      }),
+      Date.now(),
+      "corr-1",
+      async () => new Response("created", { status: 201 })
+    );
+
+    expect(response.status).toBe(201);
+    expect(exporter.spans).toHaveLength(1);
+    expect(exporter.spans[0].traceId).toBe(incomingTraceId);
+    expect(exporter.spans[0].parentSpanId).toBe(incomingSpanId);
+    expect(exporter.spans[0].attributes["http.status_code"]).toBe(201);
+    expect(exporter.spans[0].status).toBe("ok");
+  });
+});

package/src/runtime/__tests__/page-render-response.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "bun:test";
+import React from "react";
+import { renderPageResponse } from "../page-render-response";
+
+describe("runtime page render response orchestration", () => {
+  it("pre-resolves async components on the non-streaming path", async () => {
+    async function AsyncPage() {
+      return React.createElement("main", null, "resolved-page");
+    }
+
+    const response = await renderPageResponse({
+      app: React.createElement(AsyncPage),
+      useStreaming: false,
+      title: "Async Page",
+      headTags: "",
+      isDev: false,
+      routeId: "page/async",
+      routePattern: "/async",
+      loaderData: { ok: true },
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    expect(response.status).toBe(200);
+    const html = await response.text();
+    expect(html).toContain("resolved-page");
+    expect(html).toContain("Async Page");
+  });
+
+  it("uses the streaming renderer when requested", async () => {
+    const response = await renderPageResponse({
+      app: React.createElement("main", null, "stream-page"),
+      useStreaming: true,
+      title: "Stream Page",
+      headTags: "",
+      isDev: false,
+      routeId: "page/stream",
+      routePattern: "/stream",
+      loaderData: { ok: true },
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.headers.get("X-Accel-Buffering")).toBe("no");
+    const html = await response.text();
+    expect(html).toContain("stream-page");
+    expect(html).toContain("Stream Page");
+  });
+});

package/src/runtime/__tests__/request-middleware.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "bun:test";
+import { defineMiddleware } from "../../middleware/define";
+import {
+  buildRequestMiddlewareChain,
+  runRequestMiddleware,
+} from "../request-middleware";
+
+const req = new Request("https://example.test/api/echo");
+
+describe("runtime request middleware wiring", () => {
+  it("keeps the no-middleware path unset for hot-path passthrough", () => {
+    expect(buildRequestMiddlewareChain(undefined)).toBeUndefined();
+    expect(buildRequestMiddlewareChain([])).toBeUndefined();
+  });
+
+  it("returns undefined when there is no chain or middleware is skipped", async () => {
+    let finalHits = 0;
+    const finalHandler = async (): Promise<Response> => {
+      finalHits++;
+      return new Response("ok");
+    };
+    const middlewareChain = buildRequestMiddlewareChain([
+      defineMiddleware({
+        name: "marker",
+        handler: async (_req, next) => next(),
+      }),
+    ]);
+
+    await expect(
+      runRequestMiddleware({ req, middlewareChain: undefined, finalHandler })
+    ).resolves.toBeUndefined();
+    await expect(
+      runRequestMiddleware({
+        req,
+        middlewareChain,
+        finalHandler,
+        skipMiddleware: true,
+      })
+    ).resolves.toBeUndefined();
+    expect(finalHits).toBe(0);
+  });
+
+  it("dispatches through the composed chain when configured", async () => {
+    const trace: string[] = [];
+    const middlewareChain = buildRequestMiddlewareChain([
+      defineMiddleware({
+        name: "outer",
+        handler: async (_req, next) => {
+          trace.push("before");
+          const response = await next();
+          trace.push("after");
+          return response;
+        },
+      }),
+    ]);
+
+    const response = await runRequestMiddleware({
+      req,
+      middlewareChain,
+      finalHandler: async () => {
+        trace.push("final");
+        return new Response("ok");
+      },
+    });
+
+    expect(response?.status).toBe(200);
+    expect(await response?.text()).toBe("ok");
+    expect(trace).toEqual(["before", "final", "after"]);
+  });
+});

package/src/runtime/devtools-adapter.ts

@@ -0,0 +1,68 @@
+import type { RoutesManifest } from "../spec/schema";
+import type { GuardConfig } from "../guard/types";
+import {
+  KITCHEN_PREFIX,
+  KitchenHandler,
+  recordRequest,
+  type RequestEntry,
+} from "../kitchen/kitchen-handler";
+
+export type RuntimeKitchenHandler = KitchenHandler;
+
+export interface RuntimeDevtoolsAdapter {
+  readonly kitchen: RuntimeKitchenHandler | null;
+  readonly dashboardPath: string | null;
+  start(): void;
+  stop(): void;
+  updateManifest(manifest: RoutesManifest): void;
+  handleRequest(req: Request, pathname: string): Promise<Response | null>;
+}
+
+export interface CreateRuntimeDevtoolsAdapterOptions {
+  isDev: boolean;
+  rootDir: string;
+  manifest: RoutesManifest;
+  guardConfig: GuardConfig | null;
+}
+
+export function createRuntimeDevtoolsAdapter(
+  options: CreateRuntimeDevtoolsAdapterOptions
+): RuntimeDevtoolsAdapter {
+  const kitchen = options.isDev
+    ? new KitchenHandler({
+      rootDir: options.rootDir,
+      manifest: options.manifest,
+      guardConfig: options.guardConfig,
+    })
+    : null;
+
+  return {
+    kitchen,
+    dashboardPath: kitchen ? KITCHEN_PREFIX : null,
+    start() {
+      if (kitchen) void kitchen.start();
+    },
+    stop() {
+      kitchen?.stop();
+    },
+    updateManifest(manifest: RoutesManifest) {
+      kitchen?.updateManifest(manifest);
+    },
+    async handleRequest(req: Request, pathname: string): Promise<Response | null> {
+      if (!kitchen || !pathname.startsWith(KITCHEN_PREFIX)) return null;
+      return await kitchen.handle(req, pathname);
+    },
+  };
+}
+
+export function shouldRecordRuntimeRequest(pathname: string): boolean {
+  return (
+    !pathname.startsWith("/.mandu/") &&
+    !pathname.startsWith(KITCHEN_PREFIX) &&
+    !pathname.startsWith("/__mandu/")
+  );
+}
+
+export function recordRuntimeRequest(entry: RequestEntry): void {
+  recordRequest(entry);
+}

package/src/runtime/escape.ts

@@ -3,12 +3,40 @@
  * <title>, <p> 등 텍스트 노드에 들어갈 문자열을 안전하게 처리.
  * 속성값과 달리 " ' 는 이스케이프 불필요.
  */
-export function escapeHtmlText(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;");
-}
+export function escapeHtmlText(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+/**
+ * Decode the small HTML entity set React can emit inside text metadata.
+ * Callers should still escape the returned string before writing HTML.
+ */
+export function decodeHtmlText(value: string): string {
+  return value.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos|#39);/gi, (match, entity: string) => {
+    const normalized = entity.toLowerCase();
+    if (normalized === "amp") return "&";
+    if (normalized === "lt") return "<";
+    if (normalized === "gt") return ">";
+    if (normalized === "quot") return '"';
+    if (normalized === "apos" || normalized === "#39") return "'";
+    if (normalized.startsWith("#x")) {
+      const codePoint = Number.parseInt(normalized.slice(2), 16);
+      return isValidCodePoint(codePoint) ? String.fromCodePoint(codePoint) : match;
+    }
+    if (normalized.startsWith("#")) {
+      const codePoint = Number.parseInt(normalized.slice(1), 10);
+      return isValidCodePoint(codePoint) ? String.fromCodePoint(codePoint) : match;
+    }
+    return match;
+  });
+}
+
+function isValidCodePoint(value: number): boolean {
+  return Number.isInteger(value) && value >= 0 && value <= 0x10ffff;
+}
 
 /**
  * HTML 속성값 이스케이프