@mandujs/core 0.54.1 → 0.54.3

package/src/kitchen/api/file-api.ts

@@ -229,14 +229,17 @@ export class FileAPI {
     for (const line of stdout.split("\n")) {
       if (!line.trim()) continue;
 
-      const statusCode = line.substring(0, 2);
-      const gitFilePath = line.substring(3).trim();
-      const filePath = this.getProjectRelativePath(gitFilePath, gitRoot);
-
-      changes.push({
-        filePath,
-        status: parseGitStatus(statusCode),
-      });
+      const statusCode = line.substring(0, 2);
+      const gitFilePath = line.substring(3).trim();
+      const filePath = this.getProjectRelativePath(gitFilePath, gitRoot);
+      if (!filePath || filePath === ".") {
+        continue;
+      }
+
+      changes.push({
+        filePath,
+        status: parseGitStatus(statusCode),
+      });
     }
 
     return changes;

package/src/resource/__tests__/schema.test.ts

@@ -108,15 +108,20 @@ describe("validateResourceDefinition", () => {
 });
 
 describe("getPluralName", () => {
-  test("should add 's' for simple pluralization", () => {
-    const result = getPluralName(userResourceFixture);
-    expect(result).toBe("users");
-  });
-
-  test("should use custom plural name if provided", () => {
-    const result = getPluralName(productResourceFixture);
-    expect(result).toBe("inventory");
-  });
+  test("should add 's' for simple pluralization", () => {
+    const result = getPluralName(userResourceFixture);
+    expect(result).toBe("users");
+  });
+
+  test("should use conservative English pluralization for common resource names", () => {
+    expect(getPluralName({ ...minimalResourceFixture, name: "party" })).toBe("parties");
+    expect(getPluralName({ ...minimalResourceFixture, name: "box" })).toBe("boxes");
+  });
+
+  test("should use custom plural name if provided", () => {
+    const result = getPluralName(productResourceFixture);
+    expect(result).toBe("inventory");
+  });
 
   test("should respect autoPlural: false", () => {
     const definition = {

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,103 @@
+import { describe, expect, it } from "bun:test";
+import React from "react";
+import { renderPageResponse } from "../page-render-response";
+import type { BundleManifest } from "../../bundler/types";
+
+const HYDRATED_MANIFEST: BundleManifest = {
+  version: 1,
+  buildTime: "2026-05-19T00:00:00.000Z",
+  env: "production",
+  bundles: {
+    home: {
+      js: "/.mandu/client/home.island.js",
+      dependencies: ["_runtime", "_react"],
+      priority: "visible",
+    },
+  },
+  shared: {
+    runtime: "/.mandu/client/_runtime.js",
+    vendor: "/.mandu/client/_react.js",
+    router: "/.mandu/client/_router.js",
+  },
+  importMap: {
+    imports: {
+      react: "/.mandu/client/_react.js",
+      "react-dom": "/.mandu/client/_react-dom.js",
+      "react-dom/client": "/.mandu/client/_react-dom-client.js",
+    },
+  },
+};
+
+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");
+  });
+
+  it("serializes non-streaming loaderData as the route server data exactly once", async () => {
+    const response = await renderPageResponse({
+      app: React.createElement("main", null, "hydrated-page"),
+      useStreaming: false,
+      title: "Hydrated Page",
+      headTags: "",
+      isDev: false,
+      routeId: "home",
+      routePattern: "/",
+      loaderData: { items: ["a", "b"] },
+      hydration: { strategy: "island", priority: "visible", preload: false },
+      bundleManifest: HYDRATED_MANIFEST,
+      transitions: false,
+      prefetch: false,
+      spa: false,
+      devtools: false,
+    });
+
+    const html = await response.text();
+    expect(html).toContain('"home":{"serverData":{"items":["a","b"]}');
+    expect(html).not.toContain('"serverData":{"home"');
+  });
+});

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"]);
+  });
+});