@heroiclands/package-build 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @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

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>

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,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.2.1",
+    "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",
@@ -72,7 +72,7 @@
         "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",

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;