@heroiclands/package-build 22.15.1 → 22.16.0

package/markdownlint-config.mjs

@@ -14,7 +14,7 @@
 /**
  * The shared markdownlint rules, as a markdownlint-cli2 options module.
  *
- * `content-build markdown` applies these without a consumer declaring
+ * `package-build markdown` applies these without a consumer declaring
  * anything; this is for an editor's markdownlint extension, and for a consumer
  * that wants to *extend* the set rather than replace it:
  *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.15.1",
+    "version": "22.16.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",
@@ -95,13 +95,11 @@
         "./package.json": "./package.json"
     },
     "bin": {
-        "package-build": "./bin/package-build.mjs",
-        "content-build": "./bin/content-build.mjs"
+        "package-build": "./bin/package-build.mjs"
     },
     "files": [
         "CHANGELOG-content-build.md",
         "CHANGELOG.md",
-        "CONTENT.md",
         "README.md",
         "assets",
         "packagebuild-metadata.jsonl",
@@ -149,18 +147,30 @@
         "loglevel": "^1.9.2",
         "loglevel-plugin-prefix": "^0.8.4",
         "markdown-it": "^15.0.0",
+        "markdown-it-deflist": "^4.0.0",
+        "markdown-it-footnote": "^4.0.0",
         "markdownlint-cli2": "^0.23.3",
         "pagefind": "^1.5.2",
         "prettier": "^3.9.6",
+        "remark-frontmatter": "^5.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-retext": "^6.0.1",
+        "retext-english": "^5.0.0",
+        "retext-readability": "^8.0.0",
+        "retext-simplify": "^8.0.0",
+        "retext-stringify": "^4.0.0",
+        "sharp": "^0.35.4",
         "smol-toml": "^1.8.0",
         "ssh2-sftp-client": "^12.1.1",
         "typescript": "^6.0.3",
         "unidecode": "^1.1.0",
+        "unified": "^11.0.5",
         "yaml": "^2.8.1",
         "yargs": "^18.1.0"
     },
     "devDependencies": {
         "@changesets/cli": "^3.0.0",
+        "@heroiclands/hugo-theme": "^0.9.0",
         "@types/node": "^26.2.0",
         "npm-run-all": "^4.1.5",
         "vitest": "^5.0.0"
@@ -174,16 +184,26 @@
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:labels lint:content-format",
-        "lint:markdown": "node bin/content-build.mjs markdown",
+        "lint:markdown": "node bin/package-build.mjs markdown",
         "lint:yaml": "node bin/package-build.mjs yaml",
         "lint:labels": "node bin/package-build.mjs labels check",
-        "lint:markdown:fix": "node bin/content-build.mjs markdown --fix",
-        "lint:content-format": "npm run lint:content-format:schema && npm run lint:content-format:fields",
-        "lint:content-format:schema": "node bin/content-build.mjs content-format schema --schema sohl=tests/fixtures/content-format/schema-sohl.json --schema hm3=tests/fixtures/content-format/schema-hm3.json",
-        "lint:content-format:fields": "node bin/content-build.mjs content-format fields --fields sohl && node bin/content-build.mjs content-format fields --fields hm3",
+        "lint:markdown:fix": "node bin/package-build.mjs markdown --fix",
+        "lint:content-format": "npm run lint:content-format:schema && npm run lint:content-format:fields && node ci/content-format-reference.mjs --check",
+        "lint:content-format:schema": "node bin/package-build.mjs content-format schema --schema sohl=tests/fixtures/content-format/schema-sohl.json --schema hm3=tests/fixtures/content-format/schema-hm3.json",
+        "lint:content-format:fields": "node bin/package-build.mjs content-format fields --fields sohl && node bin/package-build.mjs content-format fields --fields hm3",
         "changeset": "changeset",
         "changeset:version": "changeset version && node bin/package-build.mjs changelog group && npm install --package-lock-only",
-        "prepare": "git config core.hooksPath .githooks || true"
+        "prepare": "git config core.hooksPath .githooks || true",
+        "build:deps": "node bin/package-build.mjs deps fetch",
+        "build:content-index": "node bin/package-build.mjs content-index",
+        "build:site-content": "node bin/package-build.mjs site",
+        "build:site-html": "hugo --source build/hugo --minify --gc --cleanDestinationDir",
+        "build:site-root": "node bin/package-build.mjs site-root",
+        "build:site": "run-s build:deps build:content-index build:site-content build:site-html build:site-root",
+        "build:book": "run-s build:deps build:content-index build:book-content",
+        "build:book-content": "node bin/package-build.mjs pdf",
+        "serve:site": "run-s build:deps build:content-index build:site-content serve:site-html",
+        "serve:site-html": "hugo server --source build/hugo"
     },
     "engines": {
         "node": ">=24.0.0"
@@ -204,5 +224,6 @@
         "heroiclands",
         "sohl",
         "song-of-heroic-lands"
-    ]
+    ],
+    "homepage": "https://github.com/HeroicLands/package-build#documentation"
 }

package/prettier-config.mjs

@@ -14,7 +14,7 @@
 /**
  * The shared Prettier configuration, as a Prettier config module.
  *
- * `content-build format` already applies these rules without a consumer
+ * `package-build format` already applies these rules without a consumer
  * declaring anything, so this exists for the **editor**: a format-on-save that
  * disagrees with the lint chain is a papercut every contributor hits, and
  * Prettier's editor integrations read a config file rather than asking this

package/sohl/being-info.mjs

@@ -11,42 +11,10 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
-/**
- * **A being's info-block fields**, derived from the items it embeds.
- *
- * A `being` note carries its embedded documents as `sohl.items` — a flat list
- * of `{ shortcode, type, system? }` — but the shared theme's sidebar reads
- * *resolved* shapes: a `skills` map, `gear` grouped by kind, and `spells` /
- * `talents` split out of the mystical abilities. This is the translation
- * between the two, and it is SoHL data-model knowledge: which item type is a
- * skill, where a mastery level lives, what distinguishes a spell from a talent.
- *
- * **It lives here because it was living in two places.** Both
- * `Song-of-Heroic-Lands-FoundryVTT` and `sohl-thalorna` carried a copy, and the
- * copies drifted: SoHL's caller still gated the derivation on `character` and
- * `creature`, the two legacy spellings of `being`, so it had matched
- * nothing since the merge and all 95 of its being pages published with empty
- * sidebar sections. thalorna's copy checked `being` and was right.
- * Nothing failed in either repository; the pages built and shipped.
- *
- * {@link isBeing} exists for that reason. The bug was not in the derivation —
- * it was in each caller's idea of what a being *is*, written out per repository
- * where it could rot independently. One definition, imported.
- *
- * @module
- */
-
-// The retirement window for a renamed note type: an embedded reference
-// still spelling `armorgear` names the same gear group as `armor`.
-import { currentType } from "../engine/ids.mjs";
+/** Shared being type and gear groups used by the SoHL infobox. @module */
 
 /**
- * The note `type` whose pages carry a being info block.
- *
- * One name: `character` and `creature` are the `being` they
- * had always compiled into. The retired names are deliberately **not** accepted
- * as aliases: they throw elsewhere in the system, and tolerating them here
- * would hide the next drift of this kind rather than surface it.
+ * The note type for a being.
  */
 export const BEING_TYPE = "being";
 
