@heroiclands/package-build 0.1.0 → 0.2.0

package/README.md

@@ -56,6 +56,104 @@ The whole of assemble → validate → ship, one subpath each:
 - **`text`** — locating a literal inside a file, so a finding names the line and
   column it is about.
 
+## Configure
+
+A repository declares its build in **one** file — `content-build.config.yaml`,
+the same one `content-build` reads — and this package takes its settings from
+the reserved `packageBuild:` section:
+
+```yaml
+# Read from the top level, not restated below.
+packageKind: modules
+foundryPackage: sohl-thalorna
+
+packageBuild:
+  # Where the package is assembled. Every `to:` below is relative to it, so a
+  # table reads `lang`, not `build/stage/lang`.
+  stageDir: build/stage
+
+  assets:
+    - { from: lang, to: lang }
+    - { from: assets/icons, to: assets/icons }
+    - { from: LICENSE.md, to: LICENSE.md }
+
+  # Optional. A module exporting `transform(sourcePath) -> string | null`,
+  # applied to every staged file — `null` copies it verbatim. This is the one
+  # genuine piece of code in staging, and it stays the repository's: SoHL
+  # rewrites each SVG's hard-coded fill so icons follow the Foundry theme.
+  assetTransform: ./utils/svg-theme.mjs
+
+  clean:
+    # Beyond the conventional build artifacts, which the library already knows.
+    extra: [site/content, site/public, site/resources]
+
+  lang:
+    sources: lang/*.json
+    # Printed after a failure — where this repository documents its key rules.
+    help: See kb/dev-docs/reference/localization-keys.md.
+
+  deploy:
+    # Prefix of the shared SFTP override variables. Default `SOHL`.
+    envPrefix: SOHL
+```
+
+**Why one file and not two.** Two of the values this package needs —
+`packageKind` and `foundryPackage` — are already declared for `content-build`. A
+second config file would restate them, which is two places for one fact; that is
+exactly what every consumer's `push-stage.mjs` did, hard-coding
+`packageKind: "systems"` and `packageId: "sohl"` beside a configuration that
+already said both.
+
+`content-build` checks only that `packageBuild:` is a mapping and hands it back
+frozen. Everything inside it is validated here, so neither package learns the
+other's schema — they split by input, and the dependency runs one way.
+
+**What is derived, not stated:**
+
+| Field                      | Derived from                                                         |
+| -------------------------- | -------------------------------------------------------------------- |
+| the repository root        | the configuration file's own location                                |
+| `packageKind`, `packageId` | the shared configuration's top level                                 |
+| the release artifact       | `packageKind` — a system ships `system.json`, a module `module.json` |
+
+## Command line
+
+```
+npx package-build clean [--distclean]
+npx package-build assets
+npx package-build lang check
+npx package-build release
+npx package-build deploy <stage>
+```
+
+Wrapped as npm scripts — SoHL spells them:
+
+```json
+{
+  "clean": "package-build clean",
+  "distclean": "package-build clean --distclean",
+  "build:assets": "package-build assets",
+  "lint:lang": "package-build lang check",
+  "build:pack-release": "package-build release",
+  "push:qa": "package-build deploy qa"
+}
+```
+
+**Why the CLI exists.** This package was library-only, so every consuming
+repository wrote a wrapper script per job — six of them in the SoHL repository,
+441 lines that between them contained no logic. `clean.mjs` was 47 lines that
+computed a `repoRoot` from `import.meta.url`, read one flag, and made one call.
+Every copy had drifted from its sibling in the other repositories, because
+copies do: `clean.mjs` was 47 lines in one and 48 in another, `copy-assets.mjs`
+71 and 76.
+
+It is the same shape the configuration had before it became data — not logic,
+but the boilerplate a code file needs in order to state a literal. The literals
+moved into configuration; the boilerplate lives in the CLI, once.
+
+`--version` and `--help` answer in a directory with no configuration at all.
+Running an actual command resolves it, and fails loudly when it is missing.
+
 ## Design
 
 **The rules are pure, and I/O is confined to functions named for it.** A rule

