@heroiclands/package-build 25.6.3 → 25.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @heroiclands/package-build
 
+## 25.7.0
+
+**Rendering and sites**
+
+- Preview a saved note with its website body, theme styles and findings, without building the whole site; unchanged inputs are cached for later previews.
+- Content indexing and builds that use it are faster on large content trees.
+- Root sites can generate matching menus and published navigation for the selected address, validating canonical roster data before replacing previous output.
+
+**Builds and commands**
+
+- An explicit root selects matching website and image addresses; without it, configured image hosts stay in use.
+- CDN publication defaults to internal atlas storage; choose `--dest cloudflare` for the public bucket.
+
+**Upgrading**
+
+- Pass `--root heroiclands.org` to public builds; website builds now default to `internal.heroiclands.org`.
+
 ## 25.6.3
 
 **Rendering and sites**

package/README.md

@@ -20,6 +20,13 @@ Build indexes, calendars, staged assets and packs together with `package-build c
 
 Run selected content operations together with `package-build content run index lint links compile`. The [shared content command](docs/commands.md#package-build-content-run-targets) captures one source tree for the selected checks and outputs; standalone commands remain available.
 
+Render one note to the body HTML its site page carries with
+`@heroiclands/package-build/note-page`: `renderNoteFile(path, { root })` reads a
+saved note of a repository against its content tree and fetched dependency
+indexes, and returns `{ html, styles, findings, cache }`. What it derives is
+kept in `build/cache/note-page/` and reused while its inputs are unchanged, so a
+second preview is fast; see [`./note-page`](docs/api.md#note-page).
+
 Language annotations keep authored spelling: `[Zaron]{lang=vyl}` stays Roman.
 Add `.nativefont` with an explicit `lang=` to use native script defaults;
 see [writing in invented scripts](docs/guides/writing-in-invented-scripts.md).
@@ -87,6 +94,7 @@ The documentation lives in the Markdown files in this repository. Start with [th
 | Invented languages and scripts                    | [Write in invented scripts](docs/guides/writing-in-invented-scripts.md)   |
 | Encoding rules and the conversion core            | [Encoding core](docs/encoding-core.md)                                    |
 | Buffer-only preview and Gitea rendering           | [Source preview](docs/source-preview.md)                                  |
+| One note as its site page's body                  | [`./note-page`](docs/api.md#note-page)                                    |
 | Every CLI command                                 | [Commands](docs/commands.md)                                              |
 | Every build setting                               | [Configuration](docs/configuration.md)                                    |
 | Programmatic exports                              | [API](docs/api.md)                                                        |
@@ -97,7 +105,7 @@ Place notes may declare a governing affiliation with `data.government` (`Address
 
 Every icon and image is covered by a provenance record stating `attribution`, `license` and `ai`. A Foundry package ships only the pictures whose record says `ai: false` under a licence on the shipping list, staged flat at the package root as `icons/<basename>` and `images/<basename>` and listed in its asset set, `asset-sets/default.json`; a reference to a picture it leaves out draws the package's `missing` stand-in, and every compiled reference states its asset's address. See [assets](docs/authoring/assets.md#what-the-foundry-package-ships) and [what a package ships](docs/reference/format-details.md#what-a-package-ships).
 
-`package-build cdn publish --set <file> --name <display name>` uploads every icon and image the package has, shipped or not, to `<site.assets>/<contentPackage>/` in that flat layout, and writes the named set listing the pictures the package leaves out. It reads the bucket from `CDN_ENDPOINT`, `CDN_BUCKET`, `CDN_ACCESS_KEY_ID` and `CDN_SECRET_ACCESS_KEY`, in the environment or `.env.local`. See [publish pictures to the CDN](docs/guides/release-and-deploy.md#publish-pictures-to-the-cdn).
+`package-build cdn publish [--dest internal|cloudflare] --set <file> --name <display name>` manually uploads every icon and image, shipped or left out, and writes a named set listing the left-out pictures. The default publishes to atlas at `https://cdn.internal.heroiclands.org/<contentPackage>/` using SSH and rsync. `--dest cloudflare` uses the existing R2 bucket at `site.assets` and its `CDN_ENDPOINT`, `CDN_BUCKET`, `CDN_ACCESS_KEY_ID` and `CDN_SECRET_ACCESS_KEY` environment settings. Site builds never publish pictures. See [publish pictures to the CDN](docs/guides/release-and-deploy.md#publish-pictures-to-the-cdn).
 
 Leading captions, fenced divs, inline spans, and verse quotations are described in [links and markup](docs/authoring/links-and-markup.md).
 
@@ -107,3 +115,13 @@ installed browser with `package-build e2e fast -- --browser electron` (also
 available for `run` and `open`). See [browser selection and cache settings](docs/guides/e2e.md#choose-a-browser).
 
 The package is GPL-3.0-or-later for code and CC-BY-SA-4.0 for original content. See [LICENSE.md](LICENSE.md).
+
+## Pull request checks
+
+A pull request whose title starts with `WIP:` runs the light checks. An existing
+required check runs a short guard and fails, blocking merges while the expensive
+steps stay skipped. Remove the prefix with `earl pr ready`; it starts fresh
+required checks before scheduling a merge. Changing the title by hand does not
+start those checks. Main, release and manual runs keep their existing checks.
+
+Check the workflow gating locally with `node --test ci/wip-workflows.test.mjs`.

package/bin/content-commands.mjs

@@ -133,6 +133,11 @@ import {
     siteBuildFailed,
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
+import {
+    addressDiagnostic,
+    frontmatterLinkDiagnostic,
+    pageDiagnostics,
+} from "../engine/site-page.mjs";
 import { buildPackageSite, siteDirectory } from "../engine/site-render.mjs";
 import { serveSite } from "../engine/site-serve.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
@@ -2172,23 +2177,8 @@ function reportSiteBuild(result) {
     // or two competing for it, has nothing to say about its pages
     // yet.
     for (const f of gates.homepages) emitDiagnostic(f);
-    for (const f of gates.frontmatterLinks) {
-        emitDiagnostic({
-            file: f.file,
-            severity: "error",
-            message:
-                `wikilink ${f.link} authored in frontmatter at ` +
-                `${f.path} — frontmatter is data, is copied to the ` +
-                `page verbatim, and reaches the reader as brackets`,
-        });
-    }
-    for (const f of gates.addressErrors) {
-        emitDiagnostic({
-            file: f.file,
-            severity: "error",
-            message: `cannot derive a URL: ${f.reason}`,
-        });
-    }
+    for (const f of gates.frontmatterLinks) emitDiagnostic(frontmatterLinkDiagnostic(f));
+    for (const f of gates.addressErrors) emitDiagnostic(addressDiagnostic(f));
     reportSiteFindings(gates.sections ?? []);
     for (const s of gates.staleManifests) {
         emitDiagnostic({
@@ -2208,58 +2198,7 @@ function reportSiteBuild(result) {
     // would make a single bad table hide every other problem in the tree.
     // Each is `file:line:column: error: message`, path first — the shape
     // the pack build reports the same findings in.
-    for (const e of result.tableErrors) {
-        emitDiagnostic({
-            file: e.source,
-            line: typeof e.line === "number" ? e.line + 1 : undefined,
-            column: e.column,
-            severity: "error",
-            message: e.reason,
-        });
-    }
-    for (const e of result.expressionErrors) {
-        emitDiagnostic(e);
-    }
-    for (const e of result.secretErrors) {
-        emitDiagnostic({ ...e, severity: "error" });
-    }
-    for (const e of result.captionErrors) {
-        emitDiagnostic({ ...e, severity: "error" });
-    }
-    for (const e of result.headingErrors) {
-        emitDiagnostic({ ...e, severity: "error" });
-    }
-    for (const e of result.footnoteErrors) {
-        emitDiagnostic({ ...e, severity: "error" });
-    }
-    for (const e of result.embedErrors) {
-        emitDiagnostic({ ...e, severity: "error" });
-    }
-    // Worded by the shared table the pack build words the same finding
-    // with, and located by searching the note for the link.
-    for (const e of result.wikiErrors) {
-        emitDiagnostic({
-            file: e.file,
-            ...positionOfLiteral(readRawNote(e.file), e.link, e.occurrence),
-            severity: "error",
-            // An embed's directive speaks the image vocabulary
-            // rather than the link one, and carries its own
-            // sentence; everything else is worded by the shared
-            // table.
-            message: e.message ?? linkFindingMessage(e),
-        });
-    }
-    // An image whose pathname the site cannot resolve, located the
-    // way a wikilink finding is: by searching the note for the
-    // literal the resolver was handed.
-    for (const e of result.imageErrors) {
-        emitDiagnostic({
-            file: e.file,
-            ...positionOfLiteral(readRawNote(e.file), e.src, e.occurrence),
-            severity: "error",
-            message: e.message,
-        });
-    }
+    for (const d of pageDiagnostics(result, readRawNote)) emitDiagnostic(d);
     if (siteBuildFailed(result)) return false;
 
     // Relation warnings do not fail a site build.
@@ -2307,11 +2246,11 @@ function withSiteBuildConfig(command) {
     return {
         ...command,
         handler: async (argv) => {
-            if (argv.baseUrl === undefined && argv.assets === undefined) return handler(argv);
             try {
                 const authored = argv[CONTENT_CONFIG] ?? loadPackConfig();
                 checkHomepage(authored.homepage, authored.contentPackage, authored.site.base);
                 const config = siteBuildConfig(authored, {
+                    root: argv.root,
                     baseUrl: argv.baseUrl,
                     assets: argv.assets,
                 });
@@ -2377,6 +2316,11 @@ function siteBuildCommand() {
                     type: "string",
                     describe: `The directory that is deployed (default: ${DEPLOY_ROOT})`,
                 })
+                .option("root", {
+                    type: "string",
+                    requiresArg: true,
+                    describe: "Domain for www and CDN origins (default: internal.heroiclands.org)",
+                })
                 .option("base-url", {
                     type: "string",
                     requiresArg: true,

package/bin/package-build.mjs

@@ -61,7 +61,7 @@
  *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
- *   npx package-build cdn publish --set <file> --name <display name> [--dry-run]
+ *   npx package-build cdn publish [--dest internal|cloudflare] --set <file> --name <display name> [--dry-run]
  *   npx package-build container <stage> <action>
  *   npx package-build e2e <seed|run|open|fast|sweep>
  *
@@ -96,6 +96,8 @@ import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, resetStage } from "../stage.mjs";
 import {
     CDN_ENV,
+    INTERNAL_CDN_HOST,
+    internalStore,
     cdnCredentials,
     noteArtFindings,
     noteArtReferences,
@@ -1417,11 +1419,9 @@ function deployCommand() {
  * `cdn publish` — upload every picture the package has to the CDN, and the art
  * the package leaves out as a named asset set.
  *
- * The one writer to `<site.assets>/<package>/`. It is run by hand or by a
- * dispatched workflow, never by a build or a release. The store is named by
- * the `CDN_*` variables in `CDN_ENV`, read from the environment or
- * `.env.local`; a dry run with none of them set compares against the public
- * CDN instead.
+ * Run manually, separate from builds and releases. Internal uses rsync to atlas
+ * and public HTTPS reads. Cloudflare uses the existing `CDN_*` R2 credentials;
+ * without those credentials its dry run compares against `site.assets`.
  *
  * @returns {object} The yargs command module.
  */
@@ -1431,6 +1431,12 @@ function cdnPublishCommand() {
         describe: "Upload every picture to the CDN and write a named asset set",
         builder: (y) =>
             y
+                .option("dest", {
+                    type: "string",
+                    choices: ["internal", "cloudflare"],
+                    default: "internal",
+                    describe: "CDN destination: atlas or Cloudflare R2",
+                })
                 .option("set", {
                     type: "string",
                     demandOption: true,
@@ -1455,15 +1461,18 @@ function cdnPublishCommand() {
             if (setProblem) die(setProblem);
             const name = String(args.name ?? "").trim();
             if (!name) die("`--name` is blank; a set needs a display name");
-            const host = String(packConfig.site?.assets ?? "").trim();
+            const host =
+                args.dest === "internal" ?
+                    INTERNAL_CDN_HOST
+                :   String(packConfig.site?.assets ?? "").trim();
             if (!host) {
                 die(
                     "`site.assets` is not declared, and it is the CDN root every picture " +
                         "is published under",
                 );
             }
-            const credentials = cdnCredentials(process.env);
-            if (!credentials && !args.dryRun) {
+            const credentials = args.dest === "cloudflare" ? cdnCredentials(process.env) : null;
+            if (args.dest === "cloudflare" && !credentials && !args.dryRun) {
                 die(
                     `no CDN store is configured: set ${Object.values(CDN_ENV).join(", ")} ` +
                         "in the environment or `.env.local`",
@@ -1501,7 +1510,13 @@ function cdnPublishCommand() {
                 records: plan.records,
             });
 
-            const store = credentials ? s3Store(credentials) : publicStore(host);
+            const store =
+                args.dest === "internal" ?
+                    args.dryRun ?
+                        publicStore(host)
+                    :   internalStore({ destination: process.env.CDN_INTERNAL_DESTINATION })
+                : credentials ? s3Store(credentials)
+                : publicStore(host);
             console.log(
                 `${args.dryRun ? "Dry run: comparing" : "Publishing"} ${plan.uploads.length} ` +
                     `pictures against ${store.describe}.`,

package/ci/wip-workflows.test.mjs

@@ -0,0 +1,252 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { test } from "node:test";
+
+const yaml = createRequire(import.meta.url)("yaml");
+const spec = {
+    file: "build.yml",
+    gated: ["test-build"],
+    light: "light",
+    runs: [
+        "npm run format:check",
+        "npm run lint:markdown",
+        "npm run lint:docs-links",
+        "npm run lint:content-format",
+        "node bin/package-build.mjs changelog check",
+    ],
+    dependency: "light",
+    test: "ci/wip-workflows.test.mjs",
+    required: [
+        "Build and Test / Build & Test (pull_request)",
+        "No Attribution / No AI attribution (pull_request)",
+    ],
+    lightActions: [
+        "HeroicLands/.github/actions/githooks",
+        "HeroicLands/.github/actions/todos",
+        "HeroicLands/.github/actions/no-attribution",
+    ],
+};
+const workflows = Object.fromEntries(
+    fs
+        .readdirSync(".gitea/workflows")
+        .filter((name) => name.endsWith(".yml"))
+        .map((name) => [
+            name,
+            yaml.parse(fs.readFileSync(path.join(".gitea/workflows", name), "utf8")),
+        ]),
+);
+const workflow = workflows[spec.file];
+const jobs = workflow.jobs;
+
+// Evaluate the job and step condition surface used here, including Gitea's
+// implicit success() and case-insensitive startsWith().
+function condition(
+    expression,
+    {
+        title,
+        event = "pull_request",
+        results = {},
+        steps = {},
+        success = true,
+        cancelled = false,
+    } = {},
+) {
+    const source = String(expression ?? "success()").replace(/^\$\{\{\s*|\s*\}\}$/g, "");
+    if (!/\b(?:always|cancelled|success|failure)\(/.test(source) && !success) return false;
+    const needs = Object.fromEntries(
+        Object.entries(results).map(([id, result]) => [id, { result, outputs: { run: "true" } }]),
+    );
+    return Function(
+        "github",
+        "needs",
+        "steps",
+        "startsWith",
+        "cancelled",
+        "success",
+        "failure",
+        "always",
+        `return (${source});`,
+    )(
+        { event_name: event, event: { pull_request: { title } } },
+        needs,
+        steps,
+        (value, prefix) =>
+            String(value ?? "")
+                .toLowerCase()
+                .startsWith(prefix.toLowerCase()),
+        () => cancelled,
+        () => success,
+        () => !success && !cancelled,
+        () => true,
+    );
+}
+function enabled(job, title, event = "pull_request", results = {}, cancelled = false) {
+    const dependencies = [job.needs ?? []].flat();
+    const all = Object.fromEntries(dependencies.map((id) => [id, results[id] ?? "success"]));
+    return condition(job.if, {
+        title,
+        event,
+        results: all,
+        cancelled,
+        success: Object.values(all).every((result) => result === "success"),
+    });
+}
+function shell(run, env = {}) {
+    const localEnv = { ...process.env };
+    delete localEnv.PR_TITLE;
+    delete localEnv.LIGHT_RESULT;
+    return spawnSync("bash", ["-e", "-o", "pipefail", "-c", run], { env: { ...localEnv, ...env } })
+        .status;
+}
+const requiredJobs = Object.entries(jobs).filter(([id, job]) =>
+    spec.required.includes(`${workflow.name} / ${job.name ?? id} (pull_request)`),
+);
+
+test("a required merge gate runs and fails on WIP instead of satisfying branch protection", () => {
+    const gates = requiredJobs.filter(([, job]) => enabled(job, "WIP: work"));
+    const blockers = gates.filter(
+        ([, job]) => job.steps?.[0]?.name === "Require a ready pull request",
+    );
+    assert.ok(
+        blockers.length,
+        "all required checks were satisfied or skipped without a WIP blocker",
+    );
+    for (const [, job] of blockers) {
+        assert.doesNotMatch(job.if ?? "", /startsWith/);
+        const guard = job.steps[0];
+        assert.notEqual(job["continue-on-error"], true);
+        assert.notEqual(guard["continue-on-error"], true);
+        assert.equal(condition(guard.if, { title: "WIP: work" }), true);
+        for (const result of ["success", "failure", "cancelled", "skipped"]) {
+            const results = Object.fromEntries([job.needs ?? []].flat().map((id) => [id, result]));
+            assert.equal(enabled(job, "WIP: work", "pull_request", results), true);
+        }
+        assert.equal(guard.env.PR_TITLE, "${{ github.event.pull_request.title }}");
+        assert.ok(
+            !guard.run.includes("${{ github.event.pull_request.title }}"),
+            "titles must be passed through env",
+        );
+        assert.equal(shell(guard.run), 0, "raw local replay");
+        for (const title of ["WIP: work", "wip: work", "WIP: $(exit 7)"])
+            assert.equal(shell(guard.run, { PR_TITLE: title }), 1);
+        assert.equal(shell(guard.run, { PR_TITLE: "Ready $(exit 7)" }), 0);
+    }
+});
+
+test("every expensive job or step skips WIP while ready and non-PR work remains applicable", () => {
+    const heavy = [
+        ...spec.gated.map((id) => jobs[id]),
+        ...(spec.e2e ? [workflows["e2e-full.yml"].jobs["full-e2e"]] : []),
+    ];
+    // Also derive the compile and reusable-e2e surface from the workflows.
+    for (const current of Object.values(workflows)) {
+        if (!Object.hasOwn(current.on ?? {}, "pull_request")) continue;
+        for (const job of Object.values(current.jobs ?? {}))
+            if (
+                ["build", "ubuntu-vm"].includes(job["runs-on"]) ||
+                /\/workflows\/e2e-full\.yml@/.test(job.uses ?? "")
+            )
+                if (!heavy.includes(job)) heavy.push(job);
+    }
+    for (const job of heavy) {
+        assert.ok(job);
+        assert.equal(enabled(job, "Ready work"), true, job.name);
+        for (const event of ["push", "schedule", "workflow_dispatch"])
+            assert.equal(enabled(job, undefined, event), true, `${job.name}: ${event}`);
+        if (!enabled(job, "WIP: work")) continue;
+        assert.equal(job.steps[0].name, "Require a ready pull request");
+        const outcomes = Object.fromEntries(
+            job.steps.filter((step) => step.id).map((step) => [step.id, { outcome: "success" }]),
+        );
+        for (const step of job.steps.slice(1)) {
+            assert.match(step.if ?? "", /startsWith.*WIP:/, step.name ?? step.uses);
+            assert.equal(
+                condition(step.if, { title: "WIP: work", steps: outcomes }),
+                false,
+                step.name ?? step.uses,
+            );
+        }
+    }
+});
+test("light checks, attribution and changeset review remain independent on WIP", () => {
+    const light = Object.values(workflows)
+        .flatMap((w) => Object.values(w.jobs ?? {}))
+        .filter((job) => !String(job.if ?? "").includes("startsWith"));
+    const steps = light.flatMap((job) => job.steps ?? []);
+    for (const run of spec.runs)
+        assert.ok(
+            steps.some((step) => step.run === run || step.run?.includes(`${run}\n`)),
+            `missing light command: ${run}`,
+        );
+    for (const action of spec.lightActions)
+        assert.ok(
+            steps.some((step) => step.uses?.split("@")[0] === action),
+            `missing light action: ${action}`,
+        );
+    assert.equal(enabled(jobs[spec.light], "WIP: work"), true);
+    assert.ok(![jobs[spec.light].needs ?? []].flat().some((id) => spec.gated.includes(id)));
+    for (const file of [spec.file, ...(spec.e2e ? ["e2e-full.yml"] : [])])
+        assert.ok(!workflows[file].on.pull_request?.types?.includes("edited"), file);
+});
+
+test("protected status context names retain their exact spelling", () => {
+    const names = Object.values(workflows).flatMap((w) =>
+        Object.entries(w.jobs ?? {}).map(
+            ([id, job]) => `${w.name} / ${job.name ?? id} (pull_request)`,
+        ),
+    );
+    for (const required of spec.required) assert.ok(names.includes(required), required);
+});
+
+if (spec.dependency)
+    test("light dependency results fail closed without breaking raw local replay", () => {
+        for (const id of spec.gated) {
+            const job = jobs[id];
+            assert.ok([job.needs ?? []].flat().includes(spec.dependency));
+            const check = job.steps.find((step) => step.name === "Require light checks");
+            assert.ok(check, id);
+            assert.equal(shell(check.run), 0);
+            assert.equal(check.env?.LIGHT_RESULT, `\${{ needs.${spec.dependency}.result }}`);
+            for (const result of ["success", "failure", "cancelled", "skipped", ""]) {
+                assert.equal(
+                    enabled(job, "Ready", "pull_request", { [spec.dependency]: result }),
+                    true,
+                );
+                assert.equal(
+                    shell(check.run, { LIGHT_RESULT: result }),
+                    result === "success" ? 0 : 1,
+                );
+                const outcomes = {
+                    ready: { outcome: "success" },
+                    light_checks: { outcome: result === "success" ? "success" : "failure" },
+                };
+                for (const step of job.steps.filter(
+                    (entry) =>
+                        !["Require a ready pull request", "Require light checks"].includes(
+                            entry.name,
+                        ),
+                ))
+                    assert.equal(
+                        condition(step.if, { title: "Ready", steps: outcomes }),
+                        result === "success",
+                        step.name ?? step.uses,
+                    );
+            }
+            assert.equal(enabled(job, "Ready", "pull_request", {}, true), false);
+        }
+    });

package/content-config.mjs

@@ -234,19 +234,34 @@ export function siteBase(config) {
  *
  * @param {ContentBuildConfig} config - The resolved authored configuration.
  * @param {object} options - Runtime options.
- * @param {string} [options.baseUrl] - Absolute HTTP(S) site URL ending in `/`.
- * @param {string} [options.assets] - Absolute HTTP(S) asset root.
- * @returns {ContentBuildConfig} The effective configuration, frozen.
- */
-export function siteBuildConfig(config, { baseUrl, assets }) {
-    if (baseUrl === undefined && assets === undefined) return config;
-    const homepage = baseUrl === undefined ? config.homepage : buildUrl(baseUrl, "--base-url").href;
-    const base =
-        baseUrl === undefined ? config.site.base : normalizeSiteBase(new URL(homepage).pathname);
+ * @param {string} [options.root] - Domain from which www and CDN origins derive.
+ *   Defaults to internal.heroiclands.org; explicit root replaces configured assets.
+ * @param {string} [options.baseUrl] - Absolute HTTP(S) site URL ending in `/`;
+ *   overrides the root-derived site URL.
+ * @param {string} [options.assets] - Absolute HTTP(S) asset root; overrides both
+ *   root-derived and configured assets.
+ * @returns {ContentBuildConfig} The effective configuration, frozen. Its homepage
+ *   and site.assets are the selected inputs for downstream site integrations.
+ */
+export function siteBuildConfig(config, { root, baseUrl, assets } = {}) {
+    const domain = root ?? "internal.heroiclands.org";
+    if (
+        typeof domain !== "string" ||
+        domain.length > 253 ||
+        !domain.includes(".") ||
+        !domain.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(label))
+    ) {
+        throw new TypeError("--root must be a domain without a scheme, path, port or credentials");
+    }
+    const homepage =
+        baseUrl === undefined ?
+            `https://www.${domain.toLowerCase()}${new URL(config.homepage).pathname}`
+        :   buildUrl(baseUrl, "--base-url").href;
+    const base = normalizeSiteBase(new URL(homepage).pathname);
     const assetRoot =
-        assets === undefined ?
-            config.site.assets
-        :   normalizeSiteAssets(buildUrl(assets, "--assets").href);
+        assets !== undefined ? normalizeSiteAssets(buildUrl(assets, "--assets").href)
+        : root !== undefined ? `https://cdn.${domain.toLowerCase()}`
+        : config.site.assets || `https://cdn.${domain.toLowerCase()}`;
     checkSiteSitemaps(config.site.sitemaps, base, config.contentPackage);
     return Object.freeze({
         ...config,
@@ -697,6 +712,8 @@ export function publishesContentPages(config) {
  *                                          `pack:` frontmatter, and one pack of
  *                                          the type is marked `default: true` to
  *                                          receive the notes that name none.
+ * @property {Record<string, any> & {inputs?: string}} [site] Site settings;
+ *                                          inputs names the optional local input provider.
  * @property {PathsInput} [paths]           Layout overrides. See {@link DEFAULT_PATHS}.
  * @property {string[]} [skipDirectories]   Directory names the content walk ignores
  *                                          wherever they appear (e.g. Obsidian's
@@ -752,6 +769,8 @@ export function publishesContentPages(config) {
  *                                     which Foundry serves no files for. See
  *                                     {@link module:engine/helpers.resolveImg},
  *                                     the one reader of it.
+ * @property {Readonly<Record<string, any> & {inputs: string}>} site Frozen site settings;
+ *                                     inputs is the local provider path or an empty string.
  * @property {Readonly<ResolvedPaths>} paths
  * @property {Readonly<StatsSpec>|null} stats  `null` for a `documentation`
  *                                     package, which stamps no `_stats`.
@@ -857,6 +876,7 @@ const SITE_KEYS = [
     "tags",
     "sitemaps",
     "mergeIndexes",
+    "inputs",
 ];
 const SITE_NOTFOUND_KEYS = ["tagline", "sitenoun", "heroimage", "links"];
 const SITE_NOTFOUND_LINK_KEYS = ["title", "url", "text"];
@@ -2011,6 +2031,7 @@ function normalizeSite(value, contentPackage) {
         tags: false,
         sitemaps: Object.freeze([]),
         mergeIndexes: Object.freeze([]),
+        inputs: "",
     });
     if (value === undefined) return empty;
     if (!isPlainObject(value)) fail("site", "must be a mapping");
@@ -2038,6 +2059,12 @@ function normalizeSite(value, contentPackage) {
         );
     }
 
+    const inputs =
+        input.inputs === undefined ? "" : requireNonEmptyString(input.inputs, "site.inputs");
+    if (inputs && !inputs.split("/").every((segment) => /^[a-z0-9][a-z0-9._-]*$/i.test(segment))) {
+        fail("site.inputs", "must be a plain relative module path without dot segments");
+    }
+
     return Object.freeze({
         base,
         title: input.title === undefined ? "" : requireNonEmptyString(input.title, "site.title"),
@@ -2060,6 +2087,7 @@ function normalizeSite(value, contentPackage) {
         tags: optionalBoolean(input.tags, "site.tags", false),
         sitemaps,
         mergeIndexes,
+        inputs,
     });
 }