@madojs/mado 0.11.0 → 0.12.0

package/scripts/static/discover.mjs

@@ -0,0 +1,281 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { detectContext, getPackageRoot, resolveProjectPath } from "../_config.mjs";
+import { assertJsonSerializable } from "./serialize.mjs";
+
+/**
+ * Build-time route discovery for static snapshots.
+ *
+ * Uses Vite's SSR module loader as a *control plane only* — no templates
+ * or components are rendered in Node. Routing, flattening, param
+ * extraction and pathname materialisation reuse the canonical helpers
+ * exported by src/router/match.ts so the discovery pipeline never drifts
+ * out of sync with the runtime router.
+ */
+export async function discoverStaticRoutes(options) {
+  const projectRoot = resolve(options.projectRoot);
+  const context = detectContext(projectRoot);
+  const entry = resolveProjectPath(projectRoot, options.entry ?? pickDefaultEntry(projectRoot));
+
+  if (!existsSync(entry)) {
+    // Throwing — rather than `process.exit()` — lets the outer
+    // `scripts/static.mjs` finalize its temp-directory cleanup before
+    // the process terminates.
+    throw new Error(
+      `[mado:static] entry not found: ${entry}\n` +
+        `[mado:static] expected src/app.routes.ts or src/routes.ts; ` +
+        `pass --entry <file> to override`,
+    );
+  }
+
+  installNodeDomStubs();
+
+  let createViteServer;
+  try {
+    ({ createServer: createViteServer } = await import("vite"));
+  } catch {
+    throw new Error(
+      "[mado:static] package 'vite' is required.\n" +
+        "[mado:static] Install it as a dev dependency in this project:\n" +
+        "[mado:static]   npm i -D vite playwright-core",
+    );
+  }
+
+  // Two facts to keep in sync:
+  //   1. In-repo runs MUST resolve `@madojs/mado` to the live source so the
+  //      framework can test itself without a build artefact.
+  //   2. App runs need our routing helpers loaded through SSR alongside the
+  //      user manifest; we expose them via `__mado_match__` so we can ask
+  //      for them via ssrLoadModule without colliding with user imports.
+  const aliases = {
+    __mado_match__: resolve(getPackageRoot(), "src/router/match.ts"),
+    ...(context === "repo"
+      ? { "@madojs/mado": resolve(projectRoot, "src/index.ts") }
+      : {}),
+  };
+
+  const viteServer = await createViteServer({
+    root: projectRoot,
+    logLevel: "error",
+    server: { middlewareMode: true },
+    appType: "custom",
+    resolve: { alias: aliases },
+  });
+
+  try {
+    // Load the canonical routing utilities through the SAME Vite SSR loader
+    // that loads the user manifest, so both halves see one consistent copy
+    // of @madojs/mado. Try the source first (works in-repo) and fall back
+    // to a direct import for app contexts where the package may not be
+    // resolvable through Vite's SSR alias chain.
+    const { flatten, paramKeys, applyParams, isPage } = await loadCoreHelpers(viteServer);
+
+    const routesModule = await viteServer.ssrLoadModule(toViteId(entry));
+    const manifest = routesModule.manifest ?? routesModule.default?.manifest;
+    if (!manifest) {
+      throw new Error(
+        `${entry} must export const manifest = {...} (the same object passed to routes()).`,
+      );
+    }
+
+    const records = [];
+    const seen = new Map();
+    for (const [pattern, flat] of flatten(manifest)) {
+      const page = await resolvePage(flat.loader, pattern, isPage);
+      if (!page?.static) continue;
+
+      validateStaticRoute(pattern, flat, page, paramKeys);
+      for (const layoutLoader of flat.layouts) {
+        const layout = await resolvePage(layoutLoader, `${pattern} layout`, isPage);
+        if (layout?.guard) {
+          throw new Error(`[mado:static] ${pattern}: static routes cannot use guarded layouts.`);
+        }
+      }
+
+      const config = page.static === true ? {} : page.static;
+      const paramsList = await resolveParams(pattern, config, paramKeys);
+      for (const params of paramsList) {
+        const pathname = applyParams(pattern, params);
+        if (seen.has(pathname)) {
+          throw new Error(
+            `[mado:static] duplicate generated URL ${pathname} from ${pattern}; ` +
+              `already produced by ${seen.get(pathname)}.`,
+          );
+        }
+        seen.set(pathname, pattern);
+
+        const record = {
+          pattern,
+          pathname,
+          params,
+        };
+        if (config.initialData) {
+          const initialData = await config.initialData(params);
+          assertJsonSerializable(initialData, `${pattern} -> ${pathname}`);
+          record.initialData = initialData;
+        }
+        records.push(record);
+      }
+    }
+
+    records.sort((a, b) => a.pathname.localeCompare(b.pathname));
+    return { entry, records };
+  } finally {
+    await viteServer.close();
+  }
+}
+
+function validateStaticRoute(pattern, flat, page, paramKeys) {
+  if (pattern === "*") {
+    throw new Error("[mado:static] wildcard routes cannot be static.");
+  }
+  if (flat.guards.length > 0) {
+    throw new Error(`[mado:static] ${pattern}: static routes cannot inherit layout guards.`);
+  }
+  if (page.guard) {
+    throw new Error(`[mado:static] ${pattern}: guarded pages cannot be static.`);
+  }
+  if (pattern.includes("*")) {
+    throw new Error(`[mado:static] ${pattern}: wildcard routes cannot be static.`);
+  }
+  const keys = paramKeys(pattern);
+  if (keys.length > 0 && page.static === true) {
+    throw new Error(`[mado:static] ${pattern}: dynamic static routes must provide static.paths().`);
+  }
+  if (keys.length > 0 && !page.static.paths) {
+    throw new Error(`[mado:static] ${pattern}: dynamic static routes must provide static.paths().`);
+  }
+}
+
+async function resolveParams(pattern, config, paramKeys) {
+  const keys = paramKeys(pattern);
+  const paramsList = config.paths ? await config.paths() : [{}];
+  if (!Array.isArray(paramsList)) {
+    throw new Error(`[mado:static] ${pattern}: static.paths() must return an array.`);
+  }
+  if (keys.length === 0 && !config.paths) return [{}];
+  for (const params of paramsList) {
+    if (!params || typeof params !== "object" || Array.isArray(params)) {
+      throw new Error(`[mado:static] ${pattern}: static.paths() must return params objects.`);
+    }
+    for (const key of keys) {
+      if (params[key] == null) {
+        throw new Error(`[mado:static] ${pattern}: missing route param "${key}".`);
+      }
+    }
+  }
+  return paramsList;
+}
+
+async function loadCoreHelpers(viteServer) {
+  // The Vite resolve.alias bridge maps `__mado_match__` to the live source
+  // file of this package, so the user manifest and discovery share the
+  // exact same routing helper functions (same function identity).
+  try {
+    const mod = await viteServer.ssrLoadModule("__mado_match__");
+    if (mod?.flatten && mod?.paramKeys && mod?.applyParams && mod?.isPage) {
+      return mod;
+    }
+  } catch (err) {
+    // Try the build artefact for published-only installs.
+    const distPath = resolve(getPackageRoot(), "dist/src/router/match.js");
+    if (existsSync(distPath)) {
+      const mod = await import(distPath);
+      if (mod?.flatten && mod?.paramKeys && mod?.applyParams && mod?.isPage) {
+        return mod;
+      }
+    }
+    throw new Error(
+      `[mado:static] failed to load core routing helpers: ${err.message}`,
+    );
+  }
+  throw new Error(
+    "[mado:static] core routing helpers loaded but missing expected exports.",
+  );
+}
+
+async function resolvePage(loader, label, isPage) {
+  try {
+    const value = await loader();
+    if (isPage(value)) return value;
+    // Tolerate fixtures that hand-roll a plain object with _page: true
+    // (the dynamic-static-route validation test does this).
+    if (value && value._page === true) return value;
+    throw new Error("loader did not resolve to page({...}).");
+  } catch (err) {
+    throw new Error(`[mado:static] failed to load ${label}: ${err.message}`);
+  }
+}
+
+function installNodeDomStubs() {
+  if (globalThis.document && globalThis.customElements) return;
+
+  globalThis.location = new URL("http://localhost/");
+  globalThis.history = { pushState() {}, replaceState() {} };
+  globalThis.window = {
+    addEventListener() {},
+    removeEventListener() {},
+    dispatchEvent() {},
+    location: globalThis.location,
+    history: globalThis.history,
+  };
+  globalThis.document = {
+    adoptedStyleSheets: [],
+    createElement(tag) {
+      return {
+        tagName: String(tag).toUpperCase(),
+        setAttribute() {},
+        appendChild() {},
+        append() {},
+        remove() {},
+        style: {},
+      };
+    },
+    head: { appendChild() {}, querySelectorAll: () => [] },
+    body: { appendChild() {} },
+    addEventListener() {},
+    removeEventListener() {},
+    dispatchEvent() {},
+    querySelector: () => null,
+    querySelectorAll: () => [],
+    getElementById: () => null,
+  };
+  globalThis.customElements = {
+    define() {},
+    get() {
+      return undefined;
+    },
+    whenDefined() {
+      return Promise.resolve();
+    },
+  };
+  globalThis.HTMLElement = class {};
+  globalThis.Element = class {};
+  globalThis.Node = class {};
+  globalThis.Comment = class {};
+  globalThis.DocumentFragment = class {};
+  globalThis.CSSStyleSheet = class {
+    cssRules = [];
+    replaceSync(text) {
+      this.cssRules = text ? [{ cssText: String(text) }] : [];
+    }
+  };
+  globalThis.CSS = { supports: () => false };
+  globalThis.CSSRule = {};
+  globalThis.matchMedia = () => ({
+    matches: false,
+    addEventListener() {},
+    removeEventListener() {},
+  });
+}
+
+function pickDefaultEntry(projectRoot) {
+  const appRoutes = "src/app.routes.ts";
+  if (existsSync(resolve(projectRoot, appRoutes))) return appRoutes;
+  return "src/routes.ts";
+}
+
+function toViteId(path) {
+  return path.split("\\").join("/");
+}

