@iterant/site-runtime 3.1.0 → 3.1.2

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.1.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.1.2._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.1.0",
+  "version": "3.1.2",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {

package/scripts/scan-fetch-entrypoint.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+/**
+ * Reserved-filename gate: `src/fetch.*`.
+ *
+ * Astro 7 resolves `srcDir + "fetch"` as the request-pipeline entrypoint
+ * (advanced routing): when the module resolves, its default export replaces
+ * the default fetch handler for EVERY request, in dev and in production
+ * builds alike, and a failure to resolve falls back silently. Resolution
+ * goes through Vite, so every resolvable extension counts and a `src/fetch/`
+ * directory resolves through its index file. A brand repo must never carry
+ * one: an innocently named helper would silently take over the whole request
+ * pipeline, and a broken one takes every route down with it. The platform
+ * reserves the name for a future runtime-owned shim; until that ships, the
+ * file's absence is the contract.
+ */
+
+import { readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// Vite's default resolve.extensions, which Astro does not override.
+const RESOLVABLE = /^fetch\.(mjs|js|mts|ts|jsx|tsx|json)$/;
+
+/**
+ * @param {string} rootDir
+ * @returns {Promise<string[]>}
+ */
+export async function checkFetchEntrypoint(rootDir) {
+  /** @type {import("node:fs").Dirent[]} */
+  let entries = [];
+  try {
+    entries = await readdir(join(rootDir, "src"), { withFileTypes: true });
+  } catch {
+    // No src/ at all is astro check's problem, not this gate's.
+    return [];
+  }
+  const problems = [];
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name === "fetch") {
+      problems.push(
+        "src/fetch/ is a reserved name: Astro resolves it (through its index file) " +
+          "as the request-pipeline entrypoint for every route, dev and production. " +
+          "Rename the directory.",
+      );
+      continue;
+    }
+    if (entry.isFile() && RESOLVABLE.test(entry.name)) {
+      problems.push(
+        `src/${entry.name} is a reserved filename: Astro loads it as the ` +
+          "request-pipeline entrypoint for every route, dev and production, " +
+          "replacing the platform's default handler. Rename the file.",
+      );
+    }
+  }
+  return problems;
+}
+
+// Standalone CLI: `node scripts/scan-fetch-entrypoint.mjs [rootDir]`.
+// Prints problems to stderr and exits 1 when any are found.
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
+  const problems = await checkFetchEntrypoint(
+    process.argv[2] ? resolve(process.argv[2]) : process.cwd(),
+  );
+  if (problems.length > 0) {
+    process.stderr.write(
+      `fetch-entrypoint check failed:\n${problems.join("\n")}\n`,
+    );
+    process.exit(1);
+  }
+}

package/scripts/verify.mjs

@@ -207,6 +207,19 @@ if (fontProblems.length > 0) {
   exit(1);
 }
 
+// Fetch-entrypoint gate — Astro loads src/fetch.* as the request-pipeline
+// entrypoint for EVERY route, dev and production, so an innocently named
+// helper silently takes over the whole pipeline. The check lives in
+// scan-fetch-entrypoint.mjs so its tests can exercise it on fixtures.
+const { checkFetchEntrypoint } = await import("./scan-fetch-entrypoint.mjs");
+const fetchProblems = await checkFetchEntrypoint(process.cwd());
+if (fetchProblems.length > 0) {
+  process.stderr.write(
+    `fetch-entrypoint check failed:\n${fetchProblems.join("\n")}\n`,
+  );
+  exit(1);
+}
+
 // Island-import gate — registered sections never hydrate, so an island-grade
 // ui primitive imported there ships a dead widget with zero build signal.
 // The check (direct + barrel + any-depth relative imports; type-only imports

package/src/config/preset.ts

@@ -185,6 +185,12 @@ export function iterantStarter({
       // Tunnel/preview hostnames are random per boot, so hostname
       // allow-listing is impossible; access control lives outside the dev server.
       allowedHosts,
+      // Vite 8 turns this on by itself when it sniffs an AI agent in the
+      // environment, and a forwarded browser console (any viewer with the
+      // preview open) would interleave into the process logs the platform
+      // parses for readiness and boot briefs. Pinned so a heuristic never
+      // decides the log shape; enabling it is a deliberate platform decision.
+      forwardConsole: false,
     },
   };
 

package/src/content/collections.ts

@@ -7,6 +7,7 @@ import {
   loaderBase,
 } from "../lib/content-paths";
 import { entryIdFromFile } from "../lib/locales";
+import { withDevQuarantine } from "./resilience";
 import { createContentSchemas, type ContentSchemaOptions } from "./schema";
 
 // The `pages` + `chrome` collections a brand site runs on. Astro requires the