package/bin/package-build.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/*
+ * 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
+ */
+
+/**
+ * The `package-build` command line — clean, stage, check, package, deploy.
+ *
+ * **Why this exists.** This package was library-only, so every consuming
+ * repository wrote a wrapper script per job: six of them in the Song of Heroic
+ * Lands repository, 441 lines that between them contained no logic. `clean.mjs`
+ * was 47 lines that computed a `repoRoot` from `import.meta.url`, read one
+ * flag, and made one call. `push-stage.mjs` hard-coded `packageKind: "systems"`
+ * and `packageId: "sohl"` beside a configuration that already declared both.
+ * Each copy had drifted from its sibling in the other repositories, because
+ * copies do.
+ *
+ * It is the same shape the configuration had before it became data: not logic,
+ * but the boilerplate a code file needs in order to state a literal. So the
+ * literals move into `content-build.config.yaml`'s reserved `packageBuild:`
+ * section, and the boilerplate lives here, once.
+ *
+ * **Every side effect lives in this file.** argv parsing, the environment,
+ * writing to the filesystem, and the process exit code. The library modules
+ * stay import-safe, so a consuming repository's build — or a test — can call
+ * them without any of it happening.
+ *
+ * The side effects that need *configuration* live inside the command handlers,
+ * never at module scope, so `--version` and `--help` answer in a directory with
+ * no configuration at all. Running an actual command still resolves it, and
+ * still fails loudly when it is missing.
+ *
+ * Usage:
+ *   npx package-build clean [--distclean]
+ *   npx package-build assets
+ *   npx package-build lang check
+ *   npx package-build release
+ *   npx package-build deploy <stage>
+ *
+ * In a consuming repository, wrapped as npm scripts — SoHL spells them:
+ *   npm run clean                          // → … clean
+ *   npm run build:assets                   // → … assets
+ *   npm run lint:lang                      // → … lang check
+ *   npm run build:pack-release             // → … release
+ *   npm run push:qa                        // → … deploy qa
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { globSync } from "glob";
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { loadPackageBuildConfig } from "../config.mjs";
+import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
+import { validateLangSource } from "../lang.mjs";
+import { packRelease } from "../release.mjs";
+import { deployStage } from "../deploy.mjs";
+
+/**
+ * This package's own version, for `--version`.
+ *
+ * Read from this package's manifest rather than left to yargs, which defaults
+ * to the *nearest* `package.json` walking up from the working directory —
+ * inside a consuming repository that is the consumer's, so the CLI would report
+ * the consumer's version instead of the toolchain's.
+ *
+ * @returns {string} The `version` field of this package's manifest.
+ */
+function ownVersion() {
+    return JSON.parse(
+        fs.readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+    ).version;
+}
+
+/**
+ * Report a failure the way a build should: one line, no stack, non-zero exit.
+ *
+ * @param {unknown} err - What went wrong.
+ * @returns {never}
+ */
+function die(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`package-build: ${message}`);
+    process.exit(1);
+}
+
+/**
+ * Wrap a command handler so every failure is reported the same way.
+ *
+ * yargs' own `.fail()` sees a *synchronous* handler's throw but not an async
+ * one's rejection, so without this a `clean` failure printed one clean line and
+ * a `deploy` failure printed a stack trace. A build's diagnostics should not
+ * depend on whether the command it ran happened to await something.
+ *
+ * @param {(args: object) => unknown} run - The handler body.
+ * @returns {(args: object) => Promise<void>} The wrapped handler.
+ */
+function handler(run) {
+    return async (args) => {
+        try {
+            await run(args);
+        } catch (err) {
+            die(err);
+        }
+    };
+}
+
+/**
+ * `clean` — remove this repository's build artifacts.
+ *
+ * The conventional artifact directories are the library's; a repository that
+ * generates more (a site's `content/`, `public/` and `resources/`) names them
+ * in `packageBuild.clean.extra` rather than reimplementing the walk, which is
+ * what every consumer's `clean.mjs` did.
+ *
+ * @returns {object} The yargs command module.
+ */
+function cleanCommand() {
+    return {
+        command: "clean",
+        describe: "Remove build artifacts",
+        builder: (y) =>
+            y.option("distclean", {
+                type: "boolean",
+                default: false,
+                describe: "Also remove node_modules",
+            }),
+        handler: handler((args) => {
+            const config = loadPackageBuildConfig();
+            const removed = cleanBuildArtifacts(config.rootDir, {
+                includeNodeModules: args.distclean,
+                extra: config.cleanExtra,
+            });
+            for (const dir of removed) console.log(`Removed ${dir}`);
+            if (!removed.length) console.log("Nothing to clean.");
+        }),
+    };
+}
+
+/**
+ * `assets` — stage the repository's static files into the package root.
+ *
+ * The table is data (`packageBuild.assets`). A repository that has to *change*
+ * a file on the way — SoHL rewrites each SVG's hard-coded fill so icons follow
+ * the Foundry theme — names a module in `packageBuild.assetTransform`, whose
+ * `transform(sourcePath)` returns replacement text or `null` to copy verbatim.
+ * That is the one genuine piece of code in the job, and it stays the
+ * repository's.
+ *
+ * @returns {object} The yargs command module.
+ */
+function assetsCommand() {
+    return {
+        command: "assets",
+        describe: "Stage static assets into the package root",
+        builder: (y) => y,
+        handler: handler(async () => {
+            const config = loadPackageBuildConfig();
+            if (!config.assets.length) {
+                console.log(
+                    "package-build: no `packageBuild.assets` declared; nothing to stage.",
+                );
+                return;
+            }
+
+            let transform;
+            if (config.assetTransform) {
+                const module = await import(
+                    `file://${config.assetTransform}`
+                ).catch((err) =>
+                    die(
+                        `cannot load \`packageBuild.assetTransform\` ` +
+                            `(${config.assetTransform}): ${err.message}`,
+                    ),
+                );
+                transform = module.transform;
+                if (typeof transform !== "function") {
+                    die(
+                        `\`packageBuild.assetTransform\` ` +
+                            `(${config.assetTransform}) exports no \`transform\` ` +
+                            `function. It must export ` +
+                            `\`transform(sourcePath) -> string | null\`.`,
+                    );
+                }
+            }
+
+            // `to:` is relative to the staged package root, so a
+            // repository's table reads `lang`, not `build/stage/lang`.
+            const entries = config.assets.map(({ from, to }) => [
+                from,
+                path.join(config.stageDir, to),
+            ]);
+            const { entries: count, files } = stageAssets(entries, {
+                cwd: config.rootDir,
+                transform,
+            });
+            console.log(
+                `✅ Static assets staged (${count} entries, ${files} files).`,
+            );
+        }),
+    };
+}
+
+/**
+ * `lang check` — verify every localization file survives `expandObject`.
+ *
+ * A dotted-prefix collision makes `foundry.utils.expandObject` throw, and
+ * Foundry then drops the whole translation file silently. The rule is the
+ * library's; the glob and any repository-specific guidance are data.
+ *
+ * @returns {object} The yargs command module.
+ */
+function langCommand() {
+    return {
+        command: "lang <action>",
+        describe: "Localization checks",
+        builder: (y) =>
+            y.positional("action", {
+                choices: ["check"],
+                describe: "check: verify the files are expandObject-safe",
+            }),
+        handler: handler(() => {
+            const config = loadPackageBuildConfig();
+            const files = globSync(config.langSources, {
+                cwd: config.rootDir,
+                absolute: true,
+            });
+            if (!files.length) {
+                die(
+                    `no localization files matched ` +
+                        `\`${config.langSources}\` under ${config.rootDir}.`,
+                );
+            }
+
+            let total = 0;
+            for (const file of files.sort()) {
+                const relative = path.relative(config.rootDir, file);
+                for (const finding of validateLangSource(
+                    fs.readFileSync(file, "utf8"),
+                )) {
+                    total++;
+                    // The diagnostics contract: the path starts the line, and a
+                    // field is dropped rather than guessed.
+                    const at = [relative, finding.line, finding.column]
+                        .filter((part) => part !== undefined && part !== null)
+                        .join(":");
+                    console.error(
+                        `${at}: ${finding.severity ?? "error"}: ${finding.message}`,
+                    );
+                }
+            }
+
+            if (total) {
+                if (config.langHelp) console.error(`\n${config.langHelp}`);
+                process.exit(1);
+            }
+            console.log(
+                `package-build: ${files.length} localization file(s) are ` +
+                    `expandObject-safe.`,
+            );
+        }),
+    };
+}
+
+/**
+ * `release` — zip the staged package for a GitHub release.
+ *
+ * The artifact name is derived from `packageKind`: Foundry installs a system
+ * from `system.json` and a module from `module.json`, so the kind already
+ * decides it and no repository states it.
+ *
+ * @returns {object} The yargs command module.
+ */
+function releaseCommand() {
+    return {
+        command: "release",
+        describe: "Package the staged build for release",
+        builder: (y) => y,
+        handler: handler(async () => {
+            const config = loadPackageBuildConfig();
+            const { zip, version, bytes } = await packRelease({
+                artifact: config.artifact,
+            });
+            console.log(
+                `✅ Packaged ${version} for release: ` +
+                    `${path.relative(config.rootDir, zip)} ` +
+                    `(${(bytes / 1024 / 1024).toFixed(1)} MB)`,
+            );
+        }),
+    };
+}
+
+/**
+ * `deploy <stage>` — push the staged package to a Foundry data directory.
+ *
+ * `packageKind` and `packageId` come from the shared configuration, where they
+ * were already declared. Every consumer's `push-stage.mjs` hard-coded them a
+ * second time, which is two places for one fact and exactly the drift this
+ * command removes.
+ *
+ * @returns {object} The yargs command module.
+ */
+function deployCommand() {
+    return {
+        command: "deploy <stage>",
+        describe: "Deploy the staged package to a stage",
+        builder: (y) =>
+            y.positional("stage", {
+                type: "string",
+                describe: "Target stage (e.g. dev, qa, prod, test)",
+            }),
+        handler: handler(async (args) => {
+            const config = loadPackageBuildConfig();
+
+            // Loaded here rather than at module scope: `--help` must answer in
+            // a repository that has no environment file at all.
+            const dotenv = await import("dotenv");
+            dotenv.config({
+                path: path.join(config.rootDir, ".env.local"),
+                quiet: true,
+            });
+            dotenv.config({
+                path: path.join(config.rootDir, ".env"),
+                quiet: true,
+            });
+
+            const { stage } = await deployStage({
+                stage: args.stage,
+                source: path.join(config.rootDir, config.stageDir),
+                packageKind: config.packageKind,
+                packageId: config.packageId,
+                prefix: config.envPrefix,
+                log: (message) => console.log(message),
+            });
+            console.log(`Deployed stage '${stage}' successfully.`);
+        }),
+    };
+}
+
+yargs(hideBin(process.argv))
+    .scriptName("package-build")
+    .command(cleanCommand())
+    .command(assetsCommand())
+    .command(langCommand())
+    .command(releaseCommand())
+    .command(deployCommand())
+    .demandCommand(1, "Name a command.")
+    .strict()
+    .version(ownVersion())
+    .help()
+    .alias("help", "h")
+    .fail((message, err) => die(err ?? message)).argv;

