@heroiclands/package-build 20.6.0 → 21.0.0

package/CHANGELOG.md

@@ -1,5 +1,186 @@
 # @heroiclands/package-build
 
+## 21.0.0
+
+### Major Changes
+
+- 742861f: **A pathname names the package that owns the file, and every surface derives its
+  own address from it.** A note states a file once — `img:`, `data.portrait:`, a
+  map's background, overlay, tile textures and ambient sounds, and the address of
+  every image in a body — and four surfaces resolve it: a Foundry install, the
+  repository's own tree, the website, and the book. The website used to publish
+  the address exactly as authored, so a picture that appeared in Foundry and in
+  the book 404'd on the page.
+  
+  **What a pathname looks like now**
+  
+  - `images/map.webp` — a file **this** package ships.
+  - `sohl/assets/icons/noun/shield.svg` — a file the `sohl` package ships. The
+    first segment is the **content package**, never its Foundry id: `thalorna`,
+    not `sohl-thalorna`.
+  - An absolute URL, a `data:` URI, a `//host/…` or a `/`-rooted path passes
+    through untouched on every surface, which is how a note addresses core Foundry
+    art or a package outside this constellation.
+  
+  `thalorna` writing `images/map.webp` publishes
+  `modules/sohl-thalorna/assets/images/map.webp` in Foundry,
+  `https://cdn.heroiclands.org/thalorna/images/map.webp` on the web, and a copy
+  staged at `assets/images/map.webp` in the book.
+  
+  **What every consuming repository must change**
+  
+  - **Convert authored pathnames.** `systems/sohl/assets/X` becomes
+    `sohl/assets/X`, and `systems/hm3/images/X` becomes `hm3/assets/images/X`.
+    A Foundry-spelled pathname is now refused with a located error naming its
+    replacement, so nothing converts silently and nothing is missed.
+  - **Set `site.assets`** in `package-build.config.yaml` to the host the site
+    serves imagery from. A package-owned image on a page with none set is an
+    error naming the key.
+  - **HM3 serves its pictures from `assets/images/`.** The default art this
+    toolchain pairs with each HM3 item type addresses them there.
+  - **`DEFAULT_ITEM_ART` holds pathnames, not install paths.** A runtime reading
+    the map directly resolves the pathname for itself.
+  - **A package addressed by a pathname must be one the build knows** — its own,
+    a game system it compiles content for, or a package under `relationships`.
+    Where another package's content name differs from its Foundry id, say so with
+    `relationships.<kind>[].contentPackage`.
+  
+  `banner:` is unchanged, and still not a pathname: it names a hero image on the
+  site's own asset host, reaches no compiled document and no book, and the Hugo
+  theme resolves it.
+
+### Minor Changes
+
+- 0d83c42: **Beings**
+  
+  - A being note says what kind of being it is — `character` or `creature` — as a
+    tag, declared alongside the stations, the place kinds and `draft` that a note's
+    tags are already checked against.
+  - A being is one or the other. A note carrying both is refused, naming the note
+    and the line, because two answers to one question are no answer. A being
+    carrying neither is left alone, so a setting part-way through classifying its
+    cast still builds.
+  - A misspelt kind is caught the way a misspelt `village` already is: a query for
+    the characters in a setting does not find `charcter`, and the list it returns
+    still looks complete.
+- 841b98b: **`package-build bump` takes a newer first-party release without reformatting
+  the lockfile.** Run it with no arguments to move every `@heroiclands/*`
+  dependency to its newest published version, or name the packages to move; add
+  `--check` to see what would change and write nothing.
+  
+  npm does the resolving, so a version whose dependency set differs from the one
+  it replaces is handled as correctly as one that moves three lines — and then
+  both `package-lock.json` and `package.json` are restored to the indentation they
+  already used. That is the part worth having: every repository consuming this
+  toolchain writes its lockfile with four spaces and prettier-ignores it, npm
+  rewrites it with two, and a three-line version change arrives as a whole-file
+  reformat nobody can review.
+- 5d46b86: **The page**
+  
+  - Every entry now opens a page of its own, under a full-bleed plate carrying the section it belongs to above its name. A wrapped name grows the plate rather than pushing that line off the top of it.
+  - A section opens a page of its own too, plated to twice the depth, so the book reads as parts rather than as one continuous run.
+  - The body is set in two columns, on cream stock in dark ink with rust rules. A note's `description:` sets as an epigraph under the plate, and the prose opens on a raised capital.
+  - A running foot carries the section, an ornament and the folio, so a page found by chance says where it belongs.
+  - A page number in the contents now points at the first page of the thing it names.
+  - Columns are print's alone. The website keeps one measure.
+  
+  **Tables and wide content**
+  
+  - A table of more than three columns is set across the page instead of crushed into a column: floated over both where it fits a page, and given single-column pages of its own where it does not.
+  - A narrower table sets in the column measure and carries its header onto every page and column it spills onto.
+  
+  **What a section can say about itself**
+  
+  - A section may name the banner its plate is drawn over, the line printed above each entry's name, the name the running foot carries, and how many columns its pages are set in. Everything beneath it agrees unless it says otherwise.
+  - A section that names no banner still gets its plate, its kicker and its title. A banner that cannot be read is reported.
+- 790d7ab: **An image says how wide it is and where it sits, once, in the note.** A
+  markdown image can carry a directive in the curly-attribute convention Pandoc
+  and Kramdown use, and the book, the website and a Foundry journal page each
+  honour it:
+  
+  ```markdown
+  ![Brànwâal Dôrgaar](images/beings/branwldrgr-portrait.webp){float: top-left}
+  
+  ![Map of Thalorna](images/maps/thalorna.webp){.full-width}
+  ```
+  
+  - **Width is a class**, and the ordinary width carries no marker — `.full-width`
+    is the only one there is. One column in the book, the text measure on the
+    website and in a journal page.
+  - **Position is `float:`**, taking `top-left`, `bottom-left`, `top-right`,
+    `bottom-right` or `center`. The website and Foundry wrap text around it; print
+    cannot wrap around a shape, so a float there occupies the measure and only the
+    top-or-bottom half of a position has an effect.
+  - **An image is a block** — it stands alone in its paragraph — and its **alt
+    text is the caption**, drawn under the picture on every surface.
+  - Both vocabularies are **closed**. `{.fullwidth}`, `{width=800}` and
+    `{float: middle}` are refused by `content-build lint`, located by file, line
+    and column, and they fail the run: an unrecognised value rendering as the
+    ordinary width looks exactly like a directive that worked. Nothing beyond the
+    two vocabularies and the address reaches emitted markup.
+  
+  **The book prints pictures.** An image authored in a note is copied into the
+  output directory and set at the measure its class names, where it used to reach
+  the page as italic alt text. An address naming a file the package does not ship
+  prints its caption alone and is reported.
+  
+  **A body image's address follows the `img:` rule** — its first segment says
+  which package owns the file — so `images/map.webp` reaches a journal page as
+  `modules/<package>/assets/images/map.webp`. The website passes an address
+  through as authored; one that has to resolve there is written as a full URL.
+  
+  _Styling the two HTML surfaces is each surface's own: a figure carries
+  `note-image`, plus `note-image-full-width` and `note-image-float-…` from the
+  vocabularies._
+- 086fbb4: **Infoboxes**
+  
+  - Every entry now opens with a summary panel: the subject's own facts first, then one panel for each game system the note reaches.
+  - A gear item's price, weight and durability reach the panel whichever way the note states them, each with its unit on it — 160d, 1.1 lbs.
+  - Armour states all four protection aspects, an unrated one reading `0`; a weapon states its strike modes one per line, with `—` where a value was never given.
+  - A being's system panel gathers attributes, skills, mystical abilities and equipment, each a section that stays whole when the panel breaks across a page or column.
+  - Skills group by the family each skill note declares, and equipment by what the gear is. A projectile states what it hits for.
+  - Rows are labelled for a reader rather than named after the field behind them, and the panel says what the note says and nothing else: a value the system would have assumed anyway is left off, and so is a word standing in for an unset one — no more _Potency: Na_, and a strike mode that rolls no damage says so rather than printing a die nobody can roll.
+  - A system panel is never a heading over nothing. One reads _Not available_ where the system produces no document for the note; one that produces a document but adds nothing to the profile says so. A system with no such concept draws no panel at all.
+  - The panel carries no picture. An image belongs in the note's text, where its position decides what comes after it.
+  - On the web and in Foundry each panel is a disclosure a reader can fold away, open to begin with, so several stack without burying the prose. In print they simply flow.
+  - What a panel holds is settled once and drawn the same way in the book, on the website and in a compendium journal — and a field added to a note type appears in all three without further work.
+  
+  **Content format**
+  
+  - The specification now describes the infobox: where it sits in each medium, the rules that hold everywhere, which fields each panel carries, the three things a system panel can say, and the shape a page publishes it in.
+
+### Patch Changes
+
+- 841b98b: **A being that declares no `sohl:` block no longer takes the site build down.**
+  `content-build site` failed with `unacceptable kind of an object to dump [object
+  Undefined]` for any `type: being` note whose front matter carried no `sohl:` key
+  at all, and the throw aborted the entire run rather than the one page. A note
+  carrying `sohl: null` had always been fine, so the failure only appeared once a
+  tree removed the empty key rather than emptying it. Both shapes now publish the
+  same page. Fixes HeroicLands/package-build#478.
+
+## 20.7.0
+
+### Minor Changes
+
+- 6c10f17: **A `trees` entry's pages stay where their tree mounts them** — declaring
+  `subType` on a note inside `site.trees` no longer moves its published address.
+  A `subType` classifies a page for the site index; it never routed a tree
+  page's URL to begin with for a note that left it unset, and now it does not
+  for one that sets it either. A site that already worked around this by
+  avoiding `subType` on its tree notes can declare it again: those pages move
+  back under the tree's own section on upgrade.
+
+### Patch Changes
+
+- 72daae4: **A being that declares no `sohl:` block no longer takes the site build down.**
+  `content-build site` failed with `unacceptable kind of an object to dump [object
+  Undefined]` for any `type: being` note whose front matter carried no `sohl:` key
+  at all, and the throw aborted the entire run rather than the one page. A note
+  carrying `sohl: null` had always been fine, so the failure only appeared once a
+  tree removed the empty key rather than emptying it. Both shapes now publish the
+  same page. Fixes HeroicLands/package-build#478.
+
 ## 20.6.0
 
 ### Minor Changes

