@heroiclands/package-build 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,187 @@
+# @heroiclands/package-build
+
+## 0.3.0
+
+### Minor Changes
+
+- 0a2ef1e: **The Foundry manifest is generated from configuration. The template is
+  retired.**
+  
+  `package-build manifest` writes `system.json` / `module.json` from
+  `packageBuild.manifest` plus the facts the build already holds. There is no
+  `assets/templates/*.template.json`, and the template-reading path is removed
+  rather than left as a fallback: `writeFoundryManifest`, `stampManifest` and
+  `artifactFromTemplate` are gone, replaced by `buildManifest`, `writeManifest`
+  and `manifestPacks`.
+  
+  The manifest was the one build input still hand-authored JSON, per repository,
+  with no schema and nothing checking it — and it declared facts the configuration
+  already declared. SoHL's pack list was written twice, in two formats, with
+  nothing checking the pairs agreed; `sohl-kethira-basic` hand-maintained its whole
+  `module.json`, and its `download` named an older version than the module claimed.
+  
+  Three kinds of key end up in the result:
+  
+  - **Declared** — `packageBuild.manifest`, emitted unchanged, so a key Foundry
+    adds in a later version needs no release of this package. The block is
+    deliberately not key-checked; pass-through and unknown-key checking cannot
+    coexist, which is why it is its own block rather than spread across
+    `packageBuild:` where the keys around it are still checked.
+  - **Derived** — `id`, `version`, `url`, `bugs`, `manifest`, `download`,
+    `compatibility`, `relationships`, `packs`. Declaring one is an **error**
+    naming the key and where the value actually comes from, not an override: an
+    authored copy would be silently overwritten and the two would disagree with
+    nothing to say so.
+  - **Computed** — namespaced `flags` from a module named in
+    `packageBuild.manifestFlags`, merged over any declared. That is for a value a
+    repository must work out rather than state — SoHL's credits `@UUID` only
+    exists once the content tree has been walked.
+  
+  `packs` comes from the **one** pack list at the top level of
+  `content-build.config.yaml`, with companions flattened in. Give each pack the
+  `label` Foundry should show; everything else is derived.
+  
+  Requires `@heroiclands/content-build` **1.0.0**, which moved `compatibility` and
+  `relationships` to the top level (content-build#50).
+  
+  Verified against SoHL's real package: the generated manifest is **byte-identical**
+  to what its template pipeline produces today, all 24 keys, key order included.
+
+## 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

@@ -95,8 +95,74 @@ packageBuild:
   deploy:
     # Prefix of the shared SFTP override variables. Default `SOHL`.
     envPrefix: SOHL
+
+  # Optional. A module exporting `flags(config)` returning namespaced Foundry
+  # flags the repository has to *compute* — an address that only exists once
+  # the content tree has been walked, say. Merged over any declared below.
+  manifestFlags: ./utils/manifest-flags.mjs
+
+  # The Foundry package manifest. Emitted as declared, so a key Foundry adds in
+  # a later version needs no release of this package.
+  manifest:
+    title: Song of Heroic Lands
+    description: <p>…</p>
+    license: LICENSE.md
+    readme: README.md
+    authors:
+      - { name: Toasty, discord: "toasty#8538" }
+    esmodules: [sohl.js]
+    styles: [css/sohl.css]
+    languages:
+      - { lang: en, name: English, path: lang/en.json }
+    documentTypes:
+      Item:
+        skill: { htmlFields: [notes, docHtml] }
+    packFolders:
+      - name: Song of Heroic Lands
+        sorting: m
+        color: "#094fcb"
+        packs: [items, journals, actors, macros, scenes, adventures]
+    media:
+      - { type: logo, url: systems/sohl/assets/ui/logo.webp }
+    socket: true
+    grid: { distance: 5, units: ft }
+    primaryTokenAttribute: health
 ```
 
+### The manifest is generated, not stamped
+
+`package-build manifest` writes `system.json` / `module.json` into the stage.
+**There is no template file.** A manifest used to be hand-authored JSON that the
+build stamped a few fields into — the one build input still written by hand, per
+repository, with no schema and nothing checking it. It also declared facts the
+configuration already declared: the pack list twice, in two formats, with
+nothing checking the pairs agreed.
+
+Three kinds of key end up in the result:
+
+| Kind         | Where it comes from                                                                               |
+| ------------ | ------------------------------------------------------------------------------------------------- |
+| **Declared** | `packageBuild.manifest`, emitted unchanged                                                        |
+| **Derived**  | `id`, `version`, `url`, `bugs`, `manifest`, `download`, `compatibility`, `relationships`, `packs` |
+| **Computed** | namespaced `flags` from `manifestFlags`, merged over any declared                                 |
+
+**Declaring a derived key is an error, not an override.** An authored `version`
+would look authoritative, sit there unread, and disagree with the shipped
+package forever; the build says so, naming the key and where the value actually
+comes from.
+
+`packs` is derived from the **one** pack list at the top level of
+`content-build.config.yaml` — each entry's `label`, `type`, `name` and
+`private`, plus a `system` from `stats.systemId` and a `path` of
+`packs/<name>`. Companions are flattened in, because Foundry sees no difference:
+a companion is only a pack written by another pass rather than one of its own.
+Give each pack the `label` you want Foundry to show.
+
+`compatibility` and `relationships` are read from the **top level** of the
+shared configuration, not from this section — content-build consumes them
+(`supportedCoreVersion`, and a module'''s `stats.systemVersion`) and the
+dependency runs one way.
+
 **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
@@ -121,6 +187,7 @@ other's schema — they split by input, and the dependency runs one way.
 ```
 npx package-build clean [--distclean]
 npx package-build assets
+npx package-build manifest
 npx package-build lang check
 npx package-build release
 npx package-build deploy <stage>
@@ -198,6 +265,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

@@ -42,6 +42,7 @@
  * Usage:
  *   npx package-build clean [--distclean]
  *   npx package-build assets
+ *   npx package-build manifest
  *   npx package-build lang check
  *   npx package-build release
  *   npx package-build deploy <stage>
@@ -62,9 +63,11 @@ import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
+import { loadPackConfig } from "@heroiclands/content-build/engine/pack-config";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { validateLangSource } from "../lang.mjs";
 import { packRelease } from "../release.mjs";
+import { writeManifest } from "../manifest.mjs";
 import { deployStage } from "../deploy.mjs";
 
 /**
@@ -212,6 +215,70 @@ function assetsCommand() {
     };
 }
 
+/**
+ * `manifest` — generate `system.json` / `module.json` into the build stage.
+ *
+ * There is no template to read. Everything the manifest needs is either
+ * declared in `packageBuild.manifest`, derived from configuration this
+ * repository already carries, or computed by a module the repository names in
+ * `packageBuild.manifestFlags` — for a namespaced flag it has to work out, such
+ * as the compendium address of a document that only exists once the content
+ * tree has been walked.
+ *
+ * @returns {object} The yargs command module.
+ */
+function manifestCommand() {
+    return {
+        command: "manifest",
+        describe: "Generate the Foundry package manifest",
+        builder: (y) => y,
+        handler: handler(async () => {
+            const config = loadPackageBuildConfig();
+            const shared = loadPackConfig();
+            const packageJson = JSON.parse(
+                fs.readFileSync(
+                    path.join(config.rootDir, "package.json"),
+                    "utf8",
+                ),
+            );
+
+            let flags;
+            if (config.manifestFlags) {
+                const module = await import(
+                    `file://${config.manifestFlags}`
+                ).catch((err) =>
+                    die(
+                        `cannot load \`packageBuild.manifestFlags\` ` +
+                            `(${config.manifestFlags}): ${err.message}`,
+                    ),
+                );
+                if (typeof module.flags !== "function") {
+                    die(
+                        `\`packageBuild.manifestFlags\` ` +
+                            `(${config.manifestFlags}) exports no \`flags\` ` +
+                            `function. It must export ` +
+                            `\`flags(config) -> Record<string, object>\`.`,
+                    );
+                }
+                flags = await module.flags(shared);
+            }
+
+            const { path: written, manifest } = await writeManifest({
+                config: shared,
+                packageJson,
+                artifact: config.artifact,
+                outDir: path.join(config.rootDir, config.stageDir),
+                flags,
+            });
+            console.log(
+                `✅ Wrote ${path.relative(config.rootDir, written)} ` +
+                    `(${Object.keys(manifest).length} keys, ` +
+                    `${manifest.packs.length} packs).`,
+            );
+        }),
+    };
+}
+
 /**
  * `lang check` — verify every localization file survives `expandObject`.
  *
@@ -352,6 +419,7 @@ yargs(hideBin(process.argv))
     .scriptName("package-build")
     .command(cleanCommand())
     .command(assetsCommand())
+    .command(manifestCommand())
     .command(langCommand())
     .command(releaseCommand())
     .command(deployCommand())

package/config.mjs

@@ -63,11 +63,36 @@ const SECTION_KEYS = [
     "stageDir",
     "assets",
     "assetTransform",
+    "manifest",
+    "manifestFlags",
     "clean",
     "lang",
     "deploy",
     "release",
 ];
+
+/**
+ * Manifest keys a repository may **not** declare, because the build derives
+ * them and would only overwrite what was written.
+ *
+ * Silently overwriting is the failure this list exists to prevent: a
+ * `version` typed into the configuration would look authoritative, sit there
+ * unread, and disagree with the shipped package forever. Declaring one is an
+ * error naming the key and where the value actually comes from.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_MANIFEST_KEYS = Object.freeze({
+    id: "`foundryPackage`, itself derived from package.json `name`",
+    version: "package.json `version`",
+    url: "package.json `repository`",
+    bugs: "package.json `repository`",
+    manifest: "package.json `repository` and the release tag",
+    download: "package.json `repository` and the release tag",
+    compatibility: "the top level of content-build.config.yaml",
+    relationships: "the top level of content-build.config.yaml",
+    packs: "the `packs` list at the top level of content-build.config.yaml",
+});
 const ASSET_KEYS = ["from", "to"];
 const CLEAN_KEYS = ["extra"];
 const LANG_KEYS = ["sources", "help"];
@@ -156,6 +181,41 @@ function normalizeAsset(value, index) {
     });
 }
 
+/**
+ * Validate the manifest specification.
+ *
+ * **Deliberately not key-checked.** Everything a repository declares here is
+ * emitted into the manifest unchanged, so a key Foundry adds in a later version
+ * can be declared without waiting for a release of this package. The only rule
+ * is the one that has a wrong answer rather than an unknown one: a key the
+ * build *derives* must not also be authored, because the authored value would
+ * be silently overwritten.
+ *
+ * That is also why it is its own block rather than being spread across
+ * `packageBuild:` directly — pass-through and unknown-key checking cannot
+ * coexist in one mapping, and the keys around it are worth checking.
+ *
+ * @param {unknown} value - The `manifest` block, or `undefined`.
+ * @returns {Readonly<Record<string, unknown>>} It, frozen; `{}` when absent.
+ */
+function normalizeManifest(value) {
+    if (value === undefined) return Object.freeze({});
+    if (!isMapping(value)) fail("packageBuild.manifest", "must be a mapping");
+    const input = /** @type {Record<string, unknown>} */ (value);
+
+    for (const [key, source] of Object.entries(DERIVED_MANIFEST_KEYS)) {
+        if (input[key] !== undefined) {
+            fail(
+                `packageBuild.manifest.${key}`,
+                `is derived from ${source} and must not be declared — it ` +
+                    `would be overwritten, and the two would disagree with ` +
+                    `nothing to say so`,
+            );
+        }
+    }
+    return Object.freeze(structuredClone(input));
+}
+
 /**
  * The resolved `packageBuild` section, every optional half filled in.
  *
@@ -167,6 +227,11 @@ function normalizeAsset(value, index) {
  * @property {string} stageDir      The staged package root, relative to
  *                                   `rootDir`. Every asset `to:` lands under it.
  * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {Readonly<Record<string, unknown>>} manifest  The manifest
+ *                                   specification, emitted as declared.
+ * @property {string|null} manifestFlags  Module to load a `flags` function
+ *                                   from, for namespaced flags a repository has
+ *                                   to compute. `null` when it declares none.
  * @property {string|null} assetTransform  Module to load a `transform` from,
  *                                   resolved against `rootDir`. `null` when
  *                                   the repository stages assets verbatim.
@@ -280,6 +345,17 @@ export function resolvePackageBuildConfig(shared) {
                         "packageBuild.assetTransform",
                     ),
                 ),
+        manifest: normalizeManifest(section.manifest),
+        manifestFlags:
+            section.manifestFlags === undefined ?
+                null
+            :   path.resolve(
+                    shared.rootDir,
+                    requireNonEmptyString(
+                        section.manifestFlags,
+                        "packageBuild.manifestFlags",
+                    ),
+                ),
         cleanExtra: Object.freeze(cleanExtra),
         langSources:
             langInput.sources === undefined ?

package/manifest.mjs

@@ -15,26 +15,35 @@
  * Building the Foundry package manifest — `system.json` or `module.json`.
  *
  * Foundry defines exactly two package kinds, and a repository is one of them,
- * so there is one job here with two spellings: read the repository's manifest
- * *template*, stamp the facts that must not be transcribed, and write the
- * result into the build stage.
- *
- * **The stamped fields are the ones a human copy rots.** A manifest carries the
- * version, the repository addresses, and the two release URLs Foundry fetches
- * to check for and install an update. Every one of them is already stated
- * somewhere that owns it — `package.json` — and a second, hand-maintained copy
- * in the template drifts the moment a release is cut. `sohl-kethira-basic`
- * hand-maintains its whole `module.json`, and its `download` still names an
- * older version than the module claims.
+ * so there is one job here with two spellings: assemble the manifest from the
+ * repository's configuration and write it into the build stage.
+ *
+ * **There is no template any more.** A manifest used to be a hand-authored
+ * `system.template.json` that this module stamped a few fields into — which
+ * made it the one build input still written as JSON, by hand, per repository,
+ * with no schema and nothing checking it. Worse, it declared facts the
+ * configuration also declared: the pack list twice, in two formats, with
+ * nothing checking that the pairs agreed. `sohl-kethira-basic` hand-maintained
+ * its whole `module.json`, and its `download` named an older version than the
+ * module claimed.
+ *
+ * So the manifest is generated (#9). Three kinds of key end up in it:
+ *
+ * - **Declared** — the `packageBuild.manifest` block, emitted unchanged, so a
+ *   key Foundry adds in a later version needs no release of this package.
+ * - **Derived** — the identity, the version, the release addresses, the
+ *   compatibility ranges and the pack list. Declaring one of these is an error
+ *   rather than an override: the authored copy would be silently overwritten.
+ * - **Computed** — namespaced `flags` a repository works out for itself.
  *
  * **Nothing here invents an address.** The repository URL is read from
- * `package.json`'s `repository` field, normalised, and everything else is
- * derived from it. A manifest that advertised another package's URLs would send
- * Foundry to the wrong release on every update check — which is exactly what a
- * template copied between repositories produces.
+ * `package.json`'s `repository` field, normalised, and everything else derived
+ * from it. A manifest advertising another package's URLs would send Foundry to
+ * the wrong release on every update check — exactly what a template copied
+ * between repositories produced.
  *
  * The rules are pure functions over data. I/O is confined to
- * {@link writeFoundryManifest}, which is the only export that touches disk.
+ * {@link writeManifest}, which is the only export that touches disk.
  *
  * @module
  */
@@ -52,34 +61,6 @@ import path from "node:path";
  */
 export const ARTIFACTS = Object.freeze(["system", "module"]);
 
-/**
- * Which artifact a template file builds.
- *
- * Inferred from the template's own name so the usual case takes no
- * configuration: a repository that ships `system.template.json` is a system,
- * and one that ships `module.template.json` is a module. That is the same pair
- * `@heroiclands/content-build` resolves a package manifest from, so the two
- * cannot disagree about what a repository is.
- *
- * @param {string} templatePath - Path to the manifest template.
- * @returns {"system"|"module"} The artifact name.
- * @throws {TypeError} When the name identifies neither kind — a template called
- *   something else leaves nothing to infer from, and guessing would silently
- *   emit a manifest Foundry never looks for.
- */
-export function artifactFromTemplate(templatePath) {
-    const base = path.basename(String(templatePath ?? ""));
-    const artifact = ARTIFACTS.find((a) => base.startsWith(`${a}.`));
-    if (!artifact) {
-        throw new TypeError(
-            `Cannot tell whether "${base}" builds a system or a module. ` +
-                `Name it system.template.json or module.template.json, or pass ` +
-                `\`artifact\` explicitly.`,
-        );
-    }
-    return artifact;
-}
-
 /**
  * The repository's web address, from whatever spelling `package.json` carries.
  *
@@ -138,80 +119,155 @@ export function releaseUrls({ repoUrl, version, artifact }) {
 }
 
 /**
- * Stamp a manifest template with the facts that must not be transcribed.
+ * The order the manifest's keys are written in.
  *
- * Pure: the template is not mutated, and the result is a new object.
+ * Foundry does not care, but a human reading a diff does, and the generated
+ * file has to be comparable against the hand-authored template it replaces —
+ * which is only possible if the order is fixed rather than incidental to which
+ * keys a repository happened to declare. Anything not listed keeps its declared
+ * order, after these.
  *
- * `flags` is merged **per namespace**, not wholesale, so a template may carry
- * its own keys under the same namespace and keep them. A caller supplies
- * whatever its package needs there — the credits journal's UUID, the settings
- * sidebar's links — because those are facts about one package, not about being
- * a Foundry package.
+ * @type {readonly string[]}
+ */
+const MANIFEST_KEY_ORDER = Object.freeze([
+    "id",
+    "title",
+    "description",
+    "version",
+    "authors",
+    "license",
+    "readme",
+    "changelog",
+    "flags",
+    "compatibility",
+    "relationships",
+    "esmodules",
+    "styles",
+    "languages",
+    "documentTypes",
+    "packFolders",
+    "packs",
+    "media",
+    "socket",
+    "grid",
+    "primaryTokenAttribute",
+    "url",
+    "bugs",
+    "manifest",
+    "download",
+]);
+
+/**
+ * The manifest's `packs`, derived from the one pack list the build already has.
  *
- * @param {object} template - The parsed manifest template.
- * @param {object} opts
- * @param {string} opts.version - The version being built.
- * @param {string} opts.repoUrl - Normalised repository URL.
- * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
- * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
- * @returns {object} The stamped manifest.
+ * The two used to be written separately — `content-build.config.yaml` declared
+ * a pack's name and type, and the manifest template declared them again beside
+ * a label, a path and a system id, with nothing checking that the pairs agreed.
+ * They are one list now.
+ *
+ * Companions are flattened in, because Foundry sees no difference: a companion
+ * is only a pack written by another pass rather than one of its own, and it
+ * ships as an ordinary compendium. The order matches `packDirectories`, so the
+ * manifest lists packs in the order the build compiles them.
+ *
+ * @param {object} config - The resolved content-build configuration.
+ * @returns {object[]} The manifest's `packs` array.
  */
-export function stampManifest(template, { version, repoUrl, artifact, flags }) {
-    const stamped = {
-        ...template,
-        version,
-        ...releaseUrls({ repoUrl, version, artifact }),
+export function manifestPacks(config) {
+    const flatten = (pack) => [
+        pack,
+        ...(pack.companions ?? []).flatMap(flatten),
+    ];
+    return config.packs.flatMap(flatten).map((pack) => ({
+        label: pack.label,
+        type: pack.type,
+        name: pack.name,
+        system: config.stats.systemId,
+        path: `packs/${pack.name}`,
+        private: pack.private,
+    }));
+}
+
+/**
+ * Build a Foundry package manifest from the resolved configuration.
+ *
+ * Three kinds of key end up in the result:
+ *
+ * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
+ *   a key Foundry adds later needs no release of this package.
+ * - **Derived** — the identity, the release addresses, the version, the Foundry
+ *   and system compatibility ranges, and the pack list. These are refused if
+ *   also declared: an authored copy would be overwritten and the two would
+ *   disagree with nothing to say so.
+ * - **Computed** — namespaced `flags` a repository works out for itself, merged
+ *   over any it declared.
+ *
+ * @param {object} options - Inputs.
+ * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.packageJson - The repository's `package.json`.
+ * @param {string} options.artifact - `system` or `module`.
+ * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @returns {object} The manifest, ready to serialise.
+ */
+export function buildManifest({ config, packageJson, artifact, flags }) {
+    const declared = config.packageBuild?.manifest ?? {};
+    const repoUrl = normalizeRepoUrl(packageJson.repository);
+
+    const derived = {
+        id: config.foundryPackage,
+        version: packageJson.version,
+        packs: manifestPacks(config),
+        ...releaseUrls({ repoUrl, version: packageJson.version, artifact }),
     };
+    if (config.compatibility) derived.compatibility = config.compatibility;
+    if (config.relationships && Object.keys(config.relationships).length) {
+        derived.relationships = config.relationships;
+    }
+
+    const merged = { ...declared, ...derived };
 
     if (flags && Object.keys(flags).length) {
-        stamped.flags = { ...(template.flags ?? {}) };
+        merged.flags = { ...(declared.flags ?? {}) };
         for (const [namespace, values] of Object.entries(flags)) {
-            stamped.flags[namespace] = {
-                ...(template.flags?.[namespace] ?? {}),
+            merged.flags[namespace] = {
+                ...(declared.flags?.[namespace] ?? {}),
                 ...values,
             };
         }
     }
 
-    return stamped;
+    // Ordered, so the generated file diffs against the template it replaces.
+    const ordered = {};
+    for (const key of MANIFEST_KEY_ORDER) {
+        if (merged[key] !== undefined) ordered[key] = merged[key];
+    }
+    for (const [key, value] of Object.entries(merged)) {
+        if (!(key in ordered)) ordered[key] = value;
+    }
+    return ordered;
 }
 
 /**
- * Read a manifest template, stamp it, and write the result into the stage.
+ * Write the generated manifest into the staged package.
  *
- * The only export here that touches disk. Everything it decides is decided by
- * the pure functions above, so the rules stay testable without a filesystem.
- *
- * @param {object} opts
- * @param {string} opts.templatePath - The manifest template to read.
- * @param {object} opts.packageJson - The parsed `package.json`, which owns the
- *   version and the repository address.
- * @param {string} opts.outDir - Directory to write the manifest into, created
- *   if absent.
- * @param {"system"|"module"} [opts.artifact] - Overrides the artifact inferred
- *   from the template's name.
- * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
- * @returns {Promise<{path: string, manifest: object}>} Where it was written,
- *   and what was written.
+ * @param {object} options - As {@link buildManifest}, plus where to write.
+ * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.packageJson - The repository's `package.json`.
+ * @param {string} options.artifact - `system` or `module`.
+ * @param {string} options.outDir - Directory to write into.
+ * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @returns {Promise<{path: string, manifest: object}>} Where it went, and what.
  */
-export async function writeFoundryManifest({
-    templatePath,
+export async function writeManifest({
+    config,
     packageJson,
+    artifact,
     outDir,
-    artifact = undefined,
-    flags = undefined,
+    flags,
 }) {
-    const kind = artifact ?? artifactFromTemplate(templatePath);
-    const template = JSON.parse(await fs.readFile(templatePath, "utf8"));
-    const manifest = stampManifest(template, {
-        version: packageJson.version,
-        repoUrl: normalizeRepoUrl(packageJson.repository),
-        artifact: kind,
-        flags,
-    });
-
+    const manifest = buildManifest({ config, packageJson, artifact, flags });
     await fs.mkdir(outDir, { recursive: true });
-    const outPath = path.join(outDir, `${kind}.json`);
+    const outPath = path.join(outDir, `${artifact}.json`);
     // Trailing newline: the file is committed to a release archive and read by
     // humans as often as by Foundry.
     await fs.writeFile(

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.2.0",
-    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
+    "version": "0.3.0",
+    "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",
@@ -55,6 +55,7 @@
         "stage.mjs",
         "text.mjs",
         "types",
+        "CHANGELOG.md",
         "README.md",
         "bin",
         "config.mjs"
@@ -66,10 +67,12 @@
         "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",
+        "@heroiclands/content-build": "^1.0.0",
         "acorn": "^8.18.0",
         "archiver": "^8.0.0",
         "dotenv": "^17.2.3",
@@ -78,6 +81,7 @@
         "yargs": "^18.1.0"
     },
     "devDependencies": {
+        "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
         "prettier": "^3.9.6",
         "typescript": "^6.0.3",

package/types/config.d.mts

@@ -9,6 +9,11 @@
  * @property {string} stageDir      The staged package root, relative to
  *                                   `rootDir`. Every asset `to:` lands under it.
  * @property {readonly Readonly<AssetSpec>[]} assets
+ * @property {Readonly<Record<string, unknown>>} manifest  The manifest
+ *                                   specification, emitted as declared.
+ * @property {string|null} manifestFlags  Module to load a `flags` function
+ *                                   from, for namespaced flags a repository has
+ *                                   to compute. `null` when it declares none.
  * @property {string|null} assetTransform  Module to load a `transform` from,
  *                                   resolved against `rootDir`. `null` when
  *                                   the repository stages assets verbatim.
@@ -44,6 +49,18 @@ export function resolvePackageBuildConfig(shared: object): Readonly<PackageBuild
  *   declares something malformed.
  */
 export function loadPackageBuildConfig(): Readonly<PackageBuildConfig>;
+/**
+ * Manifest keys a repository may **not** declare, because the build derives
+ * them and would only overwrite what was written.
+ *
+ * Silently overwriting is the failure this list exists to prevent: a
+ * `version` typed into the configuration would look authoritative, sit there
+ * unread, and disagree with the shipped package forever. Declaring one is an
+ * error naming the key and where the value actually comes from.
+ *
+ * @type {Readonly<Record<string, string>>}
+ */
+export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
 /**
  * One staging copy: a source path in the repository, and where it lands under
  * the staged package root.
@@ -84,6 +101,17 @@ export type PackageBuildConfig = {
      */
     stageDir: string;
     assets: readonly Readonly<AssetSpec>[];
+    /**
+     * The manifest
+     * specification, emitted as declared.
+     */
+    manifest: Readonly<Record<string, unknown>>;
+    /**
+     * Module to load a `flags` function
+     * from, for namespaced flags a repository has
+     * to compute. `null` when it declares none.
+     */
+    manifestFlags: string | null;
     /**
      * Module to load a `transform` from,
      * resolved against `rootDir`. `null` when

package/types/manifest.d.mts

@@ -1,19 +1,3 @@
-/**
- * Which artifact a template file builds.
- *
- * Inferred from the template's own name so the usual case takes no
- * configuration: a repository that ships `system.template.json` is a system,
- * and one that ships `module.template.json` is a module. That is the same pair
- * `@heroiclands/content-build` resolves a package manifest from, so the two
- * cannot disagree about what a repository is.
- *
- * @param {string} templatePath - Path to the manifest template.
- * @returns {"system"|"module"} The artifact name.
- * @throws {TypeError} When the name identifies neither kind — a template called
- *   something else leaves nothing to infer from, and guessing would silently
- *   emit a manifest Foundry never looks for.
- */
-export function artifactFromTemplate(templatePath: string): "system" | "module";
 /**
  * The repository's web address, from whatever spelling `package.json` carries.
  *
@@ -59,53 +43,65 @@ export function releaseUrls({ repoUrl, version, artifact }: {
     download: string;
 };
 /**
- * Stamp a manifest template with the facts that must not be transcribed.
+ * The manifest's `packs`, derived from the one pack list the build already has.
  *
- * Pure: the template is not mutated, and the result is a new object.
+ * The two used to be written separately — `content-build.config.yaml` declared
+ * a pack's name and type, and the manifest template declared them again beside
+ * a label, a path and a system id, with nothing checking that the pairs agreed.
+ * They are one list now.
  *
- * `flags` is merged **per namespace**, not wholesale, so a template may carry
- * its own keys under the same namespace and keep them. A caller supplies
- * whatever its package needs there — the credits journal's UUID, the settings
- * sidebar's links — because those are facts about one package, not about being
- * a Foundry package.
+ * Companions are flattened in, because Foundry sees no difference: a companion
+ * is only a pack written by another pass rather than one of its own, and it
+ * ships as an ordinary compendium. The order matches `packDirectories`, so the
+ * manifest lists packs in the order the build compiles them.
  *
- * @param {object} template - The parsed manifest template.
- * @param {object} opts
- * @param {string} opts.version - The version being built.
- * @param {string} opts.repoUrl - Normalised repository URL.
- * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
- * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
- * @returns {object} The stamped manifest.
+ * @param {object} config - The resolved content-build configuration.
+ * @returns {object[]} The manifest's `packs` array.
  */
-export function stampManifest(template: object, { version, repoUrl, artifact, flags }: {
-    version: string;
-    repoUrl: string;
-    artifact: "system" | "module";
+export function manifestPacks(config: object): object[];
+/**
+ * Build a Foundry package manifest from the resolved configuration.
+ *
+ * Three kinds of key end up in the result:
+ *
+ * - **Declared** — everything in `packageBuild.manifest`, emitted unchanged, so
+ *   a key Foundry adds later needs no release of this package.
+ * - **Derived** — the identity, the release addresses, the version, the Foundry
+ *   and system compatibility ranges, and the pack list. These are refused if
+ *   also declared: an authored copy would be overwritten and the two would
+ *   disagree with nothing to say so.
+ * - **Computed** — namespaced `flags` a repository works out for itself, merged
+ *   over any it declared.
+ *
+ * @param {object} options - Inputs.
+ * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.packageJson - The repository's `package.json`.
+ * @param {string} options.artifact - `system` or `module`.
+ * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @returns {object} The manifest, ready to serialise.
+ */
+export function buildManifest({ config, packageJson, artifact, flags }: {
+    config: object;
+    packageJson: object;
+    artifact: string;
     flags?: Record<string, object> | undefined;
 }): object;
 /**
- * Read a manifest template, stamp it, and write the result into the stage.
+ * Write the generated manifest into the staged package.
  *
- * The only export here that touches disk. Everything it decides is decided by
- * the pure functions above, so the rules stay testable without a filesystem.
- *
- * @param {object} opts
- * @param {string} opts.templatePath - The manifest template to read.
- * @param {object} opts.packageJson - The parsed `package.json`, which owns the
- *   version and the repository address.
- * @param {string} opts.outDir - Directory to write the manifest into, created
- *   if absent.
- * @param {"system"|"module"} [opts.artifact] - Overrides the artifact inferred
- *   from the template's name.
- * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
- * @returns {Promise<{path: string, manifest: object}>} Where it was written,
- *   and what was written.
+ * @param {object} options - As {@link buildManifest}, plus where to write.
+ * @param {object} options.config - The resolved content-build configuration.
+ * @param {object} options.packageJson - The repository's `package.json`.
+ * @param {string} options.artifact - `system` or `module`.
+ * @param {string} options.outDir - Directory to write into.
+ * @param {Record<string, object>} [options.flags] - Namespaced flags to merge.
+ * @returns {Promise<{path: string, manifest: object}>} Where it went, and what.
  */
-export function writeFoundryManifest({ templatePath, packageJson, outDir, artifact, flags, }: {
-    templatePath: string;
+export function writeManifest({ config, packageJson, artifact, outDir, flags, }: {
+    config: object;
     packageJson: object;
+    artifact: string;
     outDir: string;
-    artifact?: "module" | "system" | undefined;
     flags?: Record<string, object> | undefined;
 }): Promise<{
     path: string;