@heroiclands/package-build 22.0.1 → 22.0.3

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @heroiclands/package-build
 
+## 22.0.3
+
+### Patch Changes
+
+- fd58dc0: **A package may ship assets and compile nothing.** `packs: []` is now a package
+  saying it has no documents, rather than one that forgot to say which, and a
+  package with no packs needs no content tree — its index is its asset records.
+  An alternative-art module is the case: the same addresses another package
+  publishes, resolving to different files when it is installed.
+  
+  A package that _does_ declare packs is unchanged: a missing content tree is
+  still a misconfigured path and still fails, and an index that would state a
+  package has no content at all is still refused.
+- cfdf061: **Two pieces of per-repository tooling move here.** Every site-publishing
+  package held its own copy of both, and a copy per consumer is a copy free to
+  drift — which is what happened, invisibly, because nobody reads all of them at
+  once.
+  
+  - `packageBuild.assetTransform: svg-theme` names a shipped transform, so an
+    icon follows the reader's colour scheme without a module in the repository.
+    The value still takes a path, so a consumer with a transform of its own is
+    unaffected.
+  - `package-build site-root` writes a deployment's `_headers` and `_redirects`:
+    indexing suppressed on every host-assigned address, and both spellings of the
+    prefix root redirected to the landing with a lifetime on the 301. The package
+    name comes from `contentPackage`, which was the only thing the copies actually
+    varied.
+
+## 22.0.2
+
+### Patch Changes
+
+- 83fa58e: **A record states `attribution` and `license`, or it is a finding.** The nearest
+  provenance record is the whole answer and is never merged with the one above it,
+  so a key left out is not inherited — it is absent, and a record stating neither
+  would leave every file beneath it with no rights holder and no terms. `source`,
+  `ai` and `notes` stay optional, because blank is a truthful answer for each.
+
 ## 22.0.1
 
 ### Patch Changes

package/bin/package-build.mjs

@@ -78,6 +78,7 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
+import { writeSiteRoot } from "../engine/site-root.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
@@ -466,6 +467,37 @@ function manifestCommand() {
     };
 }
 
+/**
+ * `package-build site-root` — the deployment's root files.
+ *
+ * Hugo owns everything under the `/<package>/` prefix; this owns what sits
+ * beside it, which is the pair Cloudflare Pages reads from the uploaded
+ * directory and nowhere else.
+ *
+ * @returns {object} The yargs command.
+ */
+function siteRootCommand() {
+    return {
+        command: "site-root",
+        describe: "Write the deployment's _headers and _redirects",
+        builder: (y) =>
+            y.option("out", {
+                type: "string",
+                describe: "The directory that is deployed (default: build/site)",
+            }),
+        handler: handler(async (argv) => {
+            const config = loadPackageBuildConfig();
+            const shared = loadPackConfig();
+            const out = path.resolve(config.rootDir, argv.out ?? "build/site");
+
+            const { files } = writeSiteRoot({ pkg: shared.contentPackage, out });
+            for (const file of files) {
+                console.log(`✅ Wrote ${path.relative(config.rootDir, file)}.`);
+            }
+        }),
+    };
+}
+
 /**
  * Every file matching a glob, as `{ path, text }` with the path relative to the
  * repository root — the form both the rules and the findings want.
@@ -1214,6 +1246,7 @@ yargs(hideBin(process.argv))
     .command(cleanCommand())
     .command(assetsCommand())
     .command(manifestCommand())
+    .command(siteRootCommand())
     .command(schemaCommand())
     .command(langCommand())
     .command(labelsCommand())

package/config.mjs

@@ -57,6 +57,7 @@
  */
 
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { loadPackConfig, locateConfigError, packConfigPath } from "./engine/pack-config.mjs";
 
 /** Keys the reserved section may declare. */