package/CONTENT.md

@@ -259,9 +259,9 @@ What follows from the kind:
 - **`foundryPackage` is not derived.** For every other kind the loader reads it
   from the adjacent `package.json`; there is no Foundry package here to carry an
   id, so `foundryPackage` and `assetRoot` are both `null`. A note's `img:`
-  therefore names the owning package (`systems/…`, `modules/…`) or a URL — a
-  path this package would have to serve itself is refused, because Foundry
-  serves no files for a package it does not install.
+  therefore names a `/`-rooted path or a URL — a pathname this package would
+  have to serve itself is refused, because Foundry serves no files for a
+  package it does not install.
 - **`package-build manifest` refuses**, rather than emitting a `module.json`
   advertising an installable package with no id, no packs and no compatibility
   range. So does `content-build package compile`, which would otherwise exit 0
@@ -709,44 +709,57 @@ whitelist without a builder behind it.
 same `resolveImg` rule as a note's `img:`, so one spelling means one thing
 wherever it is written.
 
-#### An asset path's first segment says which package owns it
-
-Every authored asset path — a registry `img:`, a note's `img:`, an actor's
-`portrait:` — answers "which package holds this file?" in its **first segment**,
-and there are exactly three answers:
-
-| Authored path starts with | Owner                 | Emitted              |
-| ------------------------- | --------------------- | -------------------- |
-| `systems/`                | a separate **system** | unchanged            |
-| `modules/`                | a separate **module** | unchanged            |
-| anything else             | **this package**      | `<assetRoot>/<path>` |
-
-`assetRoot` is derived, never authored: it is
-`<packageKind>/<foundryPackage>/assets`, and it is the one place `systems/sohl`
-(or `modules/sohl-thalorna`) is ever spelled. The derivation is **conditional on
-the kind** — a `documentation` package has no asset root, and the third row is
-refused there rather than rooted. So `icons/relic.svg` in a module's
-registry compiles to `modules/sohl-relics/assets/icons/relic.svg`, and the same
-string in the system's compiles to `systems/sohl/assets/icons/relic.svg`. An
-already-served `systems/sohl/assets/icons/…` passes through untouched — which is
-what lets a module pair a SoHL default with one of its own types.
-
-**"Anything else" is the rule, not a list of directories.** A package owns its
+#### A pathname names the package that owns the file
+
+Every authored pathname — a registry `img:`, a note's `img:`, an actor's
+`data.portrait:`, a map's background, the address of an image in a body —
+answers "which package holds this file?" in its **first segment**, when an
+`assets/` follows it. Everything after that `assets/` is the _suffix_, and a
+pathname that does not open `<package>/assets/` belongs to the package being
+compiled, whole.
+
+Four surfaces derive an address from that one statement. For a `thalorna` note
+— the package Foundry installs as the module `sohl-thalorna` — writing
+`images/map.webp`:
+
+| Surface     | Address                                                  |
+| ----------- | -------------------------------------------------------- |
+| **Foundry** | `modules/sohl-thalorna/assets/images/map.webp`           |
+| **Local**   | `assets/images/map.webp`                                 |
+| **Web**     | `https://cdn.heroiclands.org/thalorna/images/map.webp`   |
+| **Book**    | `assets/images/map.webp`, staged beside the Typst source |
+
+`sohl/assets/icons/relic.svg` names the `sohl` package's file wherever it is
+written, which is what lets a module pair a SoHL default with one of its own
+types. The package's name is not its Foundry id: `thalorna` is the content and
+`sohl-thalorna` the install, and only the Foundry form carries the second.
+
+The web host is `site.assets`, and a package-owned image on a page with none
+set is an error naming that key.
+
+**The rule is about ownership, not a list of directories.** A package owns its
 whole `assets/` tree, so a directory this toolchain has never heard of is still
 that package's: art under `assets/artwork/` is addressed `artwork/deity.webp`