package/config.mjs

@@ -0,0 +1,318 @@
+/*
+ * 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
+ */
+
+/**
+ * The per-repository configuration this package reads.
+ *
+ * **One repository, one configuration file.** A repository already declares
+ * itself in `content-build.config.yaml`, and two of the values this package
+ * needs — `packageKind` and `foundryPackage` — are already in it. A second file
+ * would restate them, which is two places for one fact; that is precisely what
+ * every consumer's `push-stage.mjs` did, hard-coding `packageKind: "systems"`
+ * and `packageId: "sohl"` beside a config that already said both.
+ *
+ * So this package reads the *same* file, through content-build's loader, and
+ * takes its own settings from the reserved `packageBuild:` section. The two
+ * packages split by **input** — content-build reads the content tree, this one
+ * reads `lang/`, `styles/`, `src/`, the assets and the manifest template — and
+ * neither validates the other's keys. content-build checks that the section is
+ * a mapping and hands it back frozen; everything inside it is validated here.
+ *
+ * **The dependency runs one way.** This package depends on content-build;
+ * content-build must never depend on this one. It is the same direction the
+ * loader already implies, and keeping it means content-build stays usable by a
+ * repository that ships content and no Foundry package at all.
+ *
+ * ```yaml
+ * # content-build.config.yaml
+ * packageKind: systems       # read from the top level, not restated below
+ * foundryPackage: sohl
+ *
+ * packageBuild:
+ *     assets:
+ *         - { from: lang, to: lang }
+ *         - { from: assets/icons, to: assets/icons }
+ *     assetTransform: ./utils/svg-theme.mjs
+ *     stageDir: build/stage
+ *     clean:
+ *         extra: [site/content, site/public]
+ *     lang:
+ *         sources: lang/*.json
+ *     deploy:
+ *         envPrefix: SOHL
+ * ```
+ *
+ * @module
+ */
+
+import path from "node:path";
+import { loadPackConfig } from "@heroiclands/content-build/engine/pack-config";
+
+/** Keys the reserved section may declare. */
+const SECTION_KEYS = [
+    "stageDir",
+    "assets",
+    "assetTransform",
+    "clean",
+    "lang",
+    "deploy",
+    "release",
+];
+const ASSET_KEYS = ["from", "to"];
+const CLEAN_KEYS = ["extra"];
+const LANG_KEYS = ["sources", "help"];
+const DEPLOY_KEYS = ["envPrefix"];
+const RELEASE_KEYS = ["artifact"];
+
+/**
+ * The artifact name each package kind ships, so no repository states it.
+ *
+ * Foundry installs a system from `system.json` and a module from `module.json`;
+ * the kind already says which, so `pack-release.mjs` passing
+ * `{ artifact: "system" }` by hand was restating `packageKind`.
+ */
+const ARTIFACT_OF_KIND = Object.freeze({
+    systems: "system",
+    modules: "module",
+});
+
+/**
+ * @param {string} where - Dotted path of the offending key.
+ * @param {string} problem - What is wrong with it.
+ * @returns {never}
+ */
+function fail(where, problem) {
+    throw new TypeError(`package-build config: \`${where}\` ${problem}.`);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} Whether it is a plain mapping.
+ */
+function isMapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * @param {Record<string, unknown>} object - The mapping to check.
+ * @param {readonly string[]} allowed - The keys it may declare.
+ * @param {string} prefix - Dotted path prefix for the error.
+ */
+function rejectUnknownKeys(object, allowed, prefix) {
+    for (const key of Object.keys(object)) {
+        if (!allowed.includes(key)) {
+            fail(
+                `${prefix}${key}`,
+                `is not a recognised key (expected one of: ${allowed.join(", ")})`,
+            );
+        }
+    }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} where
+ * @returns {string}
+ */
+function requireNonEmptyString(value, where) {
+    if (typeof value !== "string" || value.trim() === "") {
+        fail(where, "must be a non-empty string");
+    }
+    return /** @type {string} */ (value);
+}
+
+/**
+ * One staging copy: a source path in the repository, and where it lands under
+ * the staged package root.
+ *
+ * @typedef {object} AssetSpec
+ * @property {string} from  Source path, relative to the repository root.
+ * @property {string} to    Destination, relative to the staged package root.
+ */
+
+/**
+ * @param {unknown} value
+ * @param {number} index
+ * @returns {Readonly<AssetSpec>}
+ */
+function normalizeAsset(value, index) {
+    const where = `packageBuild.assets[${index}]`;
+    if (!isMapping(value)) fail(where, "must be a mapping");
+    const asset = /** @type {Record<string, unknown>} */ (value);
+    rejectUnknownKeys(asset, ASSET_KEYS, `${where}.`);
+    return Object.freeze({
+        from: requireNonEmptyString(asset.from, `${where}.from`),
+        to: requireNonEmptyString(asset.to, `${where}.to`),
+    });
+}
+
+/**
+ * The resolved `packageBuild` section, every optional half filled in.
+ *
+ * @typedef {object} PackageBuildConfig
+ * @property {string} rootDir        The repository root, from content-build.
+ * @property {string} packageKind    `systems` or `modules`.
+ * @property {string} packageId      The Foundry package id.
+ * @property {string} artifact       Derived: `system` or `module`.
+ * @property {string} stageDir      The staged package root, relative to
+ *                                   `rootDir`. Every asset `to:` lands under it.
+ * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {string|null} assetTransform  Module to load a `transform` from,
+ *                                   resolved against `rootDir`. `null` when
+ *                                   the repository stages assets verbatim.
+ * @property {readonly string[]} cleanExtra  Directories to remove beyond the
+ *                                   conventional build artifacts.
+ * @property {string} langSources    Glob for the localization files to check.
+ * @property {string|null} langHelp  Extra guidance printed after a failure.
+ * @property {string} envPrefix      Prefix of the deploy environment variables.
+ */
+
+/**
+ * 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-build configuration.
+ * @returns {Readonly<PackageBuildConfig>} The frozen configuration.
+ * @throws {TypeError} When the reserved section declares something malformed.
+ */
+export function resolvePackageBuildConfig(shared) {
+    const section = /** @type {Record<string, unknown>} */ (
+        shared.packageBuild ?? {}
+    );
+    rejectUnknownKeys(section, SECTION_KEYS, "packageBuild.");
+
+    if (section.assets !== undefined && !Array.isArray(section.assets)) {
+        fail("packageBuild.assets", "must be a list");
+    }
+    const assets = (section.assets ?? []).map(normalizeAsset);
+
+    const clean = section.clean ?? {};
+    if (!isMapping(clean)) fail("packageBuild.clean", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (clean),
+        CLEAN_KEYS,
+        "packageBuild.clean.",
+    );
+    const extra = /** @type {Record<string, unknown>} */ (clean).extra ?? [];
+    if (!Array.isArray(extra)) {
+        fail("packageBuild.clean.extra", "must be a list");
+    }
+    const cleanExtra = extra.map((dir, i) =>
+        requireNonEmptyString(dir, `packageBuild.clean.extra[${i}]`),
+    );
+
+    const lang = section.lang ?? {};
+    if (!isMapping(lang)) fail("packageBuild.lang", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (lang),
+        LANG_KEYS,
+        "packageBuild.lang.",
+    );
+    const langInput = /** @type {Record<string, unknown>} */ (lang);
+
+    const deploy = section.deploy ?? {};
+    if (!isMapping(deploy)) fail("packageBuild.deploy", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (deploy),
+        DEPLOY_KEYS,
+        "packageBuild.deploy.",
+    );
+    const deployInput = /** @type {Record<string, unknown>} */ (deploy);
+
+    const release = section.release ?? {};
+    if (!isMapping(release)) fail("packageBuild.release", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (release),
+        RELEASE_KEYS,
+        "packageBuild.release.",
+    );
+    const releaseInput = /** @type {Record<string, unknown>} */ (release);
+
+    return Object.freeze({
+        rootDir: shared.rootDir,
+        // Where the package is assembled before it is zipped or deployed. Every
+        // asset destination is relative to it, so a repository's table says
+        // `lang`, not `build/stage/lang` — the latter is what each consumer's
+        // `copy-assets.mjs` spelled out on every row.
+        stageDir:
+            section.stageDir === undefined ?
+                "build/stage"
+            :   requireNonEmptyString(
+                    section.stageDir,
+                    "packageBuild.stageDir",
+                ),
+        packageKind: shared.packageKind,
+        packageId: shared.foundryPackage,
+        // Derived from the kind, which already decides it. Stating it was one
+        // more literal every consumer's release script carried.
+        artifact:
+            releaseInput.artifact === undefined ?
+                ARTIFACT_OF_KIND[
+                    /** @type {"systems"|"modules"} */ (shared.packageKind)
+                ]
+            :   requireNonEmptyString(
+                    releaseInput.artifact,
+                    "packageBuild.release.artifact",
+                ),
+        assets: Object.freeze(assets),
+        assetTransform:
+            section.assetTransform === undefined ?
+                null
+            :   path.resolve(
+                    shared.rootDir,
+                    requireNonEmptyString(
+                        section.assetTransform,
+                        "packageBuild.assetTransform",
+                    ),
+                ),
+        cleanExtra: Object.freeze(cleanExtra),
+        langSources:
+            langInput.sources === undefined ?
+                "lang/*.json"
+            :   requireNonEmptyString(
+                    langInput.sources,
+                    "packageBuild.lang.sources",
+                ),
+        langHelp:
+            langInput.help === undefined ?
+                null
+            :   requireNonEmptyString(langInput.help, "packageBuild.lang.help"),
+        envPrefix:
+            deployInput.envPrefix === undefined ?
+                "SOHL"
+            :   requireNonEmptyString(
+                    deployInput.envPrefix,
+                    "packageBuild.deploy.envPrefix",
+                ),
+    });
+}
+
+/**
+ * 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() {
+    return resolvePackageBuildConfig(loadPackConfig());
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -39,7 +39,11 @@
             "types": "./types/text.d.mts",
             "import": "./text.mjs"
         },
-        "./package.json": "./package.json"
+        "./package.json": "./package.json",
+        "./config": {
+            "types": "./types/config.d.mts",
+            "import": "./config.mjs"
+        }
     },
     "files": [
         "bundle.mjs",
@@ -51,7 +55,9 @@
         "stage.mjs",
         "text.mjs",
         "types",
-        "README.md"
+        "README.md",
+        "bin",
+        "config.mjs"
     ],
     "scripts": {
         "test": "vitest run",
@@ -63,9 +69,13 @@
         "prepare": "git config core.hooksPath .githooks || true"
     },
     "dependencies": {
+        "@heroiclands/content-build": "^0.15.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
-        "ssh2-sftp-client": "^12.1.1"
+        "dotenv": "^17.2.3",
+        "glob": "^11.0.3",
+        "ssh2-sftp-client": "^12.1.1",
+        "yargs": "^18.1.0"
     },
     "devDependencies": {
         "@types/node": "^26.2.0",
@@ -95,5 +105,8 @@
     },
     "bugs": {
         "url": "https://github.com/HeroicLands/package-build/issues"
+    },
+    "bin": {
+        "package-build": "./bin/package-build.mjs"
     }
 }

package/types/config.d.mts

@@ -0,0 +1,110 @@
+/**
+ * The resolved `packageBuild` section, every optional half filled in.
+ *
+ * @typedef {object} PackageBuildConfig
+ * @property {string} rootDir        The repository root, from content-build.
+ * @property {string} packageKind    `systems` or `modules`.
+ * @property {string} packageId      The Foundry package id.
+ * @property {string} artifact       Derived: `system` or `module`.
+ * @property {string} stageDir      The staged package root, relative to
+ *                                   `rootDir`. Every asset `to:` lands under it.
+ * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {string|null} assetTransform  Module to load a `transform` from,
+ *                                   resolved against `rootDir`. `null` when
+ *                                   the repository stages assets verbatim.
+ * @property {readonly string[]} cleanExtra  Directories to remove beyond the
+ *                                   conventional build artifacts.
+ * @property {string} langSources    Glob for the localization files to check.
+ * @property {string|null} langHelp  Extra guidance printed after a failure.
+ * @property {string} envPrefix      Prefix of the deploy environment variables.
+ */
+/**
+ * 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-build 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>;
+/**
+ * One staging copy: a source path in the repository, and where it lands under
+ * the staged package root.
+ */
+export type AssetSpec = {
+    /**
+     * Source path, relative to the repository root.
+     */
+    from: string;
+    /**
+     * Destination, relative to the staged package root.
+     */
+    to: string;
+};
+/**
+ * The resolved `packageBuild` section, every optional half filled in.
+ */
+export type PackageBuildConfig = {
+    /**
+     * The repository root, from content-build.
+     */
+    rootDir: string;
+    /**
+     * `systems` or `modules`.
+     */
+    packageKind: string;
+    /**
+     * The Foundry package id.
+     */
+    packageId: string;
+    /**
+     * Derived: `system` or `module`.
+     */
+    artifact: string;
+    /**
+     * The staged package root, relative to
+     *  `rootDir`. Every asset `to:` lands under it.
+     */
+    stageDir: string;
+    assets: readonly Readonly<AssetSpec>[];
+    /**
+     * Module to load a `transform` from,
+     * resolved against `rootDir`. `null` when
+     * the repository stages assets verbatim.
+     */
+    assetTransform: string | null;
+    /**
+     * Directories to remove beyond the
+     * conventional build artifacts.
+     */
+    cleanExtra: readonly string[];
+    /**
+     * Glob for the localization files to check.
+     */
+    langSources: string;
+    /**
+     * Extra guidance printed after a failure.
+     */
+    langHelp: string | null;
+    /**
+     * Prefix of the deploy environment variables.
+     */
+    envPrefix: string;
+};