@heroiclands/package-build 23.1.1 → 23.2.1

package/ci/check-banners.mjs

@@ -1,11 +1,11 @@
 /*
- * This file is part of the Heroic Lands shared Hugo theme.
+ * 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 file in the project root or visit:
+ * 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
@@ -25,6 +25,10 @@
  * So this fetches every declared name and fails on any non-200. It is the test
  * the template cannot make, moved to the one place that can make it.
  *
+ * It also refuses a name in `data/banner-kinds.yaml` that `banners.yaml` does
+ * not declare, before any request is made: a mapping to undrawn art is a dead
+ * URL on every page of that kind.
+ *
  * Usage:
  *   node utils/check-banners.mjs [--base <url>] [--concurrency <n>]
  *
@@ -43,6 +47,7 @@ import { parse } from "yaml";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const DATA_FILE = resolve(HERE, "..", "hugo-theme", "data", "banners.yaml");
+const KINDS_FILE = resolve(HERE, "..", "hugo-theme", "data", "banner-kinds.yaml");
 const DEFAULT_BASE = "https://cdn.heroiclands.org";
 
 function parseArgs(argv) {
@@ -71,13 +76,13 @@ function parseArgs(argv) {
 }
 
 /** Diagnostics carry the fields they can know and drop the ones they cannot. */