-and rooted exactly as `icons/…` and `images/…` are. An address naming no package
-at all — an absolute URL, a `data:` URI, a `/`-rooted path — passes through, on
-the same rule rather than as an exception.
+and resolved exactly as `icons/…` and `images/…` are. An address naming no
+package at all — an absolute URL, a `data:` URI, a `/`-rooted path — passes
+through on every surface, on the same rule rather than as an exception.
+
+**A `systems/…` or `modules/…` pathname is refused**, with a finding naming the
+replacement: it resolves for Foundry and for neither of the other surfaces, and
+deriving anything from it would put a wrong address on two of the three.
+`worlds/` is not such a root — a package may not ship files out of a world, so
+that path gets the ordinary reading and produces a plainly broken one rather
+than a plausible one that 404s unreported.
 
-`worlds/` is deliberately not exempt: a package may not ship art out of a world,
-so prefixing such a path produces a plainly broken one rather than a plausible
-one that 404s in Foundry unreported.
+A `documentation` package installs nothing, so it has no Foundry form to derive
+and addresses another package's file by a `/`-rooted path or a URL.
 
 **`banner:` is a path that does not follow this rule.** It reaches no compiled
-document; it is a top-level key the Hugo theme reads, and the theme prefixes a
-relative value with `images/` and joins it onto `params.cdnBaseURL`. The two
-address different places — `img:` a file Foundry serves, `banner:` a file the
-CDN serves — so they are stated apart rather than reconciled. See the
+document and no book; it is a top-level key the Hugo theme reads, and the theme
+prefixes a relative value with `images/` and joins it onto
+`params.cdnBaseURL`. The two address different places — a pathname a file a
+package ships, `banner:` a hero image on the site's own asset host — so they are
+stated apart rather than reconciled. See the
 [content format specification](docs/content-format.md#banner-addresses-the-cdn-not-the-foundry-install).
 
 #### "Names no art" and "wants no art" are different
@@ -2436,6 +2449,75 @@ The `WHERE` clause runs against the same content index the SQL tables read, and
 the build owns the `SELECT … FROM notes` — so a filter cannot name a table, and
 cannot reach another package's notes.
 
+### How the book is set
+
+**Every entry opens a page of its own**, under a full-bleed plate carrying a
+small-caps kicker above the entry's name. A reference book is consulted rather
+than read through: an entry beginning halfway down a page is harder to find,
+cannot carry its own running head honestly, and makes a page number in the
+contents point at the middle of something else. A section opens a page of its
+own too, plated to twice the depth, so a section reads as a section rather than
+as the first entry beneath it.
+
+**The body is set in two columns**, and every other measure follows from that
+one: an image with no width class is a column wide, the infobox flows in the
+column measure and breaks between its sections, and a table wider than three
+columns is set across the page. Two columns are print's answer and print's
+alone — a scrolling page has no fixed viewport, so the website keeps one
+measure with a side rail.
+
+A note's `description:` sets as an epigraph between short rules under the
+plate, and the first paragraph of the prose opens on a raised capital. Both
+disappear rather than leave a shell: a note with no description has no
+epigraph, and a body opening on a link or a number keeps its own first
+character. The running foot carries the section's name, an ornament and the
+folio.
+
+A table of **more than three columns** is given an explicit span rather than
+left to overflow the measure. Which span depends on how tall it is, and that is
+measured while the page is laid out: a table that fits a page is floated across
+both columns at the top of one, and a longer one is set on single-column pages
+of its own — a float cannot break, and a table taller than the page placed as
+one piles its rows on top of each other without a word of warning.
+
+### What a section declares, its entries inherit
+
+A section may carry presentation alongside its `contents:`, and everything
+beneath it agrees unless it says otherwise:
+
+```yaml
+contents:
+  - sectionName: Beings
+    footer: The Bestiary # what the running foot carries
+    page:
+      banner: assets/images/banners/bestiary.webp # the plate's picture
+      kicker: The Bestiary of Thalorna # the line above each entry's name
+      columns: 2 # the measure this section's pages are set in
+    contents:
+      - filter: "type = 'being'"
+```
+
+| Key            | Default                | What it does                                          |
+| -------------- | ---------------------- | ----------------------------------------------------- |
+| `footer`       | the section's own name | The name in the running foot.                         |
+| `page.banner`  | none                   | A file this repository ships, plated under the title. |
+| `page.kicker`  | the section's trail    | The small-caps line above an entry's name.            |
+| `page.columns` | `2`                    | Columns, from 1 to 4.                                 |
+
+`page:` is inherited whole: a subsection declaring one of its keys states the
+others it wants as well.
+
+**A missing banner is a plate without a picture.** A section plate implies a
+banner per section, and art arrives later than rendering does — so a section
+that names none still gets its plate, its kicker and its title, set over the
+book's ink, and nothing is reported. A banner the build _cannot read_ is a
+different matter: that is a statement the tree makes and the build cannot
+honour, so it is a finding.
+
+`header:` and `infobox:` are part of the format and read by nothing: the
+running head is a foot in this design, and which infobox a note draws is
+decided by the note's type.
+
 ### What it is fenced by
 
 **`publish.site` decides whether a book is built, and it is the only switch.**
@@ -2485,14 +2567,22 @@ hand.
 
 ### What the book gets right, and why each matters
 
-| Property                 | How                                                                           |
-| ------------------------ | ----------------------------------------------------------------------------- |
-| Searchable               | Real text, not page images — a roster nobody can search for a name is no use. |
-| Bookmark outline         | Every section and entry is a heading, so a viewer's sidebar is the way in.    |
-| Page-numbered contents   | `#outline()`, shallower than the bookmarks — 2,500 entries would be 40 pages. |
-| Repeating table headers  | `table.header`, so a property table spilling a page keeps its column names.   |
-| Internal cross-reference | A wikilink between two notes of the book becomes an internal destination.     |
-| External cross-reference | A cross-package link, and a note the book did not select, stay URLs.          |
+| Property                 | How                                                                             |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| Searchable               | Real text, not page images — a roster nobody can search for a name is no use.   |
+| Bookmark outline         | Every section and entry is a heading, so a viewer's sidebar is the way in.      |
+| Page-numbered contents   | `#outline()`, shallower than the bookmarks — 2,500 entries would be 40 pages.   |
+| Repeating table headers  | `table.header`, so a property table spilling a page keeps its column names.     |
+| Internal cross-reference | A wikilink between two notes of the book becomes an internal destination.       |
+| External cross-reference | A cross-package link, and a note the book did not select, stay URLs.            |
+| Illustration             | An image authored in the body is staged and set at the measure its class names. |
+
+An image states its own width and position once, in the note, and the book, the
+website and a Foundry journal page each honour it — see
+[Images](docs/content-format.md#images) for the two closed vocabularies. The book
+copies each picture it prints into the output directory before the compiler
+runs, because Typst reads nothing above its own root; an address naming a file
+this package does not ship prints its caption alone and is reported.
 
 `{#anchor}` on a heading becomes an internal destination namespaced by its
 entry, so `[[being-jaslyne#appearance]]` reaches the section and two notes may

package/bin/content-build.mjs

@@ -84,6 +84,7 @@ import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
 import { lintContentIcons } from "../engine/content-icons.mjs";
+import { lintContentImages } from "../engine/content-images.mjs";
 import { declaredSystems, lintFrontmatter, systemBlocksFor } from "../engine/frontmatter-lint.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
@@ -962,6 +963,14 @@ function lintCommand() {
                     skipDirectories: config.skipDirectories,
                 });
 
+                // The width and position an image states. Refused rather than
+                // reported, because an unrecognised value rendering as the
+                // ordinary width looks exactly like a directive that worked —
+                // so these are errors and they fail the run.
+                const images = lintContentImages(root, {
+                    skipDirectories: config.skipDirectories,
+                });
+
                 const findings = [
                     ...addresses.findings,
                     ...frontmatter.findings,
@@ -969,6 +978,7 @@ function lintCommand() {
                     ...charset.findings,
                     ...icons.findings,
                     ...html.findings,
+                    ...images.findings,
                 ];
                 // Only an **error** fails the run. Every finding was an error
                 // by then, so this changes nothing on its own —
@@ -1418,7 +1428,13 @@ function pdfCommand() {
                     compile: argv.compile !== false,
                 });
 
-                for (const finding of result.findings) emitDiagnostic(finding);
+                // The shared line, not a second copy of it: an **error** fails
+                // the run and a **warning** does not. A picture the book cannot
+                // carry is a warning — the entry still prints, with its caption
+                // where the image would be — and a pathname no surface can
+                // resolve is an error, because the same statement is wrong in
+                // Foundry and on the website too.
+                const errors = reportFindings(result.findings, {});
 
                 if (!result.built) {
                     // A reason is a deliberate no-op — the fence, an absent
@@ -1442,9 +1458,7 @@ function pdfCommand() {
                 );
                 log.info(`Typst source: ${result.typ}`);
                 if (result.pdf) log.info(`Book: ${result.pdf}`);
-                // Findings are reported, never fatal — a filter that selected
-                // nothing is worth fixing and is not worth refusing to publish
-                // the other two thousand entries over.
+                if (errors) process.exitCode = 1;
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1565,7 +1579,25 @@ function siteCommand() {
                         message: linkFindingMessage(e),
                     });
                 }