@@ -61,16 +29,7 @@ export function isBeing(fm) {
 }
 
 /**
- * The sidebar group each gear item type is displayed under.
- *
- * Presentation naming, not data-model naming: the note type says `weapongear`,
- * the sidebar heading says "weapons". Kept as one table so a new gear type is
- * added in a single place rather than in each consumer's site build.
- *
- * Keyed by **note** type, which is what a being's embedded `(type, shortcode)`
- * references spell — and three of those are not the document
- * subtype they compile into. A reference still on a renamed spelling is
- * normalised at the lookup below rather than given a second row here.
+ * The infobox group displayed for each gear note type.
  *
  * @type {Readonly<Record<string, string>>}
  */
@@ -82,104 +41,3 @@ export const GEAR_TYPE_TO_KEY = Object.freeze({
     containergear: "containers",
     concoctiongear: "concoctions",
 });
-
-/** Whether a value is a plain mapping. */
-const isMap = (v) => Boolean(v) && typeof v === "object" && !Array.isArray(v);
-
-/** Whether a value is a non-empty array. */
-const nonEmpty = (v) => Array.isArray(v) && v.length > 0;
-
-/**
- * Derive a being's info-block fields from its raw `sohl.items[]`.
- *
- * Each item's `shortcode` is resolved against `index` — keyed
- * `"<type>:<shortcode>"` — for a display name and a link to the item's own
- * page. `attributes` already match the sidebar shape and pass through
- * untouched.
- *
- * **Authored values win.** Only fields the author did not supply are derived,
- * so a note that hand-writes `sohl.skills` keeps exactly what it wrote. An
- * item's inline `name` beats the index, and an unresolved shortcode falls back
- * to *itself* rather than being dropped — a page that names an item the index
- * has not heard of is better than a page silently missing a row.
- *
- * Returns a new object; the input is not mutated.
- *
- * @param {object|null|undefined} sohl - The note's `sohl` frontmatter block.
- * @param {Map<string, {name?: string, url?: string}>} index - Content index,
- *   `"<type>:<shortcode>"` → the item's page.
- * @returns {object|null} The block with its info-block fields filled in, or the
- *   input unchanged when there is nothing to derive from — with an absent block
- *   reported as `null`, the value an empty one already carries.
- */
-export function deriveBeingInfo(sohl, index) {
-    // A note declaring no `sohl:` key at all arrives as `undefined`, and the
-    // site emitter assigns this result straight into a page's front matter.
-    // js-yaml refuses to dump a property whose value is `undefined`, and the
-    // throw aborts the whole build rather than the one page — so "no block"
-    // is answered with the same `null` an empty block gets.
-    if (!isMap(sohl)) return sohl ?? null;
-    const out = { ...sohl };
-    const items = Array.isArray(out.items) ? out.items : [];
-    if (items.length === 0) return out;
-
-    const lookup = (type, shortcode) => (shortcode ? index.get(`${type}:${shortcode}`) : undefined);
-
-    /** An item's display name: its own, then the index's, then its shortcode. */
-    const displayName = (it, ref, shortcode) =>
-        (typeof it.name === "string" && it.name) || ref?.name || shortcode;
-
-    // Skills: { shortcode: masteryLevelBase }.
-    if (!(isMap(out.skills) && Object.keys(out.skills).length > 0)) {
-        const skills = {};
-        for (const it of items) {
-            if (!isMap(it) || it.type !== "skill") continue;
-            const level = it.system?.masteryLevelBase;
-            if (typeof it.shortcode === "string" && typeof level === "number") {
-                skills[it.shortcode] = level;
-            }
-        }
-        if (Object.keys(skills).length > 0) out.skills = skills;
-    }
-
-    // Gear: { weapons: [{ name, shortcode?, url? }], armor: [...], … }.
-    if (!isMap(out.gear)) {
-        const gear = {};
-        for (const it of items) {
-            if (!isMap(it)) continue;
-            const key = GEAR_TYPE_TO_KEY[currentType(it.type)];
-            if (!key) continue;
-            const shortcode = typeof it.shortcode === "string" ? it.shortcode : undefined;
-            const ref = lookup(it.type, shortcode);
-            const name = displayName(it, ref, shortcode);
-            if (!name) continue;
-            const entry = { name };
-            if (shortcode) entry.shortcode = shortcode;
-            if (ref?.url) entry.url = ref.url;
-            (gear[key] ??= []).push(entry);
-        }
-        if (Object.keys(gear).length > 0) out.gear = gear;
-    }
-
-    // Mystical abilities, split by subType into spells / talents.
-    const spells = [];
-    const talents = [];
-    for (const it of items) {
-        if (!isMap(it) || it.type !== "mysticalability") continue;
-        const shortcode = typeof it.shortcode === "string" ? it.shortcode : undefined;
-        const ref = lookup("mysticalability", shortcode);
-        // No shortcode fallback here: an ability with neither an inline name
-        // nor an index entry has nothing to show, and a row reading like a
-        // shortcode is worse than no row.
-        const name = (typeof it.name === "string" && it.name) || ref?.name;
-        if (!name) continue;
-        const entry = { name };
-        if (ref?.url) entry.url = ref.url;
-        if (it.subType === "arcaneincantation") spells.push(entry);
-        else if (it.subType === "arcanetalent") talents.push(entry);
-    }
-    if (spells.length > 0 && !nonEmpty(out.spells)) out.spells = spells;
-    if (talents.length > 0 && !nonEmpty(out.talents)) out.talents = talents;
-
-    return out;
-}