@@ -565,6 +566,39 @@ function normalizeExceptions(value, field, where) {
  *   collections, as collection → source directory.
  */
 
+/**
+ * The asset transforms this package ships, by the name a consumer writes.
+ *
+ * `packageBuild.assetTransform` takes either one of these names or a path to a
+ * module of the consumer's own. A name is the answer where every package wants
+ * the same behaviour — theming an icon to the reader's colour scheme is not a
+ * per-package decision, and a copy in each consumer is a copy that drifts.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const BUILT_IN_ASSET_TRANSFORMS = Object.freeze({
+    "svg-theme": "./engine/svg-theme.mjs",
+});
+
+/**
+ * Where a declared `assetTransform` is loaded from.
+ *
+ * A built-in name resolves to the module this package ships. Anything else is a
+ * path, resolved against the repository root the way it always was — so a
+ * consumer with a transform of its own is unaffected.
+ *
+ * @param {string} declared - The authored value.
+ * @param {string} rootDir - The repository root.
+ * @returns {string} An absolute path to import.
+ */
+export function resolveAssetTransform(declared, rootDir) {
+    const builtIn = BUILT_IN_ASSET_TRANSFORMS[declared];
+    if (builtIn) {
+        return path.resolve(path.dirname(fileURLToPath(import.meta.url)), builtIn);
+    }
+    return path.resolve(rootDir, declared);
+}
+
 /**
  * Resolve a package-build configuration from an already-loaded shared one.
  *
@@ -703,9 +737,9 @@ export function resolvePackageBuildConfig(shared) {
         assetTransform:
             section.assetTransform === undefined ?
                 null
-            :   path.resolve(
-                    shared.rootDir,
+            :   resolveAssetTransform(
                     requireNonEmptyString(section.assetTransform, "packageBuild.assetTransform"),
+                    shared.rootDir,
                 ),
         manifest: normalizeManifest(section.manifest),
         manifestFlags:

package/content-config.mjs

@@ -2328,10 +2328,17 @@ export function defineConfig(config) {
         }
     }
 
-    if (!documentation) {
-        if (!Array.isArray(input.packs)) fail("packs", "must be an array");
-        if (input.packs.length === 0) fail("packs", "must declare at least one pack");
-    }
+    // A Foundry package need not compile anything. A module may ship assets and
+    // nothing else — alternative art for another package is the case, and it is
+    // an ordinary module that installs, is enabled, and supplies files. So
+    // `packs: []` is a package saying it compiles no documents, not a package
+    // that forgot to say which.
+    //
+    // What that leaves uncovered is a tree of notes with no pack to compile them
+    // into, which would be silently ignored. `packs` cannot see the tree, so the
+    // walk reports it: a declared pack that compiles nothing from a non-empty
+    // tree already fails, and so does a note whose `pack:` names none.
+    if (!documentation && !Array.isArray(input.packs)) fail("packs", "must be an array");
     const declaredPacks = Array.isArray(input.packs) ? input.packs : [];
     const packs = declaredPacks.map((pack, index) => normalizePack(pack, `packs[${index}]`));
 

package/docs/api.md

@@ -567,13 +567,14 @@ The asset types — `icon`, `image` and `audio` — and the three roots they are
 
 The asset record: one line of the content index per addressable file. The record is emitted by the package holding the bytes, so its `path` is that package's path and each consumer joins its own root onto it — Foundry its data directory, the website its CDN prefix, the book its asset base.
 
-| Export                      | Signature                                                       | Returns                       | Use it when                                                                       |
-| --------------------------- | --------------------------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------- |
-| `ASSET_RECORD_FIELDS`       | `const ASSET_RECORD_FIELDS`                                     | `readonly AssetRecordField[]` | reading what an `asset` block carries, and where each field comes from            |
-| `PROVENANCE_KEYS`           | `const PROVENANCE_KEYS`                                         | `ReadonlySet<string>`         | validating a provenance file, whose keys are derived from the record's own fields |
-| `PROVENANCE_FILE`           | `const PROVENANCE_FILE`                                         | `string` — `provenance.yaml`  | naming the file a directory records provenance for its subtree in                 |
-| `PROVENANCE_SIDECAR_SUFFIX` | `const PROVENANCE_SIDECAR_SUFFIX`                               | `string` — `.yaml`            | naming a per-file record, which replaces an inherited one wholesale               |
-| `collectAssetRecords`       | `collectAssetRecords(assetsBase, { contentPackage, problems })` | `Array<Record<string, any>>`  | reading a package's asset roots into index records, without walking its notes     |
+| Export                      | Signature                                                       | Returns                       | Use it when                                                                                                                                             |
+| --------------------------- | --------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ASSET_RECORD_FIELDS`       | `const ASSET_RECORD_FIELDS`                                     | `readonly AssetRecordField[]` | reading what an `asset` block carries, and where each field comes from                                                                                  |
+| `PROVENANCE_KEYS`           | `const PROVENANCE_KEYS`                                         | `ReadonlySet<string>`         | validating a provenance file, whose keys are derived from the record's own fields                                                                       |
+| `REQUIRED_PROVENANCE_KEYS`  | `const REQUIRED_PROVENANCE_KEYS`                                | `ReadonlySet<string>`         | the keys a provenance file must state — a record resolves wholesale, so one omitting them leaves every file it covers with no rights holder or no terms |
+| `PROVENANCE_FILE`           | `const PROVENANCE_FILE`                                         | `string` — `provenance.yaml`  | naming the file a directory records provenance for its subtree in                                                                                       |
+| `PROVENANCE_SIDECAR_SUFFIX` | `const PROVENANCE_SIDECAR_SUFFIX`                               | `string` — `.yaml`            | naming a per-file record, which replaces an inherited one wholesale                                                                                     |
+| `collectAssetRecords`       | `collectAssetRecords(assetsBase, { contentPackage, problems })` | `Array<Record<string, any>>`  | reading a package's asset roots into index records, without walking its notes                                                                           |
 
 ### `engine.packages`
 
@@ -1487,6 +1488,8 @@ console.log(normalizeRepoUrl("git@github.com:HeroicLands/sohl.git"));
 | ------------------------------ | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ARTIFACTS`                    | `const ARTIFACTS`                                                                   | —                                                                                                                       | reading the two Foundry package kinds (`"system"`, `"module"`) as the artifact name their manifest and release archive are called                                                  |
 | `normalizeRepoUrl`             | `normalizeRepoUrl(repository)`                                                      | `string` — normalised `https://` URL, no trailing slash                                                                 | normalising `package.json`'s `repository` field (object or shorthand string, `git+…git` or plain) to the exact URL Foundry fetches release assets from                             |
+| `BUILT_IN_ASSET_TRANSFORMS`    | `const BUILT_IN_ASSET_TRANSFORMS`                                                   | `Readonly<Record<string, string>>`                                                                                      | the asset transforms this package ships, by the name `packageBuild.assetTransform` writes — `svg-theme` themes an icon to the reader's colour scheme                               |
+| `resolveAssetTransform`        | `resolveAssetTransform(declared, rootDir)`                                          | `string` — an absolute path to import                                                                                   | resolving a declared transform: a built-in name reaches the shipped module, anything else is a path against the repository root                                                    |
 | `HOMEPAGE_ORIGIN`              | `HOMEPAGE_ORIGIN`                                                                   | `string` — the origin every package's homepage is served from                                                           | stating the site origin once, so the address a manifest advertises and the address the configuration documents cannot disagree                                                     |
 | `packageHomepage`              | `packageHomepage(contentPackage)`                                                   | `string` — `<origin>/<contentPackage>/`                                                                                 | deriving the homepage a manifest's `url` points at; throws when given no name rather than advertising `<origin>/undefined/`                                                        |
 | `releaseUrls`                  | `releaseUrls({ repoUrl, homeUrl, version, artifact })`                              | `{url: string, bugs: string, manifest: string, download: string}`                                                       | building the manifest's addresses — `url` is the homepage a reader follows before installing, while `bugs`, `manifest` and `download` stay on the repository holding the artefacts |

package/docs/commands.md

@@ -260,6 +260,60 @@ package-build: `packageKind: documentation` ships no Foundry package, so there i
 `content-build site`, `content-build pdf`, `package-build bundle check`,
 [Configuration](configuration.md).
 
+### `package-build site-root`
+
+**NAME**
+
+`package-build site-root` — write the deployment's `_headers` and `_redirects`.
+
+**SYNOPSIS**
+
+```
+package-build site-root [--out <dir>]
+```
+
+**DESCRIPTION**
+
+Hugo renders into `<out>/<contentPackage>/`, because the deployment carries the
+`/<contentPackage>/` prefix physically and the routing layer is a
+path-preserving pass-through. The directory that is _uploaded_ is its parent,
+and Cloudflare Pages reads `_headers` and `_redirects` from there and nowhere
+else — a copy inside the prefix is published as a text file and never applied.
+Hugo owns everything under the prefix; this owns what sits beside it.
+
+Two things are written. Indexing is suppressed on every address a deployment
+answers on but nobody advertises — the project's `pages.dev`, the per-deployment
+`pages.dev`, and the custom domain the routing layer fetches — each of which
+would otherwise compete with the canonical URL in search results. And both
+spellings of the prefix root redirect to the landing, with a lifetime pinned on
+the 301, because Pages sets no `Cache-Control` on a redirect it generates and a
+301 without one is cached indefinitely on the most-linked URL there is.
+
+The rules are scoped to those hostnames, so a site deployed under a domain of
+its own stays indexable.
+
+**OPTIONS**
+
+`--out <dir>` — the directory that is deployed. Defaults to `build/site`.
+
+**EXIT STATUS**
+
+1 when `<out>/<contentPackage>/` holds no rendered site, which means the site
+build has not run and writing root files would publish a deployment with nothing
+under the prefix. Otherwise 0.
+
+**EXAMPLES**
+
+```
+$ package-build site-root
+✅ Wrote build/site/_headers.
+✅ Wrote build/site/_redirects.
+```
+
+**SEE ALSO**
+
+`content-build site`, [Configuration](configuration.md).
+
 `package-build lang <action>` asks three independent questions about this
 repository's localization, each blind to what the others see: `check`,
 `coverage` and `hardcoded`, one section below per action.

package/docs/configuration.md

@@ -580,7 +580,9 @@ packs:
 
 > ``package-build config: `packs` must be an array.``
 
-> ``package-build config: `packs` must declare at least one pack.``
+A package may declare **no** packs. A module that ships assets and compiles
+nothing — alternative art for another package is the case — writes `packs: []`,
+and the manifest carries an empty pack list.
 
 Two packs (including companions, anywhere in the tree) may not share a name
 — two packs both named `x` produce:

package/docs/content-format.md

@@ -1508,6 +1508,17 @@ One address resolves its record in this order:
 3. Otherwise nothing, and the provenance fields are blank. A package that
    records no attribution is a fact to state, not a walk to fail.
 
+**The nearest record is the whole answer.** It is never merged with the one
+above it, so a record states every key it means to claim — which is what lets a
+reader open one file and know what the tree beneath it carries, instead of
+resolving a chain by hand.
+
+That is also why `attribution` and `license` are **required in any record that
+exists**: a key left out is not inherited from above, it is simply absent, so a
+record stating neither leaves every file it covers with no rights holder and no
+terms. Omitting one is a finding. `source`, `ai` and `notes` stay optional,
+because a blank is a truthful answer for each of them.
+
 #### A font is not an asset
 
 `assets/fonts` is not a root, and a font has no address.

package/engine/asset-index.mjs

@@ -88,6 +88,10 @@ export const PROVENANCE_SIDECAR_SUFFIX = ".yaml";
  * @property {string} name - The key inside `asset`.
  * @property {"walk"|"provenance"} from - Where the value comes from: the walk
  *   itself, or the provenance record resolved for the address.
+ * @property {boolean} [required] - Whether a provenance record that exists must
+ *   state this key. Omitting one is a finding rather than a blank, because a
+ *   record resolves wholesale: the nearest one is the whole answer, so a key it
+ *   leaves out is not inherited from above but simply absent.
  * @property {string} describe - One line, for the author-facing reference.
  */
 
@@ -119,6 +123,7 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "attribution",
         from: "provenance",
+        required: true,
         describe: "The person holding the rights, to whom attribution is legally due.",
     }),
     Object.freeze({
@@ -134,6 +139,7 @@ export const ASSET_RECORD_FIELDS = Object.freeze([
     Object.freeze({
         name: "license",
         from: "provenance",
+        required: true,
         describe: "The licence it is used under — an SPDX identifier, or terms.",
     }),
     Object.freeze({
@@ -159,6 +165,22 @@ export const PROVENANCE_KEYS = Object.freeze(
     ),
 );
 
+/**
+ * The keys a provenance file must state.
+ *
+ * Derived from {@link ASSET_RECORD_FIELDS} for the same reason the key set is:
+ * the rule and the record cannot disagree about which keys are required.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const REQUIRED_PROVENANCE_KEYS = Object.freeze(
+    new Set(
+        ASSET_RECORD_FIELDS.filter((field) => field.from === "provenance" && field.required).map(
+            (field) => field.name,
+        ),
+    ),
+);
+
 /**
  * Read one provenance file, reporting every key that is not a provenance key.
  *
@@ -218,6 +240,25 @@ function readProvenanceFile(file, findings) {
         }
         out[key] = value == null ? "" : String(value);
     }
+
+    // A record resolves wholesale — the nearest one is the whole answer, and no
+    // ancestor fills a key it leaves out. So an omitted `attribution` or
+    // `license` is not a value inherited from above; it is a file with no stated
+    // rights holder and no stated terms, which is the one thing a provenance
+    // record exists to prevent. Reported against the file rather than a line,
+    // because the fault is an absence and has no position.
+    for (const key of REQUIRED_PROVENANCE_KEYS) {
+        if (out[key]) continue;
+        findings.push({
+            file,
+            severity: "error",
+            message:
+                `a provenance record states \`${key}\`, and this one does not. ` +
+                "A record replaces rather than extends the one above it, so every " +
+                "file it covers would carry no " +
+                (key === "license" ? "licence" : key),
+        });
+    }
     return out;
 }
 
@@ -239,6 +280,9 @@ function inheritedProvenance(dir, root, cache, findings) {
     const own = path.join(dir, PROVENANCE_FILE);
     let answer;
     if (fs.existsSync(own)) {
+        // The nearest record is the whole answer. It is not merged with the one
+        // above it, so a record states every key it means to claim and a reader
+        // needs only the file in front of them to know what a file carries.
         answer = readProvenanceFile(own, findings);
     } else if (path.resolve(dir) === path.resolve(root)) {
         // The search stops at the type root: `assets/` above it is the

package/engine/content-index.mjs

@@ -567,10 +567,13 @@ export function collectContentIndex(
     // caller's omission, and `walkMarkdownTree` says so.
     const walkOpts = { skipDirectories };
 
-    for (const { frontmatter, body, bodyLine, absPath } of walkMarkdownTree(
-        contentBase,
-        walkOpts,
-    )) {
+    // A package may ship assets and no notes at all, in which case there is no
+    // tree to walk and the index is its asset records. The caller decides
+    // whether an absent tree is a mistake; by the time the walk is reached it
+    // is simply a package with nothing to compile.
+    const notes = fs.existsSync(contentBase) ? walkMarkdownTree(contentBase, walkOpts) : [];
+
+    for (const { frontmatter, body, bodyLine, absPath } of notes) {
         const fm = frontmatter ?? {};
         // The id the note's document is filed under, resolved before
         // the record is built so the index publishes the address *and* the id
@@ -674,6 +677,20 @@ export function serializeContentIndex(records) {
     return `${records.map((r) => JSON.stringify(r)).join("\n")}\n`;
 }
 
+/**
+ * Whether an absent content tree is a mistake.
+ *
+ * A package that declares a pack has notes to compile into it, so a missing
+ * tree is a misconfigured path and the build says so. A package that declares
+ * none ships assets and nothing else, and its index is its asset records.
+ *
+ * @param {object} resolved - The resolved configuration.
+ * @returns {boolean} Whether a tree is required.
+ */
+function needsContentTree(resolved) {
+    return (resolved.packs ?? []).length > 0;
+}
+
 /**
  * The index records for a content tree, without writing anything.
  *
@@ -711,7 +728,9 @@ export function indexRecordsFor({
 } = {}) {
     const resolved = config ?? loadPackConfig();
     const tree = contentBase ?? resolved.paths.content;
-    if (!fs.existsSync(tree)) throw new Error(`no content tree at ${tree}`);
+    if (!fs.existsSync(tree) && needsContentTree(resolved)) {
+        throw new Error(`no content tree at ${tree}`);
+    }
     return collectContentIndex(tree, {
         contentPackage: resolved.contentPackage,
         skipDirectories: skipDirectories ?? resolved.skipDirectories,
@@ -745,7 +764,7 @@ export function emitContentIndex({ contentBase, outDir, config } = {}) {
     const dir = outDir ?? resolved.paths.contentIndex;
     const contentPackage = resolved.contentPackage;
 
-    if (!fs.existsSync(tree)) {
+    if (!fs.existsSync(tree) && needsContentTree(resolved)) {
         throw new Error(`no content tree at ${tree}`);
     }
 

package/engine/site-root.mjs

@@ -0,0 +1,165 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The files that belong to a deployment's **root** rather than to the rendered
+ * site.
+ *
+ * Hugo renders into `<out>/<package>/`, because the deployment carries the
+ * `/<package>/` prefix physically and the routing layer is a path-preserving
+ * pass-through. The directory that is *uploaded* is its parent, and Cloudflare
+ * Pages reads `_headers` and `_redirects` from there and nowhere else — a copy
+ * inside the prefix is published as a text file and never applied. Hugo owns
+ * everything under the prefix; this owns what sits beside it.
+ *
+ * **One implementation, because it is one policy.** What is indexable, where
+ * the prefix root sends a reader, and how long that answer is cached are
+ * decisions about the hosting rather than about any one package. Held in each
+ * consumer they are the same file with one constant changed, which is a file
+ * that drifts — and the drift is invisible, because nobody reads all of the
+ * copies at once.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * The namespace the routing layer derives a package's origin in.
+ *
+ * `/<package>/` on the public host is proxied to
+ * `https://<package>.<suffix>/<package>/`, and {@link noindexHeaders} depends on
+ * that being a dedicated namespace.
+ *
+ * @type {string}
+ */
+export const ORIGIN_SUFFIX = "pkg.heroiclands.org";
+
+/**
+ * Where a package's landing is served, now that it is an addressed page.
+ *
+ * The site build emits the homepage at its own address rather than as the
+ * site root's `_index.md`, so the prefix root is a redirect to it.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The landing's path.
+ */
+export function landingPath(pkg) {
+    return `/${pkg}/homepage-root/`;
+}
+
+/**
+ * Suppress indexing of every address a deployment answers on but nobody
+ * advertises.
+ *
+ * Cloudflare Pages assigns three: the project's own `pages.dev`, a per-
+ * deployment `pages.dev`, and the custom domain the project carries so the
+ * routing layer has an origin to fetch. None is advertised, all answer with the
+ * same pages, and left alone they are indexed and compete with the canonical
+ * URL in search results.
+ *
+ * The third matters most: it is the address the routing layer fetches, so it is
+ * the host-assigned address a reader is most plausibly handed. The rules are
+ * **scoped to those hostnames**, which keeps this correct for anyone deploying
+ * the site under a domain of their own — there it is indexable, and only the
+ * host-assigned addresses are not.
+ *
+ * @returns {string[]} The header block's lines.
+ */
+export function noindexHeaders() {
+    return [
+        "https://:project.pages.dev/*",
+        "  X-Robots-Tag: noindex",
+        "",
+        "https://:version.:project.pages.dev/*",
+        "  X-Robots-Tag: noindex",
+        "",
+        `https://:package.${ORIGIN_SUFFIX}/*`,
+        "  X-Robots-Tag: noindex",
+        "",
+    ];
+}
+
+/**
+ * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ *
+ * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
+ * responses carry `location` and nothing else — and a 301 with no lifetime is
+ * cached by a browser indefinitely, on the most-linked URL there is. An hour
+ * keeps the 301's canonical signal without the permanence.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string[]} The header block's lines.
+ */
+export function cacheHeaders(pkg) {
+    return [
+        `/${pkg}/`,
+        "  Cache-Control: max-age=3600",
+        "",
+        `/${pkg}`,
+        "  Cache-Control: max-age=3600",
+        "",
+    ];
+}
+
+/**
+ * Both forms of the prefix root, because Pages matches the raw path.
+ *
+ * Redirect matching runs before any trailing-slash or `index.html` handling, so
+ * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
+ * other.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The `_redirects` file's contents.
+ */
+export function redirects(pkg) {
+    const to = landingPath(pkg);
+    return [`/${pkg}/   ${to}   301`, `/${pkg}    ${to}   301`, ""].join("\n");
+}
+
+/**
+ * The `_headers` file's contents.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The file's contents.
+ */
+export function headers(pkg) {
+    return [...noindexHeaders(), ...cacheHeaders(pkg)].join("\n");
+}
+
+/**
+ * Write `_headers` and `_redirects` beside the rendered site.
+ *
+ * @param {object} options - Options.
+ * @param {string} options.pkg - The content package name, which is also the
+ *   directory Hugo rendered into.
+ * @param {string} options.out - The directory that is deployed.
+ * @returns {{files: string[]}} The files written.
+ * @throws {Error} When no rendered site is there, which means the site build
+ *   has not run and writing root files would publish a deployment with nothing
+ *   under the prefix.
+ */
+export function writeSiteRoot({ pkg, out }) {
+    const root = path.resolve(out);
+    const rendered = path.join(root, pkg);
+    if (!fs.existsSync(path.join(rendered, "index.html"))) {
+        throw new Error(
+            `${out}/${pkg}/ holds no rendered site — build the site before its root files`,
+        );
+    }
+
+    const written = [];
+    for (const [name, body] of [
+        ["_headers", headers(pkg)],
+        ["_redirects", redirects(pkg)],
+    ]) {
+        const file = path.join(root, name);
+        fs.writeFileSync(file, body);
+        written.push(file);
+    }
+    return { files: written };
+}

package/engine/svg-theme.mjs

@@ -0,0 +1,140 @@
+/*
+ * 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
+ */
+
+/**
+ * A staged SVG follows the reader's colour scheme.
+ *
+ * An icon drawn as black line art disappears against a dark background, and
+ * Foundry themes its own chrome. So a shape that is explicitly black, or black
+ * by default because it declares no `fill`, gets a rule that paints it the
+ * ink colour for the scheme in use.
+ *
+ * **Named rather than pathed.** `packageBuild.assetTransform: svg-theme`
+ * reaches this module. Every package that themes its icons themes them the same
+ * way — the ink colours are the system's text tokens — so the transform is one
+ * implementation here rather than a copy in each consumer, where the copies
+ * drift and nobody sees all of them at once.
+ *
+ * @module
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * Iron-gall ink, and cream against a dark ground.
+ *
+ * These mirror `--sohl-color-text-primary` in the system's
+ * `scss/abstracts/_tokens.scss`. Stated once here, so a token change is one
+ * edit rather than one per consuming repository.
+ *
+ * @type {string}
+ */
+const INK_LIGHT = "#211d16";
+
+/** @type {string} */
+const INK_DARK = "#ece3cf";
+
+/**
+ * The shapes a theme rule may repaint.
+ *
+ * Explicitly black, or black by default for want of a `fill`. A shape painted
+ * some other colour is deliberate — a white highlight in a two-tone badge — and
+ * repainting it would destroy the drawing.
+ *
+ * @type {string}
+ */
+const SELECTOR = [
+    '[fill="#000"]',
+    '[fill="#000000"]',
+    '[fill="black"]',
+    "path:not([fill])",
+    "rect:not([fill])",
+    "circle:not([fill])",
+    "ellipse:not([fill])",
+    "polygon:not([fill])",
+    "polyline:not([fill])",
+    "line:not([fill])",
+    "g:not([fill])",
+].join(",");
+
+/** @type {string} */
+const STYLE =
+    `<style>${SELECTOR}{fill:${INK_LIGHT}}` +
+    `@media(prefers-color-scheme:dark){${SELECTOR}{fill:${INK_DARK}}}</style>`;
+
+/**
+ * Every `style="…"` attribute, capturing its declarations.
+ *
+ * @type {RegExp}
+ */
+const STYLE_ATTR = /style\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
+
+/**
+ * A `fill` *declaration* — the property itself, at the start or after a `;`.
+ *
+ * Deliberately not `\bfill\b`, which also matches `fill-rule`, `fill-opacity`
+ * and `paint-order: fill`, none of which set a colour.
+ *
+ * @type {RegExp}
+ */
+const FILL_DECL = /(?:^|;)\s*fill\s*:/i;
+
+/**
+ * Whether any shape sets its fill inline.
+ *
+ * @param {string} svg - The SVG source.
+ * @returns {boolean} Whether an inline `fill` declaration is present.
+ */
+function hasInlineFill(svg) {
+    for (const [, dq, sq] of svg.matchAll(STYLE_ATTR)) {
+        if (FILL_DECL.test(dq ?? sq ?? "")) return true;
+    }
+    return false;
+}
+
+/**
+ * The SVG with a scheme-aware fill rule, or unchanged where one cannot apply.
+ *
+ * Three files are returned as they are. One already carrying a
+ * `prefers-color-scheme` rule is themed — by this pass on an earlier run, or by
+ * its author — and re-theming it would stack rules. One with an inline `fill`
+ * cannot be themed at all, because an inline declaration beats a `<style>` rule
+ * and the result would be a half-recoloured icon, which is worse than an
+ * unthemed one. One with no `<svg>` element is not an SVG.
+ *
+ * @param {string} svg - The SVG source.
+ * @returns {string} The themed source, or the input unchanged.
+ */
+export function injectAdaptiveFill(svg) {
+    if (typeof svg !== "string") return svg;
+    if (svg.includes("prefers-color-scheme")) return svg;
+    if (hasInlineFill(svg)) return svg;
+
+    const open = svg.match(/<svg\b[^>]*>/i);
+    if (!open) return svg;
+
+    const at = open.index + open[0].length;
+    return svg.slice(0, at) + STYLE + svg.slice(at);
+}
+
+/**
+ * The staging hook: theme an SVG, and pass everything else through untouched.
+ *
+ * @param {string} sourcePath - The file being staged.
+ * @returns {string|null} The themed source, or `null` to stage the file as it
+ *   is — which is what every non-SVG asset gets.
+ */
+export function transform(sourcePath) {
+    if (!sourcePath.endsWith(".svg")) return null;
+    return injectAdaptiveFill(readFileSync(sourcePath, "utf8"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.0.1",
+    "version": "22.0.3",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/config.d.mts

@@ -1,3 +1,53 @@
+/**
+ * Where a declared `assetTransform` is loaded from.
+ *
+ * A built-in name resolves to the module this package ships. Anything else is a
+ * path, resolved against the repository root the way it always was — so a
+ * consumer with a transform of its own is unaffected.
+ *
+ * @param {string} declared - The authored value.
+ * @param {string} rootDir - The repository root.
+ * @returns {string} An absolute path to import.
+ */
+export function resolveAssetTransform(declared: string, rootDir: string): string;
+/**
+ * Resolve a package-build configuration from an already-loaded shared one.
+ *
+ * Separate from {@link loadPackageBuildConfig} because this half is pure: it
+ * reads no file and touches no environment, so the validation rules can be
+ * described directly by a test instead of through a fixture repository on
+ * disk. {@link loadPackageBuildConfig} is the same function with the loading
+ * put back.
+ *
+ * @param {object} shared - The resolved content configuration.
+ * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
+ * @throws {TypeError} When the reserved section declares something malformed.
+ */
+export function resolvePackageBuildConfig(shared: object): Readonly<PackageBuildConfig>;
+/**
+ * The repository's resolved package-build configuration.
+ *
+ * Read on call rather than at import, exactly as content-build resolves its
+ * own: importing a module of this package must not require a configuration to
+ * exist anywhere above it.
+ *
+ * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
+ * @throws {TypeError} When there is no configuration, or the reserved section
+ *   declares something malformed.
+ */
+export function loadPackageBuildConfig(): Readonly<PackageBuildConfig>;
+/**
+ * Manifest keys a repository may **not** declare, because the build derives
+ * them and would only overwrite what was written.
+ *
+ * Silently overwriting is the failure this list exists to prevent: a
+ * `version` typed into the configuration would look authoritative, sit there
+ * unread, and disagree with the shipped package forever. Declaring one is an
+ * error naming the key and where the value actually comes from.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
 /**
  * The resolved `packageBuild` section, every optional half filled in.
  *
@@ -65,43 +115,16 @@
  *   collections, as collection → source directory.
  */
 /**
- * Resolve a package-build configuration from an already-loaded shared one.
+ * The asset transforms this package ships, by the name a consumer writes.
  *
- * Separate from {@link loadPackageBuildConfig} because this half is pure: it
- * reads no file and touches no environment, so the validation rules can be
- * described directly by a test instead of through a fixture repository on
- * disk. {@link loadPackageBuildConfig} is the same function with the loading
- * put back.
- *
- * @param {object} shared - The resolved content configuration.
- * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
- * @throws {TypeError} When the reserved section declares something malformed.
- */
-export function resolvePackageBuildConfig(shared: object): Readonly<PackageBuildConfig>;
-/**
- * The repository's resolved package-build configuration.
- *
- * Read on call rather than at import, exactly as content-build resolves its
- * own: importing a module of this package must not require a configuration to
- * exist anywhere above it.
- *
- * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
- * @throws {TypeError} When there is no configuration, or the reserved section
- *   declares something malformed.
- */
-export function loadPackageBuildConfig(): Readonly<PackageBuildConfig>;
-/**
- * Manifest keys a repository may **not** declare, because the build derives
- * them and would only overwrite what was written.
- *
- * Silently overwriting is the failure this list exists to prevent: a
- * `version` typed into the configuration would look authoritative, sit there
- * unread, and disagree with the shipped package forever. Declaring one is an
- * error naming the key and where the value actually comes from.
+ * `packageBuild.assetTransform` takes either one of these names or a path to a
+ * module of the consumer's own. A name is the answer where every package wants
+ * the same behaviour — theming an icon to the reader's colour scheme is not a
+ * per-package decision, and a copy in each consumer is a copy that drifts.
  *
  * @type {Readonly<Record<string, string>>}
  */
-export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
+export const BUILT_IN_ASSET_TRANSFORMS: Readonly<Record<string, string>>;
 /**
  * One staging copy: a source path in the repository, and where it lands under
  * the staged package root.

package/types/engine/asset-index.d.mts

@@ -43,6 +43,10 @@ export const PROVENANCE_SIDECAR_SUFFIX: string;
  * @property {string} name - The key inside `asset`.
  * @property {"walk"|"provenance"} from - Where the value comes from: the walk
  *   itself, or the provenance record resolved for the address.
+ * @property {boolean} [required] - Whether a provenance record that exists must
+ *   state this key. Omitting one is a finding rather than a blank, because a
+ *   record resolves wholesale: the nearest one is the whole answer, so a key it
+ *   leaves out is not inherited from above but simply absent.
  * @property {string} describe - One line, for the author-facing reference.
  */
 /**
@@ -72,6 +76,15 @@ export const ASSET_RECORD_FIELDS: readonly AssetRecordField[];
  * @type {ReadonlySet<string>}
  */
 export const PROVENANCE_KEYS: ReadonlySet<string>;
+/**
+ * The keys a provenance file must state.
+ *
+ * Derived from {@link ASSET_RECORD_FIELDS} for the same reason the key set is:
+ * the rule and the record cannot disagree about which keys are required.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const REQUIRED_PROVENANCE_KEYS: ReadonlySet<string>;
 /**
  * One field of the `asset` block.
  */
@@ -85,6 +98,13 @@ export type AssetRecordField = {
      * itself, or the provenance record resolved for the address.
      */
     from: "walk" | "provenance";
+    /**
+     * - Whether a provenance record that exists must
+     * state this key. Omitting one is a finding rather than a blank, because a
+     * record resolves wholesale: the nearest one is the whole answer, so a key it
+     * leaves out is not inherited from above but simply absent.
+     */
+    required?: boolean | undefined;
     /**
      * - One line, for the author-facing reference.
      */

package/types/engine/site-root.d.mts

@@ -0,0 +1,87 @@
+/**
+ * Where a package's landing is served, now that it is an addressed page.
+ *
+ * The site build emits the homepage at its own address rather than as the
+ * site root's `_index.md`, so the prefix root is a redirect to it.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The landing's path.
+ */
+export function landingPath(pkg: string): string;
+/**
+ * Suppress indexing of every address a deployment answers on but nobody
+ * advertises.
+ *
+ * Cloudflare Pages assigns three: the project's own `pages.dev`, a per-
+ * deployment `pages.dev`, and the custom domain the project carries so the
+ * routing layer has an origin to fetch. None is advertised, all answer with the
+ * same pages, and left alone they are indexed and compete with the canonical
+ * URL in search results.
+ *
+ * The third matters most: it is the address the routing layer fetches, so it is
+ * the host-assigned address a reader is most plausibly handed. The rules are
+ * **scoped to those hostnames**, which keeps this correct for anyone deploying
+ * the site under a domain of their own — there it is indexable, and only the
+ * host-assigned addresses are not.
+ *
+ * @returns {string[]} The header block's lines.
+ */
+export function noindexHeaders(): string[];
+/**
+ * The lifetime pinned on the prefix-root redirect, and why it is pinned.
+ *
+ * Cloudflare Pages sets no `Cache-Control` on a redirect it generates — those
+ * responses carry `location` and nothing else — and a 301 with no lifetime is
+ * cached by a browser indefinitely, on the most-linked URL there is. An hour
+ * keeps the 301's canonical signal without the permanence.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string[]} The header block's lines.
+ */
+export function cacheHeaders(pkg: string): string[];
+/**
+ * Both forms of the prefix root, because Pages matches the raw path.
+ *
+ * Redirect matching runs before any trailing-slash or `index.html` handling, so
+ * `/<pkg>` and `/<pkg>/` are distinct keys and a rule on one does not catch the
+ * other.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The `_redirects` file's contents.
+ */
+export function redirects(pkg: string): string;
+/**
+ * The `_headers` file's contents.
+ *
+ * @param {string} pkg - The content package name.
+ * @returns {string} The file's contents.
+ */
+export function headers(pkg: string): string;
+/**
+ * Write `_headers` and `_redirects` beside the rendered site.
+ *
+ * @param {object} options - Options.
+ * @param {string} options.pkg - The content package name, which is also the
+ *   directory Hugo rendered into.
+ * @param {string} options.out - The directory that is deployed.
+ * @returns {{files: string[]}} The files written.
+ * @throws {Error} When no rendered site is there, which means the site build
+ *   has not run and writing root files would publish a deployment with nothing
+ *   under the prefix.
+ */
+export function writeSiteRoot({ pkg, out }: {
+    pkg: string;
+    out: string;
+}): {
+    files: string[];
+};
+/**
+ * The namespace the routing layer derives a package's origin in.
+ *
+ * `/<package>/` on the public host is proxied to
+ * `https://<package>.<suffix>/<package>/`, and {@link noindexHeaders} depends on
+ * that being a dedicated namespace.
+ *
+ * @type {string}
+ */
+export const ORIGIN_SUFFIX: string;

package/types/engine/svg-theme.d.mts

@@ -0,0 +1,22 @@
+/**
+ * The SVG with a scheme-aware fill rule, or unchanged where one cannot apply.
+ *
+ * Three files are returned as they are. One already carrying a
+ * `prefers-color-scheme` rule is themed — by this pass on an earlier run, or by
+ * its author — and re-theming it would stack rules. One with an inline `fill`
+ * cannot be themed at all, because an inline declaration beats a `<style>` rule
+ * and the result would be a half-recoloured icon, which is worse than an
+ * unthemed one. One with no `<svg>` element is not an SVG.
+ *
+ * @param {string} svg - The SVG source.
+ * @returns {string} The themed source, or the input unchanged.
+ */
+export function injectAdaptiveFill(svg: string): string;
+/**
+ * The staging hook: theme an SVG, and pass everything else through untouched.
+ *
+ * @param {string} sourcePath - The file being staged.
+ * @returns {string|null} The themed source, or `null` to stage the file as it
+ *   is — which is what every non-SVG asset gets.
+ */
+export function transform(sourcePath: string): string | null;