@mandujs/core 0.34.2 → 0.35.0

package/package.json

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

package/src/config/mandu.ts

@@ -525,6 +525,34 @@ export interface ManduConfig {
     jobs?: CronDef[];
     disabled?: boolean;
   };
+  /**
+   * Production-grade OpenAPI endpoint.
+   *
+   * When enabled, the runtime serves the contracts-derived OpenAPI 3.0.3
+   * document at `<path>.json` / `<path>.yaml` (default base path
+   * `/__mandu/openapi`). The spec is materialized from `.mandu/openapi.json`
+   * (emitted by `mandu build`) on first request and cached for the
+   * lifetime of the server instance.
+   *
+   *   - `enabled` — default `false`. Do NOT leak the API surface on
+   *     every internet-facing deployment. Operators must opt in
+   *     explicitly, or set `MANDU_OPENAPI_ENABLED=1` in the environment
+   *     for a one-off probe without editing config.
+   *   - `path` — base URL path (with or without `.json` suffix). The
+   *     runtime appends `.json` / `.yaml` to serve each variant.
+   *     Default `/__mandu/openapi`.
+   *
+   * The response stamps `Cache-Control: public, max-age=0,
+   * must-revalidate` plus a SHA-256 ETag over the JSON body so CDNs and
+   * browsers revalidate cheaply after every deploy without serving
+   * stale specs.
+   *
+   * @see `docs/runtime/openapi.md`
+   */
+  openapi?: {
+    enabled?: boolean;
+    path?: string;
+  };
   /**
    * Phase 18.μ — first-class internationalization.
    *

package/src/config/validate.ts

@@ -384,6 +384,28 @@ const ObservabilityConfigSchema = z
   })
   .strict();
 
+/**
+ * Production OpenAPI endpoint config (strict).
+ *
+ * Default `enabled: false` — we validate permissive so `openapi: {}`
+ * still loads (equivalent to disabled). Operators explicitly set
+ * `enabled: true` OR export `MANDU_OPENAPI_ENABLED=1` to turn the
+ * endpoint on.
+ */
+const OpenApiConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    path: z
+      .string()
+      .min(1)
+      .refine(
+        (value) => value.startsWith("/"),
+        { message: "openapi.path must start with '/'" }
+      )
+      .optional(),
+  })
+  .strict();
+
 const AdapterConfigSchema = z.custom<ManduAdapter | undefined>(
   (value) =>
     value === undefined ||
@@ -591,6 +613,11 @@ export const ManduConfigSchema = z
     seo: SeoConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     observability: ObservabilityConfigSchema.default({}),
+    /**
+     * Production OpenAPI endpoint (default disabled). See
+     * {@link OpenApiConfigSchema} + `docs/runtime/openapi.md`.
+     */
+    openapi: OpenApiConfigSchema.optional(),
     /** Phase 18.ζ — ISR / tag-based cache invalidation. Optional. */
     cache: CacheConfigSchema.optional(),
     plugins: z.array(ManduPluginSchema).optional(),

package/src/openapi/generator.ts

@@ -542,16 +542,150 @@ export async function generateOpenAPIDocument(
   };
 }
 
