create-ailk 0.7.0 → 0.9.0

package/dist/lib/module-tier.d.ts

@@ -1,19 +1,3 @@
-/**
- * Free vs paid module classification (K1, #5089 — REL-015.3 "AI Launch Kit —
- * Commercial line", D-17 "Flavor 3").
- *
- * The commercial line is decided: the paid modules do NOT ship on public npm
- * — delivery itself is the gate. `create-ailk` scaffolds Free's modules from
- * `templates/` with no key (today's path, unchanged); a paid module is
- * FETCHED from the internal module distribution when `AILK_LICENSE_KEY`
- * verifies (see `fetch-module.ts` + `module-license-gate.ts`).
- *
- * `FREE_MODULES` is the one hand-authored list (today just `marketing`, the
- * always-available default). `PAID_MODULES` is derived from it — every other
- * `RECOGNIZED_MODULES` entry — so adding a new module to the vocabulary
- * (`parse-args.ts`) defaults it to "paid" until someone deliberately adds it
- * to `FREE_MODULES`, rather than silently shipping it free.
- */
 import { type ModuleName } from "../parse-args.js";
 /** Modules scaffolded from `templates/` with no license — today's free path. */
 export declare const FREE_MODULES: readonly ModuleName[];
@@ -24,6 +8,51 @@ export declare const FREE_MODULES: readonly ModuleName[];
  * from `RECOGNIZED_MODULES` silently.
  */
 export declare const PAID_MODULES: readonly ModuleName[];