@@ -53,7 +54,10 @@ export function createCollections({
       base: loaderBase(pagesDir),
       generateId: ({ entry }) => entryIdFromFile(entry),
     }),
-    schema: pageEntrySchema,
+    // Strict at build/verify; in dev an invalid entry is quarantined (logged
+    // in full, route degrades to an error stand-in) instead of taking the
+    // whole content sync — and with it every route of the preview — down.
+    schema: withDevQuarantine(pageEntrySchema),
   });
 
   const chrome = defineCollection({

package/src/content/resilience.ts

@@ -0,0 +1,106 @@
+import { z } from "astro/zod";
+
+// Dev-server resilience for the pages collection (3.1.1). Astro 7 treats one
+// invalid entry as fatal to the whole content sync, so a single half-finished
+// page took the ENTIRE preview down — every route, plus the save gate's boot.
+// In dev we quarantine instead: the strict schema still decides validity, the
+// violations are logged in full, and the broken entry is replaced by a
+// minimal valid stand-in (chromed page, no sections, error title) so its
+// route degrades while every other page keeps serving. Builds stay strict:
+// verify and publish reject the entry exactly as before, so nothing invalid
+// can ship.
+
+const ROUTE_PATTERN = /^\/[a-z0-9\-/]*$/;
+
+type AnyPageSchema = z.ZodTypeAny;
+
+export function isStrictContentEnv(env: NodeJS.ProcessEnv = process.env) {
+  // astro build sets NODE_ENV=production; astro dev sets development.
+  // SITE_RUNTIME_STRICT_CONTENT=1 forces build behavior in dev (escape hatch
+  // for debugging the strict path itself).
+  return (
+    env.NODE_ENV === "production" || env.SITE_RUNTIME_STRICT_CONTENT === "1"
+  );
+}
+
+// Render a ZodError as one line per violation with full paths. Zod 4 already
+// reports the informative branch of a union failure at its deep path (the
+// bare-string wrapper rule lands on e.g. components.1.props.columns.items.1
+// .key directly); genuinely ambiguous unions still collapse to one issue
+// carrying per-branch issue lists in `errors`, so those are walked.
+type UnionBranches = { errors?: z.ZodIssue[][] };
+
+function describeIssues(
+  issues: z.ZodIssue[],
+  base: PropertyKey[] = [],
+): string[] {
+  const lines: string[] = [];
+  for (const issue of issues) {
+    const path = [...base, ...issue.path];
+    const branches = (issue as UnionBranches).errors;
+    if (issue.code === "invalid_union" && Array.isArray(branches)) {
+      lines.push(...describeIssues(branches.flat(), path));
+      continue;
+    }
+    lines.push(`${path.map(String).join(".")}: ${issue.message}`);
+  }
+  return [...new Set(lines)];
+}
+
+/**
+ * Wrap the strict page-entry schema for collection use: pass-through when the
+ * entry is valid, quarantine when it is not (dev only). In a strict env
+ * (build/verify) and for an entry whose `route` field is itself unusable (it
+ * cannot be placed on a route), the original violations surface unchanged.
+ */
+export function withDevQuarantine<S extends AnyPageSchema>(
+  strict: S,
+  env: NodeJS.ProcessEnv = process.env,
+): z.ZodType<z.output<S>> {
+  const strictMode = isStrictContentEnv(env);
+  return z.unknown().transform((raw, ctx) => {
+    const parsed = strict.safeParse(raw);
+    if (parsed.success) return parsed.data as z.output<S>;
+
+    // Replay the strict schema's own issues through this pipeline — the cast
+    // bridges zod 4's public ZodIssue to addIssue's raw-issue input, which
+    // are the same objects under different declared types.
+    const surface = () => {
+      for (const issue of parsed.error.issues) {
+        ctx.addIssue(issue as never);
+      }
+      return z.NEVER;
+    };
+    if (strictMode) return surface();
+
+    const issues = describeIssues(parsed.error.issues);
+    const route =
+      raw !== null &&
+      typeof raw === "object" &&
+      "route" in raw &&
+      typeof raw.route === "string" &&
+      ROUTE_PATTERN.test(raw.route)
+        ? raw.route
+        : null;
+    if (route === null) return surface();
+
+    console.error(
+      [
+        `[site-runtime] QUARANTINED invalid page entry for route "${route}".`,
+        "The dev server keeps serving; this route renders an error stand-in",
+        "until the entry is fixed. Publish/verify still reject it. Violations:",
+        ...issues.map((line) => `  ${line}`),
+      ].join("\n"),
+    );
+
+    return strict.parse({
+      route,
+      title: "This page has a content error",
+      meta: {
+        title: "This page has a content error",
+        description: `Invalid entry quarantined in dev: ${issues.join("; ").slice(0, 400)}`,
+      },
+      components: [],
+    }) as z.output<S>;
+  });
+}