+// ============================================
+// YAML Serialization
+// ============================================
+
+/**
+ * Quote a string value for YAML if required by the spec.
+ *
+ * Follows a conservative subset of YAML 1.2 rules: any scalar that
+ * could be confused for a YAML reserved word, a number, a boolean, a
+ * null, or that contains indicator characters must be double-quoted.
+ * Everything else is emitted as a plain scalar for maximum
+ * readability.
+ */
+function yamlScalar(value: unknown): string {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return ".nan";
+    return String(value);
+  }
+  if (typeof value === "string") {
+    // Quote strings that a YAML 1.2 parser would otherwise interpret
+    // as a non-string scalar (null/bool/number) or that contain indicator
+    // characters at positions where they are load-bearing.
+    //
+    // Conservative heuristic:
+    //   - empty string
+    //   - leading/trailing whitespace (would be silently trimmed)
+    //   - reserved scalars: null / true / false / yes / no / on / off (+ ~)
+    //   - parses cleanly as a YAML number (integer or float)
+    //   - contains a flow indicator (`[ ]`, `{ }`, `,`) or a comment start `#`
+    //   - contains `: ` (key separator) anywhere, or ends with `:`
+    //   - starts with an indicator char that would collide with block syntax:
+    //       `-` (sequence), `?` (mapping key), `&`/`*` (anchor/alias),
+    //       `!` (tag), `|`/`>` (block scalar), `'`/`"` / backtick / `%`/`@`
+    //   - embedded newline
+    const numericLike = /^[+-]?(\d+(\.\d+)?|\.\d+)([eE][+-]?\d+)?$/.test(value);
+    const reservedScalar = /^(~|null|true|false|yes|no|on|off)$/i.test(value);
+    const leadingIndicator = /^[-?&*!|>'"%@`]/.test(value);
+    const hasFlowOrComment = /[\[\]{},#]/.test(value);
+    const hasKeyLike = /:\s/.test(value) || /:$/.test(value);
+    const needsQuote =
+      value === "" ||
+      /^[\s]|[\s]$/.test(value) ||
+      reservedScalar ||
+      numericLike ||
+      leadingIndicator ||
+      hasFlowOrComment ||
+      hasKeyLike ||
+      value.includes("\n");
+    if (!needsQuote) return value;
+    // Use double quotes with JSON-style escaping (valid YAML subset).
+    return JSON.stringify(value);
+  }
+  // Fallback: JSON-stringify anything exotic.
+  return JSON.stringify(value);
+}
+
+function emitYAML(value: unknown, indent: number, lines: string[]): void {
+  const pad = "  ".repeat(indent);
+
+  if (value === null || typeof value !== "object") {
+    lines.push(`${pad}${yamlScalar(value)}`);
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      lines.push(`${pad}[]`);
+      return;
+    }
+    for (const item of value) {
+      if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+        const entries = Object.entries(item).filter(([, v]) => v !== undefined);
+        if (entries.length === 0) {
+          lines.push(`${pad}- {}`);
+          continue;
+        }
+        const [firstKey, firstVal] = entries[0];
+        lines.push(`${pad}- ${yamlKeyValue(firstKey, firstVal, indent + 1)}`);
+        for (let i = 1; i < entries.length; i++) {
+          const [k, v] = entries[i];
+          lines.push(`${pad}  ${yamlKeyValue(k, v, indent + 1)}`);
+        }
+      } else {
+        lines.push(`${pad}- ${yamlScalar(item).trimStart()}`);
+      }
+    }
+    return;
+  }
+
+  // Plain object.
+  const entries = Object.entries(value as Record<string, unknown>).filter(
+    ([, v]) => v !== undefined
+  );
+  if (entries.length === 0) {
+    lines.push(`${pad}{}`);
+    return;
+  }
+  for (const [k, v] of entries) {
+    if (v !== null && typeof v === "object") {
+      const isEmptyArray = Array.isArray(v) && v.length === 0;
+      const isEmptyObject = !Array.isArray(v) && Object.keys(v).length === 0;
+      if (isEmptyArray) {
+        lines.push(`${pad}${k}: []`);
+        continue;
+      }
+      if (isEmptyObject) {
+        lines.push(`${pad}${k}: {}`);
+        continue;
+      }
+      lines.push(`${pad}${k}:`);
+      emitYAML(v, indent + 1, lines);
+    } else {
+      lines.push(`${pad}${k}: ${yamlScalar(v)}`);
+    }
+  }
+}
+
+function yamlKeyValue(key: string, value: unknown, indent: number): string {
+  if (value === null || typeof value !== "object") {
+    return `${key}: ${yamlScalar(value)}`;
+  }
+  // Nested object / array: emit header + drop into recursion on subsequent lines.
+  // The caller pushes lines after this; we return the header only.
+  const tmp: string[] = [];
+  emitYAML(value, indent, tmp);
+  return `${key}:\n${tmp.join("\n")}`;
+}
+
 /**
- * Convert OpenAPI document to YAML string
+ * Convert an OpenAPI document to a YAML string.
+ *
+ * Emits a conservative YAML 1.2 subset — two-space indentation,
+ * double-quoted scalars where required, literal `[]` / `{}` for empty
+ * collections. Produces output that round-trips cleanly through
+ * Swagger UI, openapi-generator, and `yq`.
  */
 export function openAPIToYAML(doc: OpenAPIDocument): string {
-  // Simple YAML conversion (for production, use a proper YAML library)
-  return JSON.stringify(doc, null, 2)
-    .replace(/"/g, "")
-    .replace(/,$/gm, "")
-    .replace(/\[/g, "\n  - ")
-    .replace(/\]/g, "");
+  const lines: string[] = [];
+  emitYAML(doc, 0, lines);
+  // Terminate with a newline per POSIX text-file convention so `cat`
+  // doesn't elide the final byte.
+  return lines.join("\n") + "\n";
 }
 
 /**
@@ -560,3 +694,126 @@ export function openAPIToYAML(doc: OpenAPIDocument): string {
 export function openAPIToJSON(doc: OpenAPIDocument): string {
   return JSON.stringify(doc, null, 2);
 }
+
+// ============================================
+// Content hashing (for ETag)
+// ============================================
+
+/**
+ * Compute a SHA-256 hex digest of the serialized OpenAPI document.
+ *
+ * Uses `Bun.CryptoHasher` when available (zero allocations beyond the
+ * input buffer) and falls back to the WebCrypto API so the helper works
+ * under edge runtimes (Cloudflare Workers, Deno Deploy).
+ */
+export async function hashOpenAPIJSON(json: string): Promise<string> {
+  const bunGlobal = (globalThis as { Bun?: { CryptoHasher?: new (algo: string) => { update(input: string | Uint8Array): void; digest(encoding: "hex"): string } } }).Bun;
+  if (bunGlobal?.CryptoHasher) {
+    const hasher = new bunGlobal.CryptoHasher("sha256");
+    hasher.update(json);
+    return hasher.digest("hex");
+  }
+  // WebCrypto fallback (browser / edge runtimes).
+  const subtle = (globalThis as { crypto?: { subtle?: SubtleCrypto } }).crypto?.subtle;
+  if (subtle) {
+    const data = new TextEncoder().encode(json);
+    const buf = await subtle.digest("SHA-256", data);
+    return Array.from(new Uint8Array(buf))
+      .map((b) => b.toString(16).padStart(2, "0"))
+      .join("");
+  }
+  // Last-resort Node fallback.
+  const nodeCrypto = await import("node:crypto");
+  return nodeCrypto.createHash("sha256").update(json).digest("hex");
+}
+
+// ============================================
+// Build-time artifact emission
+// ============================================
+
+export interface OpenAPIArtifactPaths {
+  json: string;
+  yaml: string;
+}
+
+export interface OpenAPIArtifactResult {
+  /** OpenAPI 3.0.3 document serialized as JSON (two-space indented). */
+  json: string;
+  /** OpenAPI 3.0.3 document serialized as YAML. */
+  yaml: string;
+  /** SHA-256 hex digest of `json` — used as the runtime ETag. */
+  hash: string;
+  /** Absolute paths of the emitted artifacts (matches the dir argument). */
+  paths: OpenAPIArtifactPaths;
+  /** Number of route paths captured in the document. */
+  pathCount: number;
+}
+
+/**
+ * Generate and write both `openapi.json` and `openapi.yaml` under the
+ * given output directory. Returns the serialized bodies and the SHA-256
+ * hash so callers (e.g., `mandu build`) can log a stable artifact id
+ * and the runtime endpoint can skip re-hashing on boot.
+ *
+ * Safe to call repeatedly — the directory is created if absent and the
+ * existing files are overwritten atomically by `Bun.write`.
+ */
+export async function writeOpenAPIArtifacts(
+  manifest: RoutesManifest,
+  rootDir: string,
+  outDir: string,
+  options: Parameters<typeof generateOpenAPIDocument>[2] = {}
+): Promise<OpenAPIArtifactResult> {
+  const { mkdir } = await import("node:fs/promises");
+  const pathMod = await import("node:path");
+
+  const doc = await generateOpenAPIDocument(manifest, rootDir, options);
+  const json = openAPIToJSON(doc);
+  const yaml = openAPIToYAML(doc);
+  const hash = await hashOpenAPIJSON(json);
+
+  const absoluteDir = pathMod.isAbsolute(outDir)
+    ? outDir
+    : pathMod.join(rootDir, outDir);
+  await mkdir(absoluteDir, { recursive: true });
+
+  const jsonPath = pathMod.join(absoluteDir, "openapi.json");
+  const yamlPath = pathMod.join(absoluteDir, "openapi.yaml");
+  await Bun.write(jsonPath, json);
+  await Bun.write(yamlPath, yaml);
+
+  return {
+    json,
+    yaml,
+    hash,
+    paths: { json: jsonPath, yaml: yamlPath },
+    pathCount: Object.keys(doc.paths).length,
+  };
+}
+
+/**
+ * Read previously emitted OpenAPI artifacts from disk. Returns
+ * `null` when either file is missing so the caller can fall back to
+ * on-demand generation without logging a misleading error.
+ */
+export async function readOpenAPIArtifacts(
+  outDir: string,
+  rootDir: string
+): Promise<{ json: string; yaml: string; hash: string } | null> {
+  const pathMod = await import("node:path");
+  const absoluteDir = pathMod.isAbsolute(outDir)
+    ? outDir
+    : pathMod.join(rootDir, outDir);
+  const jsonPath = pathMod.join(absoluteDir, "openapi.json");
+  const yamlPath = pathMod.join(absoluteDir, "openapi.yaml");
+
+  const jsonFile = Bun.file(jsonPath);
+  const yamlFile = Bun.file(yamlPath);
+  if (!(await jsonFile.exists()) || !(await yamlFile.exists())) {
+    return null;
+  }
+  const json = await jsonFile.text();
+  const yaml = await yamlFile.text();
+  const hash = await hashOpenAPIJSON(json);
+  return { json, yaml, hash };
+}

package/src/openapi/openapi.test.ts

@@ -4,7 +4,19 @@
 
 import { describe, test, expect } from "bun:test";
 import { z } from "zod";
-import { zodToOpenAPISchema, openAPIToJSON } from "./generator";
+import {
+  generateOpenAPIDocument,
+  hashOpenAPIJSON,
+  openAPIToJSON,
+  openAPIToYAML,
+  readOpenAPIArtifacts,
+  writeOpenAPIArtifacts,
+  zodToOpenAPISchema,
+} from "./generator";
+import type { RoutesManifest } from "../spec/schema";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
 
 describe("zodToOpenAPISchema", () => {
   describe("primitive types", () => {
@@ -275,3 +287,206 @@ describe("Real-world contract conversion", () => {
     expect(result.properties!.pagination.properties!.page.minimum).toBe(1);
   });
 });
+
+// ============================================
+// End-to-end: manifest → OpenAPI → disk artifacts
+// ============================================
+
+/**
+ * Create a scratch project on disk with one API contract so we can
+ * exercise the full build pipeline (generate + write + read) without
+ * faking the dynamic import path.
+ */
+async function buildFixture(): Promise<{ rootDir: string; manifest: RoutesManifest; cleanup: () => Promise<void> }> {
+  const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-"));
+  const contractPath = "contracts/users.contract.ts";
+  const contractAbs = path.join(rootDir, contractPath);
+  await fs.mkdir(path.dirname(contractAbs), { recursive: true });
+  await fs.writeFile(
+    contractAbs,
+    `import { z } from "zod";
+export default {
+  name: "users",
+  description: "List / create users",
+  tags: ["users"],
+  request: {
+    GET: {
+      query: z.object({ limit: z.number().int().min(1).max(100).optional() }),
+    },
+    POST: {
+      body: z.object({
+        name: z.string().min(2),
+        email: z.string().email(),
+      }),
+    },
+  },
+  response: {
+    200: z.object({
+      items: z.array(z.object({ id: z.string().uuid(), name: z.string() })),
+    }),
+    201: z.object({ id: z.string().uuid() }),
+    400: z.object({ error: z.string() }),
+  },
+};
+`,
+    "utf-8"
+  );
+
+  const manifest: RoutesManifest = {
+    version: 1,
+    routes: [
+      {
+        id: "api/users",
+        pattern: "/api/users",
+        kind: "api",
+        module: contractPath,
+        contractModule: contractPath,
+        methods: ["GET", "POST"],
+      },
+    ],
+  };
+
+  return {
+    rootDir,
+    manifest,
+    cleanup: async () => {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    },
+  };
+}
+
+describe("generateOpenAPIDocument", () => {
+  test("should produce a valid OpenAPI 3.0.3 document with paths + methods + schemas", async () => {
+    const { rootDir, manifest, cleanup } = await buildFixture();
+    try {
+      const doc = await generateOpenAPIDocument(manifest, rootDir, {
+        title: "Users API",
+        version: "2.1.0",
+      });
+
+      expect(doc.openapi).toBe("3.0.3");
+      expect(doc.info.title).toBe("Users API");
+      expect(doc.info.version).toBe("2.1.0");
+
+      // The `/api/users` path should carry both GET and POST operations.
+      expect(doc.paths["/api/users"]).toBeDefined();
+      expect(doc.paths["/api/users"].get).toBeDefined();
+      expect(doc.paths["/api/users"].post).toBeDefined();
+
+      // GET query param `limit` should be captured.
+      const getParams = doc.paths["/api/users"].get!.parameters ?? [];
+      const limitParam = getParams.find((p) => p.name === "limit");
+      expect(limitParam).toBeDefined();
+      expect(limitParam!.in).toBe("query");
+
+      // POST body should be captured with JSON content.
+      const postBody = doc.paths["/api/users"].post!.requestBody;
+      expect(postBody).toBeDefined();
+      expect(postBody!.content["application/json"]).toBeDefined();
+
+      // Response schemas should be present.
+      const okResponse = doc.paths["/api/users"].get!.responses["200"];
+      expect(okResponse).toBeDefined();
+      expect(okResponse.content!["application/json"]).toBeDefined();
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe("hashOpenAPIJSON", () => {
+  test("should produce a deterministic 64-char hex digest", async () => {
+    const sample = JSON.stringify({ hello: "world" });
+    const hashA = await hashOpenAPIJSON(sample);
+    const hashB = await hashOpenAPIJSON(sample);
+
+    expect(hashA).toBe(hashB);
+    expect(hashA).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  test("should change with input", async () => {
+    const hashA = await hashOpenAPIJSON(JSON.stringify({ v: 1 }));
+    const hashB = await hashOpenAPIJSON(JSON.stringify({ v: 2 }));
+    expect(hashA).not.toBe(hashB);
+  });
+});
+
+describe("openAPIToYAML", () => {
+  test("should emit a parseable two-space-indented YAML subset", () => {
+    const doc = {
+      openapi: "3.0.3" as const,
+      info: { title: "Test API", version: "1.0.0" },
+      paths: {
+        "/api/users": {
+          get: {
+            summary: "List",
+            responses: { "200": { description: "OK" } },
+          },
+        },
+      },
+    };
+
+    const yaml = openAPIToYAML(doc);
+
+    // Must NOT contain raw curly braces from the old naive converter.
+    expect(yaml).toContain("openapi: 3.0.3");
+    expect(yaml).toContain("info:");
+    expect(yaml).toContain("  title: Test API");
+    expect(yaml).toContain("  version: 1.0.0");
+    expect(yaml).toContain("paths:");
+    // Path key contains `/` and `:` suffix is handled as block mapping,
+    // so the OpenAPI path appears as a block-mapping key — expect its
+    // presence without assuming quoting.
+    expect(yaml).toMatch(/\/api\/users:/);
+    expect(yaml).toContain("      summary: List");
+    expect(yaml).toMatch(/\n$/);
+  });
+});
+
+describe("writeOpenAPIArtifacts + readOpenAPIArtifacts", () => {
+  test("should write openapi.json and openapi.yaml then read them back with matching hash", async () => {
+    const { rootDir, manifest, cleanup } = await buildFixture();
+    try {
+      const written = await writeOpenAPIArtifacts(manifest, rootDir, ".mandu", {
+        title: "Artifact Test",
+        version: "1.0.0",
+      });
+
+      expect(written.paths.json.endsWith("openapi.json")).toBe(true);
+      expect(written.paths.yaml.endsWith("openapi.yaml")).toBe(true);
+      expect(written.hash).toMatch(/^[0-9a-f]{64}$/);
+      expect(written.pathCount).toBeGreaterThan(0);
+
+      // Both files should exist on disk.
+      const jsonOnDisk = await fs.readFile(written.paths.json, "utf-8");
+      const yamlOnDisk = await fs.readFile(written.paths.yaml, "utf-8");
+      expect(jsonOnDisk).toBe(written.json);
+      expect(yamlOnDisk).toBe(written.yaml);
+
+      // JSON should parse.
+      const parsed = JSON.parse(jsonOnDisk);
+      expect(parsed.openapi).toBe("3.0.3");
+      expect(parsed.info.title).toBe("Artifact Test");
+
+      // readOpenAPIArtifacts should recover the same bodies and recompute
+      // the same hash.
+      const readBack = await readOpenAPIArtifacts(".mandu", rootDir);
+      expect(readBack).not.toBeNull();
+      expect(readBack!.hash).toBe(written.hash);
+      expect(readBack!.json).toBe(written.json);
+      expect(readBack!.yaml).toBe(written.yaml);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  test("readOpenAPIArtifacts returns null when artifacts are missing", async () => {
+    const rootDir = await fs.mkdtemp(path.join(os.tmpdir(), "mandu-openapi-miss-"));
+    try {
+      const result = await readOpenAPIArtifacts(".mandu", rootDir);
+      expect(result).toBeNull();
+    } finally {
+      await fs.rm(rootDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/runtime/openapi-endpoint.ts

@@ -0,0 +1,236 @@
+/**
+ * Runtime OpenAPI endpoint.
+ *
+ * Serves the build-time `.mandu/openapi.json` / `.mandu/openapi.yaml`
+ * artifacts at a stable URL (default `/__mandu/openapi.json` and
+ * `.yaml`) so API consumers (Postman, codegen, Swagger UI proxies) can
+ * fetch a canonical spec without reaching into the framework's dev
+ * Kitchen dashboard.
+ *
+ * Contract:
+ *   - Disabled by default — the server dispatcher gates this handler
+ *     behind `ManduConfig.openapi.enabled` or the
+ *     `MANDU_OPENAPI_ENABLED=1` env var.
+ *   - Lazy-load artifacts on first request; in-memory cache survives
+ *     for the lifetime of the server instance. Re-deploy to invalidate.
+ *   - If artifacts are missing on disk, fall back to live generation
+ *     from the registered manifest so `mandu dev` users still get a
+ *     valid response without running `mandu build` first.
+ *   - ETag = SHA-256 of the JSON body. Supports `If-None-Match` 304
+ *     short-circuiting so downstream caches (CDN, reverse proxy) behave
+ *     correctly.
+ */
+
+import type { RoutesManifest } from "../spec/schema";
+import {
+  generateOpenAPIDocument,
+  hashOpenAPIJSON,
+  openAPIToJSON,
+  openAPIToYAML,
+  readOpenAPIArtifacts,
+} from "../openapi/generator";
+
+export const DEFAULT_OPENAPI_BASE_PATH = "/__mandu/openapi";
+const DEFAULT_ARTIFACT_DIR = ".mandu";
+const CACHE_CONTROL = "public, max-age=0, must-revalidate";
+
+/**
+ * Runtime-resolved OpenAPI endpoint configuration. Mirrors the shape
+ * the server threads through `ServerRegistrySettings` so the hot-path
+ * dispatch can stay allocation-free.
+ */
+export interface OpenAPIEndpointSettings {
+  /** Base path without the trailing `.json`/`.yaml`. Default `/__mandu/openapi`. */
+  basePath: string;
+  /** Absolute directory containing `openapi.json` / `openapi.yaml` artifacts. */
+  artifactDir: string;
+}
+
+interface CacheEntry {
+  json: string;
+  yaml: string;
+  hash: string;
+  etag: string;
+}
+
+/** Module-scoped cache — invalidated by `invalidateOpenAPIEndpointCache()`. */
+let cache: CacheEntry | null = null;
+let pending: Promise<CacheEntry | null> | null = null;
+
+/** Test / HMR hook: drop the cached spec so the next request recomputes. */
+export function invalidateOpenAPIEndpointCache(): void {
+  cache = null;
+  pending = null;
+}
+
+/**
+ * Resolve the OpenAPI body, either from disk artifacts (preferred) or
+ * by generating live from the manifest. Concurrent callers share one
+ * in-flight load so we never rebuild the spec twice on a thundering
+ * herd.
+ */
+async function loadSpec(
+  manifest: RoutesManifest,
+  rootDir: string,
+  settings: OpenAPIEndpointSettings
+): Promise<CacheEntry | null> {
+  if (cache) return cache;
+  if (pending) return pending;
+
+  pending = (async (): Promise<CacheEntry | null> => {
+    try {
+      // 1. Prefer on-disk artifacts (produced by `mandu build`). Keeps
+      //    request-time cost at a single file read instead of walking
+      //    every contract module again.
+      const fromDisk = await readOpenAPIArtifacts(settings.artifactDir, rootDir);
+      if (fromDisk) {
+        const entry: CacheEntry = {
+          json: fromDisk.json,
+          yaml: fromDisk.yaml,
+          hash: fromDisk.hash,
+          etag: `"${fromDisk.hash}"`,
+        };
+        cache = entry;
+        return entry;
+      }
+
+      // 2. Fallback: generate live. Useful in `mandu dev` before the
+      //    user has run `mandu build`, or in test harnesses that boot a
+      //    server directly from a manifest fixture.
+      const doc = await generateOpenAPIDocument(manifest, rootDir);
+      const json = openAPIToJSON(doc);
+      const yaml = openAPIToYAML(doc);
+      const hash = await hashOpenAPIJSON(json);
+      const entry: CacheEntry = {
+        json,
+        yaml,
+        hash,
+        etag: `"${hash}"`,
+      };
+      cache = entry;
+      return entry;
+    } catch {
+      // Swallow the error — a 500 here would be worse DX than a 404.
+      // Invalidate so the next request retries.
+      cache = null;
+      return null;
+    } finally {
+      pending = null;
+    }
+  })();
+
+  return pending;
+}
+
+/**
+ * Handle a GET request for the OpenAPI endpoint.
+ *
+ * Returns `null` when the pathname does not match — the dispatcher
+ * should fall through to the normal route resolution pipeline. Returns
+ * a `Response` for both hit (200 + spec) and miss (404 when the spec
+ * cannot be materialized). Only `GET` and `HEAD` are accepted; every
+ * other method gets a 405 with `Allow: GET, HEAD`.
+ */
+export async function handleOpenAPIRequest(
+  req: Request,
+  pathname: string,
+  manifest: RoutesManifest,
+  rootDir: string,
+  settings: OpenAPIEndpointSettings
+): Promise<Response | null> {
+  const jsonPath = `${settings.basePath}.json`;
+  const yamlPath = `${settings.basePath}.yaml`;
+
+  let variant: "json" | "yaml";
+  if (pathname === jsonPath) variant = "json";
+  else if (pathname === yamlPath) variant = "yaml";
+  else return null;
+
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    return new Response("Method Not Allowed", {
+      status: 405,
+      headers: {
+        Allow: "GET, HEAD",
+        "Cache-Control": "no-store",
+      },
+    });
+  }
+
+  const entry = await loadSpec(manifest, rootDir, settings);
+  if (!entry) {
+    return new Response("Not Found", { status: 404 });
+  }
+
+  // Conditional-GET: honour `If-None-Match` for CDN / browser caches.
+  const ifNoneMatch = req.headers.get("if-none-match");
+  if (ifNoneMatch && ifNoneMatch === entry.etag) {
+    return new Response(null, {
+      status: 304,
+      headers: {
+        ETag: entry.etag,
+        "Cache-Control": CACHE_CONTROL,
+      },
+    });
+  }
+
+  const body = variant === "json" ? entry.json : entry.yaml;
+  const contentType =
+    variant === "json"
+      ? "application/json; charset=utf-8"
+      : "application/yaml; charset=utf-8";
+
+  // HEAD responses carry the headers but drop the body.
+  const responseBody = req.method === "HEAD" ? null : body;
+  return new Response(responseBody, {
+    status: 200,
+    headers: {
+      "Content-Type": contentType,
+      "Cache-Control": CACHE_CONTROL,
+      ETag: entry.etag,
+      // Expose ETag to browser JS so API explorer UIs can display the
+      // deploy identifier without a round-trip.
+      "Access-Control-Expose-Headers": "ETag",
+    },
+  });
+}
+
+/**
+ * Resolve the effective endpoint settings for a server boot. Normalizes
+ * the `path` option (users may pass with or without leading slash, and
+ * with or without the `.json` suffix) and chooses the artifact
+ * directory default.
+ */
+export function resolveOpenAPIEndpointSettings(
+  rootDir: string,
+  path?: string
+): OpenAPIEndpointSettings {
+  let basePath = path ?? DEFAULT_OPENAPI_BASE_PATH;
+  if (!basePath.startsWith("/")) basePath = `/${basePath}`;
+  // Strip trailing `.json` / `.yaml` / trailing slash so the handler can
+  // append suffixes uniformly.
+  basePath = basePath.replace(/\.(json|yaml|yml)$/i, "").replace(/\/+$/, "");
+  if (basePath === "") basePath = DEFAULT_OPENAPI_BASE_PATH;
+
+  // POSIX-style join — artifact paths are treated as absolute by
+  // `readOpenAPIArtifacts`, which itself uses `node:path` for portability.
+  const normalizedRoot = rootDir.replace(/[\\/]+$/, "");
+  const separator = normalizedRoot.includes("\\") ? "\\" : "/";
+  const artifactDir = `${normalizedRoot}${separator}${DEFAULT_ARTIFACT_DIR}`;
+  return { basePath, artifactDir };
+}
+
+/**
+ * Decide whether the OpenAPI endpoint should be active for this
+ * server instance. The config flag wins; an explicit `false` still
+ * disables the endpoint even when the env var is set (explicit > env).
+ * Absent config + truthy env var (`MANDU_OPENAPI_ENABLED=1`) opts in.
+ */
+export function isOpenAPIEndpointEnabled(
+  enabled: boolean | undefined,
+  env: NodeJS.ProcessEnv | Record<string, string | undefined> = process.env
+): boolean {
+  if (enabled === true) return true;
+  if (enabled === false) return false;
+  const raw = env.MANDU_OPENAPI_ENABLED;
+  return raw === "1" || raw === "true";
+}

package/src/runtime/server.ts

@@ -62,6 +62,11 @@ import {
   isObservabilityExposed,
   recordHttpRequest,
 } from "../observability/metrics";
+import {
+  handleOpenAPIRequest,
+  isOpenAPIEndpointEnabled,
+  resolveOpenAPIEndpointSettings,
+} from "./openapi-endpoint";
 // Phase 18.ψ — user-facing perf marks dashboard append. We include a
 // `perf` block on the `/_mandu/heap` payload when the feature is active
 // so operators see a unified view (heap + caches + perf histogram).
@@ -499,6 +504,30 @@ export interface ServerOptions {
       serviceName?: string;
     };
   };
+  /**
+   * Production-grade OpenAPI endpoint.
+   *
+   * When enabled, the runtime serves the contracts-derived OpenAPI 3.0.3
+   * document at `<path>.json` / `<path>.yaml` (default base path
+   * `/__mandu/openapi`). The body is loaded once from the build-time
+   * artifacts under `.mandu/openapi.{json,yaml}` (emitted by
+   * `mandu build`) and cached for the lifetime of the server.
+   *
+   *   - `enabled` — default `false`. Security-conscious: production
+   *     deployments must explicitly opt in, or set
+   *     `MANDU_OPENAPI_ENABLED=1` in the environment.
+   *   - `path` — base URL path (with or without `.json` suffix).
+   *     Default `/__mandu/openapi`.
+   *
+   * Wired from `ManduConfig.openapi`. The response carries
+   * `Cache-Control: public, max-age=0, must-revalidate` + a SHA-256
+   * ETag so CDNs / browsers revalidate on every deploy without holding
+   * stale specs.
+   */
+  openapi?: {
+    enabled?: boolean;
+    path?: string;
+  };
   /**
    * Phase 18 — prerendered HTML pass-through (SSG).
    *
@@ -787,6 +816,14 @@ export interface ServerRegistrySettings {
    * request opens a root span via `tracer.startSpanFromRequest()`.
    */
   tracer?: import("../observability/tracing").Tracer;
+  /**
+   * Production OpenAPI endpoint — resolved from `ServerOptions.openapi`.
+   * `undefined` means the endpoint is disabled (hot path branch-free).
+   * When populated, every request whose pathname matches
+   * `<basePath>.json` / `<basePath>.yaml` short-circuits before route
+   * dispatch to serve the cached spec body.
+   */
+  openapi?: import("./openapi-endpoint").OpenAPIEndpointSettings;
   /**
    * Phase 18 — resolved prerender pass-through state. `undefined`
    * means the feature is disabled for this server instance.
@@ -3916,6 +3953,26 @@ async function handleRequestInternal(
     }
   }
 
+  // Production OpenAPI endpoint — `/__mandu/openapi.json` + `.yaml`.
+  // Gated behind `ManduConfig.openapi.enabled` (or MANDU_OPENAPI_ENABLED=1).
+  // Every response carries an ETag so CDNs / browsers revalidate cheaply
+  // after a deploy. Falls through to route dispatch if disabled OR the
+  // pathname doesn't match the configured base path.
+  if (settings.openapi) {
+    const openapiManifest: RoutesManifest = {
+      version: 1,
+      routes: router.getRoutes(),
+    };
+    const openapiResponse = await handleOpenAPIRequest(
+      req,
+      pathname,
+      openapiManifest,
+      settings.rootDir,
+      settings.openapi
+    );
+    if (openapiResponse) return ok(openapiResponse);
+  }
+
   // 2. Kitchen dev dashboard (dev mode only)
   if (settings.isDev && pathname.startsWith(KITCHEN_PREFIX) && registry.kitchen) {
     const kitchenResponse = await registry.kitchen.handle(req, pathname);
@@ -4252,6 +4309,7 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     spa,
     devtools,
     observability: observabilityOption,
+    openapi: openapiOption,
     prerender: prerenderOption,
     middleware: middlewareOption,
     rpc: rpcOption,
@@ -4373,6 +4431,13 @@ export function startServer(manifest: RoutesManifest, options: ServerOptions = {
     heapEndpoint: observabilityOption?.heapEndpoint,
     metricsEndpoint: observabilityOption?.metricsEndpoint,
     tracer: tracerInstance.enabled ? tracerInstance : undefined,
+    // Production OpenAPI endpoint — default OFF so an internet-facing
+    // deployment does not leak its API surface without explicit opt-in.
+    // `MANDU_OPENAPI_ENABLED=1` in the environment forces-on without a
+    // config edit; explicit `enabled: false` still wins (explicit > env).
+    openapi: isOpenAPIEndpointEnabled(openapiOption?.enabled)
+      ? resolveOpenAPIEndpointSettings(rootDir, openapiOption?.path)
+      : undefined,
     prerender: prerenderSettings,
     middlewareChain,
     i18n: i18nOption,