@mandujs/core 0.25.2 → 0.26.0

package/src/routes/metadata-routes.ts

@@ -0,0 +1,427 @@
+/**
+ * Metadata Routes — Runtime Handlers
+ *
+ * Pure renderers + request dispatchers for the four file-convention
+ * metadata routes (`sitemap.ts`, `robots.ts`, `llms.txt.ts`,
+ * `manifest.ts`). Each `render*` function takes the validated, typed
+ * value and produces the serialized body. The `handleMetadataRoute`
+ * dispatcher wires an imported user module to a `Response`, including
+ * validation, caching headers, and typed error responses.
+ *
+ * Design notes
+ * ────────────
+ * • Renderers are pure and synchronous so tests can hit them directly
+ *   without mocking Request/Response.
+ * • Validation runs AFTER the user function resolves but BEFORE we
+ *   attempt to render — this lets us surface the exact Zod error
+ *   (with the failing path) in the 500 response instead of crashing
+ *   inside `renderSitemap` / `renderManifest` when a required field
+ *   is missing.
+ * • Cache headers are `public, max-age=3600` by default. Callers can
+ *   opt in to custom values via the `cache` option, and opting out
+ *   entirely is supported by passing `cache: false`.
+ *
+ * @module routes/metadata-routes
+ */
+import {
+  SitemapSchema,
+  RobotsSchema,
+  WebAppManifestSchema,
+  METADATA_ROUTES,
+  type MetadataRouteKind,
+  type Sitemap,
+  type SitemapEntry,
+  type Robots,
+  type RobotsRule,
+  type WebAppManifest,
+} from "./types";
+
+// ═══════════════════════════════════════════════════════════════════════════
+// XML / text escape helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Escape characters that are illegal in XML text / attribute content.
+ * We deliberately avoid bringing in a dependency here — the five
+ * predefined entities cover every case we emit.
+ */
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Normalize a Date / date-like string into an ISO-8601 string. We
+ * accept strings verbatim to let users pass pre-formatted values
+ * (e.g. a DB-returned timestamp) without re-parsing.
+ */
+function formatDate(value: string | Date): string {
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Sitemap rendering
+// ═══════════════════════════════════════════════════════════════════════════
+
+function renderSitemapEntry(entry: SitemapEntry): string {
+  const lines: string[] = ["  <url>"];
+  lines.push(`    <loc>${escapeXml(entry.url)}</loc>`);
+
+  if (entry.lastModified !== undefined) {
+    lines.push(`    <lastmod>${escapeXml(formatDate(entry.lastModified))}</lastmod>`);
+  }
+  if (entry.changeFrequency) {
+    lines.push(`    <changefreq>${entry.changeFrequency}</changefreq>`);
+  }
+  if (entry.priority !== undefined) {
+    lines.push(`    <priority>${entry.priority.toFixed(1)}</priority>`);
+  }
+  if (entry.images?.length) {
+    for (const image of entry.images) {
+      lines.push("    <image:image>");
+      lines.push(`      <image:loc>${escapeXml(image)}</image:loc>`);
+      lines.push("    </image:image>");
+    }
+  }
+  if (entry.alternates?.languages) {
+    for (const [lang, url] of Object.entries(entry.alternates.languages)) {
+      lines.push(
+        `    <xhtml:link rel="alternate" hreflang="${escapeXml(lang)}" href="${escapeXml(url)}" />`
+      );
+    }
+  }
+  lines.push("  </url>");
+  return lines.join("\n");
+}
+
+/**
+ * Render a sitemap entry array to XML 1.0. The `xmlns:image` and
+ * `xmlns:xhtml` namespaces are added on demand so a plain sitemap
+ * stays as compact as possible.
+ */
+export function renderSitemap(entries: Sitemap): string {
+  const hasImages = entries.some((e) => e.images && e.images.length > 0);
+  const hasAlternates = entries.some((e) => e.alternates?.languages);
+
+  const namespaces = ['xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"'];
+  if (hasImages) {
+    namespaces.push('xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"');
+  }
+  if (hasAlternates) {
+    namespaces.push('xmlns:xhtml="http://www.w3.org/1999/xhtml"');
+  }
+
+  const lines = [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<urlset ${namespaces.join(" ")}>`,
+    ...entries.map(renderSitemapEntry),
+    "</urlset>",
+  ];
+  return lines.join("\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Robots rendering
+// ═══════════════════════════════════════════════════════════════════════════
+
+function toArray<T>(value: T | T[] | undefined): T[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function renderRobotsRule(rule: RobotsRule): string {
+  const lines: string[] = [];
+  const userAgents = toArray(rule.userAgent);
+  for (const ua of userAgents) {
+    lines.push(`User-agent: ${ua}`);
+  }
+  for (const path of toArray(rule.allow)) {
+    lines.push(`Allow: ${path}`);
+  }
+  for (const path of toArray(rule.disallow)) {
+    lines.push(`Disallow: ${path}`);
+  }
+  if (rule.crawlDelay !== undefined) {
+    lines.push(`Crawl-delay: ${rule.crawlDelay}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Render a `Robots` object to a robots.txt text body. Rule groups are
+ * separated by blank lines; `sitemap:` and `host:` directives go at
+ * the bottom per convention.
+ */
+export function renderRobots(robots: Robots): string {
+  const sections: string[] = [];
+  const rules = toArray(robots.rules);
+  for (const rule of rules) {
+    sections.push(renderRobotsRule(rule));
+  }
+  if (robots.host) {
+    sections.push(`Host: ${robots.host}`);
+  }
+  for (const sitemap of toArray(robots.sitemap)) {
+    sections.push(`Sitemap: ${sitemap}`);
+  }
+  return sections.join("\n\n");
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Web App Manifest rendering
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Serialize a `WebAppManifest` to JSON. Formatting is deterministic
+ * (2-space indent) so CDN caches don't generate spurious diffs when
+ * the underlying object is logically unchanged.
+ */
+export function renderManifest(manifest: WebAppManifest): string {
+  return JSON.stringify(manifest, null, 2);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// llms.txt passthrough
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Identity-ish passthrough for llms.txt content. Exposed as a function
+ * so the dispatcher can treat every route type uniformly — and so
+ * future formats (e.g. stripping BOM, normalizing line endings) can be
+ * added here without touching call sites.
+ */
+export function renderLlmsTxt(content: string): string {
+  if (typeof content !== "string") {
+    throw new TypeError(
+      `[@mandujs/core/routes] llms.txt default export must return a string, got ${typeof content}`
+    );
+  }
+  return content;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Dispatcher
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Options passed to {@link handleMetadataRoute}. `sourceFile` is used
+ * purely for error messages — it appears in the 500 body when the user
+ * export throws or returns an invalid shape, which dramatically
+ * shortens the edit-test loop.
+ */
+export interface MetadataRouteHandlerOptions {
+  /** Which of the four metadata routes we're serving. */
+  kind: MetadataRouteKind;
+  /** The imported user module's default export (not yet invoked). */
+  userExport: unknown;
+  /** The source file path, surfaced in error messages. */
+  sourceFile?: string;
+  /**
+   * Cache-Control header. `true` (default) emits
+   * `public, max-age=3600`. `false` omits the header. A string is
+   * passed through unchanged.
+   */
+  cache?: boolean | string;
+}
+
+/**
+ * Typed error thrown when metadata route validation fails. The message
+ * includes the source file + Zod path so the developer can jump
+ * directly to the offending line.
+ */
+export class MetadataRouteValidationError extends Error {
+  readonly kind: MetadataRouteKind;
+  readonly issues: { path: string; message: string }[];
+  readonly sourceFile?: string;
+
+  constructor(
+    kind: MetadataRouteKind,
+    issues: { path: string; message: string }[],
+    sourceFile?: string
+  ) {
+    const header = sourceFile
+      ? `[@mandujs/core/routes] Invalid ${kind} value in ${sourceFile}`
+      : `[@mandujs/core/routes] Invalid ${kind} value`;
+    const body = issues.map((i) => `  • ${i.path || "(root)"}: ${i.message}`).join("\n");
+    super(`${header}\n${body}`);
+    this.name = "MetadataRouteValidationError";
+    this.kind = kind;
+    this.issues = issues;
+    this.sourceFile = sourceFile;
+  }
+}
+
+function defaultCacheControl(cache: boolean | string | undefined): string | null {
+  if (cache === false) return null;
+  if (typeof cache === "string") return cache;
+  return "public, max-age=3600";
+}
+
+/**
+ * Look up the Content-Type + URL pattern for a metadata route kind.
+ * Exposed so fs-scanner / manifest builders can reuse the same table
+ * without reaching into METADATA_ROUTES directly.
+ */
+export function getMetadataRouteMeta(kind: MetadataRouteKind) {
+  return METADATA_ROUTES[kind];
+}
+
+/**
+ * Dispatch a metadata route request.
+ *
+ * Pipeline:
+ *   1. Extract the default-export function from the imported module.
+ *   2. Invoke it (await its result).
+ *   3. Zod-validate the returned shape.
+ *   4. Render the correct body format.
+ *   5. Wrap in a Response with the right Content-Type + cache headers.
+ *
+ * Any failure in steps 1-4 yields a typed 500 Response whose body
+ * includes the source file and Zod issue path.
+ */
+export async function handleMetadataRoute(
+  options: MetadataRouteHandlerOptions
+): Promise<Response> {
+  const { kind, userExport, sourceFile } = options;
+  const { contentType } = METADATA_ROUTES[kind];
+  const cacheControl = defaultCacheControl(options.cache);
+
+  const fn = extractDefaultFn(userExport);
+  if (!fn) {
+    return errorResponse(
+      kind,
+      sourceFile,
+      "Module default export must be a function. " +
+        `Expected \`export default function ${friendlyName(kind)}() { ... }\`.`
+    );
+  }
+
+  let result: unknown;
+  try {
+    result = await fn();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return errorResponse(kind, sourceFile, `User function threw: ${message}`);
+  }
+
+  try {
+    const body = renderValidated(kind, result, sourceFile);
+    const headers = new Headers({ "Content-Type": contentType });
+    if (cacheControl) headers.set("Cache-Control", cacheControl);
+    return new Response(body, { status: 200, headers });
+  } catch (err) {
+    if (err instanceof MetadataRouteValidationError) {
+      return errorResponse(kind, sourceFile, err.message);
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return errorResponse(kind, sourceFile, `Render failed: ${message}`);
+  }
+}
+
+/**
+ * Validate + render a single metadata route value. Shared between the
+ * production dispatcher and tests (where we often want to exercise a
+ * specific branch without spinning up a Request).
+ */
+export function renderValidated(
+  kind: MetadataRouteKind,
+  value: unknown,
+  sourceFile?: string
+): string {
+  switch (kind) {
+    case "sitemap": {
+      const parsed = SitemapSchema.safeParse(value);
+      if (!parsed.success) throw zodToValidationError(kind, parsed.error, sourceFile);
+      return renderSitemap(parsed.data);
+    }
+    case "robots": {
+      const parsed = RobotsSchema.safeParse(value);
+      if (!parsed.success) throw zodToValidationError(kind, parsed.error, sourceFile);
+      return renderRobots(parsed.data);
+    }
+    case "llms-txt": {
+      if (typeof value !== "string") {
+        throw new MetadataRouteValidationError(
+          kind,
+          [{ path: "(root)", message: `expected string, got ${typeof value}` }],
+          sourceFile
+        );
+      }
+      return renderLlmsTxt(value);
+    }
+    case "manifest": {
+      const parsed = WebAppManifestSchema.safeParse(value);
+      if (!parsed.success) throw zodToValidationError(kind, parsed.error, sourceFile);
+      return renderManifest(parsed.data as WebAppManifest);
+    }
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Helpers
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Accept both a raw function export and a `{ default: fn }` namespace
+ * object (the shape returned by `await import(...)`). Returns the
+ * callable or null if neither is available.
+ */
+function extractDefaultFn(userExport: unknown): ((...args: unknown[]) => unknown) | null {
+  if (typeof userExport === "function") {
+    return userExport as (...args: unknown[]) => unknown;
+  }
+  if (userExport && typeof userExport === "object") {
+    const maybeDefault = (userExport as { default?: unknown }).default;
+    if (typeof maybeDefault === "function") {
+      return maybeDefault as (...args: unknown[]) => unknown;
+    }
+  }
+  return null;
+}
+
+function friendlyName(kind: MetadataRouteKind): string {
+  switch (kind) {
+    case "sitemap":
+      return "sitemap";
+    case "robots":
+      return "robots";
+    case "llms-txt":
+      return "llmsTxt";
+    case "manifest":
+      return "manifest";
+  }
+}
+
+function zodToValidationError(
+  kind: MetadataRouteKind,
+  error: { issues: { path: (string | number)[]; message: string }[] },
+  sourceFile?: string
+): MetadataRouteValidationError {
+  const issues = error.issues.map((i) => ({
+    path: i.path.join("."),
+    message: i.message,
+  }));
+  return new MetadataRouteValidationError(kind, issues, sourceFile);
+}
+
+/**
+ * Build a 500 Response with a plain-text body describing the problem.
+ * Mirrors how Next.js surfaces metadata errors — the text is read
+ * directly from the browser "View Source", no JSON framing.
+ */
+function errorResponse(
+  kind: MetadataRouteKind,
+  sourceFile: string | undefined,
+  detail: string
+): Response {
+  const location = sourceFile ? ` (${sourceFile})` : "";
+  const body = `# Mandu metadata route error: ${kind}${location}\n${detail}\n`;
+  return new Response(body, {
+    status: 500,
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}