npm - @mandujs/core - Versions diffs - 0.34.1 → 0.35.0 - Mend

@mandujs/core 0.34.1 → 0.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/package.json +1 -1
package/src/client/spa-nav-helper.ts +12 -1
package/src/config/mandu.ts +28 -0
package/src/config/validate.ts +27 -0
package/src/openapi/generator.ts +264 -7
package/src/openapi/openapi.test.ts +216 -1
package/src/runtime/openapi-endpoint.ts +236 -0
package/src/runtime/server.ts +65 -0

package/package.json CHANGED Viewed

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

package/src/client/spa-nav-helper.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 /**
  * Issue #208 — Minimal inline SPA-navigation helper.
  * Issue #220 — body-swap observability + fallback + script re-execution.
+ * Issue #222 — hash-anchor preservation across SPA swaps.
  *
  * Self-contained IIFE injected into the SSR `<head>` that upgrades plain
  * full-page navigations into client-side `history.pushState` +
@@ -64,6 +65,16 @@
  *      `detail: { url, durationMs, container }` so islands and
  *      integrations can re-hydrate if needed.
  *
+ *   6b. **Hash anchor preservation** (issue #222): after a successful
+ *      swap, if the target URL carries a `#hash`, the helper resolves
+ *      `document.getElementById(hash)` (with a fallback to
+ *      `[name="<hash>"]`) and calls `scrollIntoView({block:"start"})`
+ *      so `<a href="/docs#intro">` lands on `<h1 id="intro">` instead
+ *      of the top of the page. Missing targets fall back to `scrollTo(0,0)`.
+ *      Same-page hash navigation (identical pathname + search) skips the
+ *      body swap entirely — only pushState + scrollIntoView fire.
+ *      `CSS.escape` is used when available to handle punctuation in ids.
+ *
  *   7. **Inline, not external**: same rationale as #192's prefetch
  *      helper — inline removes the extra round-trip on every SSR
  *      response, keeps the CSP posture simple, and sidesteps the
@@ -86,7 +97,7 @@
  * flow is documented in this file's JSDoc; anyone editing this string
  * MUST update the exclusion-matrix test and the body-swap test to match.
  */
