@heroiclands/package-build 22.1.1 → 22.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @heroiclands/package-build
 
+## 22.2.0
+
+### Minor Changes
+
+- 241451e: **`schema.json` is a release asset, not a committed file.** `package-build schema` writes `build/schema.json` instead of the repository root, and `--check` is gone — there is no committed copy left to compare against. `package-build release` publishes `schema.json` beside the archive and the manifest, the way it already publishes the content index, whenever the staged tree carries one.
+  
+  To keep publishing a schema: drop the committed `schema.json` and any lint step that runs `package-build schema --check`; add `{ from: build/schema.json, to: schema.json }` to `packageBuild.assets`, and run `package-build schema` before `package-build assets` in the build chain so the release never ships one older than the source it was cut from.
+- 483b630: **`content-build site` refuses to generate a configuration with no `site.assets`.** The theme resolves every relative asset — the brand logo, the 404 hero, every CDN-resolved image — against `site.assets`, and there is no defensible default: a package that built a site with the key absent published every one of those as a broken relative path. Declare `site.assets` — the `https://` host every package's imagery is served from — in `package-build.config.yaml` for any package that publishes a site.
+- 985f599: **A package now describes itself once for Foundry and once for the site.** Foundry's package browser wants a pitch — HTML, any length — and a site's `<meta name="description">` wants one plain sentence; deriving both from `package.json`'s `description` forced one string onto both. Declare `packageBuild.manifest.descriptionHtml` in `package-build.config.yaml` for the Foundry pitch (HTML allowed, emitted as the manifest's `description`) and `site.description` for the site's meta description (plain text, required for `content-build site`). `package.json`'s own `description` is read by neither any more — a warning names both keys when one is still declared — and the field can be deleted.
+
 ## 22.1.1
 
 ### Patch Changes

package/bin/package-build.mjs

