create-ailk 0.30.0 → 0.32.0

package/dist/inventory.js

@@ -0,0 +1,833 @@
+/**
+ * `create-ailk inventory <dir> [--origin <url>] [--refreeze]` — freeze what a
+ * site serves today, and audit it against its workspace (#10648, spec
+ * docs/specs/10648-the-cutover-kit-frozen-inventory-spec.md D1–D3).
+ *
+ * The one inventory shape the cutover kit shares (D1): every URL the sitemap,
+ * a same-origin crawl and the route roster name, probed once with no redirect
+ * followed. A direct 200 is `frozen` — with its kind, locale, sources, prose
+ * status and images — and anything else is `notFrozen` with its status, so
+ * nothing is dropped silently. The file is written once
+ * (`.ailk-cutover/inventory.json`, committed in the site); a second run reads
+ * it and crawls nothing, and `--refreeze` crawls again keeping the operator's
+ * `joins` and exclusions.
+ *
+ * Every run rewrites `.ailk-cutover/audit.json` (D2, D3): each frozen page
+ * joined to its workspace page by a deterministic rule, and its verdict —
+ * whether it is published and whether its words are in its Markdown, read
+ * through the words codec (ADR 0038). Exit 0 only when every prose page passes.
+ *
+ * The workspace reads here (`resolveWorkspaceAccess`, `listWorkspacePages`,
+ * `readPublishedPage`, `readDraftPage`, `loadSiteWordsCodec`) are the kit's
+ * shared ones: `export-content` and `cutover` use them too. Credentials follow
+ * `migrate-content`: the key from `AILK_AGENT_KEY` only, sent only as a bearer
+ * token to the API origin, never across a redirect, never printed.
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { IN_FLIGHT, mapLimit } from "./lib/render-comparison.js";
+import { sitemapLocPaths } from "./lib/scaffold-render-sweep.js";
+import { ParseError } from "./parse-args.js";
+import { AGENT_KEY_ENV_VAR, WORKSPACE_ID_ENV_VAR } from "./seed-workspace.js";
+import { readSiteRoster } from "./site-roster.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, } from "./topology.js";
+/** The kit's directory in the site: committed, unlike `.ailk/`. */
+export const CUTOVER_DIR = ".ailk-cutover";
+export const INVENTORY_FILE = "inventory.json";
+export const AUDIT_FILE = "audit.json";
+/** The spoke's key for the hub's public read (`x-ailk-spoke-key`). */
+export const SPOKE_KEY_ENV_VAR = "AILK_SPOKE_KEY";
+/** The package the words codec comes from, resolved from the site at run time. */
+const VALIDATION_PACKAGE = "@working-theory/validation";
+const DEFAULT_DOCS_PATH = "/docs";
+const CRAWL_CAP = 5_000;
+const REQUEST_TIMEOUT_MS = 15_000;
+/** Paths every site is probed for, frozen as files when they answer 200. */
+const FILE_PATHS = ["/sitemap.xml", "/robots.txt", "/llms.txt"];
+/** A refusal the CLI exits 2 on. */
+export class InventoryRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "InventoryRefusedError";
+    }
+}
+export const AUDIT_VERDICTS = [
+    "pass",
+    "excluded",
+    "read-failed",
+    "unjoined",
+    "no-page",
+    "ambiguous",
+    "locale-not-imported",
+    "not-published",
+    "words-not-in-markdown",
+];
+/** A value given, or `undefined` for an absent or empty one. */
+export function given(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+const KEY_SHAPE = /^[\x21-\x7e]+$/;
+const WORKSPACE_ID = /^wksp_[0-9a-f-]{36}$/;
+/**
+ * The key, workspace and API origin, as `migrate-content` reads them, plus the
+ * spoke key on a spoke. Every miss is refused through `refuse`, before any
+ * request.
+ */
+export function resolveWorkspaceAccess(targetDir, o, refuse) {
+    const apiKey = given(o.env[AGENT_KEY_ENV_VAR]);
+    if (apiKey === undefined || !KEY_SHAPE.test(apiKey)) {
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+    }
+    const workspaceId = given(o.workspaceId) ?? given(o.env[WORKSPACE_ID_ENV_VAR]);
+    if (workspaceId === undefined || !WORKSPACE_ID.test(workspaceId)) {
+        refuse(`no workspace id (wksp_<uuidv7>) was given. Pass --workspace <wksp_id>, or set ${WORKSPACE_ID_ENV_VAR}.`);
+    }
+    const raw = given(o.apiUrl) ?? given(o.env[HUB_ORIGIN_ENV_VAR]);
+    if (raw === undefined) {
+        refuse(`no API origin was given. Pass --api-url <origin>, or set ${HUB_ORIGIN_ENV_VAR}.`);
+    }
+    let origin;
+    try {
+        origin = normalizeHubUrl(raw);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse("the API origin must be an https: origin (http: only on a loopback host) with no path, query, fragment or credentials.");
+    }
+    let topology;
+    try {
+        topology = readSiteTopology(targetDir);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(err.message);
+    }
+    if (topology !== "spoke")
+        return { origin, workspaceId, apiKey };
+    const spokeKey = given(o.env[SPOKE_KEY_ENV_VAR]);
+    if (spokeKey === undefined || !KEY_SHAPE.test(spokeKey)) {
+        refuse(`this site is a spoke: set ${SPOKE_KEY_ENV_VAR} so the hub's public read answers its workspace.`);
+    }
+    return { origin, workspaceId, apiKey, spokeKey };
+}
+/** A site origin: http(s), reduced to its origin. */
+export function siteOrigin(value, flag, refuse) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        refuse(`${flag} is not a URL.`);
+    }
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        refuse(`${flag} must be an http(s) origin.`);
+    return url.origin;
+}
+async function getJson(fetch, url, headers) {
+    let response;
+    try {
+        response = await fetch(url, {
+            headers,
+            // A redirect would re-send the key to another URL.
+            redirect: "error",
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+    }
+    catch {
+        // A timeout, a network failure or a redirect: status 0, the read failed.
+        return { status: 0, body: undefined };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch {
+        body = undefined;
+    }
+    return { status: response.status, body };
+}
+const bearer = (access) => ({ authorization: `Bearer ${access.apiKey}` });
+/**
+ * The workspace's pages in `locale`, through the editor's view. A row with no
+ * `version` is the member projection — a key without `content-edit` — which
+ * reports every live row `published` and would hide a draft ahead: refused.
+ * @throws Error on a read that does not answer 200.
+ */
+export async function listWorkspacePages(access, fetch, locale, refuse) {
+    const { status, body } = await getJson(fetch, `${access.origin}/v1/workspaces/${encodeURIComponent(access.workspaceId)}/content?locale=${encodeURIComponent(locale)}`, bearer(access));
+    const data = body?.data;
+    if (status !== 200 || !Array.isArray(data)) {
+        throw new Error(`the workspace list answered ${status}`);
+    }
+    const rows = data.filter((row) => row["kind"] !== "file" && typeof row["type"] === "string" && typeof row["slug"] === "string");
+    if (rows.some((row) => typeof row["version"] !== "string")) {
+        refuse(`the workspace list answered its published-only projection: ${AGENT_KEY_ENV_VAR} needs the content-edit grant.`);
+    }
+    return rows;
+}
+/** The public read of one page with its body: what the site serves. */
+export async function readPublishedPage(access, fetch, type, slug, locale) {
+    const { status, body } = await getJson(fetch, `${access.origin}/v1/content/${encodeURIComponent(type)}/${encodeURIComponent(slug)}?include=body&locale=${encodeURIComponent(locale)}`, access.spokeKey === undefined ? {} : { "x-ailk-spoke-key": access.spokeKey });
+    const doc = body;
+    if (status !== 200 || doc?.page === undefined)
+        return { found: false, status };
+    return {
+        found: true,
+        sections: Array.isArray(doc.page.sections) ? doc.page.sections : undefined,
+        body: typeof doc.body === "string" ? doc.body : "",
+        publishedVersionId: typeof doc.publishedVersionId === "string" ? doc.publishedVersionId : undefined,
+    };
+}
+/** The draft tip's raw stored content — the value the importer compares against. */
+export async function readDraftPage(access, fetch, type, slug, locale) {
+    const { status, body } = await getJson(fetch, `${access.origin}/v1/workspaces/${encodeURIComponent(access.workspaceId)}/content/${encodeURIComponent(type)}/${encodeURIComponent(slug)}?locale=${encodeURIComponent(locale)}`, bearer(access));
+    const data = body?.data;
+    const content = data?.content;
+    if (status !== 200 || content === null || typeof content !== "object")
+        return { status };
+    return {
+        status,
+        content: content,
+        ...(typeof data?.version === "string" && { version: data.version }),
+    };
+}
+/**
+ * The site's words codec: `@working-theory/validation` resolved from its
+ * `apps/web`, the name held in a constant so no import specifier names it.
+ */
+export async function loadSiteWordsCodec(targetDir, refuse) {
+    const web = join(resolve(targetDir), "apps", "web");
+    let mod = {};
+    try {
+        const entry = createRequire(join(web, "package.json")).resolve(VALIDATION_PACKAGE);
+        mod = (await import(pathToFileURL(entry).href));
+    }
+    catch {
+        // Reported below.
+    }
+    if (typeof mod["applyWords"] !== "function" || typeof mod["sectionsToMarkdown"] !== "function") {
+        refuse(`${VALIDATION_PACKAGE} with the words codec is not installed in ${web}. Install the site's dependencies (pnpm install) first.`);
+    }
+    return mod;
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, sortKeys(value[key])]));
+}
+/** Equal as JSON, keys sorted at every depth. */
+export function sameJson(a, b) {
+    return JSON.stringify(sortKeys(a)) === JSON.stringify(sortKeys(b));
+}
+/** The site's locales from `project.yaml` `product`, read without a YAML dependency. */
+export function readSiteLocales(targetDir) {
+    const path = join(targetDir, "project.yaml");
+    const fallback = { defaultLocale: "en", locales: ["en"] };
+    if (!existsSync(path))
+        return fallback;
+    const lines = readFileSync(path, "utf8").split("\n");
+    const start = lines.findIndex((line) => /^product:\s*$/.test(line));
+    if (start < 0)
+        return fallback;
+    const unquote = (v) => v.trim().replace(/^["']|["']$/g, "");
+    let defaultLocale = fallback.defaultLocale;
+    let locales;
+    for (let i = start + 1; i < lines.length && /^(\s|$)/.test(lines[i]); i++) {
+        const line = lines[i].replace(/\s+#.*$/, "");
+        const def = /^\s+default_locale:\s*(\S+)/.exec(line);
+        if (def)
+            defaultLocale = unquote(def[1]);
+        const list = /^\s+locales:\s*(.*)$/.exec(line);
+        if (!list)
+            continue;
+        const flow = /^\[(.*)\]$/.exec(list[1].trim());
+        if (flow) {
+            locales = flow[1].split(",").map(unquote).filter((v) => v !== "");
+        }
+        else {
+            locales = [];
+            for (let j = i + 1; j < lines.length && /^\s+-\s/.test(lines[j]); j++) {
+                locales.push(unquote(lines[j].replace(/^\s+-\s/, "")));
+            }
+        }
+    }
+    return { defaultLocale, locales: locales !== undefined && locales.length > 0 ? locales : [defaultLocale] };
+}
+// ── The crawl (D1) ──────────────────────────────────────────────────────────
+function decodeEntities(value) {
+    return value
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .replace(/&#0*39;|&apos;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">");
+}
+/** Each `<tag …>` of `names` with its attributes, names lower-cased. */
+function tags(html, names) {
+    const out = [];
+    for (const tag of html.matchAll(new RegExp(`<(?:${names})\\b([^>]*)>`, "gi"))) {
+        const attrs = {};
+        for (const a of tag[1].matchAll(/([\w:-]+)\s*=\s*("([^"]*)"|'([^']*)'|([^\s"'>]+))/g)) {
+            attrs[a[1].toLowerCase()] = decodeEntities(a[3] ?? a[4] ?? a[5] ?? "");
+        }
+        out.push(attrs);
+    }
+    return out;
+}
+/** The same-origin page paths `html` links to: query and hash stripped, `/_next/` and `/api/` skipped. */
+function linkedPaths(html, pageUrl, origin) {
+    const paths = [];
+    for (const { href } of tags(html, "a")) {
+        if (href === undefined)
+            continue;
+        let url;
+        try {
+            url = new URL(href, pageUrl);
+        }
+        catch {
+            continue;
+        }
+        if (url.origin !== origin)
+            continue;
+        if (url.pathname.startsWith("/_next/") || url.pathname.startsWith("/api/"))
+            continue;
+        paths.push(url.pathname);
+    }
+    return paths;
+}
+/** Every `<img src>`, every `srcset` candidate and `og:image`, as absolute URLs. */
+function imageUrls(html, pageUrl) {
+    const raw = [];
+    for (const attrs of tags(html, "img|source")) {
+        if (attrs["src"] !== undefined)
+            raw.push(attrs["src"]);
+        for (const candidate of (attrs["srcset"] ?? "").split(",")) {
+            const url = candidate.trim().split(/\s+/)[0];
+            if (url)
+                raw.push(url);
+        }
+    }
+    for (const attrs of tags(html, "meta")) {
+        if (attrs["property"] === "og:image" && attrs["content"])
+            raw.push(attrs["content"]);
+    }
+    const urls = new Set();
+    for (const value of raw) {
+        try {
+            urls.add(new URL(value, pageUrl).href);
+        }
+        catch {
+            // Not a URL: not an image the sweep can fetch.
+        }
+    }
+    return [...urls].sort();
+}
+const NOT_PROSE_ELEMENTS = ["script", "style", "noscript", "nav", "header", "footer", "form"];
+/**
+ * Whether a page carries prose (D3): inside `<main>` when it has one, with its
+ * script, style, noscript, nav, header, footer and form elements removed, a
+ * `<p>`, heading, `<li>` or `<blockquote>` with non-whitespace text.
+ */
+export function isProseBearing(html) {
+    let scope = /<main\b[^>]*>([\s\S]*?)<\/main>/i.exec(html)?.[1] ?? html;
+    for (const name of NOT_PROSE_ELEMENTS) {
+        scope = scope.replace(new RegExp(`<${name}\\b[^>]*>[\\s\\S]*?<\\/${name}>`, "gi"), "");
+    }
+    for (const match of scope.matchAll(/<(p|h[1-6]|li|blockquote)\b[^>]*>([\s\S]*?)<\/\1>/gi)) {
+        if (match[2].replace(/<[^>]*>/g, "").trim() !== "")
+            return true;
+    }
+    return false;
+}
+async function probe(fetch, url, readBody = true) {
+    try {
+        const response = await fetch(url, { redirect: "manual", signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+        const type = response.headers.get("content-type") ?? "";
+        const kind = type.includes("text/html") ? "page" : "file";
+        const location = response.headers.get("location");
+        const body = readBody && response.status === 200 ? await response.text() : undefined;
+        return {
+            status: response.status,
+            kind,
+            ...(location !== null && { location }),
+            ...(body !== undefined && (kind === "page" ? { html: body } : { text: body })),
+        };
+    }
+    catch {
+        return { status: 0, kind: "file" };
+    }
+}
+/** The static `page.tsx` routes under `apps/web/app`, `[locale]` and `(group)` dropped, dynamic ones skipped. */
+function appRoutes(targetDir) {
+    const routes = [];
+    const walk = (dir, segments) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name === "page.tsx")
+                routes.push(`/${segments.join("/")}`);
+            if (!entry.isDirectory() || /^[_@]/.test(entry.name))
+                continue;
+            if (entry.name === "[locale]" || /^\(.*\)$/.test(entry.name))
+                walk(join(dir, entry.name), segments);
+            else if (!entry.name.includes("["))
+                walk(join(dir, entry.name), [...segments, entry.name]);
+        }
+    };
+    walk(join(targetDir, "apps", "web", "app"), []);
+    return routes;
+}
+function rosterRoutes(targetDir) {
+    const roster = readSiteRoster(targetDir);
+    return (roster?.rows ?? []).flatMap(({ value }) => typeof value["route"] === "string"
+        ? [{ route: value["route"], pageType: typeof value["pageType"] === "string" ? value["pageType"] : null }]
+        : []);
+}
+/** A route's or a path's non-empty segments. */
+function routePattern(route) {
+    return route.split("/").filter((s) => s !== "");
+}
+const isDynamic = (segment) => /^\[[^.\]]+\]$/.test(segment);
+function matchRoute(route, path) {
+    const pattern = routePattern(route);
+    const segments = routePattern(path);
+    if (pattern.length !== segments.length)
+        return undefined;
+    let slug;
+    for (const [i, part] of pattern.entries()) {
+        if (isDynamic(part))
+            slug = segments[i];
+        else if (part !== segments[i])
+            return undefined;
+    }
+    return slug === undefined ? {} : { slug };
+}
+const sorted = (values) => [...values].sort();
+const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+async function crawl(c) {
+    const from = new Map();
+    const probes = new Map();
+    const add = (path, source) => {
+        const set = from.get(path) ?? new Set();
+        set.add(source);
+        from.set(path, set);
+        if (from.size > CRAWL_CAP) {
+            c.refuse(`the site names more than ${CRAWL_CAP} URLs; the inventory stops at that cap.`);
+        }
+    };
+    const probeAll = async (paths) => {
+        const todo = [...new Set(paths)].filter((p) => !probes.has(p));
+        const results = await mapLimit(todo, IN_FLIGHT, (p) => probe(c.fetch, c.origin + p));
+        todo.forEach((p, i) => probes.set(p, results[i]));
+        return todo;
+    };
+    // The sitemap, one level of index.
+    await probeAll(["/sitemap.xml"]);
+    const sitemapPaths = [];
+    const sitemap = probes.get("/sitemap.xml");
+    const xml = sitemap.text ?? sitemap.html;
+    if (sitemap.status === 200 && xml !== undefined) {
+        const locs = (text) => {
+            try {
+                return sitemapLocPaths(text);
+            }
+            catch {
+                return [];
+            }
+        };
+        if (/<sitemapindex\b/.test(xml)) {
+            const children = locs(xml);
+            const texts = await mapLimit(children, IN_FLIGHT, async (p) => (await probe(c.fetch, c.origin + p)).text ?? "");
+            for (const text of texts)
+                sitemapPaths.push(...locs(text));
+        }
+        else {
+            sitemapPaths.push(...locs(xml));
+        }
+    }
+    for (const p of sitemapPaths)
+        add(p, "sitemap");
+    // The roster: static routes, each `[slug]` row over the list's slugs, the app's static pages.
+    const rosterPaths = new Set();
+    for (const { route, pageType } of rosterRoutes(c.targetDir)) {
+        const pattern = routePattern(route);
+        const dynamic = pattern.filter(isDynamic).length;
+        if (dynamic === 0)
+            rosterPaths.add(route === "" ? "/" : route);
+        else if (dynamic === 1 && pageType !== null && !route.includes("...")) {
+            for (const row of c.rows) {
+                if (row.type !== pageType)
+                    continue;
+                rosterPaths.add(`/${pattern.map((s) => (isDynamic(s) ? row.slug : s)).join("/")}`);
+            }
+        }
+    }
+    for (const route of appRoutes(c.targetDir))
+        rosterPaths.add(route);
+    for (const p of rosterPaths)
+        add(p, "roster");
+    // The crawl: from `/`, and from every page any source names.
+    add("/", "crawl");
+    for (const p of FILE_PATHS)
+        add(p, "probe");
+    let pending = [...from.keys()];
+    const crawlPaths = new Set(["/"]);
+    while (pending.length > 0) {
+        const probed = await probeAll(pending);
+        pending = [];
+        for (const path of probed) {
+            const result = probes.get(path);
+            if (result.status !== 200 || result.html === undefined)
+                continue;
+            for (const linked of linkedPaths(result.html, c.origin + path, c.origin)) {
+                crawlPaths.add(linked);
+                const known = from.has(linked);
+                add(linked, "crawl");
+                if (!known)
+                    pending.push(linked);
+            }
+        }
+    }
+    const frozen = [];
+    const notFrozen = [];
+    const noProse = [];
+    const imagePages = new Map();
+    for (const path of sorted(from.keys())) {
+        const sources = sorted(from.get(path));
+        const result = probes.get(path);
+        if (result.status !== 200) {
+            notFrozen.push({
+                path,
+                status: result.status,
+                ...(result.location !== undefined && { location: result.location }),
+                from: sources,
+            });
+            continue;
+        }
+        const first = routePattern(path)[0];
+        const locale = first !== undefined && c.locales.includes(first) ? first : c.defaultLocale;
+        const images = result.html === undefined ? [] : imageUrls(result.html, c.origin + path);
+        const prose = result.kind === "page" && result.html !== undefined && isProseBearing(result.html);
+        if (result.kind === "page" && !prose)
+            noProse.push(path);
+        for (const url of images)
+            imagePages.set(url, (imagePages.get(url) ?? new Set()).add(path));
+        frozen.push({ path, kind: result.kind, locale, from: sources, prose, images });
+    }
+    const imageList = sorted(imagePages.keys());
+    const statuses = await mapLimit(imageList, IN_FLIGHT, async (url) => (await probe(c.fetch, url, false)).status);
+    return {
+        frozen,
+        notFrozen,
+        images: imageList.map((url, i) => ({ url, status: statuses[i], pages: sorted(imagePages.get(url)) })),
+        sources: { sitemap: new Set(sitemapPaths).size, crawl: crawlPaths.size, roster: rosterPaths.size },
+        noProse,
+    };
+}
+/** A URL's workspace page: the operator's join, then the roster, then the editorial prefixes. */
+export function joinUrl(rawPath, ctx) {
+    const prefix = `/${ctx.defaultLocale}`;
+    const path = rawPath === prefix ? "/" : rawPath.startsWith(`${prefix}/`) ? rawPath.slice(prefix.length) : rawPath;
+    const keys = new Set(ctx.rows.map((r) => `${r.type}/${r.slug}`));
+    const found = (join) => (keys.has(join) ? { join } : { verdict: "no-page", join });
+    const operator = ctx.joins[rawPath] ?? ctx.joins[path];
+    if (operator !== undefined)
+        return found(operator);
+    for (const { route, pageType } of ctx.roster) {
+        if (pageType === null)
+            continue;
+        const match = matchRoute(route, path);
+        if (match === undefined)
+            continue;
+        if (match.slug !== undefined)
+            return found(`${pageType}/${match.slug}`);
+        const ofType = ctx.rows.filter((r) => r.type === pageType);
+        if (ofType.length === 0)
+            return { verdict: "no-page" };
+        if (ofType.length > 1)
+            return { verdict: "ambiguous" };
+        return { join: `${pageType}/${ofType[0].slug}` };
+    }
+    for (const [base, list, detail] of [
+        ["/blog", "BlogList", "BlogPosting"],
+        [ctx.docsPath, "DocsList", "DocsDetail"],
+    ]) {
+        if (path === base)
+            return found(`${list}/index`);
+        const rest = path.startsWith(`${base}/`) ? path.slice(base.length + 1) : undefined;
+        if (rest !== undefined && rest !== "" && !rest.includes("/"))
+            return found(`${detail}/${rest}`);
+    }
+    return { verdict: "unjoined" };
+}
+/** Whether a published page's words are in its Markdown (D3). */
+function wordsInMarkdown(read, codec) {
+    if (read.sections === undefined || read.sections.length === 0)
+        return read.body.trim() !== "";
+    const applied = codec.applyWords(read.body, read.sections);
+    return applied.issues.length === 0 && sameJson(applied.sections, read.sections);
+}
+async function audit(o) {
+    const { inv } = o;
+    const excluded = new Set(inv.proseExclusions.map((e) => e.path));
+    const rowOf = new Map(o.rows.map((r) => [`${r.type}/${r.slug}`, r]));
+    const joined = new Set();
+    const pages = await mapLimit(inv.frozen.filter((e) => e.kind === "page"), IN_FLIGHT, async (entry) => {
+        const j = joinUrl(entry.path, {
+            joins: inv.joins,
+            roster: o.roster,
+            rows: o.rows,
+            docsPath: inv.docsPath,
+            defaultLocale: inv.defaultLocale,
+        });
+        const join = j.join ?? null;
+        const row = join === null ? undefined : rowOf.get(join);
+        if (row !== undefined)
+            joined.add(join);
+        const published = row === undefined ? null : row.status === "published";
+        const page = (verdict, words = null) => ({
+            path: entry.path,
+            join,
+            verdict,
+            prose: !excluded.has(entry.path),
+            published,
+            wordsInMarkdown: words,
+        });
+        if (excluded.has(entry.path))
+            return page("excluded");
+        if (entry.locale !== inv.defaultLocale)
+            return page("locale-not-imported");
+        if ("verdict" in j)
+            return page(j.verdict);
+        if (!published)
+            return page("not-published");
+        const read = await readPublishedPage(o.access, o.fetch, row.type, row.slug, inv.defaultLocale);
+        if (!read.found || read.publishedVersionId !== row.publishedVersionId)
+            return page("read-failed");
+        const words = wordsInMarkdown(read, o.codec);
+        return page(words ? "pass" : "words-not-in-markdown", words);
+    });
+    const counts = Object.fromEntries(AUDIT_VERDICTS.map((v) => [v, 0]));
+    for (const p of pages)
+        counts[p.verdict] += 1;
+    return {
+        version: 1,
+        inventoryFrozenAt: inv.frozenAt,
+        pages: pages.sort(byPath),
+        orphans: sorted(rowOf.keys()).filter((key) => !joined.has(key)),
+        counts,
+    };
+}
+/** The inventory file as written: fixed key order, sorted arrays. */
+function writeInventory(path, inv) {
+    const ordered = {
+        version: 1,
+        origin: inv.origin,
+        frozenAt: inv.frozenAt,
+        defaultLocale: inv.defaultLocale,
+        docsPath: inv.docsPath,
+        sources: { sitemap: inv.sources.sitemap, crawl: inv.sources.crawl, roster: inv.sources.roster },
+        frozen: [...inv.frozen].sort(byPath).map((e) => ({
+            path: e.path,
+            kind: e.kind,
+            locale: e.locale,
+            from: sorted(e.from),
+            prose: e.prose,
+            images: sorted(e.images),
+        })),
+        notFrozen: [...inv.notFrozen].sort(byPath),
+        images: [...inv.images].sort((a, b) => (a.url < b.url ? -1 : 1)),
+        proseExclusions: [...inv.proseExclusions].sort(byPath),
+        joins: Object.fromEntries(Object.entries(inv.joins).sort(([a], [b]) => (a < b ? -1 : 1))),
+    };
+    writeFileSync(path, `${JSON.stringify(ordered, null, 2)}\n`);
+}
+/**
+ * The inventory in the site, or `undefined` when none is frozen.
+ * @throws Error on a file that is not JSON or not a version-1 inventory.
+ */
+export function readInventory(targetDir) {
+    const path = join(targetDir, CUTOVER_DIR, INVENTORY_FILE);
+    if (!existsSync(path))
+        return undefined;
+    const inv = JSON.parse(readFileSync(path, "utf8"));
+    const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+    if (!isObject(inv) ||
+        inv.version !== 1 ||
+        typeof inv.origin !== "string" ||
+        typeof inv.frozenAt !== "string" ||
+        typeof inv.defaultLocale !== "string" ||
+        typeof inv.docsPath !== "string" ||
+        !Array.isArray(inv.frozen) ||
+        !Array.isArray(inv.notFrozen) ||
+        !Array.isArray(inv.images) ||
+        !Array.isArray(inv.proseExclusions) ||
+        !isObject(inv.joins)) {
+        throw new Error(`${CUTOVER_DIR}/${INVENTORY_FILE} is not a version-1 inventory`);
+    }
+    return inv;
+}
+export function formatAuditCounts(counts) {
+    return AUDIT_VERDICTS.map((v) => `${v} ${counts[v]}`).join(" · ");
+}
+export async function inventory(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    const fetch = opts.fetch ?? globalThis.fetch;
+    const refuse = (message) => {
+        throw new InventoryRefusedError(`inventory: ${message}`);
+    };
+    const access = resolveWorkspaceAccess(targetDir, { apiUrl: opts.apiUrl, workspaceId: opts.workspaceId, env }, refuse);
+    const dir = join(targetDir, CUTOVER_DIR);
+    const path = join(dir, INVENTORY_FILE);
+    let previous;
+    try {
+        previous = readInventory(targetDir);
+    }
+    catch (err) {
+        refuse(`${CUTOVER_DIR}/${INVENTORY_FILE} is not JSON (${err.message}).`);
+    }
+    const freeze = previous === undefined || opts.refreeze === true;
+    if (!freeze && given(opts.origin) !== undefined && siteOrigin(opts.origin, "--origin", refuse) !== previous.origin) {
+        refuse(`the inventory was frozen from ${previous.origin}, not ${opts.origin}. Pass --refreeze to freeze again.`);
+    }
+    const rawOrigin = given(opts.origin) ?? previous?.origin;
+    if (freeze && rawOrigin === undefined)
+        refuse("no inventory is frozen yet: pass --origin <url>, the site as served today.");
+    const origin = rawOrigin === undefined ? undefined : siteOrigin(rawOrigin, "--origin", refuse);
+    const { defaultLocale, locales } = readSiteLocales(targetDir);
+    let roster;
+    try {
+        roster = rosterRoutes(targetDir);
+    }
+    catch (err) {
+        refuse(err.message);
+    }
+    const codec = opts.codec ?? (await loadSiteWordsCodec(targetDir, refuse));
+    const rows = (await listWorkspacePages(access, fetch, defaultLocale, refuse)).filter((r) => r.locale === defaultLocale);
+    let inv;
+    if (freeze) {
+        onLine(`Freezing ${origin} into ${CUTOVER_DIR}/${INVENTORY_FILE}.`);
+        const crawled = await crawl({ origin: origin, targetDir, rows, locales, defaultLocale, fetch, refuse });
+        const kept = (previous?.proseExclusions ?? []).filter((e) => e.by === "operator");
+        const keptPaths = new Set(kept.map((e) => e.path));
+        inv = {
+            version: 1,
+            origin: origin,
+            frozenAt: (opts.now ?? (() => new Date()))().toISOString(),
+            defaultLocale,
+            docsPath: given(opts.docsPath) ?? previous?.docsPath ?? DEFAULT_DOCS_PATH,
+            sources: crawled.sources,
+            frozen: crawled.frozen,
+            notFrozen: crawled.notFrozen,
+            images: crawled.images,
+            proseExclusions: [
+                ...kept,
+                ...crawled.noProse
+                    .filter((p) => !keptPaths.has(p))
+                    .map((p) => ({ path: p, reason: "no-prose", by: "inventory" })),
+            ],
+            joins: previous?.joins ?? {},
+        };
+        mkdirSync(dir, { recursive: true });
+        writeInventory(path, inv);
+        inv = readInventory(targetDir);
+    }
+    else {
+        inv = previous;
+        onLine(`Read the frozen ${CUTOVER_DIR}/${INVENTORY_FILE} (${inv.frozenAt}); nothing was crawled.`);
+    }
+    onLine(`${inv.frozen.length} frozen URL(s), ${inv.notFrozen.length} not frozen.`);
+    const result = await audit({ inv, rows, roster, access, fetch, codec });
+    writeFileSync(join(dir, AUDIT_FILE), `${JSON.stringify(result, null, 2)}\n`);
+    const failing = result.pages.filter((p) => p.verdict !== "pass" && p.verdict !== "excluded");
+    for (const p of failing)
+        onLine(`${p.path}: ${p.verdict}${p.join === null ? "" : ` (${p.join})`}`);
+    onLine(formatAuditCounts(result.counts));
+    return { exitCode: failing.length > 0 ? 1 : 0, inventory: inv, audit: result };
+}
+export const INVENTORY_HELP = `create-ailk inventory — freeze what a site serves today, and audit it against its workspace.
+
+Usage:
+  AILK_AGENT_KEY=<key> create-ailk inventory [<dir>] --origin <url> [--refreeze] [--docs-path <path>] [--api-url <origin>] [--workspace <wksp_id>]
+
+Arguments:
+  <dir>                    The site. Defaults to the current dir.
+
+Options:
+  --origin <url>           The site as served today. Needed to freeze; a
+                           frozen inventory keeps its own.
+  --refreeze               Crawl again. The operator's joins and exclusions
+                           are kept; the inventory's own are recomputed.
+  --docs-path <path>       Where the site serves its docs. Default /docs.
+  --api-url <origin>       The API origin that holds the workspace — on a
+                           spoke, its hub's. Else AILK_API_URL.
+  --workspace <wksp_id>    The workspace. Else AILK_WORKSPACE_ID.
+  -h, --help               Show this help.
+
+The first run writes ${CUTOVER_DIR}/${INVENTORY_FILE}: every URL the sitemap,
+a crawl of the site and the route roster name, each probed with no
+redirect followed. A direct 200 is frozen with its prose status and its
+images; anything else is listed as not frozen with its status. A later
+run reads that file and crawls nothing. Commit it.
+
+Every run writes ${CUTOVER_DIR}/${AUDIT_FILE}: each frozen page joined to its
+workspace page — by the inventory's "joins", then the roster, then /blog and
+the docs path — and whether it is published and whether its words are in
+its Markdown. The agent key needs the content-edit grant; on a spoke,
+AILK_SPOKE_KEY is needed too. Exit 0 when every prose page passes, 1 when
+any does not (one line each), 2 on a refusal.
+`;
+export function parseInventoryArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                origin: { type: "string" },
+                refreeze: { type: "boolean", default: false },
+                "docs-path": { type: "string" },
+                "api-url": { type: "string" },
+                workspace: { type: "string" },
+                help: { type: "boolean", default: false, short: "h" },
+            },
+        });
+    }
+    catch (err) {
+        throw new ParseError(`inventory: ${err.message}`);
+    }
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`inventory takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        origin: parsed.values.origin,
+        refreeze: parsed.values.refreeze === true,
+        docsPath: parsed.values["docs-path"],
+        apiUrl: parsed.values["api-url"],
+        workspaceId: parsed.values.workspace,
+        help: parsed.values.help === true,
+    };
+}