-export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h||h.charAt(0)==="#")return null;var u;try{u=new URL(h,L.origin);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);try{window.scrollTo(0,0);}catch(_){}var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
+export const SPA_NAV_HELPER_BODY = `(function(){if(typeof document==="undefined"||typeof window==="undefined")return;var L=window.location;var H=window.history;var TAG="[mandu-spa-nav]";function warn(m,d){try{console.warn(TAG+" "+m,d==null?"":d);}catch(_){}}function info(m,d){try{console.debug(TAG+" "+m,d==null?"":d);}catch(_){}}function hardNav(u,why){warn("falling back to full navigation: "+why,u);try{L.href=u;}catch(_){}}function esc(h){try{if(typeof CSS!=="undefined"&&CSS&&typeof CSS.escape==="function")return CSS.escape(h);}catch(_){}return String(h).replace(/([^a-zA-Z0-9_-])/g,"\\\\$1");}function extractHash(u){var i=u.indexOf("#");return i>=0?u.slice(i+1):"";}function scrollToHash(hash,url){if(!hash){try{window.scrollTo(0,0);}catch(_){}return;}var el=null;try{el=document.getElementById?document.getElementById(hash):null;}catch(_){}if(!el){try{el=document.querySelector?document.querySelector('[name="'+esc(hash)+'"]'):null;}catch(_){}}if(el&&typeof el.scrollIntoView==="function"){try{el.scrollIntoView({behavior:"instant",block:"start"});}catch(e1){try{el.scrollIntoView();}catch(_){}}try{if(L.hash!=="#"+hash)L.hash="#"+hash;}catch(_){}info("scrolled to #"+hash,url==null?"":url);}else{info("hash target #"+hash+" not found, scrolling to top",url==null?"":url);try{window.scrollTo(0,0);}catch(_){}}}function okAnchor(a){if(!a||!a.getAttribute)return null;if(a.hasAttribute("data-no-spa"))return null;if(a.hasAttribute("download"))return null;var t=a.getAttribute("target");if(t&&t!=="_self")return null;var h=a.getAttribute("href");if(!h)return null;var u;try{u=new URL(h,L.href);}catch(_){return null;}if(u.origin!==L.origin)return null;if(u.protocol!=="http:"&&u.protocol!=="https:")return null;if(u.pathname===L.pathname&&u.search===L.search&&!u.hash)return null;return u;}function pickContainer(doc){var main=doc.querySelector("main");if(main)return{src:main,dst:document.querySelector("main"),kind:"main"};var root=doc.getElementById&&doc.getElementById("root");if(root){var dstR=document.getElementById?document.getElementById("root"):null;if(dstR)return{src:root,dst:dstR,kind:"#root"};}if(doc.body)return{src:doc.body,dst:document.body,kind:"body"};return null;}function mergeHead(doc){try{var newTitle=doc.querySelector("title");if(newTitle)document.title=newTitle.textContent||document.title;var nh=doc.head,ch=document.head;if(!nh||!ch)return;var keep={};var metas=ch.querySelectorAll("meta[name=viewport],meta[charset]");for(var i=0;i<metas.length;i++)keep[metas[i].outerHTML]=true;var sel="meta,link[rel=icon],link[rel=shortcut icon],link[rel=canonical]";var oldMetas=ch.querySelectorAll(sel);for(var j=0;j<oldMetas.length;j++){if(!keep[oldMetas[j].outerHTML])oldMetas[j].parentNode.removeChild(oldMetas[j]);}var newMetas=nh.querySelectorAll(sel);for(var k=0;k<newMetas.length;k++){if(!keep[newMetas[k].outerHTML])ch.appendChild(newMetas[k].cloneNode(true));}}catch(e){warn("head merge failed",e&&e.message||e);}}function runScripts(container){try{var scripts=container.querySelectorAll("script");for(var i=0;i<scripts.length;i++){var old=scripts[i];var s=document.createElement("script");for(var j=0;j<old.attributes.length;j++){var a=old.attributes[j];try{s.setAttribute(a.name,a.value);}catch(_){}}if(!old.src)s.text=old.textContent||"";old.parentNode&&old.parentNode.removeChild(old);(document.head||document.body||document.documentElement).appendChild(s);}}catch(e){warn("script re-exec failed",e&&e.message||e);}}function doSwap(doc,url,startedAt){var perr=doc.querySelector&&doc.querySelector("parsererror");if(perr){hardNav(url,"DOMParser returned parsererror");return false;}var pick=pickContainer(doc);if(!pick||!pick.dst){hardNav(url,"no swap container matched (main/#root/body)");return false;}info("swap target container: "+pick.kind);try{pick.dst.innerHTML=pick.src.innerHTML;}catch(e){hardNav(url,"innerHTML assignment threw: "+(e&&e.message||e));return false;}mergeHead(doc);runScripts(pick.dst);scrollToHash(extractHash(url),url);var dur=0;try{dur=Math.round((performance&&performance.now?performance.now():Date.now())-startedAt);}catch(_){}info("swapped to "+url+" in "+dur+"ms (container="+pick.kind+")");try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:dur,container:pick.kind}}));}catch(_){}try{window.dispatchEvent(new CustomEvent("mandu:spa-navigate",{detail:{url:url}}));}catch(_){}return true;}function nav(url,push){var startedAt=0;try{startedAt=performance&&performance.now?performance.now():Date.now();}catch(_){startedAt=Date.now();}fetch(url,{credentials:"same-origin",headers:{"Accept":"text/html"}}).then(function(r){if(!r.ok){hardNav(url,"fetch responded "+r.status);return null;}var ct=r.headers.get("content-type");if(!ct||ct.indexOf("text/html")<0){hardNav(url,"non-HTML response ("+(ct||"no content-type")+")");return null;}return r.text();}).then(function(html){if(html==null)return;if(typeof DOMParser==="undefined"){hardNav(url,"DOMParser unavailable");return;}var doc;try{doc=new DOMParser().parseFromString(html,"text/html");}catch(e){hardNav(url,"DOMParser threw: "+(e&&e.message||e));return;}if(push){try{H.pushState({mandu:1},"",url);}catch(e){hardNav(url,"pushState threw: "+(e&&e.message||e));return;}}var run=function(){doSwap(doc,url,startedAt);};if(typeof document.startViewTransition==="function"){try{document.startViewTransition(run);}catch(e){warn("startViewTransition threw, running swap directly",e&&e.message||e);run();}}else{run();}}).catch(function(e){hardNav(url,"fetch rejected: "+(e&&e.message||e));});}function samePageHashNav(u,push){var url=u.pathname+u.search+u.hash;if(push){try{H.pushState({mandu:1},"",url);}catch(e){warn("pushState threw on same-page hash nav",e&&e.message||e);}}info("same-page hash nav "+url);scrollToHash(u.hash?u.hash.slice(1):"",url);try{window.dispatchEvent(new CustomEvent("__MANDU_SPA_NAV__",{detail:{url:url,durationMs:0,container:"hash"}}));}catch(_){}}document.addEventListener("click",function(e){if(e.defaultPrevented)return;if(e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;if(window.__MANDU_ROUTER_STATE__)return;var tgt=e.target;var a=tgt&&typeof tgt.closest==="function"?tgt.closest("a"):null;if(!a)return;var url=okAnchor(a);if(!url)return;e.preventDefault();if(url.pathname===L.pathname&&url.search===L.search&&url.hash){samePageHashNav(url,true);return;}nav(url.pathname+url.search+url.hash,true);},false);window.addEventListener("popstate",function(){if(window.__MANDU_ROUTER_STATE__)return;nav(L.pathname+L.search+L.hash,false);});window.__MANDU_SPA_HELPER__=1;})();`;
 /** Ready-to-inject `<script>` tag for SSR `<head>` injection. */
 export const SPA_NAV_HELPER_SCRIPT = `<script>${SPA_NAV_HELPER_BODY}</script>`;

package/src/config/mandu.ts CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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,