create-ailk 0.8.0 → 0.9.0

package/dist/lib/design-checks.d.ts

@@ -0,0 +1,78 @@
+/** One row of theme's contrast audit, as the audit script prints it. */
+export interface ContrastRow {
+    name: string;
+    bg: string;
+    fg: string;
+    ratio: number | null;
+    threshold: number;
+    status: "pass" | "fail" | "unmeasurable";
+}
+export type DesignContrastVerdict = {
+    ok: true;
+    pairs: number;
+} | {
+    ok: false;
+    pairs: number;
+    failing: ContrastRow[];
+    reason: string;
+};
+/**
+ * Decide whether `design`'s derived token set passes WCAG AA. Every row whose
+ * status is not `pass` fails it; an audit of no pair never passes.
+ */
+export declare function assessDesignContrast(design: string, results: ContrastRow[]): DesignContrastVerdict;
+/** `__tests__/fixtures/page-jsonld.ts`'s stdout: page path → its composed JSON-LD. */
+export type ComposedPages = Record<string, {
+    jsonld: string;
+    sectionsValid: boolean;
+}>;
+/** One changed node: the page and its JSON-pointer path (or a `(page …)` pseudo-path). */
+export interface DriftNode {
+    page: string;
+    path: string;
+}
+/**
+ * Every node that differs between two compositions, sorted by page then path.
+ * A removed or added page, and a page whose sections no longer validate after,
+ * are one pseudo-path node each; a `logo` subtree is never compared.
+ */
+export declare function jsonLdDrift(before: ComposedPages, after: ComposedPages): DriftNode[];
+export type JsonLdDriftVerdict = {
+    ok: true;
+    pages: number;
+} | {
+    ok: false;
+    pages: number;
+    changed: DriftNode[];
+    reason: string;
+};
+/** Decide whether `apply-design <design>` left every page's JSON-LD unchanged (logo excluded). */
+export declare function assessJsonLdDrift(design: string, before: ComposedPages, after: ComposedPages): JsonLdDriftVerdict;
+export interface MeasureApplyDesignDriftOptions {
+    /** create-ailk's built `dist/cli.js`. */
+    cliPath: string;
+    /** The monorepo's `tsx` binary. */
+    tsxPath: string;
+    /** `__tests__/fixtures/page-jsonld.ts` — the one production composer, run from source. */
+    composerPath: string;
+    /** Its tsconfig, passed as `TSX_TSCONFIG_PATH`. */
+    composerTsconfig: string;
+    /** The design `apply-design` applies (a name or a package path). */
+    design: string;
+    /** An existing empty directory; the drift site is scaffolded at `<workDir>/site`. */
+    workDir: string;
+    /** The loopback registry the CLI resolves modules and templates from. */
+    registryUrl?: string;
+    /** Written to the site's own `ailk.key`, which `apply-design` gates a non-Free design on. */
+    licenseKey?: string;
+}
+/**
+ * Scaffold a keyless `organization-product` site on `standard`, compose its
+ * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
+ * exit at any step throws naming the step and the child's stderr.
+ */
+export declare function measureApplyDesignDrift(opts: MeasureApplyDesignDriftOptions): {
+    before: ComposedPages;
+    after: ComposedPages;
+    applyStdout: string;
+};

package/dist/lib/design-checks.js