-                if (result.tableErrors.length || result.wikiErrors.length) {
+                // An image whose pathname the site cannot resolve, located the
+                // way a wikilink finding is: by searching the note for the
+                // literal the resolver was handed. The page is written either
+                // way — a missing picture is visible, and stopping before the
+                // write would hide every other finding in the tree behind one
+                // address.
+                for (const e of result.imageErrors) {
+                    emitDiagnostic({
+                        file: e.file,
+                        ...positionOfLiteral(readRawNote(e.file), e.src, e.occurrence),
+                        severity: "error",
+                        message: e.message,
+                    });
+                }
+                if (
+                    result.tableErrors.length ||
+                    result.wikiErrors.length ||
+                    result.imageErrors.length
+                ) {
                     process.exitCode = 1;
                     return;
                 }

package/bin/package-build.mjs

@@ -86,6 +86,7 @@ import { SCHEMA_ARTIFACT_FILE } from "../engine/foreign-catalog.mjs";
 import { validateLangSource } from "../lang.mjs";
 import { checkLabelRegistry } from "../labels.mjs";
 import { lintYaml } from "../engine/yaml-lint.mjs";
+import { bumpDependencies } from "../engine/dependency-bump.mjs";
 import {
     analyzeCoverage,
     collectScriptReferences,
@@ -1132,6 +1133,81 @@ function e2eCommand() {
     };
 }
 
+/**
+ * `bump [packages..]` — take a newer version of a dependency.
+ *
+ * npm does the resolving, so a bump whose dependency set changed is as correct
+ * as one that moves three lines. What this adds is the indentation: every
+ * repository here writes `package-lock.json` with four spaces and
+ * prettier-ignores it, and npm rewrites it with two, so the version change
+ * arrives buried in a whole-file reformat.
+ *
+ * Named nothing, it takes the first-party packages — the ones a person bumps
+ * by hand, the moment a release publishes, usually to unblock the change that
+ * prompted it. Third-party bumps arrive from Dependabot on their own schedule.
+ *
+ * @returns {object} The yargs command module.
+ */
+function bumpCommand() {
+    return {
+        command: "bump [packages..]",
+        describe: "Take a newer version of a dependency, keeping the lockfile's formatting",
+        builder: (y) =>
+            y
+                .positional("packages", {
+                    type: "string",
+                    array: true,
+                    describe: "Packages to bump (default: every @heroiclands/* dependency)",
+                })
+                .option("tag", {
+                    type: "string",
+                    default: "latest",
+                    describe: "Dist-tag to take",
+                })
+                .option("check", {
+                    type: "boolean",
+                    default: false,
+                    describe: "Report what would change and write nothing",
+                }),
+        handler: handler(async (args) => {
+            const rootDir = process.cwd();
+            const result = bumpDependencies({
+                rootDir,
+                packages: args.packages,
+                tag: args.tag,
+                check: args.check,
+            });
+
+            if (result.changes.length === 0) {
+                const named =
+                    result.unchanged.length ?
+                        result.unchanged.join(", ")
+                    :   "no first-party dependency";
+                console.log(`Already on the newest ${args.tag}: ${named}`);
+                return;
+            }
+
+            for (const { name, from, to } of result.changes) {
+                console.log(`${name}  ${from ?? "—"} → ${to}`);
+            }
+
+            if (result.checked) {
+                console.log(
+                    `\nRun without --check to take ${result.changes.length > 1 ? "them" : "it"}.`,
+                );
+                return;
+            }
+
+            for (const file of result.reindented) {
+                console.log(`   kept the existing indentation of ${path.basename(file)}`);
+            }
+            console.log(
+                `\nInstall it with \`npm ci\`, which resolves from the lockfile this just moved.`,
+            );
+        }),
+    };
+}
+
 yargs(hideBin(process.argv))
     .scriptName("package-build")
     .command(cleanCommand())
@@ -1140,6 +1216,7 @@ yargs(hideBin(process.argv))
     .command(schemaCommand())
     .command(langCommand())
     .command(labelsCommand())
+    .command(bumpCommand())
     .command(yamlCommand())
     .command(bundleCommand())
     .command(releaseCommand())