+/**
+ * The levels a key can be at (#6759 D2). A value, never read from a flag, a
+ * manifest or a key claim — it is always DERIVED, by `deriveLevel`
+ * (`module-license-gate.ts`), from what the registry actually answers.
+ */
+export declare const LEVELS: readonly ["free", "pro", "pro-plus"];
+export type Level = (typeof LEVELS)[number];
+export declare const LEVEL_LABEL: Readonly<Record<Level, string>>;
+/**
+ * Bought per site on top of a paid level — never switched on BY a level
+ * (OFFERINGS §4a). Naming one in `--modules` adds it without trimming
+ * (`composeModuleSet`), and it is refused below Pro naming the level it is
+ * an add-on ON TOP of.
+ */
+export declare const ADD_ONS: readonly ModuleName[];
+/**
+ * Included at Pro and above (the licence manifest's `pro` tier), but not
+ * switched on by default at any level (D1) — an authed app surface
+ * contributing no PUBLIC page to a marketing site. Naming it in `--modules`
+ * adds it without trimming, exactly like an add-on.
+ */
+export declare const OPT_IN_MODULES: readonly ModuleName[];
+/**
+ * What a key at each level switches on with no `--modules` (D2). Derived —
+ * every list is `RECOGNIZED_MODULES.filter(...)`, so declaration order is
+ * preserved and a module added to the vocabulary later lands in `pro` by
+ * derivation (loud: `module-tier.test.ts`'s table test pins the exact sets).
+ */
+export declare const LEVEL_MODULES: Readonly<Record<Level, readonly ModuleName[]>>;
+/**
+ * Which level (or add-on status) a module belongs to (D2). `"free"` for
+ * `FREE_MODULES`, `"add-on"` for `ADD_ONS`, `"pro-plus"` for
+ * `PRO_PLUS_MODULES`, else `"pro"` (`workspace` included — D1). Pure.
+ */
+export declare function levelOf(m: ModuleName): Level | "add-on";
+/**
+ * The pure core of FR-2/FR-3 (D2): compose the effective module set from
+ * what `--modules` named and the key's derived level. Naming any module that
+ * is not an addition (`ADDITIONS`) is a KEEP — it names exactly the set,
+ * unchanged from today (NFR-2), and the level plays no part. Naming only
+ * additions (or nothing) takes the level's default plus those additions.
+ * Never refuses — refusals belong to the gate (`resolveModuleSet`), because
+ * whether a named module is covered is a registry answer, not a table lookup.
+ */
+export declare function composeModuleSet(named: readonly ModuleName[] | undefined, level: Level): ModuleName[];
 export interface ModuleClassification {
     free: ModuleName[];
     paid: ModuleName[];

package/dist/lib/module-tier.js

@@ -14,6 +14,7 @@
  * (`parse-args.ts`) defaults it to "paid" until someone deliberately adds it
  * to `FREE_MODULES`, rather than silently shipping it free.
  */
+import { normalizeModules } from "../module-architecture.js";
 import { RECOGNIZED_MODULES } from "../parse-args.js";
 /** Modules scaffolded from `templates/` with no license — today's free path. */
 export const FREE_MODULES = ["marketing"];
@@ -24,6 +25,81 @@ export const FREE_MODULES = ["marketing"];
  * from `RECOGNIZED_MODULES` silently.
  */
 export const PAID_MODULES = RECOGNIZED_MODULES.filter((m) => !FREE_MODULES.includes(m));
+/**
+ * The levels a key can be at (#6759 D2). A value, never read from a flag, a
+ * manifest or a key claim — it is always DERIVED, by `deriveLevel`
+ * (`module-license-gate.ts`), from what the registry actually answers.
+ */
+export const LEVELS = ["free", "pro", "pro-plus"];
+export const LEVEL_LABEL = {
+    free: "Free",
+    pro: "Pro",
+    "pro-plus": "Pro Plus",
+};
+/**
+ * Bought per site on top of a paid level — never switched on BY a level
+ * (OFFERINGS §4a). Naming one in `--modules` adds it without trimming
+ * (`composeModuleSet`), and it is refused below Pro naming the level it is
+ * an add-on ON TOP of.
+ */
+export const ADD_ONS = ["commerce"];
+/**
+ * Included at Pro and above (the licence manifest's `pro` tier), but not
+ * switched on by default at any level (D1) — an authed app surface
+ * contributing no PUBLIC page to a marketing site. Naming it in `--modules`
+ * adds it without trimming, exactly like an add-on.
+ */
+export const OPT_IN_MODULES = ["workspace"];
+/** The Pro Plus membership: what Pro Plus switches on beyond Pro. */
+const PRO_PLUS_MODULES = ["multi-tenant"];
+/** Named modules that never trim the level default when composing a set (D2). */
+const ADDITIONS = [...ADD_ONS, ...OPT_IN_MODULES];
+const PRO_EXCLUDED = new Set([...ADDITIONS, ...PRO_PLUS_MODULES]);
+/**
+ * What a key at each level switches on with no `--modules` (D2). Derived —
+ * every list is `RECOGNIZED_MODULES.filter(...)`, so declaration order is
+ * preserved and a module added to the vocabulary later lands in `pro` by
+ * derivation (loud: `module-tier.test.ts`'s table test pins the exact sets).
+ */
+export const LEVEL_MODULES = Object.freeze({
+    free: [...FREE_MODULES],
+    pro: RECOGNIZED_MODULES.filter((m) => FREE_MODULES.includes(m) ||
+        (PAID_MODULES.includes(m) && !PRO_EXCLUDED.has(m))),
+    "pro-plus": RECOGNIZED_MODULES.filter((m) => FREE_MODULES.includes(m) ||
+        (PAID_MODULES.includes(m) && !ADDITIONS.includes(m))),
+});
+/**
+ * Which level (or add-on status) a module belongs to (D2). `"free"` for
+ * `FREE_MODULES`, `"add-on"` for `ADD_ONS`, `"pro-plus"` for
+ * `PRO_PLUS_MODULES`, else `"pro"` (`workspace` included — D1). Pure.
+ */
+export function levelOf(m) {
+    if (FREE_MODULES.includes(m))
+        return "free";
+    if (ADD_ONS.includes(m))
+        return "add-on";
+    if (PRO_PLUS_MODULES.includes(m))
+        return "pro-plus";
+    return "pro";
+}
+/**
+ * The pure core of FR-2/FR-3 (D2): compose the effective module set from
+ * what `--modules` named and the key's derived level. Naming any module that
+ * is not an addition (`ADDITIONS`) is a KEEP — it names exactly the set,
+ * unchanged from today (NFR-2), and the level plays no part. Naming only
+ * additions (or nothing) takes the level's default plus those additions.
+ * Never refuses — refusals belong to the gate (`resolveModuleSet`), because
+ * whether a named module is covered is a registry answer, not a table lookup.
+ */
+export function composeModuleSet(named, level) {
+    const namedList = [...(named ?? [])];
+    const keep = namedList.filter((m) => !ADDITIONS.includes(m));
+    if (keep.length > 0) {
+        return normalizeModules(namedList);
+    }
+    const add = namedList.filter((m) => ADDITIONS.includes(m));
+    return normalizeModules([...LEVEL_MODULES[level], ...add]);
+}
 /**
  * Split a requested (already-validated, `ModuleName`) module set into its
  * free and paid subsets, each preserving the input's relative order.

package/dist/lib/pro-callout.js

@@ -9,7 +9,7 @@
  * and a licensed install already owns the tier it pitches.
  */
 import { normalizeModules } from "../module-architecture.js";
-import { resolveTemplate } from "../template-manifest.js";
+import { SHAPE_STARTERS, resolveTemplate } from "../template-manifest.js";
 import { classifyModules } from "./module-tier.js";
 export function proCallout() {
     return [
@@ -34,7 +34,15 @@ export const LICENSED_PREREQUISITES_NOTE = "No database and no vendor API key ar
  * `templateDelivery` derives "paid" from `requires` alone.
  */
 export function isLicensedInstall(opts) {
-    const requires = opts.template !== undefined ? resolveTemplate(opts.template).requires : [];
+    // #6757 D6 row 4 — a bare-shape starter's name (the shape itself, passed
+    // here after #6754 D4 item 3 resolves it) is looked up through
+    // SHAPE_STARTERS first; `resolveTemplate` alone throws `unknown template`
+    // for one (NFR-3).
+    const requires = opts.template !== undefined
+        ? Object.prototype.hasOwnProperty.call(SHAPE_STARTERS, opts.template)
+            ? SHAPE_STARTERS[opts.template].requires
+            : resolveTemplate(opts.template).requires
+        : [];
     const modules = normalizeModules([
         ...requires,
         ...(opts.modules ?? ["marketing"]),

package/dist/lib/render-verdict.d.ts

@@ -0,0 +1,52 @@
+/** What the driver observed of one route's render. */
+export interface RenderObservation {
+    /** The requested route, e.g. `/` or `/about`. */
+    route: string;
+    /** The message `page.goto` threw with, when it threw. */
+    gotoError?: string;
+    /** The status of the response `page.goto` resolved; undefined when it resolved none. */
+    status: number | undefined;
+    /** `page.url()` after navigation settled. */
+    finalUrl: string;
+    /** The screenshot's size on disk; undefined when none was written. */
+    pngBytes: number | undefined;
+}
+export type RenderVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Decide whether `route` rendered. Checked in order: a navigation error (a
+ * net error — `ERR_TOO_MANY_REDIRECTS` included — or a timeout), a final
+ * status other than 200, a final pathname other than the requested route (a
+ * redirect elsewhere is not a render of this route), and a missing or empty
+ * PNG. Pathnames are compared, never whole URLs, so a query or hash is fine.
+ */
+export declare function assessRender(observation: RenderObservation): RenderVerdict;
+/** The slice of a Playwright `Page` that `renderRoute` uses. */
+export interface RenderPage {
+    goto(url: string, options: {
+        waitUntil: "load";
+        timeout: number;
+    }): Promise<{
+        status(): number;
+    } | null>;
+    url(): string;
+    screenshot(options: {
+        path: string;
+        fullPage: boolean;
+    }): Promise<unknown>;
+}
+/** How long one navigation may take before it counts as a failed render. */
+export declare const RENDER_TIMEOUT_MS = 60000;
+/**
+ * Navigate `page` to `base + route`, screenshot it to `pngPath`, and return
+ * `assessRender`'s verdict on what happened. `status` comes from the response
+ * `page.goto` itself resolved and `finalUrl` from `page.url()` — never the
+ * requested URL, never a side `fetch` — so a redirect cannot pass as a render.
+ * A failed navigation takes no screenshot; a screenshot that throws counts
+ * as no PNG written — never a stale one left at `pngPath` by an earlier run.
+ */
+export declare function renderRoute(page: RenderPage, base: string, route: string, pngPath: string): Promise<RenderVerdict>;

package/dist/lib/render-verdict.js

@@ -0,0 +1,77 @@
+/**
+ * The verdict on one browser render of a scaffold route (#6821, spec
+ * docs/specs/6821-the-shape-design-render-matrix-spec.md D4).
+ *
+ * A design leg of `scripts/verify-scaffold.mjs` renders its scaffold's home
+ * route and one inner route in Chromium and stores a screenshot of each — the
+ * shape × design render matrix. A render that did not happen must fail the
+ * leg, and proving that rule must not cost a scaffold build, so it lives here
+ * as a pure function (`assessRender`, the `api-boot-assertion.ts` precedent)
+ * plus the one function that gathers its facts (`renderRoute`), which touches
+ * Playwright only through the `page` it is handed. The driver loads both from
+ * `dist/`; `__tests__/verify-scaffold-render.test.ts` drives them with a fake
+ * page. Nothing here imports `@playwright/test`.
+ */
+import { existsSync, rmSync, statSync } from "node:fs";
+/**
+ * Decide whether `route` rendered. Checked in order: a navigation error (a
+ * net error — `ERR_TOO_MANY_REDIRECTS` included — or a timeout), a final
+ * status other than 200, a final pathname other than the requested route (a
+ * redirect elsewhere is not a render of this route), and a missing or empty
+ * PNG. Pathnames are compared, never whole URLs, so a query or hash is fine.
+ */
+export function assessRender(observation) {
+    const { route, gotoError, status, finalUrl, pngBytes } = observation;
+    if (gotoError !== undefined) {
+        return { ok: false, reason: `navigation failed: ${gotoError}` };
+    }
+    if (status !== 200) {
+        return {
+            ok: false,
+            reason: status === undefined ? "navigation resolved no response" : `final status ${status}, expected 200`,
+        };
+    }
+    const finalPath = new URL(finalUrl).pathname;
+    if (finalPath !== route) {
+        return { ok: false, reason: `requested "${route}" but the page settled on "${finalPath}"` };
+    }
+    if (typeof pngBytes !== "number" || pngBytes <= 0) {
+        return { ok: false, reason: pngBytes === 0 ? "the screenshot PNG is empty" : "no screenshot PNG was written" };
+    }
+    return { ok: true };
+}
+/** How long one navigation may take before it counts as a failed render. */
+export const RENDER_TIMEOUT_MS = 60_000;
+/**
+ * Navigate `page` to `base + route`, screenshot it to `pngPath`, and return
+ * `assessRender`'s verdict on what happened. `status` comes from the response
+ * `page.goto` itself resolved and `finalUrl` from `page.url()` — never the
+ * requested URL, never a side `fetch` — so a redirect cannot pass as a render.
+ * A failed navigation takes no screenshot; a screenshot that throws counts
+ * as no PNG written — never a stale one left at `pngPath` by an earlier run.
+ */
+export async function renderRoute(page, base, route, pngPath) {
+    let status;
+    try {
+        const response = await page.goto(base + route, { waitUntil: "load", timeout: RENDER_TIMEOUT_MS });
+        status = response === null ? undefined : response.status();
+    }
+    catch (err) {
+        return assessRender({
+            route,
+            gotoError: err instanceof Error ? err.message : String(err),
+            status: undefined,
+            finalUrl: page.url(),
+            pngBytes: undefined,
+        });
+    }
+    rmSync(pngPath, { force: true });
+    try {
+        await page.screenshot({ path: pngPath, fullPage: true });
+    }
+    catch {
+        // Falls through to the missing-PNG check below.
+    }
+    const pngBytes = existsSync(pngPath) ? statSync(pngPath).size : undefined;
+    return assessRender({ route, status, finalUrl: page.url(), pngBytes });
+}

package/dist/lib/scaffold-render-sweep.d.ts

@@ -0,0 +1,105 @@
+/** One redirect the driver followed: the status and the raw `Location`. */
+export interface RedirectHop {
+    status: number;
+    location: string | null;
+}
+export interface SweepVerdict {
+    ok: boolean;
+    reason: string;
+}
+/** A passing page verdict names the own-content marker that matched. */
+export interface PageRenderVerdict extends SweepVerdict {
+    marker?: PageMarker;
+}
+export type PageMarker = "h1" | "auth-card" | "sign-in-gate";
+/** More hops than this is a redirect chain, not a render. */
+export declare const MAX_REDIRECTS = 5;
+/**
+ * Routes that are correct to answer 404 in every leg, and the licence claim
+ * that gates them. No leg's served app holds a signed licence — the driver
+ * scrubs `AILK_LICENSE_KEY`, and the mock key is a fixture string, not a JWT —
+ * so each entry must answer exactly 404. A 200 means the gate stopped gating.
+ */
+export declare const CLAIM_GATED_ROUTES: Readonly<Record<string, string>>;
+/**
+ * A route whose live page needs an env var the driver never sets (#6146).
+ * While it is unset the route serves its Free placeholder seed instead
+ * (#6942): a 200 whose `<h1>` carries the `CONFIG_GATED_PLACEHOLDERS`
+ * heading. A 404 is the bug — the site's own nav link dead — and a rendered
+ * page without that heading means the gate stopped gating. Unlike
+ * `CLAIM_GATED_ROUTES`, a route absent from the route table is not stale: the
+ * module that owns it may simply not be installed in this leg.
+ */
+export declare const CONFIG_GATED_ROUTES: Readonly<Record<string, string>>;
+/**
+ * The placeholder heading each `CONFIG_GATED_ROUTES` entry renders while its
+ * env var is unset — for `/meet`, the hero headline of the overlay's
+ * `content/en/LandingPage/meet.mdx` seed. A fresh scaffold never edits it.
+ */
+export declare const CONFIG_GATED_PLACEHOLDERS: Readonly<Record<string, string>>;
+/** Reachability only — for routes that are not pages (`/og`, `/llms.txt`, …). */
+export declare function assessRouteStatus(input: {
+    route: string;
+    hops: RedirectHop[];
+    status: number | null;
+}): SweepVerdict;
+/**
+ * A `CLAIM_GATED_ROUTES` entry: it must be in the route table (a missing one
+ * is stale) and answer exactly 404.
+ */
+export declare function assessClaimGatedRoute(input: {
+    route: string;
+    routeTable: string[];
+    hops: RedirectHop[];
+    status: number | null;
+}): SweepVerdict;
+/**
+ * Decide whether a page route rendered, under the real locale, with its own
+ * content. The first failed rule is the reason:
+ *
+ * 1. no self-redirect, and at most `MAX_REDIRECTS` hops;
+ * 2. a final 200;
+ * 3. an HTML response;
+ * 4. `<html lang>` equal to `locale` — a page under a bogus locale fails;
+ * 5. no streamed error or not-found digest;
+ * 6. an own-content marker — a non-empty `<h1>` (a content page), an
+ *    `auth-card` testid (an `(auth)` page), or a `sign-in-gate` testid (an
+ *    `(authed)` page seen anonymously). The layout carries none of them.
+ */
+export declare function assessPageRender(input: {
+    route: string;
+    hops: RedirectHop[];
+    status: number | null;
+    contentType: string | null;
+    html: string;
+    locale: string;
+}): PageRenderVerdict;
+/**
+ * A `CONFIG_GATED_ROUTES` entry. Unlike `assessClaimGatedRoute`, a route
+ * absent from the route table is not stale — the module that owns it may
+ * simply not be installed in this leg — so it PASSES, skipped, with no
+ * network call needed to decide that (mirroring how `assessClaimGatedRoute`
+ * is called with sentinel `hops`/`status` for its own absent case, never
+ * fetched). Once the route IS present it is scored as an ordinary page via
+ * `assessPageRender`; with its gating env var unset it must ALSO be the
+ * placeholder — an `<h1>` carrying its `CONFIG_GATED_PLACEHOLDERS` heading.
+ * Every failure with the env var unset names it, pinning the cause.
+ */
+export declare function assessConfigGatedRoute(input: {
+    route: string;
+    envVar: string;
+    envSet: boolean;
+    routeTable: string[];
+    hops: RedirectHop[];
+    status: number | null;
+    contentType: string | null;
+    html: string;
+    locale: string;
+}): SweepVerdict;
+/**
+ * Every FILE under `dir`, recursing into directories, as sorted slash-joined
+ * paths relative to it — so `public/.well-known/security.txt` is listed and
+ * the `.well-known` directory never is. Anything that is neither (a symlink,
+ * a socket) throws rather than being silently followed or skipped.
+ */
+export declare function listPublicFiles(dir: string): string[];

package/dist/lib/scaffold-render-sweep.js

@@ -0,0 +1,236 @@
+/**
+ * The verdicts of the scaffold render sweep (#6146).
+ *
+ * `scripts/verify-scaffold.mjs` serves a built scaffold and fetches every
+ * declared route. Until #6146 it served on `-H 127.0.0.1`, which made Next
+ * proxy next-intl's locale rewrite as an EXTERNAL one back into the same
+ * server, so every locale page answered a 307 to itself — and the driver
+ * recorded each as a "known gap" and passed. No request in a leg rendered a
+ * page, and a scaffold that 500'd on every page (#6107) stayed green.
+ *
+ * The rules that decide whether a route really rendered live here, apart from
+ * the driver, for the reason `api-boot-assertion.ts` does: proving them must
+ * not cost a templates build, an install and a `next build`. Each is a pure
+ * function of what the driver observed, so
+ * `__tests__/verify-scaffold-render-sweep.test.ts` drives them directly. The
+ * driver loads this module from `dist/`. Only `listPublicFiles` touches the
+ * filesystem, and none of it touches the network.
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+/** More hops than this is a redirect chain, not a render. */
+export const MAX_REDIRECTS = 5;
+/**
+ * Routes that are correct to answer 404 in every leg, and the licence claim
+ * that gates them. No leg's served app holds a signed licence — the driver
+ * scrubs `AILK_LICENSE_KEY`, and the mock key is a fixture string, not a JWT —
+ * so each entry must answer exactly 404. A 200 means the gate stopped gating.
+ */
+export const CLAIM_GATED_ROUTES = {
+    "/purchase/success": "commerce",
+    "/purchase/cancel": "commerce",
+};
+/**
+ * A route whose live page needs an env var the driver never sets (#6146).
+ * While it is unset the route serves its Free placeholder seed instead
+ * (#6942): a 200 whose `<h1>` carries the `CONFIG_GATED_PLACEHOLDERS`
+ * heading. A 404 is the bug — the site's own nav link dead — and a rendered
+ * page without that heading means the gate stopped gating. Unlike
+ * `CLAIM_GATED_ROUTES`, a route absent from the route table is not stale: the
+ * module that owns it may simply not be installed in this leg.
+ */
+export const CONFIG_GATED_ROUTES = {
+    "/meet": "SCHEDULING_CAL_LINK",
+};
+/**
+ * The placeholder heading each `CONFIG_GATED_ROUTES` entry renders while its
+ * env var is unset — for `/meet`, the hero headline of the overlay's
+ * `content/en/LandingPage/meet.mdx` seed. A fresh scaffold never edits it.
+ */
+export const CONFIG_GATED_PLACEHOLDERS = {
+    "/meet": "{Book a time with us}",
+};
+const LOOPBACK_BASE = "http://localhost";
+function pathnameOf(location, relativeTo) {
+    return new URL(location, new URL(relativeTo, LOOPBACK_BASE)).pathname;
+}
+/**
+ * Rules 1 and 2 of every verdict: no self-redirect, at most `MAX_REDIRECTS`
+ * hops, and a final 200. A hop is a self-redirect when its `Location`
+ * pathname equals the pathname that hop answered — the route itself for the
+ * first hop, the previous hop's target after that. Query and host are not
+ * compared: the next-intl loop this catches differs from its request in
+ * neither.
+ */
+function assessReachable(route, hops, status) {
+    let answered = route;
+    for (const hop of hops) {
+        if (hop.location === null)
+            break;
+        const target = pathnameOf(hop.location, answered);
+        if (target === new URL(answered, LOOPBACK_BASE).pathname) {
+            return { ok: false, reason: `${answered} -> ${hop.status} self-redirect` };
+        }
+        answered = target;
+    }
+    if (hops.length > MAX_REDIRECTS) {
+        return { ok: false, reason: `${route} -> redirect chain of more than ${MAX_REDIRECTS} hops` };
+    }
+    if (status !== 200)
+        return { ok: false, reason: `${route} -> status ${status}` };
+    return { ok: true, reason: "200" };
+}
+/** Reachability only — for routes that are not pages (`/og`, `/llms.txt`, …). */
+export function assessRouteStatus(input) {
+    return assessReachable(input.route, input.hops, input.status);
+}
+/**
+ * A `CLAIM_GATED_ROUTES` entry: it must be in the route table (a missing one
+ * is stale) and answer exactly 404.
+ */
+export function assessClaimGatedRoute(input) {
+    const { route, routeTable, hops, status } = input;
+    const claim = CLAIM_GATED_ROUTES[route];
+    if (!routeTable.some((r) => (r.replace("/[locale]", "") || "/") === route)) {
+        return { ok: false, reason: `${route} -> stale CLAIM_GATED_ROUTES entry: not in the route table` };
+    }
+    if (hops.length > 0 || status !== 404) {
+        const first = hops[0];
+        const seen = first ? `${first.status} redirect` : `status ${status}`;
+        const why = status === 200 ? "gate open in a keyless serve" : `expected 404, got ${seen}`;
+        return { ok: false, reason: `${route} -> ${why} (claim-gated: ${claim})` };
+    }
+    return { ok: true, reason: `404 (claim-gated: ${claim})` };
+}
+/** The `lang` of the document's `<html>` element, or null when it has none. */
+function htmlLang(html) {
+    return /<html\b[^>]*\slang="([^"]*)"/i.exec(html)?.[1] ?? null;
+}
+/**
+ * The first React Server Components error digest in the flight payload, or
+ * null. It is serialized inside a script string as `\"digest\":\"<value>\"`.
+ * An error or not-found boundary streamed after the shell answers 200 and can
+ * carry its own `<h1>`; this entry is the one reliable trace it leaves.
+ */
+function flightDigest(html) {
+    return /\\"digest\\":\\"([^"\\]*)\\"/.exec(html)?.[1] ?? null;
+}
+/**
+ * Whether an `<h1>`'s inner HTML carries a name: text once tags are stripped,
+ * or an image with a non-empty `alt` (the Hero's lockup renders the wordmark
+ * inside the `<h1>`, and the heading takes its accessible name from it).
+ */
+function headingHasName(inner) {
+    if (inner.replace(/<[^>]*>/g, "").trim() !== "")
+        return true;
+    return [...inner.matchAll(/<img\b[^>]*\salt="([^"]*)"/gi)].some((m) => (m[1] ?? "").trim() !== "");
+}
+/** The first own-content marker the page carries, in the order checked. */
+function ownContentMarker(html) {
+    for (const m of html.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi)) {
+        if (headingHasName(m[1] ?? ""))
+            return "h1";
+    }
+    if (html.includes('data-testid="auth-card"'))
+        return "auth-card";
+    if (html.includes('data-testid="sign-in-gate'))
+        return "sign-in-gate";
+    return null;
+}
+/**
+ * Decide whether a page route rendered, under the real locale, with its own
+ * content. The first failed rule is the reason:
+ *
+ * 1. no self-redirect, and at most `MAX_REDIRECTS` hops;
+ * 2. a final 200;
+ * 3. an HTML response;
+ * 4. `<html lang>` equal to `locale` — a page under a bogus locale fails;
+ * 5. no streamed error or not-found digest;
+ * 6. an own-content marker — a non-empty `<h1>` (a content page), an
+ *    `auth-card` testid (an `(auth)` page), or a `sign-in-gate` testid (an
+ *    `(authed)` page seen anonymously). The layout carries none of them.
+ */
+export function assessPageRender(input) {
+    const { route, hops, status, contentType, html, locale } = input;
+    const reachable = assessReachable(route, hops, status);
+    if (!reachable.ok)
+        return reachable;
+    if (!(contentType ?? "").startsWith("text/html")) {
+        return { ok: false, reason: `${route} -> not html (${contentType})` };
+    }
+    const lang = htmlLang(html);
+    if (lang !== locale)
+        return { ok: false, reason: `${route} -> rendered under locale "${lang}"` };
+    const digest = flightDigest(html);
+    if (digest !== null) {
+        const why = digest.startsWith("NEXT_HTTP_ERROR_FALLBACK;404")
+            ? "streamed not-found"
+            : `streamed error (digest ${digest})`;
+        return { ok: false, reason: `${route} -> ${why}` };
+    }
+    const marker = ownContentMarker(html);
+    if (marker === null) {
+        return { ok: false, reason: `${route} -> no own content (no <h1>, auth-card or sign-in-gate)` };
+    }
+    return { ok: true, reason: marker, marker };
+}
+/**
+ * A `CONFIG_GATED_ROUTES` entry. Unlike `assessClaimGatedRoute`, a route
+ * absent from the route table is not stale — the module that owns it may
+ * simply not be installed in this leg — so it PASSES, skipped, with no
+ * network call needed to decide that (mirroring how `assessClaimGatedRoute`
+ * is called with sentinel `hops`/`status` for its own absent case, never
+ * fetched). Once the route IS present it is scored as an ordinary page via
+ * `assessPageRender`; with its gating env var unset it must ALSO be the
+ * placeholder — an `<h1>` carrying its `CONFIG_GATED_PLACEHOLDERS` heading.
+ * Every failure with the env var unset names it, pinning the cause.
+ */
+export function assessConfigGatedRoute(input) {
+    const { route, envVar, envSet, routeTable, hops, status, contentType, html, locale } = input;
+    if (!routeTable.some((r) => (r.replace("/[locale]", "") || "/") === route)) {
+        return { ok: true, reason: `${route} -> skipped: not in the route table (module not installed)` };
+    }
+    const rendered = assessPageRender({ route, hops, status, contentType, html, locale });
+    if (envSet)
+        return rendered;
+    if (!rendered.ok)
+        return { ok: false, reason: `${rendered.reason} (${envVar} unset)` };
+    const placeholder = CONFIG_GATED_PLACEHOLDERS[route];
+    if (placeholder === undefined) {
+        return { ok: false, reason: `${route} -> no CONFIG_GATED_PLACEHOLDERS entry to check with ${envVar} unset` };
+    }
+    if (!headingTexts(html).some((text) => text.includes(placeholder))) {
+        return {
+            ok: false,
+            reason: `${route} -> expected the "${placeholder}" placeholder with ${envVar} unset, rendered another page`,
+        };
+    }
+    return { ok: true, reason: `placeholder (${envVar} unset)` };
+}
+/** The text of every `<h1>` in the document, tags stripped. */
+function headingTexts(html) {
+    return [...html.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi)].map((m) => (m[1] ?? "").replace(/<[^>]*>/g, ""));
+}
+/**
+ * Every FILE under `dir`, recursing into directories, as sorted slash-joined
+ * paths relative to it — so `public/.well-known/security.txt` is listed and
+ * the `.well-known` directory never is. Anything that is neither (a symlink,
+ * a socket) throws rather than being silently followed or skipped.
+ */
+export function listPublicFiles(dir) {
+    return listFilesUnder(dir, "");
+}
+function listFilesUnder(dir, relPrefix) {
+    const out = [];
+    const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1));
+    for (const entry of entries) {
+        const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            out.push(...listFilesUnder(join(dir, entry.name), rel));
+        else if (entry.isFile())
+            out.push(rel);
+        else
+            throw new Error(`public/${rel} is neither a file nor a directory`);
+    }
+    return out;
+}