-function diag(line, message) {
-    const where = line ? `${DATA_FILE}:${line}` : DATA_FILE;
+function diag(line, message, file = DATA_FILE) {
+    const where = line ? `${file}:${line}` : file;
     console.error(`${where}: error: ${message}`);
 }
 
-function fail(message, line) {
-    diag(line, message);
+function fail(message, line, file) {
+    diag(line, message, file);
     process.exit(1);
 }
 
@@ -123,6 +128,36 @@ function readInventory() {
     return { source, dir, available };
 }
 
+/** Every banner name `banner-kinds.yaml` maps a page kind to, with the kind that maps it. */
+function mappedNames() {
+    const source = readFileSync(KINDS_FILE, "utf8");
+    const kinds = parse(source)?.kinds;
+    if (!kinds || typeof kinds !== "object") fail("`kinds` must be a map", 0, KINDS_FILE);
+    const mapped = [];
+    for (const [type, value] of Object.entries(kinds)) {
+        if (typeof value === "string") mapped.push({ kind: type, name: value });
+        else
+            for (const [subType, name] of Object.entries(value ?? {}))
+                mapped.push({ kind: `${type}/${subType}`, name });
+    }
+    return { source, mapped };
+}
+
+/** Fail on a mapped name the inventory does not declare. */
+function checkMapping(available) {
+    const { source, mapped } = mappedNames();
+    const undeclared = mapped.filter(({ name }) => !available.includes(name));
+    for (const { kind, name } of undeclared) {
+        const line = source.split("\n").findIndex((l) => l.trim().endsWith(`: ${name}`));
+        diag(
+            line === -1 ? 0 : line + 1,
+            `${kind} maps to banner ${name}, which banners.yaml does not declare`,
+            KINDS_FILE,
+        );
+    }
+    if (undeclared.length) process.exit(1);
+}
+
 async function probe(url) {
     try {
         // HEAD first — it is what the question actually is. Some object stores
@@ -147,6 +182,7 @@ async function probe(url) {
 async function main() {
     const { base, concurrency } = parseArgs(process.argv.slice(2));
     const { source, dir, available } = readInventory();
+    checkMapping(available);
     const root = `${base.replace(/\/$/, "")}/${dir.replace(/^\//, "")}`;
 
     const failures = [];

package/ci/confirm-npm-version.mjs

@@ -0,0 +1,135 @@
+/*
+ * 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
+ */
+
+/**
+ * Asserts that npm serves an exact package version.
+ *
+ * `npm publish` returns before the registry serves the new version, and a
+ * version that is accepted but never served is indistinguishable from success
+ * by the publish alone. This polls `npm view <name>@<version> version` until
+ * it prints the version, then exits 0. When the time budget runs out it exits 1
+ * with an `::error::` annotation naming the package, the version and the last
+ * registry answer.
+ *
+ * Usage: `node ci/confirm-npm-version.mjs <name> <version> [--interval <s>]
+ * [--timeout <s>]`. The defaults are 15 seconds between queries and 600 seconds
+ * overall.
+ */
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/** Seconds between registry queries. */
+export const DEFAULT_INTERVAL_SECONDS = 15;
+/** Seconds the registry has to serve the version. */
+export const DEFAULT_TIMEOUT_SECONDS = 600;
+
+/**
+ * Ask the registry which version `name@version` resolves to.
+ *
+ * @param {string} spec - `<name>@<version>`.
+ * @returns {string} The version npm printed, or its error text when the query
+ *   fails (an unpublished version answers E404).
+ */
+export function queryNpm(spec) {
+    const result = spawnSync("npm", ["view", spec, "version"], { encoding: "utf8" });
+    if (result.error) return result.error.message;
+    const out = (result.stdout ?? "").trim();
+    if (result.status === 0) return out;
+    const err = (result.stderr ?? "").trim().replace(/\s*\n\s*/g, " | ");
+    return err || out || `npm exited ${result.status}`;
+}
+
+/**
+ * Poll until the registry serves `version` of `name`.
+ *
+ * @param {object} options
+ * @param {string} options.name - Package name.
+ * @param {string} options.version - Exact version expected.
+ * @param {(spec: string) => string} [options.query] - Registry query; returns
+ *   the registry's answer for `<name>@<version>`.
+ * @param {(ms: number) => Promise<void>} [options.sleep] - Waits between queries.
+ * @param {number} [options.intervalSeconds] - Seconds between queries.
+ * @param {number} [options.timeoutSeconds] - Seconds before giving up.
+ * @param {(line: string) => void} [options.log] - Progress output.
+ * @returns {Promise<{ok: true, attempts: number} | {ok: false, attempts: number, last: string}>}
+ */
+export async function confirmNpmVersion({
+    name,
+    version,
+    query = queryNpm,
+    sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    intervalSeconds = DEFAULT_INTERVAL_SECONDS,
+    timeoutSeconds = DEFAULT_TIMEOUT_SECONDS,
+    log = () => {},
+}) {
+    const spec = `${name}@${version}`;
+    const attemptLimit = Math.floor(timeoutSeconds / intervalSeconds) + 1;
+    let last = "";
+    for (let attempts = 1; attempts <= attemptLimit; attempts++) {
+        last = query(spec);
+        if (last === version) {
+            log(`${spec} is served by npm.`);
+            return { ok: true, attempts };
+        }
+        log(`${spec} is not served yet (${last || "empty answer"}).`);
+        if (attempts < attemptLimit) await sleep(intervalSeconds * 1000);
+    }
+    return { ok: false, attempts: attemptLimit, last };
+}
+
+function parseArguments(argv) {
+    const positional = [];
+    const options = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--interval" || arg === "--timeout") {
+            const value = Number(argv[++i]);
+            if (!Number.isFinite(value) || value <= 0) {
+                throw new Error(`${arg} takes a positive number of seconds.`);
+            }
+            options[arg === "--interval" ? "intervalSeconds" : "timeoutSeconds"] = value;
+        } else if (arg.startsWith("--")) {
+            throw new Error(`Unknown option ${arg}.`);
+        } else {
+            positional.push(arg);
+        }
+    }
+    if (positional.length !== 2) {
+        throw new Error(
+            "Usage: confirm-npm-version.mjs <name> <version> [--interval <s>] [--timeout <s>]",
+        );
+    }
+    return { name: positional[0], version: positional[1], ...options };
+}
+
+async function main(argv) {
+    let options;
+    try {
+        options = parseArguments(argv);
+    } catch (error) {
+        console.error(`::error::${error.message}`);
+        return 2;
+    }
+    const outcome = await confirmNpmVersion({ ...options, log: (line) => console.log(line) });
+    if (outcome.ok) return 0;
+    const timeout = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+    console.error(
+        `::error::npm does not serve ${options.name}@${options.version} after ${timeout}s and ${outcome.attempts} queries. Last registry answer: ${outcome.last || "(empty)"}`,
+    );
+    return 1;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    process.exitCode = await main(process.argv.slice(2));
+}

package/ci/content-format-reference.mjs

@@ -1,4 +1,13 @@
 /*
+ * 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
  */
 
@@ -12,6 +21,7 @@ import {
     NOTE_TOP_LEVEL_FIELDS,
     NOTE_VOCABULARY,
     SHARED_DATA_FIELDS,
+    dataFields,
 } from "../engine/note-vocabulary.mjs";
 import { EXPRESSION_HELPERS } from "../engine/markdown-expressions.mjs";
 import { PAGE_LIST_ATTRIBUTES } from "../engine/page-lists.mjs";
@@ -98,7 +108,7 @@ const rows = [
     "",
     "## Shared `data` fields",
     "",
-    "These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.",
+    "These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can. `data.icon` is not shared: it is listed under each type whose document carries art.",
     "",
     "| Field | Shape | Meaning |",
     "| --- | --- | --- |",
@@ -127,13 +137,12 @@ for (const [type, spec] of contract.types) {
         );
     }
     rows.push("| Field | Shape | Meaning |", "| --- | --- | --- |");
+    const typeData = dataFields(type).filter((field) => !SHARED_DATA_FIELDS.includes(field));
     rows.push(
-        ...(declared.data?.length ?
-            fields(declared.data)
-        :   ["| — | — | No type-specific `data` fields. |"]),
+        ...(typeData.length ? fields(typeData) : ["| — | — | No type-specific `data` fields. |"]),
     );
     rows.push("");
-    rows.push(...innerKeyTable(declared.data ?? []));
+    rows.push(...innerKeyTable(typeData));
     const claims = contract.claims.filter((claim) => !claim.shared && claim.noteType === type);
     if (claims.length) {
         rows.push("**System mappings**", "", "| Source | System | Target |", "| --- | --- | --- |");

package/config.mjs

@@ -94,6 +94,7 @@ const SECTION_KEYS = [
 export const DERIVED_MANIFEST_KEYS = Object.freeze({
     id: "`foundryPackage`, itself derived from package.json `name`",
     version: "package.json `version`",
+    authors: "the `authors` list at the top level of package-build.config.yaml",
     description: "`packageBuild.manifest.descriptionHtml`",
     url: "package.json `repository`",
     bugs: "package.json `repository`",

package/container.mjs

@@ -217,10 +217,12 @@ export function resolveFoundryVersion(
 /**
  * The image a run uses.
  *
- * `FOUNDRYVTT_CONTAINER_IMAGE` wins, then `packageBuild.container.image`, then
- * felddy's major tag for whichever version the package already implies — the
- * pinned build, or failing that the compatibility floor. Only a package that
- * claims neither floats.
+ * `FOUNDRYVTT_CONTAINER_IMAGE` wins, then `packageBuild.container.image`. A
+ * pinned exact build takes felddy's tag for that build: each image installs its
+ * own build by default and warns that a different `FOUNDRY_VERSION` "may not
+ * function properly". Otherwise felddy's major tag for whichever version the
+ * package implies — the pin, or failing that the compatibility floor. Only a
+ * package that claims neither floats.
  *
  * @param {object} [opts]
  * @param {NodeJS.ProcessEnv} [opts.env] - Environment to read.
@@ -238,6 +240,7 @@ export function resolveImage({
     const explicit = env.FOUNDRYVTT_CONTAINER_IMAGE?.trim();
     if (explicit) return explicit;
     if (image) return image;
+    if (EXACT_BUILD.test(version ?? "")) return `felddy/foundryvtt:${version}`;
     const major = (version ?? compatibilityMinimum ?? "").split(".")[0];
     return major ? `felddy/foundryvtt:${major}` : FLOATING_IMAGE;
 }
@@ -331,6 +334,52 @@ export function passthroughEnv(env = process.env) {
     return pairs;
 }
 
+/** The account variables the image signs in to foundryvtt.com with. */
+const ACCOUNT_VARIABLES = Object.freeze(["FOUNDRY_USERNAME", "FOUNDRY_PASSWORD"]);
+
+/** The shortest value the image reads as a licence key rather than an index. */
+const LICENSE_KEY_MIN_LENGTH = 24;
+
+/**
+ * Whether the image has to sign in to foundryvtt.com to start.
+ *
+ * Given `FOUNDRY_USERNAME` and `FOUNDRY_PASSWORD`, the image signs in and asks
+ * for a download URL on every container it creates, even when the release is
+ * already in its cache. Each of those is a request foundryvtt.com rate-limits,
+ * and one refused with HTTP 429 stops the container before Foundry starts. The
+ * account serves two purposes only: downloading a release that is not cached,
+ * and fetching a licence key for an unlicensed data root. When neither applies
+ * the account is withheld, and the release installs from the cache with no
+ * network request.
+ *
+ * The image caches `foundryvtt-<version>.zip` in the mounted cache, or in
+ * `container_cache` beneath the data root when no cache is mounted.
+ *
+ * @param {object} opts
+ * @param {string|null} [opts.cacheDir] - The host cache mounted into the container.
+ * @param {string} opts.dataRoot - The host data root mounted at `/data`.
+ * @param {string|null} [opts.version] - The pinned build; with none, the
+ *   archive's name is unknown.
+ * @param {string|null} [opts.licenseKey] - The licence key the image is given.
+ * @param {(file: string) => boolean} [opts.fileExists] - Replaceable for tests.
+ * @returns {boolean} Whether to pass the account through.
+ */
+export function needsFoundryAccount({
+    cacheDir = null,
+    dataRoot,
+    version = null,
+    licenseKey = null,
+    fileExists = (file) => fs.existsSync(file),
+}) {
+    if (!version) return true;
+    const cache = cacheDir ?? path.join(dataRoot, "container_cache");
+    if (!fileExists(path.join(cache, `foundryvtt-${version}.zip`))) return true;
+    const licensed =
+        (licenseKey?.length ?? 0) >= LICENSE_KEY_MIN_LENGTH ||
+        fileExists(path.join(dataRoot, "Config", "license.json"));
+    return !licensed;
+}
+
 /**
  * The full `docker run` argument vector for a stage's container.
  *
@@ -348,6 +397,13 @@ export function passthroughEnv(env = process.env) {
  * @param {string|null} [opts.version] - Exact build to pin.
  * @param {string|null} [opts.world] - World to auto-launch; `""` forces none.
  * @param {string|null} [opts.licenseKey] - Dedicated licence key.
+ * @param {boolean} [opts.account] - Whether to pass `FOUNDRY_USERNAME` and
+ *   `FOUNDRY_PASSWORD` through; see {@link needsFoundryAccount}.
+ * @param {string|null} [opts.user] - `--user` value to run the container as.
+ *   `felddy/foundryvtt` runs Foundry as user 1000 and ignores `FOUNDRY_UID` and
+ *   `FOUNDRY_GID`; under rootless Docker, container root is the host user, so
+ *   `0:0` makes every file under the data root theirs. Blank or `null` leaves
+ *   the image's own user.
  * @returns {string[]} Arguments after `docker`.
  */
 export function dockerRunArgs({
@@ -360,6 +416,8 @@ export function dockerRunArgs({
     version = null,
     world = null,
     licenseKey = null,
+    account = true,
+    user = null,
 }) {
     const args = [
         "run",
@@ -380,11 +438,13 @@ export function dockerRunArgs({
         args.push("--volume", `${cacheDir}:${CACHE_MOUNT}`, "-e", `CONTAINER_CACHE=${CACHE_MOUNT}`);
     }
     for (const [key, value] of passthroughEnv(env)) {
+        if (!account && ACCOUNT_VARIABLES.includes(key)) continue;
         args.push("-e", `${key}=${value}`);
     }
     if (version) args.push("-e", `FOUNDRY_VERSION=${version}`);
     if (world !== null) args.push("-e", `FOUNDRY_WORLD=${world}`);
     if (licenseKey) args.push("-e", `FOUNDRY_LICENSE_KEY=${licenseKey}`);
+    if (user?.trim()) args.push("--user", user.trim());
     args.push(image);
     return args;
 }
@@ -410,6 +470,118 @@ export function runDocker(args) {
     return result.status ?? 0;
 }
 
+/**
+ * The `docker run` argument vector for a short-lived container that runs a
+ * shell script against a stage's data root.
+ *
+ * It uses the stage's own image and mounts the data root at `/data`, so the
+ * script sees files exactly as the Foundry container does. Under rootless
+ * Docker, only the container's user namespace can unlink what the container's
+ * user wrote, and only it can hand files to that user.
+ *
+ * @param {object} opts
+ * @param {string} opts.image - Image reference.
+ * @param {string} opts.dataRoot - Host directory to mount at `/data`.
+ * @param {string} opts.script - A `sh` script; `$1`, `$2` … are `args`.
+ * @param {string[]} [opts.args] - Positional arguments for the script.
+ * @param {string|null} [opts.user] - `--user` value; `null` runs as the image's
+ *   own user.
+ * @returns {string[]} Arguments after `docker`.
+ */
+export function dataRootScriptArgs({ image, dataRoot, script, args = [], user = null }) {
+    const argv = [
+        "run",
+        "--rm",
+        "--volume",
+        `${path.resolve(dataRoot)}:/data`,
+        "--entrypoint",
+        "sh",
+    ];
+    if (user?.trim()) argv.push("--user", user.trim());
+    argv.push(image, "-c", script, "sh", ...args);
+    return argv;
+}
+
+/**
+ * Run a shell script against a stage's data root in a throwaway container.
+ *
+ * @param {object} opts - As for {@link dataRootScriptArgs}.
+ * @returns {string} The script's standard output.
+ * @throws {Error} When `docker` is missing or the script exits non-zero.
+ */
+export function runDataRootScript(opts) {
+    const result = spawnSync("docker", dataRootScriptArgs(opts), { encoding: "utf8" });
+    if (result.error?.code === "ENOENT") {
+        throw new Error(
+            "docker was not found on PATH. Install Docker and make sure the `docker` CLI is available.",
+        );
+    }
+    if (result.status !== 0) {
+        throw new Error(
+            `A helper container failed (exit ${result.status}): ` +
+                `${(result.stderr || result.stdout || "").trim()}`,
+        );
+    }
+    return result.stdout ?? "";
+}
+
+/**
+ * A tree's path beneath the data root, as the helper container sees it there.
+ *
+ * @param {string} dataRoot - Host directory mounted at `/data`.
+ * @param {string} tree - A host path beneath it.
+ * @returns {string} The `/`-separated path relative to the data root.
+ * @throws {Error} When the tree is the data root or lies outside it.
+ */
+function beneathDataRoot(dataRoot, tree) {
+    const relative = path.relative(path.resolve(dataRoot), path.resolve(tree));
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new Error(`${tree} is not beneath the data root ${dataRoot}.`);
+    }
+    return relative.split(path.sep).join("/");
+}
+
+/**
+ * A remover for trees under a stage's data root that the container's user
+ * owns, run as root in a throwaway container on that data root — the same
+ * mechanism that hands an end-to-end install to the container's user.
+ *
+ * @param {object} opts
+ * @param {ResolvedContainer} opts.container - The stage's container.
+ * @param {(opts: object) => string} [opts.runScript] - Throwaway-container runner.
+ * @returns {(tree: string, where: {dataRoot: string}) => void} Removes one tree.
+ */
+export function containerTreeRemover({ container, runScript = runDataRootScript }) {
+    return (tree, { dataRoot }) => {
+        const relative = beneathDataRoot(dataRoot, tree);
+        runScript({
+            image: container.image,
+            dataRoot,
+            user: "0:0",
+            script: 'rm -rf "/data/$1"',
+            args: [relative],
+        });
+    };
+}
+
+/**
+ * The command {@link containerTreeRemover} runs, written out for a person to
+ * paste when the deploy could not run it.
+ *
+ * @param {object} opts
+ * @param {string} opts.image - Image reference.
+ * @param {string} opts.dataRoot - Host directory mounted at `/data`.
+ * @param {string} opts.tree - The tree to remove, beneath the data root.
+ * @returns {string} A `docker run` command line.
+ */
+export function containerRemovalCommand({ image, dataRoot, tree }) {
+    const relative = beneathDataRoot(dataRoot, tree);
+    return (
+        `docker run --rm --user 0:0 --volume ${path.resolve(dataRoot)}:/data ` +
+        `--entrypoint rm ${image} -rf /data/${relative}`
+    );
+}
+
 /**
  * Run the `docker` CLI and capture its output, tolerating failure.
  *
@@ -487,6 +659,7 @@ export function clearStaleLock(dataRoot, log = () => {}) {
  * @property {string|null} world
  * @property {string|null} licenseKey
  * @property {string|null} cacheDir
+ * @property {string|null} user - From `FOUNDRYVTT_CONTAINER_USER`.
  */
 
 /**
@@ -522,6 +695,7 @@ export function resolveContainer({ stage, config, env = process.env }) {
         world: resolveWorld(stage, { env, stages }),
         licenseKey: resolveLicenseKey(stage, env),
         cacheDir: env.FOUNDRYVTT_CACHE?.trim() || null,
+        user: env.FOUNDRYVTT_CONTAINER_USER?.trim() || null,
     };
 }
 
@@ -563,6 +737,13 @@ export function startContainer(container, { dataRoot, env = process.env, log = (
             version: container.version,
             world: container.world,
             licenseKey: container.licenseKey,
+            account: needsFoundryAccount({
+                cacheDir: container.cacheDir,
+                dataRoot,
+                version: container.version,
+                licenseKey: container.licenseKey ?? env.FOUNDRY_LICENSE_KEY?.trim() ?? null,
+            }),
+            user: container.user,
         }),
     );
     if (status === 0) {