create-ailk 0.30.0 → 0.31.0

package/dist/cutover.js

@@ -0,0 +1,494 @@
+/**
+ * `create-ailk cutover <dir> --before <origin> --after <origin> [--apply]` —
+ * move a site from its page files to its database, one checked step at a time
+ * (#10648, spec docs/specs/10648-the-cutover-kit-frozen-inventory-spec.md D7,
+ * D8; roadmap D15, D16).
+ *
+ * Eight steps, in this order only: import → publish → inventory → comparison →
+ * set env → deploy → verify → remove files. With `--apply` they run, and the
+ * first that fails ends the run with exit 1 and every later step recorded
+ * `not-run`. Each step's command and evidence go into
+ * `.ailk-cutover/runs/<UTC stamp>/run.json`, beside the comparison's
+ * `comparison.json`, `comparison.md` and screenshots (`runs/` is gitignored:
+ * screenshots do not belong in the site's history).
+ *
+ * Without `--apply` it is a dry run: the import is `migrate-content`'s own dry
+ * run (over `readOnlyFetch`), the other steps are planned and printed, only
+ * `GET`s are sent, no `vercel` or `git` command is spawned and no file is
+ * written anywhere.
+ *
+ * The kit never publishes — publishing is a human act (#10345 D7) — so the
+ * publish step checks that every page the import read is `published` and,
+ * on the first `--apply`, names the pages to publish in Admin and stops. A
+ * re-run continues. The rollback is `export-content` (the runbook,
+ * docs/internal/runbooks/site-cutover.md).
+ *
+ * Pure module: no `import.meta.url`, so jest imports it directly; every step's
+ * collaborator is injectable.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { CUTOVER_DIR, INVENTORY_FILE, formatAuditCounts, given, inventory, listWorkspacePages, readInventory, readSiteLocales, resolveWorkspaceAccess, siteOrigin, } from "./inventory.js";
+import { languageCountsLine, renderChangeLine, } from "./language-import.js";
+import { PLAYWRIGHT_INSTALL_HINT, loadChromium, runComparison, } from "./lib/render-comparison.js";
+import { migrateContent } from "./migrate-content.js";
+import { ParseError } from "./parse-args.js";
+export const CUTOVER_STEPS = [
+    "import",
+    "publish",
+    "inventory",
+    "comparison",
+    "set-env",
+    "deploy",
+    "verify",
+    "remove-files",
+];
+export const ENV_TARGETS = ["preview", "production"];
+/** The env var the site's web app switches its content reads on. */
+const CONTENT_ADAPTER_VAR = "CONTENT_ADAPTER";
+/** A Vercel preview's protection bypass, sent only to `--after` and the deployment. */
+const BYPASS_ENV_VAR = "VERCEL_AUTOMATION_BYPASS_SECRET";
+/** A refusal the CLI exits 2 on, raised before step 1. */
+export class CutoverRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "CutoverRefusedError";
+    }
+}
+/** The default runner: `spawnSync` with no shell, stdout piped, stderr shown. */
+export const spawnRunner = (command, args, options) => {
+    const result = spawnSync(command, args, {
+        cwd: options.cwd,
+        encoding: "utf8",
+        shell: false,
+        ...(options.input !== undefined && { input: options.input }),
+        stdio: [options.input !== undefined ? "pipe" : "ignore", "pipe", "inherit"],
+    });
+    return {
+        status: result.status,
+        stdout: result.stdout ?? "",
+        ...(result.error !== undefined && {
+            error: result.error.code ?? result.error.name,
+        }),
+    };
+};
+/** `20261103T100000Z`. */
+function stamp(date) {
+    return date.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+}
+/**
+ * Step 8's paths: each imported file under the root it came from, repo-relative
+ * (D8). An outcome's path is relative to the content root the importer walked.
+ */
+export function removablePaths(pages) {
+    return pages
+        .filter((p) => p.result === "created" || p.result === "updated" || p.result === "unchanged")
+        .map((p) => `${p.root === "editorial" ? "apps/web/content" : "content"}/${p.path}`);
+}
+const imported = (pages) => pages.flatMap((p) => ("type" in p ? [`${p.type}/${p.slug}`] : []));
+const vercelEnvArgs = (target) => ({
+    rm: ["env", "rm", CONTENT_ADAPTER_VAR, target, "--yes"],
+    add: ["env", "add", CONTENT_ADAPTER_VAR, target],
+    ls: ["env", "ls", target],
+});
+const deployArgs = (target) => (target === "production" ? ["deploy", "--prod"] : ["deploy"]);
+// ── The command (D7) ────────────────────────────────────────────────────────
+export async function cutover(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    const fetch = opts.fetch ?? globalThis.fetch;
+    const apply = opts.apply === true;
+    const refuse = (message) => {
+        throw new CutoverRefusedError(`cutover: ${message} Nothing was run.`);
+    };
+    // Refusals, before step 1.
+    const access = resolveWorkspaceAccess(targetDir, { apiUrl: opts.apiUrl, workspaceId: opts.workspaceId, env }, refuse);
+    const rawBefore = given(opts.before);
+    const rawAfter = given(opts.after);
+    if (rawBefore === undefined)
+        refuse("pass --before <origin>, the site served from its files.");
+    if (rawAfter === undefined)
+        refuse("pass --after <origin>, a deployment reading the database.");
+    const before = siteOrigin(rawBefore, "--before", refuse);
+    const after = siteOrigin(rawAfter, "--after", refuse);
+    const target = opts.envTarget ?? "preview";
+    if (!ENV_TARGETS.includes(target))
+        refuse("--env-target must be preview or production.");
+    const tolerance = opts.pixelTolerance ?? 0;
+    if (!(tolerance >= 0 && tolerance <= 1))
+        refuse("--pixel-tolerance must be a ratio from 0 to 1.");
+    const bypass = given(env[BYPASS_ENV_VAR]);
+    const afterHeaders = bypass === undefined ? undefined : { "x-vercel-protection-bypass": bypass };
+    const { defaultLocale } = readSiteLocales(targetDir);
+    const web = join(targetDir, "apps", "web");
+    const spoke = access.spokeKey !== undefined;
+    const deps = {
+        migrate: ({ apply: write }) => migrateContent({
+            targetDir,
+            apply: write,
+            apiUrl: opts.apiUrl,
+            workspaceId: opts.workspaceId,
+            env,
+            fetch,
+            ...(opts.adapters !== undefined && { adapters: opts.adapters }),
+        }),
+        list: async () => (await listWorkspacePages(access, fetch, defaultLocale, refuse)).filter((r) => r.locale === defaultLocale),
+        inventory: async () => {
+            const result = await inventory({
+                targetDir,
+                origin: before,
+                docsPath: opts.docsPath,
+                apiUrl: opts.apiUrl,
+                workspaceId: opts.workspaceId,
+                env,
+                fetch,
+                ...(opts.codec !== undefined && { codec: opts.codec }),
+                onLine: (line) => onLine(`  ${line}`),
+            });
+            return { exitCode: result.exitCode, summary: formatAuditCounts(result.audit.counts) };
+        },
+        frozen: () => {
+            const inv = readInventory(targetDir);
+            if (inv === undefined)
+                return undefined;
+            const images = inv.images.flatMap((i) => {
+                const url = new URL(i.url);
+                return url.origin === inv.origin ? [url.pathname + url.search] : [];
+            });
+            return {
+                pages: inv.frozen.filter((e) => e.kind === "page").map((e) => e.path),
+                sweep: [...inv.frozen.map((e) => e.path), ...images],
+            };
+        },
+        compare: async (o) => {
+            const chromium = loadChromium([targetDir, process.cwd()]);
+            if (chromium === undefined) {
+                return { pass: false, summary: `no Playwright Chromium found — ${PLAYWRIGHT_INSTALL_HINT}` };
+            }
+            const report = await runComparison({
+                chromium,
+                before,
+                after: o.after,
+                ...(afterHeaders !== undefined && { afterHeaders }),
+                pages: o.pages,
+                sweepPaths: o.sweep,
+                tolerance,
+                screenshots: o.screenshots,
+                dir: o.dir,
+                fetch,
+                onLine: (line) => onLine(`  ${line}`),
+            });
+            const differing = report.pages.filter((p) => !p.pass).map((p) => p.path);
+            const not200 = report.sweep.results.filter((r) => r.status !== 200).length;
+            return {
+                pass: report.pass,
+                summary: `${report.pages.length - differing.length}/${report.pages.length} page(s) the same; sweep: ${not200} of ${report.sweep.results.length} not 200${differing.length > 0 ? `; differs: ${differing.join(", ")}` : ""}`,
+            };
+        },
+        run: spawnRunner,
+        git: spawnRunner,
+        ...opts.deps,
+    };
+    const runDir = join(targetDir, CUTOVER_DIR, "runs", stamp((opts.now ?? (() => new Date()))()));
+    const steps = CUTOVER_STEPS.map((name, i) => ({
+        n: i + 1,
+        name,
+        status: "not-run",
+        command: "",
+        evidence: [],
+    }));
+    const record = () => {
+        if (!apply)
+            return;
+        const runs = join(targetDir, CUTOVER_DIR, "runs");
+        mkdirSync(runDir, { recursive: true });
+        if (!existsSync(join(runs, ".gitignore")))
+            writeFileSync(join(runs, ".gitignore"), "*\n");
+        writeFileSync(join(runDir, "run.json"), `${JSON.stringify({ apply, steps }, null, 2)}\n`);
+    };
+    onLine(apply
+        ? `Cutting ${opts.targetDir} over: ${before} (files) → ${after} (database), env target ${target}.`
+        : `Planning the cutover of ${opts.targetDir}: ${before} (files) → ${after} (database), env target ${target}. Nothing is written or spawned without --apply.`);
+    // State the steps hand on.
+    let outcomes = [];
+    let deployed;
+    const STEP = {
+        import: async () => {
+            const command = `create-ailk migrate-content ${opts.targetDir}${apply ? " --apply" : ""}`;
+            // #10735 D8 — a Language render change stops here, before any write:
+            // `--apply` first plans, and imports only a plan with none.
+            const changes = (language) => language === undefined || language.renderChanges.length === 0
+                ? undefined
+                : [
+                    ...language.renderChanges.map(renderChangeLine),
+                    "make each listed copy match the words its line names (or reword the question), redeploy --before, and re-run",
+                ];
+            if (apply) {
+                const planned = changes((await deps.migrate({ apply: false })).language);
+                if (planned !== undefined)
+                    return { ok: false, command, evidence: planned };
+            }
+            const { result, language } = await deps.migrate({ apply });
+            outcomes = result.pages;
+            const { created, updated, unchanged, skipped, failed } = result.counts;
+            const counts = `created ${created} · updated ${updated} · unchanged ${unchanged} · skipped ${skipped} · failed ${failed}`;
+            const changed = changes(language);
+            return {
+                ok: failed === 0 && changed === undefined,
+                command,
+                evidence: [
+                    ...result.pages.filter((p) => p.result === "failed").map((p) => `${p.path}: failed`),
+                    counts,
+                    ...(language === undefined ? [] : [languageCountsLine(language, apply)]),
+                    ...(changed ?? []),
+                ],
+            };
+        },
+        publish: async () => {
+            const rows = new Map((await deps.list()).map((r) => [`${r.type}/${r.slug}`, r.status]));
+            const unpublished = imported(outcomes).filter((key) => rows.get(key) !== "published");
+            return {
+                ok: unpublished.length === 0,
+                command: "read the workspace list: every imported page is published",
+                evidence: unpublished.length === 0
+                    ? [`${imported(outcomes).length} imported page(s), all published`]
+                    : [
+                        ...unpublished.map((key) => `${key}: ${rows.get(key) ?? "absent"} — publish it in Admin`),
+                        "Publish these pages in Admin, then re-run. Publishing is a human act; the kit never publishes.",
+                    ],
+            };
+        },
+        inventory: async () => {
+            const command = `create-ailk inventory ${opts.targetDir} --origin ${before}`;
+            if (!apply) {
+                const frozen = deps.frozen();
+                return {
+                    ok: true,
+                    command,
+                    evidence: [
+                        frozen === undefined
+                            ? `not frozen: ${before} would be crawled into ${CUTOVER_DIR}/${INVENTORY_FILE}`
+                            : `frozen: ${frozen.sweep.length} URL(s), ${frozen.pages.length} page(s); the audit would be rewritten`,
+                    ],
+                };
+            }
+            const { exitCode, summary } = await deps.inventory();
+            return { ok: exitCode === 0, command, evidence: [`${CUTOVER_DIR}/${INVENTORY_FILE} and audit.json: ${summary}`] };
+        },
+        comparison: async () => {
+            const command = `compare every frozen page on ${before} and ${after} (text, JSON-LD, screenshots), sweep for 200`;
+            const frozen = deps.frozen();
+            if (!apply) {
+                return {
+                    ok: true,
+                    command,
+                    evidence: [frozen === undefined ? "every URL the inventory freezes" : `${frozen.pages.length} page(s), ${frozen.sweep.length} URL(s) swept`],
+                };
+            }
+            if (frozen === undefined)
+                return { ok: false, command, evidence: ["no frozen inventory"] };
+            const dir = join(runDir, "comparison");
+            const { pass, summary } = await deps.compare({ after, ...frozen, screenshots: true, dir });
+            return { ok: pass, command, evidence: [summary, `${dir}/comparison.md`] };
+        },
+        "set-env": async () => {
+            const args = vercelEnvArgs(target);
+            const command = `(cd apps/web && vercel ${args.rm.join(" ")}; echo database | vercel ${args.add.join(" ")})`;
+            if (!apply)
+                return { ok: true, command, evidence: [`${CONTENT_ADAPTER_VAR}=database on ${target}`] };
+            deps.run("vercel", args.rm, { cwd: web });
+            const added = deps.run("vercel", args.add, { cwd: web, input: "database" });
+            if (added.error === "ENOENT")
+                return { ok: false, command, evidence: ["vercel is not installed (npm i -g vercel)"] };
+            if (added.status !== 0)
+                return { ok: false, command, evidence: [`vercel env add exited ${added.status}`] };
+            if (spoke) {
+                const listed = deps.run("vercel", args.ls, { cwd: web });
+                if (listed.status !== 0 || !/\bAILK_SPOKE_KEY\b/.test(listed.stdout)) {
+                    return { ok: false, command, evidence: [`AILK_SPOKE_KEY is not set on ${target}: a spoke's database read needs it`] };
+                }
+            }
+            return { ok: true, command, evidence: [`${CONTENT_ADAPTER_VAR}=database on ${target}`] };
+        },
+        deploy: async () => {
+            const args = deployArgs(target);
+            const command = `(cd apps/web && vercel ${args.join(" ")})`;
+            if (!apply)
+                return { ok: true, command, evidence: ["the deployment URL"] };
+            const result = deps.run("vercel", args, { cwd: web });
+            deployed = [...result.stdout.matchAll(/https:\/\/[^\s"'<>]+/g)].at(-1)?.[0];
+            if (result.status !== 0 || deployed === undefined) {
+                return { ok: false, command, evidence: [`vercel deploy exited ${result.status}${deployed === undefined ? " with no URL" : ""}`] };
+            }
+            deployed = new URL(deployed).origin;
+            return { ok: true, command, evidence: [deployed] };
+        },
+        verify: async () => {
+            const command = `compare every frozen page on ${before} and the deployment (text, JSON-LD), sweep for 200`;
+            if (!apply)
+                return { ok: true, command, evidence: ["the deployment from step 6"] };
+            const frozen = deps.frozen();
+            if (frozen === undefined)
+                return { ok: false, command, evidence: ["no frozen inventory"] };
+            const dir = join(runDir, "verify");
+            const { pass, summary } = await deps.compare({ after: deployed, ...frozen, screenshots: false, dir });
+            return { ok: pass, command, evidence: [summary, `${dir}/comparison.md`] };
+        },
+        "remove-files": async () => {
+            const paths = removablePaths(outcomes);
+            const command = `git rm --quiet -- ${paths.join(" ")}`;
+            if (!apply)
+                return { ok: true, command, evidence: [`${paths.length} file(s), staged, never committed`] };
+            const refused = paths.filter((p) => p.split("/").some((s) => s.startsWith("_")));
+            if (refused.length > 0)
+                return { ok: false, command, evidence: refused.map((p) => `${p}: never removed`) };
+            const missing = paths.filter((p) => !existsSync(join(targetDir, p)));
+            if (missing.length > 0)
+                return { ok: false, command, evidence: missing.map((p) => `${p}: not in the work tree`) };
+            if (paths.length === 0)
+                return { ok: true, command, evidence: ["no file to remove"] };
+            const status = deps.git("git", ["status", "--porcelain", "--", ...paths], { cwd: targetDir });
+            if (status.status !== 0 || status.stdout.trim() !== "") {
+                return { ok: false, command, evidence: ["uncommitted changes in the files to remove — commit or discard them first", status.stdout.trim()] };
+            }
+            const removed = deps.git("git", ["rm", "--quiet", "--", ...paths], { cwd: targetDir });
+            return removed.status === 0
+                ? { ok: true, command, evidence: [`${paths.length} file(s) staged for removal; commit them`] }
+                : { ok: false, command, evidence: [`git rm exited ${removed.status}`] };
+        },
+    };
+    let exitCode = 0;
+    for (const step of steps) {
+        let result;
+        try {
+            result = await STEP[step.name]();
+        }
+        catch (err) {
+            // A refusal raised by the import before it sent anything is the run's
+            // refusal (exit 2); anything else thrown in a step fails that step.
+            if (step.n === 1 && err.exitCode === 2)
+                throw err;
+            result = { ok: false, command: step.command, evidence: [`error: ${err.message}`] };
+        }
+        step.command = result.command;
+        step.evidence = result.evidence;
+        step.status = !apply ? "planned" : result.ok ? "passed" : "failed";
+        onLine(`[${step.n}/8] ${step.name}: ${step.status} — ${step.command}`);
+        for (const line of result.evidence)
+            onLine(`      ${line}`);
+        record();
+        // A dry run fails only on its import plan; a later step is planned, not run.
+        if (!result.ok && (apply || step.name === "import"))
+            exitCode = 1;
+        if (!result.ok && apply)
+            break;
+    }
+    if (apply) {
+        onLine(exitCode === 0
+            ? `Cut over. Commit the removal and ${CUTOVER_DIR}/; the run record is ${runDir}.`
+            : `Stopped. The run record is ${runDir}. Rollback: docs/internal/runbooks/site-cutover.md.`);
+    }
+    else {
+        onLine("Dry run: nothing was written or spawned. Re-run with --apply to cut over.");
+    }
+    return { exitCode, steps };
+}
+export const CUTOVER_HELP = `create-ailk cutover — move a site from its page files to its database, one checked step at a time.
+
+Usage:
+  AILK_AGENT_KEY=<key> create-ailk cutover [<dir>] --before <origin> --after <origin> [--apply] [--env-target preview|production] [--docs-path <path>] [--pixel-tolerance <ratio>] [--api-url <origin>] [--workspace <wksp_id>]
+
+Arguments:
+  <dir>                      The site. Defaults to the current dir.
+
+Options:
+  --before <origin>          The site served from its files.
+  --after <origin>           A deployment reading the database (a preview
+                             with CONTENT_ADAPTER=database).
+  --apply                    Run the steps. Without it the command plans
+                             them: it sends only reads, spawns nothing and
+                             writes nothing.
+  --env-target <target>      preview (the default) or production — where
+                             step 5 sets CONTENT_ADAPTER and step 6 deploys.
+  --docs-path <path>         Where the site serves its docs. Default /docs.
+  --pixel-tolerance <ratio>  The share of a screenshot's pixels that may
+                             differ. Default 0.
+  --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.
+
+Steps, in this order; the first that fails stops the run:
+  1 import        create-ailk migrate-content <dir> --apply; stops, before
+                  writing, when the import would change a page's render
+  2 publish       every imported page is published (publish in Admin)
+  3 inventory     create-ailk inventory <dir> --origin <before>; audit passes
+  4 comparison    text, JSON-LD and screenshots per frozen page, before and
+                  after, at 1440 and 390 wide; every frozen URL answers 200
+  5 set env       vercel env add CONTENT_ADAPTER <target> = database (apps/web)
+  6 deploy        vercel deploy [--prod] (apps/web)
+  7 verify        text and JSON-LD per frozen page on the deployment; 200s
+  8 remove files  git rm --quiet -- <the imported files> (staged, not committed)
+
+Each run writes .ailk-cutover/runs/<UTC time>/run.json and the comparison's
+evidence beside it (gitignored). The comparison needs Playwright's Chromium:
+${PLAYWRIGHT_INSTALL_HINT}. When VERCEL_AUTOMATION_BYPASS_SECRET is set,
+requests to --after and the deployment carry it. The agent key needs the
+content-edit grant; on a spoke, AILK_SPOKE_KEY is needed too. The rollback
+is create-ailk export-content (docs/internal/runbooks/site-cutover.md).
+Exit 0 when every step passed (a dry run: when the import plan has no
+failed page), 1 when one failed, 2 on a refusal.
+`;
+export function parseCutoverArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                before: { type: "string" },
+                after: { type: "string" },
+                apply: { type: "boolean", default: false },
+                "env-target": { type: "string" },
+                "docs-path": { type: "string" },
+                "pixel-tolerance": { type: "string" },
+                "api-url": { type: "string" },
+                workspace: { type: "string" },
+                help: { type: "boolean", default: false, short: "h" },
+            },
+        });
+    }
+    catch (err) {
+        throw new ParseError(`cutover: ${err.message}`);
+    }
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`cutover takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    const envTarget = parsed.values["env-target"];
+    if (envTarget !== undefined && !ENV_TARGETS.includes(envTarget)) {
+        throw new ParseError("cutover: --env-target must be preview or production");
+    }
+    const tolerance = parsed.values["pixel-tolerance"];
+    const pixelTolerance = tolerance === undefined ? undefined : Number(tolerance);
+    if (pixelTolerance !== undefined && (tolerance.trim() === "" || Number.isNaN(pixelTolerance))) {
+        throw new ParseError("cutover: --pixel-tolerance must be a number from 0 to 1");
+    }
+    return {
+        target,
+        before: parsed.values.before,
+        after: parsed.values.after,
+        apply: parsed.values.apply === true,
+        envTarget: envTarget,
+        docsPath: parsed.values["docs-path"],
+        pixelTolerance,
+        apiUrl: parsed.values["api-url"],
+        workspaceId: parsed.values.workspace,
+        help: parsed.values.help === true,
+    };
+}

package/dist/design-presets.js

@@ -94,11 +94,14 @@ export function shippedPageTypes(siteTemplatesDir) {
 // ── D3: validateDesignPresets ──────────────────────────────────────────────
 /** The JSON Schema keywords the value check evaluates (spec § 1.2); `default` is not a constraint. */
 const SUPPORTED_KEYWORDS = new Set([
+    "additionalProperties",
     "anyOf",
     "const",
     "default",
     "enum",
     "exclusiveMinimum",
+    "maximum",
+    "minimum",
     "properties",
     "type",
 ]);
@@ -173,13 +176,26 @@ function checkValue(schema, value, field, label) {
     if (typeof min === "number" && !(typeof value === "number" && value > min)) {
         return { field, reason: `must be greater than ${min}` };
     }
-    if (isPlainObject(schema["properties"]) && isPlainObject(value)) {
-        const properties = schema["properties"];
+    const minimum = schema["minimum"];
+    if (typeof minimum === "number" && !(typeof value === "number" && value >= minimum)) {
+        return { field, reason: `must be at least ${minimum}` };
+    }
+    const maximum = schema["maximum"];
+    if (typeof maximum === "number" && !(typeof value === "number" && value <= maximum)) {
+        return { field, reason: `must be at most ${maximum}` };
+    }
+    if ((isPlainObject(schema["properties"]) || hasOwn(schema, "additionalProperties")) &&
+        isPlainObject(value)) {
+        const properties = isPlainObject(schema["properties"]) ? schema["properties"] : {};
+        // An unlisted sub-key is refused unless `additionalProperties` admits it
+        // (`true`, or a schema it is then checked against); absent or `false` refuses.
+        const extra = schema["additionalProperties"];
         for (const [sub, subValue] of Object.entries(value)) {
-            if (!hasOwn(properties, sub)) {
+            const listed = hasOwn(properties, sub);
+            if (!listed && extra !== true && !isPlainObject(extra)) {
                 return { field: `${field}.${sub}`, reason: `is not a field of ${label}` };
             }
-            const failure = checkValue(properties[sub], subValue, `${field}.${sub}`, `${label}.${sub}`);
+            const failure = checkValue(listed ? properties[sub] : extra, subValue, `${field}.${sub}`, `${label}.${sub}`);
             if (failure !== undefined)
                 return failure;
         }

package/dist/export-content.d.ts

@@ -0,0 +1,55 @@
+import { type WordsCodec } from "./inventory.js";
+import { type LanguageItemKind } from "./language-import.js";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export declare class ExportContentRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export declare const SPOKE_HINT = "the site's read does not serve this workspace's published version \u2014 is the spoke at --store database?";
+/** The site-relative file a stored page is written to, and whether it is editorial. */
+export declare function fileFor(targetDir: string, type: string, slug: string, locale: string): {
+    path: string;
+    editorial: boolean;
+};
+/**
+ * The file whose import yields `content` again with `sections` as its layout,
+ * or why there is none.
+ */
+export declare function recombine(content: Record<string, unknown>, sections: readonly unknown[] | undefined, codec: WordsCodec, editorial: boolean, pinned?: Record<LanguageItemKind, Map<string, Record<string, string>>>): {
+    text: string;
+} | {
+    reason: string;
+};
+export interface ExportContentOptions {
+    targetDir: string;
+    /** `--dry-run`: print what would be written, write nothing. */
+    dryRun?: boolean;
+    apiUrl?: string | undefined;
+    workspaceId?: string | undefined;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof globalThis.fetch;
+    /** Injectable for tests; defaults to the site's installed codec. */
+    codec?: WordsCodec;
+    onLine?: (line: string) => void;
+}
+export interface ExportedPage {
+    type: string;
+    slug: string;
+    /** The site-relative file; `null` when the page failed before one was chosen. */
+    file: string | null;
+    result: "created" | "written" | "unchanged" | "failed";
+    reason?: string;
+}
+export declare function exportContent(opts: ExportContentOptions): Promise<{
+    exitCode: 0 | 1;
+    pages: ExportedPage[];
+}>;
+export interface ExportContentArgs {
+    target: string | undefined;
+    dryRun: boolean;
+    apiUrl: string | undefined;
+    workspaceId: string | undefined;
+    help: boolean;
+}
+export declare const EXPORT_CONTENT_HELP = "create-ailk export-content \u2014 write every published page back to its content file.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk export-content [<dir>] [--dry-run] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --dry-run                Print what would be written, and write nothing.\n  --api-url <origin>       The API origin that holds the workspace \u2014 on a\n                           spoke, its hub's. Else AILK_API_URL.\n  --workspace <wksp_id>    The workspace. Else AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nThe rollback for a cutover: every page the workspace list reports published\nin the default locale is written to the file migrate-content reads it from\n\u2014 content/en/<Type>/<slug>.mdx (or the legacy content/<Type>/<slug>.mdx that\nexists), apps/web/content/en/blog/<slug>.mdx for a post and the same under\ndocs for a docs page \u2014 with its words moved back into its sections, so a\nre-run of migrate-content reports every page unchanged. Published edits are\nkept. A page with a draft ahead of its published version fails by name:\npublish or revert it in Admin, then re-run. The site's own API read must\nserve the workspace's published version (on a spoke, the hub's row at\n--store database). Each page prints created, written, unchanged or failed.\nThe agent key needs the content-edit grant; on a spoke, AILK_SPOKE_KEY is\nneeded too. Exit 0 when no page failed, 1 when any did, 2 on a refusal.\n";
+export declare function parseExportContentArgs(argv: string[]): ExportContentArgs;