package/sohl/index.mjs

@@ -53,4 +53,4 @@ export * as infobox from "./infobox.mjs";
 // compilers arrived.
 export { DEFAULT_ITEM_ART, defaultItemArt } from "./default-item-art.mjs";
 export { AFFILIATION_STANDINGS } from "./affiliation-standings.mjs";
-export { BEING_TYPE, GEAR_TYPE_TO_KEY, deriveBeingInfo, isBeing } from "./being-info.mjs";
+export { BEING_TYPE, GEAR_TYPE_TO_KEY, isBeing } from "./being-info.mjs";

package/sohl/infobox.mjs

@@ -148,6 +148,7 @@ export const SOHL_FIELD_PRESENTATION = Object.freeze({
     improveFlag: Object.freeze({
         withheld: "character-sheet machinery — whether the item is flagged for improvement",
     }),
+    "trauma.treatmentModifierBase": Object.freeze({ label: "Treatment modifier" }),
     facing: Object.freeze({
         withheld: "a body-location layout, which has no summary shape",
     }),
@@ -312,7 +313,7 @@ function itemValue(item, resolve, block) {
  * sparse creature's box short rather than mostly empty.
  *
  * @param {object} fm - The note's frontmatter.
- * @param {object} ctx - `{ block, resolve }`.
+ * @param {{block: string, resolve?: Function}} ctx - Rendering context.
  * @returns {object[]} The sections.
  */
 export function beingSections(fm, { block, resolve }) {

package/sohl/item-builders.mjs

@@ -49,31 +49,8 @@
 import { defaultItemArt } from "./default-item-art.mjs";
 import { documentSubtype } from "../engine/document-subtypes.mjs";
 import { SOHL_DOCUMENT_SUBTYPES } from "./document-subtypes.mjs";
-import { buildFromFields, readField } from "../engine/field-spec.mjs";
-import { COMBAT_TECHNIQUE_STRIKE_MODE, ITEM_FIELDS } from "./item-fields.mjs";
-
-/**
- * The conditionals a flat field list cannot state, keyed by item type.
- *
- * A finalizer runs after the declaration has produced the `system` block, and
- * exists only for a field whose *presence* depends on another field's value.
- * There is exactly one: a combat technique is authored as a `skill` of subtype
- * `combattechnique`, and carries a strike mode that no other skill has.
- *
- * Keeping this list short is the point. Anything expressible as a field
- * declaration is said there, where a generator and a linter can read it; a
- * finalizer is opaque again, so it earns its place one conditional at a time.
- *
- * @type {Readonly<Record<string, (fm: object, out: object) => object>>}
- */
-const FINALIZERS = Object.freeze({
-    skill(fm, out) {
-        if (out.subType === "combattechnique") {
-            out.strikeMode = readField(COMBAT_TECHNIQUE_STRIKE_MODE, fm);
-        }
-        return out;
-    },
-});
+import { buildFromFields } from "../engine/field-spec.mjs";
+import { ITEM_FIELDS } from "./item-fields.mjs";
 
 /**
  * Build one registry entry: the declared fields, the builder they generate, and
@@ -102,9 +79,8 @@ const FINALIZERS = Object.freeze({
 function entryFor(type) {
     const fields = ITEM_FIELDS[type];
     const build = buildFromFields(fields);
-    const finalize = FINALIZERS[type];
     return Object.freeze({
-        system: finalize ? (fm) => finalize(fm, build(fm)) : build,
+        system: build,
         img: defaultItemArt(documentSubtype(SOHL_DOCUMENT_SUBTYPES, type, {}) ?? type),
         fields,
     });

package/sohl/item-fields.mjs

@@ -336,6 +336,18 @@ const GEAR_COMMON = Object.freeze([
 /*  Per-type declarations                                                 */
 /* --------------------------------------------------------------------- */
 
+/** The strike mode required for combat techniques and omitted for other skills.
+ * @type {import("../engine/field-spec.mjs").FieldSpec}
+ */
+export const COMBAT_TECHNIQUE_STRIKE_MODE = Object.freeze({
+    name: "strikeMode",
+    to: "strikeMode",
+    ...STRIKE_MODE,
+    required: true,
+    when: (_fm, out) => out.subType === "combattechnique",
+    describe: "The strike mode the combat technique trains. Required for combat techniques only.",
+});
+
 /**
  * Every item type's frontmatter vocabulary, in the order the `system` block
  * emits it.
@@ -513,6 +525,21 @@ export const ITEM_FIELDS = Object.freeze({
             describe:
                 "Days from contracting to onset, rolled by the receiving actor. Unset means no incubation.",
         },
+        {
+            name: "onsetMacroUuid",
+            to: "onsetMacroUuid",
+            ...BLANK_IS_NULL,
+            default: null,
+            describe: "UUID of the macro run when symptoms begin, if any.",
+        },
+        {
+            name: "data.outcomeTraumas",
+            legacyKey: "outcomeTraumas",
+            to: "outcomeTraumas",
+            ...BLANK_IS_NULL,
+            default: null,
+            describe: "SafeExpression selecting traumas caused by the affliction's outcome.",
+        },
         {
             name: "data.outcome",
             legacyKey: "outcome",
@@ -630,6 +657,11 @@ export const ITEM_FIELDS = Object.freeze({
 
     armorgear: Object.freeze([
         ...GEAR_COMMON,
+        {
+            to: "isWorn",
+            runtimeOnly: "whether the armor is currently worn by an actor",
+            describe: "Worn state set during play, never authored.",
+        },
         {
             name: "material",
             to: "material",
@@ -973,6 +1005,13 @@ export const ITEM_FIELDS = Object.freeze({
             default: "",
             describe: "Shortcode of the skill this one specialises, for a specialisation.",
         },
+        {
+            name: "adoptParentMasteryLevel",
+            to: "adoptParentMasteryLevel",
+            ...BOOLEAN,
+            default: false,
+            describe: "Whether a specialization uses its parent's mastery level.",
+        },
         {
             name: "initSkillMult",
             to: "initSkillMult",
@@ -987,6 +1026,7 @@ export const ITEM_FIELDS = Object.freeze({
             default: [],
             describe: "Body-part roles whose impairment penalises tests against this skill.",
         },
+        COMBAT_TECHNIQUE_STRIKE_MODE,
     ]),
 
     trauma: Object.freeze([
@@ -1018,6 +1058,27 @@ export const ITEM_FIELDS = Object.freeze({
             default: 0,
             describe: "How readily it heals.",
         },
+        {
+            name: "treatmentModifierBase",
+            to: "treatmentModifierBase",
+            ...NULLABLE_NUMBER,
+            default: null,
+            describe: "Modifier to treatment tests; unset means no modifier.",
+        },
+        {
+            name: "permanentImpairmentEligible",
+            to: "permanentImpairmentEligible",
+            ...BOOLEAN,
+            default: false,
+            describe: "Whether healing may leave a permanent impairment.",
+        },
+        {
+            name: "infectable",
+            to: "infectable",
+            ...BOOLEAN,
+            default: false,
+            describe: "Whether a failed healing test can cause infection.",
+        },
         {
             name: "aspect",
             to: "aspect",
@@ -1136,25 +1197,3 @@ export const ITEM_FIELDS = Object.freeze({
         },
     ]),
 });
-
-/**
- * The one conditional field in the vocabulary: a combat technique's strike
- * mode.
- *
- * A combat technique is authored as a `skill` of subtype `combattechnique` —
- * the standalone item type was merged into Skill — and carries an embedded,
- * discriminated strike mode. It is mandatory for that subtype and absent from
- * every other skill, which is a conditional a flat field list cannot state, so
- * it is applied after the declaration runs.
- *
- * @type {import("../engine/field-spec.mjs").FieldSpec}
- */
-export const COMBAT_TECHNIQUE_STRIKE_MODE = Object.freeze({
-    name: "strikeMode",
-    to: "strikeMode",
-    ...STRIKE_MODE,
-    required: true,
-    default: null,
-    describe:
-        "The strike mode the technique trains. Required on a `combattechnique` skill, and set on no other.",
-});

package/sohl/kb-passes.mjs

@@ -14,7 +14,7 @@
 /**
  * The `sohl` knowledgebase's own body pass.
  *
- * `content-build site` publishes a content tree as a website, and almost all of
+ * `package-build site` publishes a content tree as a website, and almost all of
  * that job is the same for every package. This rewrite is not: it is driven by
  * a TypeDoc symbol map only this package has, and it is ruled explicitly
  * per-consumer.
@@ -60,7 +60,7 @@ import log from "loglevel";
  *
  * The path is resolved against the **repository root**, never the process cwd.
  * `site.passOptions.symbolMap` is authored repo-relative, so a cwd-relative
- * read misses the moment `content-build site` is driven from anywhere but the
+ * read misses the moment `package-build site` is driven from anywhere but the
  * repository root — which is exactly how the end-to-end verification, running
  * through `PACKAGE_BUILD_CONFIG` from outside the tree, found this.
  *

package/sohl/note-schemas.mjs

@@ -295,14 +295,6 @@ const PRESENTATION_FIELDS = Object.freeze({
             describe: "Descriptive traits, read by the publishing sites.",
         },
     ]),
-    skill: Object.freeze([
-        {
-            name: "strikeMode",
-            ...AS_AUTHORED,
-            describe:
-                "The strike mode a combat technique declares. Compiled, but applied by the builder rather than listed in the type's fields.",
-        },
-    ]),
     being: Object.freeze([
         {
             name: "attrRollFormula",

package/stage.mjs

@@ -166,3 +166,22 @@ export function cleanBuildArtifacts(root, { extra = [], includeNodeModules = fal
     }
     return removed;
 }
+
+/**
+ * Remove the configured Foundry stage before a complete build assembles it.
+ * Other build outputs, including the content index, remain available.
+ *
+ * @param {string} root - Repository root.
+ * @param {string} stageDir - Configured stage directory, relative to root.
+ * @returns {boolean} Whether the stage existed.
+ */
+export function resetStage(root, stageDir) {
+    const projectRoot = path.resolve(root);
+    const target = path.resolve(projectRoot, stageDir);
+    if (!target.startsWith(`${projectRoot}${path.sep}`)) {
+        throw new Error("The stage directory must be inside the project root.");
+    }
+    if (!fs.existsSync(target)) return false;
+    fs.rmSync(target, { recursive: true, force: true });
+    return true;
+}

package/types/config.d.mts

@@ -68,7 +68,7 @@ export function resolvePackageBuildConfig(shared: object): Readonly<PackageBuild
 /**
  * The repository's resolved package-build configuration.
  *
- * Read on call rather than at import, exactly as content-build resolves its
+ * Read on call rather than at import, exactly as package-build resolves its
  * own: importing a module of this package must not require a configuration to
  * exist anywhere above it.
  *
@@ -93,7 +93,8 @@ export const DERIVED_MANIFEST_KEYS: Readonly<Record<string, string>>;
  * The resolved `packageBuild` section, every optional half filled in.
  *
  * @typedef {object} PackageBuildConfig
- * @property {string} rootDir        The repository root, from content-build.
+ * @property {string} rootDir        The repository root, from package-build.
+ * @property {{age: number, threshold: number, minWords: number}} proseLint Optional prose analysis settings.
  * @property {string} packageKind    `systems` or `modules`.
  * @property {string} packageId      The Foundry package id.
  * @property {string} artifact       Derived: `system` or `module`.
@@ -193,9 +194,17 @@ export type AssetSpec = {
  */
 export type PackageBuildConfig = {
     /**
-     * The repository root, from content-build.
+     * The repository root, from package-build.
      */
     rootDir: string;
+    /**
+     * Optional prose analysis settings.
+     */
+    proseLint: {
+        age: number;
+        threshold: number;
+        minWords: number;
+    };
     /**
      * `systems` or `modules`.
      */