@@ -0,0 +1,174 @@
+/**
+ * The two design checks a design-wearing run of `scripts/verify-scaffold.mjs`
+ * runs before install (#6823, spec
+ * docs/specs/6823-the-matrix-runs-the-derived-spec.md D3).
+ *
+ * CONTRAST — `assessDesignContrast` turns the rows
+ * `packages/theme/scripts/audit-site-theme-contrast.ts` prints (theme's
+ * `auditTokenSetContrast` over the design's derived token set) into a verdict
+ * naming every non-passing `{bg, fg}` pair and the design. The WCAG math and
+ * the pair list stay theme's; this file only decides pass/fail.
+ *
+ * DRIFT — `jsonLdDrift` / `assessJsonLdDrift` compare every page's composed
+ * JSON-LD before and after `apply-design`, excluding the logo image (the PRD
+ * metric "structural drift after apply"), and `measureApplyDesignDrift`
+ * gathers the two snapshots (the `renderRoute` precedent, #6821 D4): it
+ * touches the filesystem and processes only through the paths it is handed,
+ * so the driver and `__tests__/verify-scaffold-checks.test.ts` run the same
+ * procedure. Nothing here imports `@working-theory/theme`.
+ */
+import { execFileSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+function describePair(row) {
+    const measured = row.status === "unmeasurable" || row.ratio === null
+        ? "unmeasurable"
+        : `${row.ratio.toFixed(2)}:1 < ${row.threshold}:1`;
+    return `${row.name} {bg ${row.bg}, fg ${row.fg}} ${measured}`;
+}
+/**
+ * Decide whether `design`'s derived token set passes WCAG AA. Every row whose
+ * status is not `pass` fails it; an audit of no pair never passes.
+ */
+export function assessDesignContrast(design, results) {
+    const pairs = results.length;
+    if (pairs === 0) {
+        return { ok: false, pairs, failing: [], reason: `design ${design}: no contrast pair was audited` };
+    }
+    const failing = results.filter((row) => row.status !== "pass");
+    if (failing.length === 0)
+        return { ok: true, pairs };
+    return {
+        ok: false,
+        pairs,
+        failing,
+        reason: `design ${design}: ${failing.length} of ${pairs} contrast pair(s) below WCAG AA — ${failing
+            .map(describePair)
+            .join("; ")}`,
+    };
+}
+/** schema.org's logo property — the one subtree the PRD's "excluding the logo image" skips. */
+const LOGO_KEY = "logo";
+const kindOf = (value) => value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+function walk(before, after, path, out) {
+    const kind = kindOf(before);
+    if (kind !== kindOf(after)) {
+        out.push(path);
+        return;
+    }
+    if (kind === "array") {
+        const a = before;
+        const b = after;
+        if (a.length !== b.length)
+            out.push(path);
+        for (let i = 0; i < Math.min(a.length, b.length); i++)
+            walk(a[i], b[i], `${path}/${i}`, out);
+        return;
+    }
+    if (kind === "object") {
+        const a = before;
+        const b = after;
+        for (const key of [...new Set([...Object.keys(a), ...Object.keys(b)])].sort()) {
+            if (key === LOGO_KEY)
+                continue;
+            walk(a[key], b[key], `${path}/${key}`, out);
+        }
+        return;
+    }
+    if (before !== after)
+        out.push(path);
+}
+/**
+ * Every node that differs between two compositions, sorted by page then path.
+ * A removed or added page, and a page whose sections no longer validate after,
+ * are one pseudo-path node each; a `logo` subtree is never compared.
+ */
+export function jsonLdDrift(before, after) {
+    const nodes = [];
+    for (const page of [...new Set([...Object.keys(before), ...Object.keys(after)])]) {
+        const b = before[page];
+        const a = after[page];
+        if (a === undefined) {
+            nodes.push({ page, path: "(page removed)" });
+        }
+        else if (b === undefined) {
+            nodes.push({ page, path: "(page added)" });
+        }
+        else if (!a.sectionsValid) {
+            nodes.push({ page, path: "(sections invalid)" });
+        }
+        else {
+            const paths = [];
+            walk(JSON.parse(b.jsonld), JSON.parse(a.jsonld), "", paths);
+            for (const path of paths)
+                nodes.push({ page, path: path === "" ? "/" : path });
+        }
+    }
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return nodes.sort((x, y) => cmp(x.page, y.page) || cmp(x.path, y.path));
+}
+/** How many changed nodes a drift reason lists before it stops. */
+const REASON_NODE_LIMIT = 10;
+/** Decide whether `apply-design <design>` left every page's JSON-LD unchanged (logo excluded). */
+export function assessJsonLdDrift(design, before, after) {
+    const pages = Object.keys(before).length;
+    if (pages === 0) {
+        return { ok: false, pages, changed: [], reason: `design ${design}: no page was composed` };
+    }
+    const changed = jsonLdDrift(before, after);
+    if (changed.length === 0)
+        return { ok: true, pages };
+    const listed = changed
+        .slice(0, REASON_NODE_LIMIT)
+        .map((n) => `${n.page} ${n.path}`)
+        .join("; ");
+    return {
+        ok: false,
+        pages,
+        changed,
+        reason: `design ${design}: ${changed.length} JSON-LD node(s) changed by apply-design — ${listed}${changed.length > REASON_NODE_LIMIT ? "; …" : ""}`,
+    };
+}
+/**
+ * Scaffold a keyless `organization-product` site on `standard`, compose its
+ * JSON-LD, run `apply-design <design>` on it, and compose again. A non-zero
+ * exit at any step throws naming the step and the child's stderr.
+ */
+export function measureApplyDesignDrift(opts) {
+    const baseEnv = { ...process.env };
+    delete baseEnv["AILK_LICENSE_KEY"];
+    const registryEnv = opts.registryUrl === undefined
+        ? {}
+        : { AILK_MODULE_REGISTRY_URL: opts.registryUrl, AILK_TEMPLATE_REGISTRY_URL: opts.registryUrl };
+    const site = join(opts.workDir, "site");
+    const exec = (label, cmd, args, env) => {
+        try {
+            return execFileSync(cmd, args, {
+                encoding: "utf8",
+                env: { ...baseEnv, ...env },
+                stdio: ["ignore", "pipe", "pipe"],
+                maxBuffer: 64 * 1024 * 1024,
+            });
+        }
+        catch (err) {
+            const { stderr, message } = err;
+            throw new Error(`drift: ${label} failed: ${(stderr || message || "").trim()}`, { cause: err });
+        }
+    };
+    const compose = (label) => {
+        const stdout = exec(label, opts.tsxPath, [opts.composerPath, site], { TSX_TSCONFIG_PATH: opts.composerTsconfig });
+        try {
+            return JSON.parse(stdout);
+        }
+        catch (err) {
+            throw new Error(`drift: ${label} printed no JSON: ${err.message}`, { cause: err });
+        }
+    };
+    exec("scaffold organization-product on standard", process.execPath, [opts.cliPath, site, "--shape", "organization-product", "--design", "standard"], registryEnv);
+    if (opts.licenseKey !== undefined)
+        writeFileSync(join(site, "ailk.key"), `${opts.licenseKey}\n`);
+    const before = compose("compose JSON-LD before apply-design");
+    const applyStdout = exec(`apply-design ${opts.design}`, process.execPath, [opts.cliPath, "apply-design", opts.design, "--target", site], opts.registryUrl === undefined ? {} : { AILK_MODULE_REGISTRY_URL: opts.registryUrl });
+    const after = compose("compose JSON-LD after apply-design");
+    return { before, after, applyStdout };
+}

package/dist/lib/license-key-files.d.ts

@@ -6,6 +6,15 @@ export declare const LICENSE_ENV_VAR = "AILK_LICENSE_KEY";
  * describes the rule, never the value.
  */
 export declare function assertLicenseKeyShape(key: string): void;
+/**
+ * Write `content` only when it differs, with mode 0600 either way. An existing
+ * file is tightened BEFORE the write — `mode` applies only on creation, so a
+ * looser pre-existing `.env` would otherwise hold the key for a moment at its
+ * old permissions.
+ */
+export declare function writeOwnerOnly(path: string, content: string): void;
+/** `text` plus `line`, starting on a fresh line. */
+export declare function appendLine(text: string, line: string): string;
 /**
  * Persist `key` into the scaffold at `dir`: `ailk.key` (0600), the
  * `apps/api/.env` line (0600, other lines kept), and a `.gitignore` entry for

package/dist/lib/license-key-files.js

@@ -48,7 +48,7 @@ export function assertLicenseKeyShape(key) {
  * looser pre-existing `.env` would otherwise hold the key for a moment at its
  * old permissions.
  */
-function writeOwnerOnly(path, content) {
+export function writeOwnerOnly(path, content) {
     mkdirSync(dirname(path), { recursive: true });
     if (existsSync(path))
         chmodSync(path, 0o600);
@@ -58,7 +58,7 @@ function writeOwnerOnly(path, content) {
     chmodSync(path, 0o600);
 }
 /** `text` plus `line`, starting on a fresh line. */
-function appendLine(text, line) {
+export function appendLine(text, line) {
     const sep = text.length === 0 || text.endsWith("\n") ? "" : "\n";
     return `${text}${sep}${line}\n`;
 }

package/dist/lib/module-license-gate.d.ts

@@ -22,7 +22,6 @@
  * run's level, before `scaffold()`'s first disk write.
  */
 import type { ModuleName } from "../parse-args.js";
-import type { StarterDesign } from "../template-manifest.js";
 import { type Level } from "./module-tier.js";
 /**
  * Where a refused run sends the buyer. `/pricing`, not `/pro`: there is no
@@ -39,18 +38,29 @@ export declare const CONVERSION_HINT_URL = "https://ailaunchkit.ai/pricing";
 export declare class LicenseRequiredError extends Error {
     constructor(message: string);
 }
-/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
-export declare const FREE_DESIGNS: readonly StarterDesign[];
+/**
+ * Design names every level renders (#6760 D1). Anything else in
+ * `STARTER_DESIGNS` is Pro and up. A path design's Free-ness is decided by
+ * `resolveDesign`'s identity rule (#6813 D2), never by this list directly —
+ * `assertDesignAllowed`'s `free` parameter carries that verdict in.
+ */
+export declare const FREE_DESIGNS: readonly string[];
 /** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
 export declare const DESIGN_LEVELS: readonly Level[];
 /**
- * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
- * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
- * resolved; never reads a key or derives a level itself (D2, fail-closed:
- * both checks below are allow-lists, so an unrecognized `level` refuses
- * rather than granting it).
+ * Refuse a non-Free design at a level below Pro (#6760 D1, D6; widened to a
+ * path design #6813 D7). Pure and synchronous — takes the level
+ * `deriveLevel`/`resolveModuleSet` already resolved; never reads a key or
+ * derives a level itself (D2, fail-closed: both checks below are allow-lists,
+ * so an unrecognized `level` refuses rather than granting it).
+ *
+ * @param free Whether `design` is Free — defaults to `FREE_DESIGNS.includes(design)`
+ *   (a design NAME's own answer), so a caller passing a name never changes
+ *   behaviour. A path design's caller (`programmatic.ts`, off `resolveDesign`'s
+ *   identity rule) passes it explicitly: a byte-identical copy of a shipped
+ *   Free design is Free; any other path is not, whatever it is named.
  */
-export declare function assertDesignAllowed(design: StarterDesign | undefined, level: Level): void;
+export declare function assertDesignAllowed(design: string | undefined, level: Level, free?: boolean): void;
 export interface ResolvePaidModulesOptions {
     /** The requested module set's paid subset (see `module-tier.ts`). */
     paidModules: ModuleName[];

package/dist/lib/module-license-gate.js

@@ -19,19 +19,30 @@ export class LicenseRequiredError extends Error {
         this.name = "LicenseRequiredError";
     }
 }
-/** Designs every level renders (#6760 D1). Anything else in `STARTER_DESIGNS` is Pro and up. */
+/**
+ * Design names every level renders (#6760 D1). Anything else in
+ * `STARTER_DESIGNS` is Pro and up. A path design's Free-ness is decided by
+ * `resolveDesign`'s identity rule (#6813 D2), never by this list directly —
+ * `assertDesignAllowed`'s `free` parameter carries that verdict in.
+ */
 export const FREE_DESIGNS = ["standard"];
 /** Levels that render any design (#6760 D1) — an allow-list: an unknown level is not in it. */
 export const DESIGN_LEVELS = ["pro", "pro-plus"];
 /**
- * Refuse a non-`standard` design at a level below Pro (#6760 D1, D6). Pure
- * and synchronous — takes the level `deriveLevel`/`resolveModuleSet` already
- * resolved; never reads a key or derives a level itself (D2, fail-closed:
- * both checks below are allow-lists, so an unrecognized `level` refuses
- * rather than granting it).
+ * Refuse a non-Free design at a level below Pro (#6760 D1, D6; widened to a
+ * path design #6813 D7). Pure and synchronous — takes the level
+ * `deriveLevel`/`resolveModuleSet` already resolved; never reads a key or
+ * derives a level itself (D2, fail-closed: both checks below are allow-lists,
+ * so an unrecognized `level` refuses rather than granting it).
+ *
+ * @param free Whether `design` is Free — defaults to `FREE_DESIGNS.includes(design)`
+ *   (a design NAME's own answer), so a caller passing a name never changes
+ *   behaviour. A path design's caller (`programmatic.ts`, off `resolveDesign`'s
+ *   identity rule) passes it explicitly: a byte-identical copy of a shipped
+ *   Free design is Free; any other path is not, whatever it is named.
  */
-export function assertDesignAllowed(design, level) {
-    if (design === undefined || FREE_DESIGNS.includes(design))
+export function assertDesignAllowed(design, level, free = design !== undefined && FREE_DESIGNS.includes(design)) {
+    if (design === undefined || free)
         return;
     if (DESIGN_LEVELS.includes(level))
         return;

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[];