@@ -334,9 +334,11 @@ async function formatGenerated(text, filepath) {
  * so the system publishes the field sets as data — the same shape the link
  * manifest already uses for addresses.
  *
- * `--check` fails when the committed copy disagrees with what the source would
- * produce now, because a generated file nothing checks drifts from its
- * generator silently — and this one is read by other repositories.
+ * Writes under `build/`, alongside every other generated artifact: a release
+ * publishes it beside the archive and the manifest (see `package-build
+ * release`), and `packageBuild.assets` carries it into the staged tree from
+ * there. There is nothing committed to compare it against, so there is no
+ * `--check`.
  *
  * @returns {object} The yargs command module.
  */
@@ -344,15 +346,8 @@ function schemaCommand() {
     return {
         command: "schema",
         describe: "Publish this package's DataModel field sets as schema.json",
-        builder: (y) =>
-            y.option("check", {
-                type: "boolean",
-                default: false,
-                describe:
-                    "Fail when the committed schema.json is out of date " +
-                    "rather than rewriting it",
-            }),
-        handler: handler(async (argv) => {
+        builder: (y) => y,
+        handler: handler(async () => {
             const config = loadPackageBuildConfig();
             if (!config.schema.length) {
                 console.log(
@@ -369,25 +364,13 @@ function schemaCommand() {
                 version: pkg.version,
             });
 
-            const out = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
+            const out = path.join(config.rootDir, "build", SCHEMA_ARTIFACT_FILE);
             const text = await formatGenerated(JSON.stringify(artifact), out);
             const counts = Object.entries(artifact.documents)
                 .map(([kind, subtypes]) => `${Object.keys(subtypes).length} ${kind}`)
                 .join(", ");
 
-            if (argv.check) {
-                const current = fs.existsSync(out) ? fs.readFileSync(out, "utf8") : null;
-                if (current !== text) {
-                    die(
-                        `${SCHEMA_ARTIFACT_FILE} does not match what this ` +
-                            `package's data models would produce — regenerate ` +
-                            `it with \`package-build schema\`.`,
-                    );
-                }
-                console.log(`✅ ${SCHEMA_ARTIFACT_FILE} is up to date ` + `(${counts} subtypes).`);
-                return;
-            }
-
+            fs.mkdirSync(path.dirname(out), { recursive: true });
             fs.writeFileSync(out, text, "utf8");
             console.log(
                 `✅ Wrote ${SCHEMA_ARTIFACT_FILE} for ${artifact.system} ` +

package/config.mjs

@@ -91,7 +91,7 @@ const SECTION_KEYS = [
 export const DERIVED_MANIFEST_KEYS = Object.freeze({
     id: "`foundryPackage`, itself derived from package.json `name`",
     version: "package.json `version`",
-    description: "package.json `description`",
+    description: "`packageBuild.manifest.descriptionHtml`",
     url: "package.json `repository`",
     bugs: "package.json `repository`",
     manifest: "package.json `repository` and the release tag",
@@ -152,11 +152,16 @@ const ARTIFACT_OF_KIND = Object.freeze({
  * message, so {@link loadPackageBuildConfig} — the half that knows which file
  * was read — can resolve it to a line and column. This half stays pure.
  *
+ * Exported so a sibling module composing a configuration value this module
+ * does not itself validate — {@link module:engine/site-config}'s
+ * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * rather than a second copy.
+ *
  * @param {string} where - Dotted path of the offending key.
  * @param {string} problem - What is wrong with it.
  * @returns {never}
  */
-function fail(where, problem) {
+export function fail(where, problem) {
     throw Object.assign(new TypeError(`package-build config: \`${where}\` ${problem}.`), {
         field: where,
     });

package/content-config.mjs

@@ -759,6 +759,7 @@ const DOCS_KEYS = ["itemFields"];
 const SITE_KEYS = [
     "base",
     "assets",
+    "description",
     "packages",
     "sections",
     "readmeSections",
@@ -1575,6 +1576,33 @@ function normalizeSiteAssets(value) {
     return assets.replace(/\/+$/, "");
 }
 
+/**
+ * The site's `<meta name="description">`, plain text.
+ *
+ * Foundry's package browser wants a pitch — HTML, any length,
+ * `packageBuild.manifest.descriptionHtml` — and a `<meta>` tag wants one
+ * plain sentence. The two audiences are different enough that one string
+ * cannot serve both, so this is the site's own, checked for markup rather
+ * than trusted to carry none: a value with a `<` in it is refused, naming
+ * `descriptionHtml` as where markup belongs.
+ *
+ * @param {unknown} value - The configured value, or `undefined`.
+ * @returns {string} The description; `""` when unset.
+ */
+function normalizeSiteDescription(value) {
+    if (value === undefined) return "";
+    const description = requireNonEmptyString(value, "site.description");
+    if (description.includes("<")) {
+        fail(
+            "site.description",
+            "contains `<` — this is plain text for the site's " +
+                '`<meta name="description">`; markup belongs in ' +
+                "`packageBuild.manifest.descriptionHtml`",
+        );
+    }
+    return description;
+}
+
 /**
  * A map of section name → landing metadata.
  *
@@ -1616,7 +1644,7 @@ export const DERIVED_HUGO_KEYS = Object.freeze({
     disableKinds: "whether any note in the tree carries `tags:`, which the site walk discovers",
     taxonomies: "whether any note in the tree carries `tags:`, which the site walk discovers",
     outputs: "whether any note in the tree carries `tags:`, which the site walk discovers",
-    "params.description": "package.json `description`",
+    "params.description": "`site.description`",
     "params.author": "package.json `author`",
     "params.cdnBaseURL": "`site.assets`",
     "params.brand": "the organisation's brand links, in `engine/site-config.mjs`",
@@ -1739,6 +1767,7 @@ function normalizeSite(value) {
     const empty = Object.freeze({
         base: "",
         assets: "",
+        description: "",
         packages: Object.freeze([]),
         sections: Object.freeze({}),
         readmeSections: Object.freeze({}),
@@ -1807,6 +1836,7 @@ function normalizeSite(value) {
     return Object.freeze({
         base: input.base === undefined ? "" : requireNonEmptyString(input.base, "site.base"),
         assets: normalizeSiteAssets(input.assets),
+        description: normalizeSiteDescription(input.description),
         packages: Object.freeze(packages),
         sections: normalizeSectionMap(input.sections, "site.sections"),
         readmeSections: normalizeSectionMap(input.readmeSections, "site.readmeSections"),

package/docs/api.md

@@ -1290,6 +1290,7 @@ console.log(config.stageDir);
 | `resolvePackageBuildConfig` | `resolvePackageBuildConfig(shared)`       | `Readonly<PackageBuildConfig>` | validating the `packageBuild:` section from an already-loaded shared configuration — the pure half, usable without touching disk                                                |
 | `loadPackageBuildConfig`    | `loadPackageBuildConfig()`                | `Readonly<PackageBuildConfig>` | reading and validating the repository's resolved package-build configuration from disk, read fresh on each call rather than cached at import                                    |
 | `checkHomepage`             | `checkHomepage(homepage, contentPackage)` | `void`                         | validating a resolved `homepage` against `contentPackage` — called by `content-build site` before the generated `baseURL` is written, not by `resolvePackageBuildConfig` itself |
+| `fail`                      | `fail(where, problem)`                    | `never`                        | rejecting a configured value from a sibling module, naming the dotted key path it was written under, so the loader can resolve it to a line and column                          |
 
 ## `./prettier`
 

package/docs/commands.md

@@ -166,7 +166,7 @@ Publish this package's DataModel field sets as `schema.json`.
 **SYNOPSIS**
 
 ```
-package-build schema [--check]
+package-build schema
 ```
 
 **DESCRIPTION**
@@ -174,23 +174,20 @@ package-build schema [--check]
 Publishes the registries named in `packageBuild.schema` as `schema.json`, read
 by `content-build content-format schema` and, in a consuming package, by
 `content-build lint`'s emitted-versus-declared check. A repository that
-declares no registries has nothing to publish. `--check` compares the
-committed file against what the source would produce now instead of
-rewriting it, so CI can gate on the file being current. Reads the registries
-`packageBuild.schema` names; writes (or checks) `schema.json` at the
-repository root.
+declares no registries has nothing to publish. Reads the registries
+`packageBuild.schema` names; writes `build/schema.json`. A release publishes
+it beside the archive and the manifest when `packageBuild.assets` names
+`build/schema.json` (see `package-build release`); a module's
+`content-build deps fetch` keeps the copy from the archive it downloads.
 
 **OPTIONS**
 
-| Option    | Type    | Default | Description                                                                    |
-| --------- | ------- | ------- | ------------------------------------------------------------------------------ |
-| `--check` | boolean | `false` | Fail when the committed `schema.json` is out of date rather than rewriting it. |
+None.
 
 **EXIT STATUS**
 
-1 when `--check` finds the committed file does not match what the source
-would produce. 1 on any other thrown error. Otherwise 0 — including when
-`packageBuild.schema` is empty, which logs and publishes nothing.
+1 on any thrown error. Otherwise 0 — including when `packageBuild.schema` is
+empty, which logs and publishes nothing.
 
 **EXAMPLES**
 
@@ -202,7 +199,7 @@ package-build: no `packageBuild.schema` declared; nothing to publish.
 **SEE ALSO**
 
 `content-build content-format schema`, `content-build lint [root]`,
-[Configuration](configuration.md).
+`package-build release`, [Configuration](configuration.md).
 
 ### `package-build manifest`
 
@@ -670,14 +667,17 @@ package-build release [--no-pdf]
 
 The artifact name comes from `packageKind` — a system ships as
 `system.json`'s sibling, a module as `module.json`'s — so no repository
-states it a second time. When the package publishes content
-(`publish.site: content`), it also builds the content-tree book (see
-`content-build pdf`) and reports it alongside the archive; `--no-pdf` skips
-that step for a release that has a tree but does not want the book this
-time. A book that fails to build is reported, never fatal — the archive
-above is the release regardless. Reads the staged package and (for the book)
-the content tree; writes `<artifact>.zip` and, unless skipped, the book,
-both under `build/dist`.
+states it a second time. It also publishes the content index the manifest
+advertises (`flags.metadataUrl`) and, when the stage carries one,
+`schema.json` — a repository that names `build/schema.json` in
+`packageBuild.assets` gets it released beside the archive; one that does not
+gets none. When the package publishes content (`publish.site: content`), it
+also builds the content-tree book (see `content-build pdf`) and reports it
+alongside the archive; `--no-pdf` skips that step for a release that has a
+tree but does not want the book this time. A book that fails to build is
+reported, never fatal — the archive above is the release regardless. Reads
+the staged package and (for the book) the content tree; writes
+`<artifact>.zip` and, unless skipped, the book, both under `build/dist`.
 
 **OPTIONS**
 
@@ -701,7 +701,7 @@ $ package-build release
 
 **SEE ALSO**
 
-`content-build pdf`, [Configuration](configuration.md).
+`content-build pdf`, `package-build schema`, [Configuration](configuration.md).
 
 ### `package-build deploy <stage>`
 

package/docs/configuration.md

@@ -752,21 +752,22 @@ Any other key under `docs.itemFields` is refused:
 
 **Type:** object · **Optional** · every key defaults to nothing published:
 
-| Key                     | Type     | Default               |
-| ----------------------- | -------- | --------------------- |
-| `site.base`             | string   | `""`                  |
-| `site.assets`           | string   | `""`                  |
-| `site.packages`         | string[] | `[]`                  |
-| `site.sections`         | object   | `{}`                  |
-| `site.readmeSections`   | object   | `{}`                  |
-| `site.landing`          | object   | `null`                |
-| `site.trees`            | array    | `[]`                  |
-| `site.pass`             | string   | `""`                  |
-| `site.passOptions`      | object   | `{}`                  |
-| `site.backfillSections` | boolean  | `false`               |
-| `site.list`             | object   | `{shortcodes: false}` |
-| `site.notfound`         | object   | `null`                |
-| `site.hugo`             | object   | `{}`                  |
+| Key                     | Type     | Default                                     |
+| ----------------------- | -------- | ------------------------------------------- |
+| `site.base`             | string   | `""`                                        |
+| `site.assets`           | string   | `""`, but required for `content-build site` |
+| `site.description`      | string   | `""`, but required for `content-build site` |
+| `site.packages`         | string[] | `[]`                                        |
+| `site.sections`         | object   | `{}`                                        |
+| `site.readmeSections`   | object   | `{}`                                        |
+| `site.landing`          | object   | `null`                                      |
+| `site.trees`            | array    | `[]`                                        |
+| `site.pass`             | string   | `""`                                        |
+| `site.passOptions`      | object   | `{}`                                        |
+| `site.backfillSections` | boolean  | `false`                                     |
+| `site.list`             | object   | `{shortcodes: false}`                       |
+| `site.notfound`         | object   | `null`                                      |
+| `site.hugo`             | object   | `{}`                                        |
 
 How much of a package reaches the web at all is **not** here — it is
 [`publish.site`](#publish). `site` is framing: what a section is called,
@@ -785,7 +786,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, packages, sections, readmeSections, landing, trees, pass, passOptions, backfillSections, list, notfound, hugo).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, sections, readmeSections, landing, trees, pass, passOptions, backfillSections, list, notfound, hugo).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -798,11 +799,30 @@ Absolute, and the trailing slash is trimmed:
 
 > ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
 
+`content-build site` refuses to generate a configuration with no
+`site.assets` at all — there is no defensible default, because the theme
+resolves every relative asset against it:
+
+> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
+
 The generated Hugo configuration carries the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
 The two are one value read by two readers: the toolchain emits it into a
 page, and the theme joins it onto anything the toolchain left relative.
 
+`site.description` is the site's `<meta name="description">` — one plain
+sentence, distinct from the Foundry package browser's pitch
+([`packageBuild.manifest.descriptionHtml`](#packagebuildmanifest), which
+allows HTML). Required for `content-build site`, the way `packageBuild.manifest.title`
+is:
+
+> ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
+
+Markup belongs in `descriptionHtml`, not here — a value containing `<` is
+refused:
+
+> ``package-build config: `site.description` contains `<` — this is plain text for the site's `<meta name="description">`; markup belongs in `packageBuild.manifest.descriptionHtml`.``
+
 `site.packages` names which content packages' notes the site walks, beyond
 this one's own; `site.pass` names a repository's own body-rewrite bundle
 (the one part of the site contract that is code, exactly as `itemBuilders`
@@ -968,9 +988,9 @@ in it has one source, and that source is where it is edited:
 | `disableKinds`                    | whether any note in the tree carries `tags:`, which the site walk discovers: `["taxonomy", "term", "RSS"]` when none does, `["RSS"]` when at least one does |
 | `taxonomies`                      | the same fact — written as `{ tag = "tags" }` when at least one note carries `tags:`, absent otherwise                                                      |
 | `outputs`                         | the same fact — written as `{ taxonomy = ["HTML"], term = ["HTML"] }` when at least one note carries `tags:`, absent otherwise                              |
-| `params.description`              | `package.json` `description`; absent when the package declares none                                                                                         |
+| `params.description`              | `site.description`, which is required                                                                                                                       |
 | `params.author`                   | `package.json` `author`, its `name`; absent when the package declares none                                                                                  |
-| `params.cdnBaseURL`               | `site.assets`; absent when unset                                                                                                                            |
+| `params.cdnBaseURL`               | `site.assets`, which is required                                                                                                                            |
 | `params.brand`                    | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                           |
 | `params.list`                     | `site.list`                                                                                                                                                 |
 | `params.notfound`                 | `site.notfound`; absent when undeclared                                                                                                                     |
@@ -991,6 +1011,17 @@ none fails the site build:
 
 > ``package-build config: `packageBuild.manifest.title` is not declared, and the site's `title` reads from it.``
 
+`params.description` reads from `site.description` the same way, and fails
+the same way when it is absent:
+
+> ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
+
+`params.cdnBaseURL` reads from `site.assets`, and the theme resolves every
+relative asset against it, so a configuration declaring none fails the site
+build the same way:
+
+> ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
+
 Nothing else is emitted. A site whose notes carry no `tags:` publishes no
 taxonomy pages — `[taxonomies]` and `[outputs]` go unwritten, and Hugo's
 defaults never apply because `taxonomy` and `term` are disabled kinds. A site
@@ -1436,11 +1467,22 @@ that has a wrong answer rather than an unknown one: a key the build
 silently overwritten and the two would be free to disagree with nothing to
 say so.
 
+`packageBuild.manifest.descriptionHtml` is the exception worth calling out on
+its own: it is not forbidden, it **is** how `description` is authored. It is
+the pitch Foundry's package browser shows — HTML allowed, any length — and it
+is emitted into the generated manifest as `description`; the key itself never
+survives into the manifest under its own name. `package.json`'s own
+`description` is read by neither this nor the site (see
+[`site.description`](#site)) — a declared one is reported as a warning naming
+both real keys, so it cannot drift back into use:
+
+> `package.json: warning: \`description\` is read by nothing; the Foundry pitch is \`packageBuild.manifest.descriptionHtml\` and the site's is \`site.description\`` — a JSON manifest carries no line to point at, so only the file is named.
+
 | Forbidden key                         | Derived from                                                     |
 | ------------------------------------- | ---------------------------------------------------------------- |
 | `packageBuild.manifest.id`            | `foundryPackage`, itself derived from `package.json` `name`      |
 | `packageBuild.manifest.version`       | `package.json` `version`                                         |
-| `packageBuild.manifest.description`   | `package.json` `description`                                     |
+| `packageBuild.manifest.description`   | `packageBuild.manifest.descriptionHtml`                          |
 | `packageBuild.manifest.url`           | `package.json` `repository`                                      |
 | `packageBuild.manifest.bugs`          | `package.json` `repository`                                      |
 | `packageBuild.manifest.manifest`      | `package.json` `repository` and the release tag                  |
@@ -1451,7 +1493,7 @@ say so.
 
 > ``package-build config: `packageBuild.manifest.version` is derived from package.json `version` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
 
-> ``package-build config: `packageBuild.manifest.description` is derived from package.json `description` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
+> ``package-build config: `packageBuild.manifest.description` is derived from `packageBuild.manifest.descriptionHtml` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
 
 > ``package-build config: `packageBuild.manifest` must be a mapping.``
 

package/engine/pack-config.mjs

@@ -570,9 +570,22 @@ export function configFromData(data, configPath) {
             );
         }
     }
-    const { pkg } = readPackageJson(rootDir);
+    const { manifestPath, pkg } = readPackageJson(rootDir);
     if (pkg.homepage !== undefined) input.homepage = pkg.homepage;
     if (pkg.author !== undefined) input.author = pkg.author;
+    // `description` is npm metadata nothing displays for a private package —
+    // read by neither the manifest nor the site, so a declared one is a
+    // warning rather than a silent no-op that looks like it did something.
+    if (pkg.description !== undefined) {
+        emitDiagnostic({
+            file: manifestPath,
+            severity: "warning",
+            message:
+                "`description` is read by nothing; the Foundry pitch is " +
+                "`packageBuild.manifest.descriptionHtml` and the site's is " +
+                "`site.description`",
+        });
+    }
 
     if (input.itemBuilders !== undefined) {
         const declared = input.itemBuilders;

package/engine/schema-check.mjs

@@ -466,8 +466,8 @@ export function compareEmittedSystem({
  * Two places to find it, because a system checks itself against source it owns
  * while a module checks against a dependency it fetched:
  *
- * - **A system**: its own `schema.json`, generated from its `src/` and
- *   committed beside it.
+ * - **A system**: its own `schema.json`, generated from its `src/` into
+ *   `build/` by `package-build schema`.
  * - **A module**: the copy cached by `content-build deps fetch`, from the
  *   archive of the version it pins — which is what makes the comparison happen
  *   at `verified` rather than against whatever the system's `main` holds today.
@@ -505,7 +505,7 @@ export function resolveSchemaArtifact(config, system = undefined) {
 
     // The system checking itself, against the schema its own build published.
     if (config.packageKind === "systems" && config.foundryPackage === systemId) {
-        const own = path.join(config.rootDir, SCHEMA_ARTIFACT_FILE);
+        const own = path.join(config.rootDir, "build", SCHEMA_ARTIFACT_FILE);
         return fs.existsSync(own) ? read(own) : null;
     }
 
@@ -683,9 +683,9 @@ export function checkAuthoredSystemData(
  * subtype declares.
  *
  * The build-time face of {@link compareEmittedSystem}: it resolves the schema
- * the way every other check here does — the system's own committed artifact, or
- * the cached one from the release a module pins — and attaches the message a
- * reader sees.
+ * the way every other check here does — the system's own published artifact,
+ * or the cached one from the release a module pins — and attaches the message
+ * a reader sees.
  *
  * **Silent where there is nothing to check against**, exactly as its two
  * siblings are: a module pinning a system version released before the artifact

package/engine/site-config.mjs

@@ -44,7 +44,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { stringify as stringifyToml } from "smol-toml";
 
-import { checkHomepage } from "../config.mjs";
+import { checkHomepage, fail } from "../config.mjs";
 import { slugify } from "./content-slug.mjs";
 
 /** The Hugo source directory, relative to the repository root. */
@@ -381,7 +381,6 @@ function deepMerge(base, overrides) {
  *
  * @param {object} options - The sources.
  * @param {object} options.config - The resolved build configuration.
- * @param {string} [options.description] - `package.json`'s `description`.
  * @param {readonly NavigationEntry[]} options.navigation - The navigation.
  * @param {string} options.themesDir - From {@link resolveThemesDir}.
  * @param {boolean} [options.hasTags] - Whether any note the site build walked
@@ -389,9 +388,10 @@ function deepMerge(base, overrides) {
  *   `hasTags`. Defaults to `false` — no tagged note, no taxonomy pages.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
- *   configuration declares no `packageBuild.manifest.title`.
+ *   configuration declares no `packageBuild.manifest.title`, no
+ *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, description, navigation, themesDir, hasTags = false }) {
+export function hugoConfig({ config, navigation, themesDir, hasTags = false }) {
     checkHomepage(config.homepage, config.contentPackage);
 
     const title = config.packageBuild?.manifest?.title;
@@ -401,10 +401,23 @@ export function hugoConfig({ config, description, navigation, themesDir, hasTags
                 "and the site's `title` reads from it.",
         );
     }
+    if (!config.site.description) {
+        fail(
+            "site.description",
+            'is not declared, and the site\'s `<meta name="description">` reads from it',
+        );
+    }
+    if (!config.site.assets) {
+        fail(
+            "site.assets",
+            "is not declared, and a site build needs one — it is the host every " +
+                "package's imagery is served from, and the theme resolves every " +
+                "relative asset against it",
+        );
+    }
 
     /** @type {Record<string, unknown>} */
-    const params = {};
-    if (typeof description === "string" && description.trim()) params.description = description;
+    const params = { description: config.site.description };
     if (config.author?.name) params.author = config.author.name;
     if (config.site.assets) params.cdnBaseURL = config.site.assets;
     params.brand = { ...BRAND };
@@ -449,24 +462,12 @@ export function hugoToml(generated) {
     );
 }
 
-/**
- * `package.json`'s `description`, or `undefined` when it declares none.
- *
- * @param {string} rootDir - The repository root.
- * @returns {string|undefined} The description.
- */
-function packageDescription(rootDir) {
-    const pkg = JSON.parse(fs.readFileSync(path.join(rootDir, "package.json"), "utf8"));
-    return typeof pkg.description === "string" ? pkg.description : undefined;
-}
-
 /**
  * The Hugo configuration, every source read from the repository.
  *
- * Reads `package.json`, the cached navigation and the installed theme's
- * location, and composes them with {@link hugoConfig}. Nothing is written, so
- * a caller can run this before touching the output tree and fail with it
- * intact.
+ * Reads the cached navigation and the installed theme's location, and
+ * composes them with {@link hugoConfig}. Nothing is written, so a caller can
+ * run this before touching the output tree and fail with it intact.
  *
  * @param {object} config - The resolved build configuration.
  * @param {object} [options] - Options.
@@ -480,7 +481,6 @@ function packageDescription(rootDir) {
 export function generateHugoConfig(config, { hasTags = false } = {}) {
     return hugoConfig({
         config,
-        description: packageDescription(config.rootDir),
         navigation: readCachedNavigation(config),
         themesDir: resolveThemesDir(config.rootDir),
         hasTags,

package/manifest.mjs

@@ -28,10 +28,12 @@
  *
  * - **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 description, 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.
+ *   `descriptionHtml` is the one exception, folded into the derived
+ *   `description` below rather than surviving under its own name.
+ * - **Derived** — the identity, the description (from `descriptionHtml`), the
+ *   version, the release addresses, the compatibility ranges and the pack
+ *   list. Declaring `description` directly 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
@@ -459,11 +461,13 @@ function withoutBuildKeys(entry) {
  * 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.
+ *   a key Foundry adds later needs no release of this package. The one
+ *   exception is `descriptionHtml`, folded into the description below rather
+ *   than surviving under its own name.
  * - **Derived** — the identity, the description, 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.
+ *   These are refused if also declared (`description` directly; `descriptionHtml`
+ *   is how it is authored) and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *
@@ -479,7 +483,9 @@ function withoutBuildKeys(entry) {
  * @returns {object} The manifest, ready to serialise.
  */
 export function buildManifest({ config, packageJson, artifact, flags }) {
-    const declared = config.packageBuild?.manifest ?? {};
+    // `descriptionHtml` is the authored source of `description` — pulled out
+    // so it never survives the spread below under its own name.
+    const { descriptionHtml, ...declared } = config.packageBuild?.manifest ?? {};
     const repoUrl = normalizeRepoUrl(packageJson.repository);
 
     const derived = {
@@ -495,8 +501,8 @@ export function buildManifest({ config, packageJson, artifact, flags }) {
     };
     // Own-property presence, not just value, decides whether a key survives
     // into `ordered` below — an explicit `undefined` would still occupy a slot
-    // in it. Set only when `package.json` actually declares one.
-    if (packageJson.description !== undefined) derived.description = packageJson.description;
+    // in it. Set only when the repository actually declares one.
+    if (descriptionHtml !== undefined) derived.description = descriptionHtml;
     if (config.compatibility) derived.compatibility = config.compatibility;
 
     // `requiresSystem` is the gate half of the declare/require split. It

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.1.1",
+    "version": "22.2.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/release.mjs

@@ -13,7 +13,7 @@
 
 /**
  * The release archive — the two files a Foundry package's GitHub Release
- * carries.
+ * carries, plus the optional siblings a repository opts into.
  *
  * Foundry installs a package by fetching the `download` URL its manifest
  * advertises, so a release publishes `<artifact>.zip`, the whole staged tree,
@@ -21,7 +21,10 @@
  * re-fetches to notice a new version. A package that ships content publishes a
  * third: the content index other packages resolve its addresses through,
  * named by the `flags.metadataUrl` the manifest advertises. Every name is fixed
- * by what the manifest says, not chosen here — see `manifest.mjs`.
+ * by what the manifest says, not chosen here — see `manifest.mjs`. A package
+ * that publishes a DataModel schema (`packageBuild.schema`, staged through
+ * `packageBuild.assets`) gets a fourth: `schema.json`, published whenever the
+ * stage carries one and silently skipped otherwise.
  *
  * Kept apart from `stage.mjs` because this is the only part of assembling a
  * package that needs a dependency. A repository that never cuts a release from
@@ -40,6 +43,8 @@ import path from "node:path";
 // release job came to fail before a single byte was written.
 import { ZipArchive } from "archiver";
 
+import { SCHEMA_ARTIFACT_FILE } from "./engine/foreign-catalog.mjs";
+
 /**
  * Zip the staged tree and place the manifest beside the archive.
  *
@@ -60,14 +65,14 @@ import { ZipArchive } from "archiver";
  * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
  *   bytes: number, version: string}>} The paths written, what the book build
  *   found, the archive's size, and the version the manifest declares.
- *   `metadata` is absent when the manifest advertises no content index, and
- *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
- *   book was built, and otherwise the reason none was — itself `null` when the
- *   book builder could not be loaded, which is reported through
- *   `pdfFindings`.
+ *   `metadata` is absent when the manifest advertises no content index,
+ *   `schema` is absent when the stage carries no `schema.json`, and `pdf` is
+ *   absent when no book was written. `pdfSkipped` is `null` when a book was
+ *   built, and otherwise the reason none was — itself `null` when the book
+ *   builder could not be loaded, which is reported through `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -119,6 +124,7 @@ export async function packRelease({
     await fsp.copyFile(stagedManifest, path.join(out, manifestName));
 
     const metadata = await publishMetadataIndex({ manifest, stage, out, metadataDir });
+    const schema = await publishSchemaAsset({ stage, out });
 
     // Last, and never fatal: the archive and the manifest are the release, and
     // a book that failed to set is a reported problem rather than a reason to
@@ -132,6 +138,7 @@ export async function packRelease({
         zip: zipPath,
         manifest: path.join(out, manifestName),
         ...(metadata ? { metadata } : {}),
+        ...(schema ? { schema } : {}),
         ...(book.pdf ? { pdf: book.pdf } : {}),
         pdfFindings: book.findings,
         pdfSkipped: book.pdf ? null : book.reason,
@@ -226,3 +233,29 @@ async function publishMetadataIndex({ manifest, stage, out, metadataDir }) {
     await fsp.copyFile(found, dest);
     return dest;
 }
+
+/**
+ * Place the published DataModel schema beside the archive, when the stage
+ * carries one.
+ *
+ * **The stage is the one place this looks.** `package-build schema` writes
+ * `build/schema.json`, and a repository that wants it released names it in
+ * `packageBuild.assets` (`from: build/schema.json`) the way every other
+ * staged file is declared — so a schema at the stage root is a repository
+ * that opted in, and its absence is a repository that has not, which is
+ * exactly as releasable as one that never adopted the artifact at all.
+ *
+ * @param {object} opts
+ * @param {string} opts.stage - The staged tree.
+ * @param {string} opts.out - Where release assets are written.
+ * @returns {Promise<string|undefined>} The published path, or nothing when
+ *   the stage carries no `schema.json`.
+ */
+async function publishSchemaAsset({ stage, out }) {
+    const src = path.join(stage, SCHEMA_ARTIFACT_FILE);
+    if (!fs.existsSync(src)) return undefined;
+
+    const dest = path.join(out, SCHEMA_ARTIFACT_FILE);
+    await fsp.copyFile(src, dest);
+    return dest;
+}

package/types/config.d.mts

@@ -1,3 +1,20 @@
+/**
+ * Reject a configured value, naming the key it was written under.
+ *
+ * The dotted path rides on the error as `field` as well as appearing in the
+ * message, so {@link loadPackageBuildConfig} — the half that knows which file
+ * was read — can resolve it to a line and column. This half stays pure.
+ *
+ * Exported so a sibling module composing a configuration value this module
+ * does not itself validate — {@link module:engine/site-config}'s
+ * `hugoConfig`, checking `site.assets` — reports through the one helper
+ * rather than a second copy.
+ *
+ * @param {string} where - Dotted path of the offending key.
+ * @param {string} problem - What is wrong with it.
+ * @returns {never}
+ */
+export function fail(where: string, problem: string): never;
 /**
  * Where a declared `assetTransform` is loaded from.
  *

package/types/engine/schema-check.d.mts

@@ -157,8 +157,8 @@ export function compareEmittedSystem({ system, artifact, documentType, subtype,
  * Two places to find it, because a system checks itself against source it owns
  * while a module checks against a dependency it fetched:
  *
- * - **A system**: its own `schema.json`, generated from its `src/` and
- *   committed beside it.
+ * - **A system**: its own `schema.json`, generated from its `src/` into
+ *   `build/` by `package-build schema`.
  * - **A module**: the copy cached by `content-build deps fetch`, from the
  *   archive of the version it pins — which is what makes the comparison happen
  *   at `verified` rather than against whatever the system's `main` holds today.
@@ -282,9 +282,9 @@ export function checkAuthoredSystemData(fm: object, { block, documentType, subTy
  * subtype declares.
  *
  * The build-time face of {@link compareEmittedSystem}: it resolves the schema
- * the way every other check here does — the system's own committed artifact, or
- * the cached one from the release a module pins — and attaches the message a
- * reader sees.
+ * the way every other check here does — the system's own published artifact,
+ * or the cached one from the release a module pins — and attaches the message
+ * a reader sees.
  *
  * **Silent where there is nothing to check against**, exactly as its two
  * siblings are: a module pinning a system version released before the artifact

package/types/engine/site-config.d.mts

@@ -89,7 +89,6 @@ export function resolveThemesDir(rootDir: string): string;
  *
  * @param {object} options - The sources.
  * @param {object} options.config - The resolved build configuration.
- * @param {string} [options.description] - `package.json`'s `description`.
  * @param {readonly NavigationEntry[]} options.navigation - The navigation.
  * @param {string} options.themesDir - From {@link resolveThemesDir}.
  * @param {boolean} [options.hasTags] - Whether any note the site build walked
@@ -97,11 +96,11 @@ export function resolveThemesDir(rootDir: string): string;
  *   `hasTags`. Defaults to `false` — no tagged note, no taxonomy pages.
  * @returns {Record<string, any>} The configuration Hugo reads.
  * @throws {TypeError} When `homepage` fails `checkHomepage`, or the
- *   configuration declares no `packageBuild.manifest.title`.
+ *   configuration declares no `packageBuild.manifest.title`, no
+ *   `site.description`, or no `site.assets`.
  */
-export function hugoConfig({ config, description, navigation, themesDir, hasTags }: {
+export function hugoConfig({ config, navigation, themesDir, hasTags }: {
     config: object;
-    description?: string | undefined;
     navigation: readonly NavigationEntry[];
     themesDir: string;
     hasTags?: boolean | undefined;
@@ -116,10 +115,9 @@ export function hugoToml(generated: Record<string, unknown>): string;
 /**
  * The Hugo configuration, every source read from the repository.
  *
- * Reads `package.json`, the cached navigation and the installed theme's
- * location, and composes them with {@link hugoConfig}. Nothing is written, so
- * a caller can run this before touching the output tree and fail with it
- * intact.
+ * Reads the cached navigation and the installed theme's location, and
+ * composes them with {@link hugoConfig}. Nothing is written, so a caller can
+ * run this before touching the output tree and fail with it intact.
  *
  * @param {object} config - The resolved build configuration.
  * @param {object} [options] - Options.

package/types/manifest.d.mts

@@ -187,11 +187,13 @@ export function publishedRelationships(relationships: Record<string, unknown>):
  * 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.
+ *   a key Foundry adds later needs no release of this package. The one
+ *   exception is `descriptionHtml`, folded into the description below rather
+ *   than surviving under its own name.
  * - **Derived** — the identity, the description, 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.
+ *   These are refused if also declared (`description` directly; `descriptionHtml`
+ *   is how it is authored) and the two would disagree with nothing to say so.
  * - **Computed** — namespaced `flags` a repository works out for itself, merged
  *   over any it declared.
  *

package/types/release.d.mts

@@ -18,14 +18,14 @@
  * @param {boolean} [opts.pdf] - Whether to build the book that ships beside the
  *   archive. `true` by default; `false` skips the build and reports the skip.
  * @returns {Promise<{zip: string, manifest: string, metadata?: string,
- *   pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
+ *   schema?: string, pdf?: string, pdfFindings: object[], pdfSkipped: string|null,
  *   bytes: number, version: string}>} The paths written, what the book build
  *   found, the archive's size, and the version the manifest declares.
- *   `metadata` is absent when the manifest advertises no content index, and
- *   `pdf` is absent when no book was written. `pdfSkipped` is `null` when a
- *   book was built, and otherwise the reason none was — itself `null` when the
- *   book builder could not be loaded, which is reported through
- *   `pdfFindings`.
+ *   `metadata` is absent when the manifest advertises no content index,
+ *   `schema` is absent when the stage carries no `schema.json`, and `pdf` is
+ *   absent when no book was written. `pdfSkipped` is `null` when a book was
+ *   built, and otherwise the reason none was — itself `null` when the book
+ *   builder could not be loaded, which is reported through `pdfFindings`.
  * @throws {Error} When the stage has no manifest — there is nothing to release,
  *   and an archive without one installs as nothing.
  */
@@ -39,6 +39,7 @@ export function packRelease({ stageDir, outDir, artifact, metadataDir, pdf, }?:
     zip: string;
     manifest: string;
     metadata?: string;
+    schema?: string;
     pdf?: string;
     pdfFindings: object[];
     pdfSkipped: string | null;