package/scripts/static/output.mjs

@@ -0,0 +1,141 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { addNoIndex, escapeXml } from "./serialize.mjs";
+
+/**
+ * Stage a deterministic temp output for the snapshot pipeline.
+ *
+ *   out/index.html           ← Vite-built SPA shell, consumed as capture seed
+ *   <os-temp>/spa.html       ← noindexed copy, staged before promotion
+ *   <os-temp>/routes/...     ← per-route captured HTML, also staged
+ *
+ * Nothing inside `out/` is mutated until all routes capture cleanly. A
+ * mid-pipeline crash leaves the existing deployment untouched; only a
+ * verified, complete capture is promoted by `promoteCapturedRoutes()`
+ * and `promoteSpaShell()`.
+ */
+export async function prepareStaticOutput(outDir) {
+  const shellPath = join(outDir, "index.html");
+  if (!existsSync(shellPath)) {
+    throw new Error(
+      `[mado:static] missing ${shellPath}. Run \`mado build\` or Vite build before \`mado static\`.`,
+    );
+  }
+
+  const shellHtml = await readFile(shellPath, "utf8");
+
+  // External temp directory — never leaks into `out/` on failure.
+  const { mkdtemp } = await import("node:fs/promises");
+  const { tmpdir } = await import("node:os");
+  const tempRoot = await mkdtemp(join(tmpdir(), "mado-static-"));
+  const routesDir = join(tempRoot, "routes");
+  await mkdir(routesDir, { recursive: true });
+
+  // Stage the SPA fallback in temp; promote later, only after all
+  // captures verified. Until then `out/_mado/spa.html` either does not
+  // exist (cold release) or holds the previous release's copy (re-run).
+  const stagedSpaPath = join(tempRoot, "spa.html");
+  await writeFile(stagedSpaPath, addNoIndex(shellHtml));
+
+  return { shellHtml, tempRoot, routesDir, stagedSpaPath };
+}
+
+export async function writeCapturedRoutes(routesDir, captured) {
+  for (const record of captured) {
+    const file = safeRouteFile(routesDir, record.pathname);
+    await mkdir(dirname(file), { recursive: true });
+    await writeFile(file, record.html);
+  }
+}
+
+export async function promoteCapturedRoutes({ outDir, routesDir, captured }) {
+  for (const record of captured) {
+    const source = safeRouteFile(routesDir, record.pathname);
+    const target = safeRouteFile(outDir, record.pathname);
+    await mkdir(dirname(target), { recursive: true });
+    await copyFile(source, target);
+  }
+}
+
+/**
+ * Promote the staged SPA fallback shell into `out/_mado/spa.html` after
+ * all routes captured successfully. Called once at the end of the
+ * pipeline; any crash before this point leaves the previous shell (or
+ * no shell at all) in place.
+ */
+export async function promoteSpaShell({ outDir, stagedSpaPath }) {
+  const target = join(outDir, "_mado", "spa.html");
+  await mkdir(dirname(target), { recursive: true });
+  await copyFile(stagedSpaPath, target);
+}
+
+/**
+ * Drop the build-time bridge `out/_mado/build.json` from the final
+ * deployment artifact. It is internal CLI plumbing (the
+ * `@madojs/mado/vite` plugin emits it so `mado static` can read the
+ * resolved Vite base/site without parsing `vite.config.ts`); leaving it
+ * in `out/` would leak the build pipeline's view of the project to
+ * production traffic.
+ */
+export async function dropBuildBridge(outDir) {
+  await rm(join(outDir, "_mado", "build.json"), { force: true });
+}
+
+/**
+ * Files owned by `mado static`: the sitemap (derived from discovered
+ * static routes) and the SPA fallback shell.
+ *
+ * Files owned by `mado release` (so it can decide writeIfMissing
+ * semantics for user-customised deployments): 404.html, _headers,
+ * _redirects, and asset precompression.
+ */
+export async function writeStaticDeploymentFiles({ outDir, records, site, base }) {
+  await writeFile(join(outDir, "sitemap.xml"), sitemap(records, site, base));
+}
+
+export async function cleanupTemp(tempRoot) {
+  await rm(tempRoot, { recursive: true, force: true });
+}
+
+/**
+ * Map a route pathname to an `index.html` file inside `root`, refusing
+ * any path that would traverse outside the deployment tree.
+ */
+function safeRouteFile(root, pathname) {
+  const decoded = decodeURIComponent(pathname);
+  if (decoded.includes("\0") || decoded.includes("\\")) {
+    throw new Error(`[mado:static] illegal pathname: ${pathname}`);
+  }
+  const cleaned = decoded === "/" ? "" : decoded.replace(/^\/+/, "").replace(/\/+$/, "");
+  if (cleaned.split("/").some((seg) => seg === "..")) {
+    throw new Error(`[mado:static] pathname traversal not allowed: ${pathname}`);
+  }
+  const target = resolve(root, cleaned, "index.html");
+  const rootAbs = resolve(root) + sep;
+  if (!target.startsWith(rootAbs)) {
+    throw new Error(`[mado:static] pathname escapes deployment root: ${pathname}`);
+  }
+  // Use forward slashes inside join so cross-platform output is stable.
+  return target;
+}
+
+function sitemap(records, site, base) {
+  const origin = (site ?? "").replace(/\/+$/, "");
+  const prefix = ((base ?? "/") || "/").replace(/\/+$/, "");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${records
+  .map((record) => {
+    const pathname = record.pathname === "/" ? "" : record.pathname;
+    const loc = `${origin}${prefix}${pathname}` || "/";
+    return `  <url><loc>${escapeXml(loc)}</loc></url>`;
+  })
+  .join("\n")}
+</urlset>
+`;
+}
+
+// Silence the unused-import linter for the helpers we still re-export.
+void relative;

package/scripts/static/serialize.mjs

@@ -0,0 +1,212 @@
+/**
+ * Strict JsonValue validator.
+ *
+ * Mirrors the public `JsonValue` type from src/page.ts: only null,
+ * booleans, finite numbers, strings, plain arrays and plain object trees
+ * are allowed. Forbidden shapes (Date, Map, Set, class instances, NaN,
+ * Infinity, undefined values, functions, symbols, bigints, cycles,
+ * non-plain prototypes) are reported with a path-aware error so a static
+ * route author can find the bad field immediately.
+ *
+ *   [mado:static] /products/keyboard:
+ *     seed.product.createdAt is Date; expected JsonValue.
+ *
+ * `JSON.stringify()` alone is too forgiving — Date coerces to a string,
+ * Map serialises as `{}`, undefined fields silently disappear — so the
+ * snapshot would look "fine" at build time but mismatch the runtime
+ * shape on the first SPA navigation. The custom walker stops the bad
+ * value before it ever reaches the snapshot HTML.
+ */
+function describeNonJson(value) {
+  if (value === undefined) return "undefined";
+  if (value === null) return "null";
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return Number.isNaN(value) ? "NaN" : "Infinity";
+  }
+  if (typeof value === "bigint") return "bigint";
+  if (typeof value === "symbol") return "symbol";
+  if (typeof value === "function") return "function";
+  if (Array.isArray(value)) return "Array";
+  if (value instanceof Date) return "Date";
+  if (typeof Map !== "undefined" && value instanceof Map) return "Map";
+  if (typeof Set !== "undefined" && value instanceof Set) return "Set";
+  if (typeof RegExp !== "undefined" && value instanceof RegExp) return "RegExp";
+  if (typeof URL !== "undefined" && value instanceof URL) return "URL";
+  if (ArrayBuffer.isView?.(value)) return value.constructor?.name ?? "TypedArray";
+  if (value instanceof ArrayBuffer) return "ArrayBuffer";
+  if (value && typeof value === "object") {
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== null && proto !== Object.prototype) {
+      return value.constructor?.name ?? "non-plain object";
+    }
+    return "object";
+  }
+  return typeof value;
+}
+
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+
+/**
+ * Walk a value and throw on the first non-JsonValue shape. `seen`
+ * tracks containers to catch cycles deterministically (Set keyed by
+ * identity).
+ */
+function walkJsonValue(value, path, contextLabel, seen) {
+  if (value === null) return;
+  const t = typeof value;
+  if (t === "boolean" || t === "string") return;
+  if (t === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error(
+        `[mado:static] ${contextLabel}: ${path} is ${
+          Number.isNaN(value) ? "NaN" : "Infinity"
+        }; expected JsonValue.`,
+      );
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      throw new Error(
+        `[mado:static] ${contextLabel}: ${path} contains a circular reference; expected JsonValue.`,
+      );
+    }
+    seen.add(value);
+    for (let i = 0; i < value.length; i++) {
+      walkJsonValue(value[i], `${path}[${i}]`, contextLabel, seen);
+    }
+    seen.delete(value);
+    return;
+  }
+  if (isPlainObject(value)) {
+    if (seen.has(value)) {
+      throw new Error(
+        `[mado:static] ${contextLabel}: ${path} contains a circular reference; expected JsonValue.`,
+      );
+    }
+    seen.add(value);
+    for (const key of Object.keys(value)) {
+      const child = value[key];
+      // `undefined` would silently disappear through JSON.stringify; we
+      // reject it explicitly so the schema stays honest. To omit a field
+      // simply do not include the key.
+      if (child === undefined) {
+        throw new Error(
+          `[mado:static] ${contextLabel}: ${path}.${key} is undefined; ` +
+            `expected JsonValue. Omit the key instead of assigning undefined.`,
+        );
+      }
+      walkJsonValue(child, `${path}.${key}`, contextLabel, seen);
+    }
+    seen.delete(value);
+    return;
+  }
+  throw new Error(
+    `[mado:static] ${contextLabel}: ${path} is ${describeNonJson(value)}; ` +
+      `expected JsonValue.`,
+  );
+}
+
+/**
+ * Throw if `value` is not a strict JsonValue (see walkJsonValue).
+ * `contextLabel` is included in every error so the discovery output can
+ * point a user at the failing route or pathname.
+ */
+export function assertJsonSerializable(value, contextLabel) {
+  walkJsonValue(value, "seed", contextLabel, new Set());
+}
+
+export function serializeJsonForScript(value, contextLabel) {
+  assertJsonSerializable(value, contextLabel);
+  // The validator guarantees JSON.stringify cannot drop, coerce or
+  // silently expand anything, so the resulting string is exactly the
+  // shape page.head/load will receive on first client boot.
+  const json = JSON.stringify(value);
+  if (json === undefined) {
+    // Should be unreachable after assertJsonSerializable; defensive.
+    throw new Error(
+      `[mado:static] ${contextLabel}: top-level value cannot be serialized as JSON.`,
+    );
+  }
+  return json
+    .replace(/</g, "\\u003C")
+    .replace(/>/g, "\\u003E")
+    .replace(/&/g, "\\u0026")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}
+
+/**
+ * Prepare the shell HTML for browser capture of a single route.
+ *
+ * Two CSP-safe markers are injected:
+ *   1. `data-mado-static-capture` on the <html> tag — the runtime checks
+ *      that attribute (and removes it before serialization) instead of
+ *      relying on an inline script that strict CSP would block.
+ *   2. `<script type="application/json" data-mado-static-data="${pathname}">`
+ *      carrying the build-time seed. The runtime consumes it once, the
+ *      serializer preserves it in the final snapshot, and the real client
+ *      boot consumes it again on first load.
+ *
+ * The seed is URL-bound through the `data-mado-static-data` attribute so
+ * SPA navigations to other routes (or accidentally cached copies) cannot
+ * reuse a stale value.
+ */
+export function injectSnapshotMode(html, record) {
+  let out = setHtmlAttribute(html, "data-mado-static-capture", "");
+  if ("initialData" in record) {
+    const seedScript =
+      `<script type="application/json" data-mado-static-data="${escapeAttr(record.pathname)}">` +
+      serializeJsonForScript(record.initialData, record.pathname) +
+      `</script>`;
+    out = injectAfterHeadOpen(out, seedScript);
+  }
+  return out;
+}
+
+function setHtmlAttribute(html, name, value) {
+  const match = /<html\b([^>]*)>/i.exec(html);
+  if (!match) return html;
+  const attrs = match[1] ?? "";
+  if (new RegExp(`\\b${name}\\b`, "i").test(attrs)) return html;
+  const replacement = `<html${attrs} ${name}="${escapeAttr(value)}">`;
+  return html.slice(0, match.index) + replacement + html.slice(match.index + match[0].length);
+}
+
+function escapeAttr(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+export function addNoIndex(html) {
+  if (/<meta\s+[^>]*(?:name=["']robots["']|content=["'][^"']*noindex)/i.test(html)) {
+    return html;
+  }
+  return injectAfterHeadOpen(
+    html,
+    `<meta name="robots" content="noindex">`,
+  );
+}
+
+export function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function injectAfterHeadOpen(html, content) {
+  const match = /<head\b[^>]*>/i.exec(html);
+  if (!match) return content + html;
+  const at = match.index + match[0].length;
+  return html.slice(0, at) + content + html.slice(at);
+}