@heroiclands/package-build 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# @heroiclands/package-build
+
+## 0.2.1
+
+### Patch Changes
+
+- 4144291: **Release from merged changesets instead of a remembered command**
+  
+  Fixes [#4](https://github.com/HeroicLands/package-build/issues/4). Releasing was
+  hand-driven — bump `package.json` on a branch, merge, then remember
+  `gh release create`, because cutting the Release is what published. Nothing
+  enforced the last step, so a merged version could sit unpublished with no check
+  red; the sibling repository lost two versions that way.
+  
+  - Every pull request now declares its bump as a `.changeset/*.md` file, and CI's
+    **Changeset declared** job fails one that does not. `npx changeset add --empty`
+    is how a change says it needs no release — explicitly, rather than by omission.
+  - Merging to `main` opens a **Version Packages** pull request carrying the bump
+    and the rewritten `CHANGELOG.md`. An unreleased state is now a pull request
+    waiting in the queue rather than nothing at all.
+  - Merging that runs `changeset publish`: npm publish, the `v<version>` tag, and
+    the GitHub Release with the changelog section as its body. The OIDC Trusted
+    Publishing step is unchanged and still last; there is still no `NPM_TOKEN`, and
+    re-running on a published version is a no-op.
+  - `CHANGELOG.md` is seeded from the two hand-cut Releases so far and now ships
+    with the package. A changeset is also where a raised dependency floor gets
+    recorded — 0.2.0 raised one to `@heroiclands/content-build >= 0.15.0` and said
+    so nowhere.
+
+<!-- Sections at 0.2.1 and above are generated by `changeset version` from the
+     changesets merged into `main`. Sections at 0.2.0 and below predate that
+     pipeline and are the hand-written GitHub Release notes, kept verbatim
+     (headings demoted one level to sit under their version) so no history was
+     lost in adopting it. -->
+
+## 0.2.0
+
+_2026-08-22 — a command line, not a wrapper script per job_
+
+**A command line, so a consumer writes configuration instead of scripts.**
+
+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:
+
+| Wrapper | Lines | What was in it |
+| --- | --- | --- |
+| `build-system-json.mjs` | 143 | |
+| `push-stage.mjs` | 76 | argv, dotenv, then `packageKind: "systems"` and `packageId: "sohl"` hard-coded beside a configuration that already declared both |
+| `copy-assets.mjs` | 71 | a nine-entry data table, plus one genuine repository-specific transform |
+| `check-lang.mjs` | 69 | a glob, a call, and a help string |
+| `clean.mjs` | 47 | a `repoRoot` from `import.meta.url`, one flag, one call — no consumer-specific value at all |
+| `pack-release.mjs` | 35 | one call passing `{ artifact: "system" }`, which `packageKind` already decides |
+
+Every copy had drifted from its sibling in the other repositories, because copies do: `clean.mjs` was 47 lines in SoHL and 48 in `sohl-thalorna`, `copy-assets.mjs` 71 and 76. `sohl-thalorna`'s copy still reimplements the recursive directory copy this package has exported since it was extracted, because it was written before the extraction and nobody went back.
+
+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 moved into configuration, and the boilerplate lives here, once.
+
+#### The commands
+
+```
+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:
+
+```json
+{
+  "clean": "package-build clean",
+  "build:assets": "package-build assets",
+  "lint:lang": "package-build lang check",
+  "build:pack-release": "package-build release",
+  "push:qa": "package-build deploy qa"
+}
+```
+
+#### One configuration file, not two
+
+Settings come from the reserved `packageBuild:` section of `content-build.config.yaml` — the file a repository already has — which requires **`@heroiclands/content-build` 0.15.0 or later**.
+
+```yaml
+packageKind: systems      # read from the top level, never restated below
+foundryPackage: sohl
+
+packageBuild:
+    assets:
+        - { from: lang, to: lang }
+    assetTransform: ./utils/svg-theme.mjs
+    clean:
+        extra: [site/content, site/public]
+    deploy:
+        envPrefix: SOHL
+```
+
+A second config file would have restated `packageKind` and `foundryPackage`, which is two places for one fact. content-build validates only that the section is a mapping and hands it back frozen; everything inside it is validated here, so neither package learns the other's schema.
+
+**Derived, never stated:** the repository root (the config file's own location), `packageKind` and `packageId` (the shared configuration's top level), and the release artifact — a system ships `system.json`, a module `module.json`, so the kind already decides it.
+
+**The one genuine piece of consumer code stays the consumer's.** SoHL rewrites each SVG's hard-coded fill so icons follow the Foundry theme; `packageBuild.assetTransform` names a module exporting `transform(sourcePath) -> string | null`.
+
+#### Also in this release
+
+- `exports["./config"]` now ships its type declaration. It was declared but never generated — `tsconfig.dts.json` lists its inputs explicitly and `config.mjs` was missing from the list — so the subpath would have pointed at a file that does not exist.
+- The library modules are unchanged. Every signature the CLI needed was already there.
+
+#### Notes
+
+`--version` and `--help` answer in a directory with no configuration at all. Failures report one line rather than a stack, whether the handler was synchronous or asynchronous. Localization findings follow the diagnostics contract, `file:line:column: severity: message`.
+
+**Full changelog:** https://github.com/HeroicLands/package-build/compare/v0.1.0...v0.2.0
+
+## 0.1.0
+
+_2026-08-22 — the Foundry package toolchain_
+
+The counterpart to [`@heroiclands/content-build`](https://github.com/HeroicLands/content-build). The two split by **input**, not by repository: content-build reads `assets/content/**` and answers for what a package *says*; this one reads `lang/`, `styles/`, `src/`, `assets/` and the manifest template, and answers for what a package *is* — the parts Foundry loads whether or not the package ships any content.
+
+A module uses either, or both. An adventure module that ships only notes needs no bundler; a variant module that ships only behavior needs no Markdown pipeline. The coupling runs one way: package-build asks content-build for the compiled `packs[]` block, never the reverse.
+
+### Seven modules — the whole of assemble → validate → ship
+
+- **`manifest`** — `system.json` / `module.json`. The artifact is inferred from the template's name, and every address is derived from `package.json`'s `repository` rather than transcribed. Handles the `git+https://….git` spelling npm writes, which yields a 404 on every Foundry update check if left in place.
+- **`stage`** — assembling the build stage and clearing it away. A listed asset that does not exist **fails the build** instead of shipping a package that quietly lacks its localization or templates; the whole list is checked before anything is copied.
+- **`lang`** — what a shippable localization file must satisfy: it parses, its top level is an object, no key is both a leaf and a dotted prefix of another (which makes Foundry discard the entire file), placeholders are single-braced, key segments carry no data.
+- **`bundle`** — whether the manifest agrees with the file it points at. Declared under `"esmodules"` the bundle must parse as a module; declared under `"scripts"` it must declare **nothing** at top level, because each top-level declaration in a classic script is a global lexical binding and one colliding with a non-configurable `window` property throws at parse time. That rule bricked SoHL v0.8.0.
+- **`release`** — the two assets a GitHub Release carries. Waits for the archive to be *written*, not merely finalized.
+- **`deploy`** — installing into a Foundry data directory, local or SFTP, always as a staged atomic swap: a running Foundry holds its LevelDB packs open, and replacing them in place leaves a directory LevelDB "repairs" to zero.
+- **`text`** — locating a literal, so a finding names its line and column.
+
+### Design
+
+The rules are pure functions over data; the functions that touch disk or a network are named for what they do. That is what makes them testable at all — the scripts they were extracted from each ran their work at import time and exported nothing.
+
+### Provenance
+
+Developed as a workspace inside the Song of Heroic Lands repository across six changes (SoHL#1680, #1682, #1684, #1685, #1686), exactly as content-build incubated before its own extraction, and extracted now that its shape has stopped changing.
+
+128 tests; declaration files are emitted from the JSDoc at pack time.

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
@@ -100,6 +198,43 @@ would let something reach for one.
 declared `dependency`. Inside a workspace a missing declaration is invisible;
 installed from npm it fails on the first import.
 
+## Releasing
+
+Releasing is not a command anyone runs. It is a consequence of merging, in two
+steps, and each step is visible while it is pending.
+
+**Every pull request declares its bump.** Run `npx changeset` and pick
+major/minor/patch; the summary you write becomes the changelog entry and the
+release note. If the change ships nothing a consumer can see, say so explicitly
+with `npx changeset add --empty`. CI's **Changeset declared** job fails a pull
+request that declares neither — `npm run changeset:check` is the same check,
+locally.
+
+**Merging to `main` opens a Version Packages pull request** carrying the version
+bump and the rewritten `CHANGELOG.md`. That pull request _is_ the pending
+release: as long as something is merged but unpublished, there is an open pull
+request saying so. The previous, hand-driven process failed by leaving _nothing_
+behind when its final step was forgotten (#4).
+
+**Merging that publishes.** `changeset publish` puts the version on npm through
+Trusted Publishing (OIDC — there is no `NPM_TOKEN`), tags the commit `v<version>`
+and cuts the GitHub Release with the changelog section as its body. It publishes
+only versions that are not already on the registry, so re-running it is a no-op;
+`workflow_dispatch` on **Publish to npm** is the recovery path if a run fails
+after versioning.
+
+A changeset is also where a **raised dependency floor** gets recorded. 0.2.0 began
+requiring `@heroiclands/content-build >= 0.15.0` and announced it nowhere; a
+changeset is the place that now happens.
+
+Below 1.0.0, `^0.x` never crosses a minor — a consumer on `^0.2.0` will not see
+`0.3.0` until it bumps the pin deliberately, and Dependabot raises that as its own
+pull request.
+
+> After a successful publish, `npm view @heroiclands/package-build version` can
+> report the _previous_ version for a minute or so. `dist-tags` is correct
+> immediately, and is what the workflow prints.
+
 ## Licence
 
 GPL-3.0-or-later.

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,7 +1,7 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.1.0",
-    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
+    "version": "0.2.1",
+    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
     "main": "./index.mjs",
@@ -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,10 @@
         "stage.mjs",
         "text.mjs",
         "types",
-        "README.md"
+        "CHANGELOG.md",
+        "README.md",
+        "bin",
+        "config.mjs"
     ],
     "scripts": {
         "test": "vitest run",
@@ -60,14 +67,21 @@
         "build:types": "tsc -p tsconfig.dts.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
+        "changeset": "changeset",
+        "changeset:check": "changeset status --since=origin/main",
         "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": {
+        "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
         "prettier": "^3.9.6",
         "typescript": "^6.0.3",
@@ -95,5 +109,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;
+};