@heroiclands/package-build 18.1.1 → 19.0.0

package/CHANGELOG.md

@@ -1,5 +1,158 @@
 # @heroiclands/package-build
 
+## 19.0.0
+
+### Major Changes
+
+- e46a791: **`folder:` and the `*-folders.yaml` schema are retired** (#260) — the last step
+  of #254, once every tree is green on the new spelling.
+  
+  They go together. The `folder:` Foundry-id spelling had nothing left to resolve
+  against once the YAML was gone, and the YAML had no reader once the spelling was
+  refused. What replaces both landed in #255–#258: a folder is a note
+  (`type: folder`), `packFolder:` names one by **address**, the packs a folder
+  materialises in are derived from what references it, and its Foundry id is
+  hashed from its canonical address.
+  
+  **What is gone**
+  
+  | Removed                                                      | Replaced by                                                                  |
+  | ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+  | `*-folders.yaml`, five files per tree                        | `type: folder` notes, resolved through the address index                     |
+  | `loadFolders`, `buildFolderResolver` and its five invariants | `collectFolderNotes` / `buildFolderNoteIndex`                                |
+  | `writeFolderDocs`                                            | `writeFolderNoteDocs`, written after the pass that learns what it references |
+  | The `folders:` pack-configuration key                        | nothing — a pack materialises what its documents reference                   |
+  | `folder:` on a note                                          | `packFolder:`                                                                |
+  
+  **Both are refused, not ignored.** A retired field left ignored reads to its
+  author as though it still works: the note says one thing and the build does
+  another, and nothing says so. A note that writes `folder:` fails the build
+  naming `packFolder` and the line to rewrite, and the frontmatter lint reports
+  every one of them in the tree at once — which is what a tree still to sweep
+  needs. A pack configuration that still names a `folders:` file is refused the
+  same way, saying where the folders went rather than merely "no such key".
+  
+  **Presence is the whole test**, in both positions a note wrote it — top-level
+  and inside the `sohl:` block. An empty `folder:` parses as `null` and is still
+  the field, and a value that happens to match a folder note's id is still the
+  retired spelling. There is no value that makes writing it correct, so each
+  message says what to write instead rather than which value to change.
+  
+  **Why this is a major.** A tree that has not swept goes red on adoption, by
+  design — that is the signal, and it is the reason the removal waited until the
+  support and the sweeps had landed. Removing either half earlier would have
+  broken a repository mid-migration, which is the failure the `image:` → `img:`
+  migration (#142, #149) was staged to avoid: read both, sweep, then remove.
+  
+  _The adventure-configuration path is untouched here — see #259, deferred._
+
+### Patch Changes
+
+- 829363c: **The container's export is a git repository**, so a workflow step that shells
+  out to git behaves as it does on the runner.
+  
+  `git archive HEAD` yields a bare directory with no `.git`. A step that asks git
+  something — `git ls-files` in a tracked-artifact check, for instance — then
+  fails for want of a repository, which reads as _the check failing_ rather than
+  as this harness lacking something the runner has. GitHub's own first step is a
+  **checkout**, so the faithful export is one too.
+  
+  Found by `HarnMaster-3-FoundryVTT`, whose `check-no-compiled-packs.mjs` lists
+  tracked files that way: it passed on the host and failed in the container, and
+  the pre-push hook duly refused a push over a defect that was entirely this
+  harness's — exactly the false positive that teaches people to reach for
+  `--no-verify`.
+  
+  Initialised and staged rather than committed: `git ls-files` reads the index, so
+  staging every extracted file reproduces exactly the set the runner would see,
+  and nothing needs a configured identity to commit with. Where `git init` cannot
+  run, it says so and carries on rather than pretending.
+
+## 18.2.0
+
+### Minor Changes
+
+- e55c1c0: **The git hooks ship here now**, and with them a pre-push check that runs a
+  repository's own Build & Test workflow in a container before the push leaves.
+  
+  **Why here.** Five repositories carried `.githooks/` with `commit-msg`,
+  `pre-commit`, `pre-merge-commit` and `protected-branch.sh` — **twenty copies of
+  four byte-identical files**, each free to drift. The `.github` repository cannot
+  help: its `actions/*` are fetched by the GitHub _runner_ through `uses:`, and
+  nothing on a developer's machine fetches from it. This package is what every
+  repository already installs, so it is the only thing that reaches every
+  checkout.
+  
+  A consumer points git at the packaged directory once:
+  
+  ```json
+  "prepare": "git config core.hooksPath node_modules/@heroiclands/package-build/githooks"
+  ```
+  
+  and then carries no hook files at all.
+  
+  **Every hook has its own switch.** They read `hooks.<key>` through one shared
+  `hook_enabled` helper, with git's normal precedence — a plain `git config` sets
+  one clone, `--global` sets a machine — so they are turned on and off
+  individually rather than as a set:
+  
+  | hook                             | key                     | default |
+  | -------------------------------- | ----------------------- | ------- |
+  | `pre-commit`, `pre-merge-commit` | `hooks.protectedBranch` | on      |
+  | `commit-msg`                     | `hooks.noAttribution`   | on      |
+  | `pre-push`                       | `hooks.prePushCi`       | **off** |
+  
+  The defaults differ deliberately: a guard that costs nothing is on unless
+  refused, while one that runs a container for minutes is off unless asked for.
+  `hooks.allowCommitOnMain` is still honoured — it is the name that has always
+  meant this, and an existing opt-out must not quietly stop working. The two
+  branch hooks share a key because they are one rule: git runs `pre-merge-commit`
+  _instead of_ `pre-commit` for a merge, so separate keys would let a `git pull`
+  on `main` through a half-disabled guard.
+  
+  **The new hook, and it is off unless you ask for it.** `pre-push` runs the
+  steps of the repository's own `.github/workflows/build.yml` and refuses the push
+  if they fail — but only where someone has opted in:
+  
+  ```bash
+  git config hooks.prePushCi true            # this clone, and every worktree of it
+  git config --global hooks.prePushCi true   # every repository on this machine
+  ```
+  
+  Off, it is silent and instant. That is deliberate: the check costs a couple of
+  minutes and ships to every repository installing this package, so it must not
+  be something a contributor discovers by having their push get slow.
+  
+  Four decisions worth knowing:
+  
+  - **The steps are read, not restated.** `ci/ci-steps.mjs` parses them from the
+    workflow, so there is no second copy of the command list to go stale — which
+    matters because a stale copy fails _silently_: running four of five steps
+    still exits 0. It refuses loudly when it recognises no steps or finds no
+    workflow, and names the `uses:` steps it cannot run. It parses rather than
+    importing a YAML library because the first step it must run is `npm ci`, so
+    anything from `node_modules` is missing exactly when it is needed.
+  - **In a container, over `git archive HEAD`.** Timing decides this: the workflow
+    begins with `npm ci`, so a host run costs about what the container costs
+    (134s cold, measured) and pays it by deleting the working tree's
+    `node_modules` each time. The container touches nothing of yours and tests
+    only committed content, as GitHub does — closing a dirty environment and a
+    case-sensitive filesystem, neither of which a Mac can catch.
+  - **`linux/amd64` by default**, matching the runner. Measured on Apple silicon
+    with Docker Desktop's Rosetta translation: JS compute 1104/1071/1078 ms native
+    against 1098/1062/1093 ms emulated, and `npm ci` 23s either way —
+    indistinguishable, so matching the runner is free. `--native` opts out, for a
+    machine where that translation is unavailable.
+  
+  - **Docker is not required, even when enabled.** Without it the check reports
+    that it could not run, says so loudly, and **lets the push through**. The
+    workflow is what enforces this; the hook only saves a round trip, so someone
+    without Docker — or without this package installed — must still be able to
+    open a pull request. Only a genuine check _failure_ refuses a push.
+  
+  `git push --no-verify` skips it once. A branch delete pushes no commits, so the
+  hook stands aside. First enabled run pulls the image (~400MB), once.
+
 ## 18.1.1
 
 ### Patch Changes

package/CONTENT.md

@@ -85,7 +85,7 @@ paths:
 # order is worked out separately, from what each pass reads (see "Declaration
 # order is presentation" below).
 packs:
-  - { name: items, type: Item, label: Items, folders: item-folders.yaml }
+  - { name: items, type: Item, label: Items }
   - { name: journals, type: JournalEntry, label: Journals }
   # A companion is written by its parent's pass rather than one of its own.
   - name: scenes
@@ -96,7 +96,7 @@ packs:
   # A pack whose per-document JSON is already built — checked in rather than
   # generated. `prebuilt` names where it lives, generation is skipped for it,
   # and `cleanPackEntry` and the Scene/Level integrity check still run. It may
-  # not carry `folders`, `companions` or `default`, and may not be a companion:
+  # not carry `companions` or `default`, and may not be a companion:
   # each of those describes a generation pass a prebuilt pack does not have.
   # When every configured pack is prebuilt the content walk is skipped
   # entirely, so a package with no `assets/content` builds.

package/ci/ci-docker.mjs

@@ -0,0 +1,236 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Run the Build & Test steps in a container, from a **clean export of HEAD**.
+ *
+ * The pre-push hook runs the same steps on this machine, which catches nearly
+ * everything. Two things it structurally cannot catch, and this does:
+ *
+ * 1. **A dirty environment.** The hook runs against your working tree with its
+ *    `node_modules`, its `build/`, its `.env.local` and whatever a previous run
+ *    left behind. GitHub starts from a checkout of the commit and nothing else.
+ *    So this exports `HEAD` with `git archive` — committed content only, no
+ *    ignored files, no stale artifacts — and runs there.
+ * 2. **macOS is case-insensitive; the runner is not.** An import whose case does
+ *    not match its file resolves here and fails on Linux, and no amount of
+ *    running the right commands locally will show it.
+ *
+ * **It runs `linux/amd64`, matching the runner, and that costs nothing.** The
+ * expected objection is that this machine is arm64 and emulation is slow. It is
+ * not, because Docker Desktop translates `linux/amd64` with **Rosetta** rather
+ * than QEMU. Measured here, three runs each:
+ *
+ * | | arm64 native | amd64 |
+ * | --- | --- | --- |
+ * | JS compute | 1104 / 1071 / 1078 ms | 1098 / 1062 / 1093 ms |
+ * | `npm ci`, 1,134 packages | 23s | 23s |
+ *
+ * Indistinguishable — so matching the runner is free, and the architecture gap
+ * this otherwise carried is simply closed.
+ *
+ * ⚠️ **That speed is a setting, not a property of the machine.** It depends on
+ * Docker Desktop's `UseVirtualizationFrameworkRosetta`; with it off the
+ * translation falls back to QEMU and the picture reverses sharply. `--native`
+ * runs on the host architecture if that ever becomes the better trade — it is
+ * the faster-but-less-faithful option, which is why it is the one you ask for.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/** This package's `ci/` directory, mounted into the container. */
+const CI_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The repository under test — the git work tree the hook fired in, never this
+ * package's own.
+ *
+ * Asked of git rather than assumed from the working directory, so the command
+ * behaves the same run from a subdirectory as from the root.
+ */
+const ROOT = (() => {
+    const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8" });
+    return (top.stdout ?? "").trim() || process.cwd();
+})();
+
+/** The image. Node's own, matching the `node-version` the workflow sets up. */
+const DEFAULT_IMAGE = "node:24-bookworm";
+
+/**
+ * Exit status meaning *the check could not run*, as distinct from *it failed*.
+ *
+ * The caller has to tell those apart: one is a reason to refuse a push, the
+ * other is a reason to say so and let it through.
+ */
+export const UNAVAILABLE = 2;
+
+/**
+ * Run a command, inheriting stdio, and return whether it succeeded.
+ *
+ * @param {string} command - The executable.
+ * @param {string[]} args - Its arguments.
+ * @param {object} [opts] - Passed to `spawnSync`.
+ * @returns {number} The exit status.
+ */
+function run(command, args, opts = {}) {
+    const result = spawnSync(command, args, { stdio: "inherit", ...opts });
+    return result.status ?? 1;
+}
+
+/**
+ * Export `HEAD` to a temporary directory — committed content, nothing else.
+ *
+ * @returns {string} The directory.
+ * @throws {Error} When the export fails.
+ */
+function exportHead() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "sohl-ci-"));
+    const archive = spawnSync("git", ["archive", "--format=tar", "HEAD"], {
+        cwd: ROOT,
+        maxBuffer: 1024 * 1024 * 512,
+    });
+    if (archive.status !== 0) {
+        throw new Error(`git archive HEAD failed: ${String(archive.stderr)}`);
+    }
+    const untar = spawnSync("tar", ["-x", "-C", dir], { input: archive.stdout });
+    if (untar.status !== 0) throw new Error("could not unpack the export");
+
+    // Make the export a repository. `git archive` yields a bare directory, and
+    // a workflow step that shells out to git — `git ls-files` in a
+    // tracked-artifact check, say — then fails for want of a `.git`, which
+    // reads as the check failing rather than as this harness lacking something
+    // the runner has. GitHub's own step is a *checkout*, so the faithful export
+    // is one too.
+    //
+    // Initialised and staged rather than committed: `git ls-files` lists the
+    // index, so staging every extracted file reproduces exactly the set the
+    // runner would see, without needing an identity configured to commit with.
+    const init = spawnSync("git", ["init", "-q"], { cwd: dir });
+    if (init.status === 0) {
+        spawnSync("git", ["add", "-A"], { cwd: dir });
+    } else {
+        console.error(
+            "ci-docker: NOTE — could not make the export a git repository, so a " +
+                "workflow step that shells out to git will fail here in a way it " +
+                "would not on the runner.",
+        );
+    }
+    return dir;
+}
+
+function main() {
+    const argv = process.argv.slice(2);
+    // Matching the runner is the default; `--native` opts out. See the module
+    // note for why the usual speed objection does not apply here.
+    const native = argv.includes("--native");
+    const image =
+        argv.find((a) => a.startsWith("--image="))?.slice("--image=".length) ?? DEFAULT_IMAGE;
+
+    // Docker absent, or installed but not running. **Not a failure**: this
+    // check is a convenience that saves a round trip, and the thing that
+    // actually enforces the workflow is the workflow. A contributor without
+    // Docker must still be able to push — blocking them would turn a courtesy
+    // into a barrier, for exactly the people who are not its audience.
+    //
+    // `UNAVAILABLE` rather than success, so the hook can say so loudly instead
+    // of passing in silence; a skipped check that looks like a green one is how
+    // a guard stops being trusted.
+    if (run("docker", ["info"], { stdio: "ignore" }) !== 0) {
+        console.error(
+            "ci-docker: Docker is not available, so the workflow was NOT checked here.\n" +
+                "  This is not a failure — GitHub will run it. Install or start Docker\n" +
+                "  to catch these before pushing.",
+        );
+        return UNAVAILABLE;
+    }
+
+    // Uncommitted work is invisible to this run *and* to GitHub, which is the
+    // point — but say so, because a green run over a stale HEAD proves nothing
+    // about what is on your disk.
+    const dirty = spawnSync("git", ["status", "--porcelain"], { cwd: ROOT, encoding: "utf8" });
+    if (dirty.stdout?.trim()) {
+        console.log(
+            "ci-docker: NOTE — your working tree has uncommitted changes.\n" +
+                "  This runs HEAD, exactly as GitHub would; those changes are not tested.",
+        );
+    }
+
+    let dir;
+    try {
+        dir = exportHead();
+    } catch (err) {
+        console.error(`ci-docker: ${err.message}`);
+        return 1;
+    }
+
+    const head = spawnSync("git", ["rev-parse", "--short", "HEAD"], {
+        cwd: ROOT,
+        encoding: "utf8",
+    });
+    console.log(
+        `ci-docker: running the workflow's steps in ${image} over a clean export of ` +
+            `${head.stdout?.trim() ?? "HEAD"} ` +
+            `(${native ? "linux/arm64, this machine's own" : "linux/amd64, as the runner"}).`,
+    );
+
+    const status = run("docker", [
+        "run",
+        "--rm",
+        ...(native ? [] : ["--platform", "linux/amd64"]),
+        "-v",
+        `${dir}:/work`,
+        // The step runner comes from this package, not from the export: the
+        // repository under test does not carry it, and should not have to.
+        "-v",
+        `${CI_DIR}:/ci:ro`,
+        "-w",
+        "/work",
+        image,
+        "node",
+        "/ci/ci-steps.mjs",
+    ]);
+
+    fs.rmSync(dir, { recursive: true, force: true });
+    // The runner says 2 when the repository has nothing for it to check; that
+    // travels back out unchanged so the hook can let the push through.
+    if (status === UNAVAILABLE) {
+        console.error("\nci-docker: nothing to check in this repository.");
+        return UNAVAILABLE;
+    }
+    if (status !== 0) {
+        console.error("\nci-docker: FAILED — GitHub would report the same.");
+        return status;
+    }
+    console.log("\nci-docker: clean, from a fresh checkout on Linux.");
+    return 0;
+}
+
+// Compared as *real* paths: a consumer reaches this through
+// `node_modules/@heroiclands/package-build`, which npm may make a symlink, and
+// `import.meta.url` is symlink-resolved while `process.argv[1]` is not. Comparing
+// them raw makes the module exit 0 having done nothing — silently, which is the
+// worst way for a check to fail.
+const invokedDirectly = (() => {
+    try {
+        return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    } catch {
+        return false;
+    }
+})();
+if (invokedDirectly) process.exit(main());

package/ci/ci-steps.mjs

@@ -0,0 +1,249 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Run, locally, exactly what the Build & Test workflow runs.
+ *
+ * **The workflow is the statement; this reads it.** A hook holding its own copy
+ * of the command list is a second statement of one thing, and the copy is the
+ * one that goes stale — silently, because a pre-push check that runs four of
+ * five steps still exits 0. So the steps are parsed out of
+ * `.github/workflows/build.yml` at run time and there is nothing to keep in
+ * step.
+ *
+ * **It refuses rather than assumes.** If the workflow's shape changes so that
+ * no `run:` steps are found, this fails loudly instead of passing having done
+ * nothing. A guard that quietly covers nothing is worse than no guard, because
+ * it is trusted.
+ *
+ * **What it cannot run**, and says so: a `uses:` step is a published action, not
+ * a command — the forbidden-marker check, the coverage upload. Those stay
+ * GitHub's to run, and the summary names them so the gap is visible rather than
+ * assumed away.
+ *
+ * **It parses the workflow itself rather than importing a YAML library**, for a
+ * reason that is easy to miss: the *first* step it has to run is `npm ci`, so
+ * anything this script imports from `node_modules` is unavailable exactly when
+ * it is needed — on a fresh clone, or in a worktree that has never been
+ * installed. The parser is therefore deliberately small, and strict: it reads
+ * `run:` scalars and `run: |` blocks by indentation and refuses when it
+ * recognises nothing.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The repository whose workflow is being run — the working directory, not this
+ * file's package.
+ *
+ * This ships in `@heroiclands/package-build` and runs against whichever
+ * repository invoked it: from a hook, git sets the working directory to the
+ * repository root; in the container, it is the mounted export. Resolving
+ * relative to `import.meta.url` would find the *package's* own tree, which is
+ * never the one under test.
+ */
+const ROOT = process.cwd();
+
+/**
+ * Exit status meaning *there was nothing to check*, as distinct from *the check
+ * failed*. Mirrors the same constant in `ci-docker.mjs`.
+ */
+export const UNAVAILABLE = 2;
+const WORKFLOW_DIR = path.join(ROOT, ".github/workflows");
+
+/**
+ * The workflow's steps, split into what can be run here and what cannot.
+ *
+ * @returns {{run: Array<{name: string, run: string}>, skipped: string[]}} The
+ *   `run:` steps in workflow order, and the names of the `uses:` steps.
+ * @throws {Error} When the workflow cannot be read or declares no `run:` step.
+ */
+export function ciSteps() {
+    const files = prTriggeredWorkflows();
+    if (!files.length) {
+        throw new NoWorkflow(
+            `no workflow under .github/workflows is triggered by \`pull_request\`, ` +
+                `so there is nothing here that a pull request would run.`,
+        );
+    }
+    const run = [];
+    const skipped = [];
+    for (const file of files) {
+        const found = stepsIn(file);
+        run.push(...found.run);
+        skipped.push(...found.skipped);
+    }
+    if (!run.length) {
+        throw new Error(
+            `${files.map((f) => path.relative(ROOT, f)).join(", ")} declare no ` +
+                `\`run:\` steps — either their shape changed or they are entirely ` +
+                `composed of actions. Refusing to report success having run nothing.`,
+        );
+    }
+    return { run, skipped, files };
+}
+
+/**
+ * Raised when the repository has no workflow a pull request would run.
+ *
+ * Distinguished from a parse failure because the two deserve opposite answers:
+ * a repository that simply has no such workflow is not broken and its pushes
+ * must not be refused, while one whose workflow stopped parsing is a defect in
+ * this parser that should be loud.
+ */
+export class NoWorkflow extends Error {}
+
+/**
+ * Every workflow a pull request would run.
+ *
+ * `pull_request` appearing before the first `jobs:` key is the test — it is the
+ * trigger block, and these files put it there. Deliberately not a YAML parse:
+ * see the module note on why this cannot import a library.
+ *
+ * @returns {string[]} Absolute paths, in directory order.
+ */
+function prTriggeredWorkflows() {
+    let names;
+    try {
+        names = fs.readdirSync(WORKFLOW_DIR).filter((n) => /\.ya?ml$/i.test(n));
+    } catch {
+        return [];
+    }
+    return names
+        .map((name) => path.join(WORKFLOW_DIR, name))
+        .filter((file) => {
+            const text = fs.readFileSync(file, "utf8");
+            const head = text.split(/^jobs:/m)[0];
+            return /^\s*pull_request:?\s*$/m.test(head) || /^on:.*pull_request/m.test(head);
+        });
+}
+
+/**
+ * The `run:` and `uses:` steps of one workflow.
+ *
+ * @param {string} file - The workflow.
+ * @returns {{run: Array<{name: string, run: string}>, skipped: string[]}} Its steps.
+ */
+function stepsIn(file) {
+    const lines = fs.readFileSync(file, "utf8").split("\n");
+    const run = [];
+    const skipped = [];
+    /** The most recent `- name:` seen, which labels whatever step follows. */
+    let name = null;
+
+    const indentOf = (line) => line.length - line.trimStart().length;
+
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const text = line.trim();
+        if (text.startsWith("#") || text === "") continue;
+
+        const named = /^-?\s*name:\s*(.+)$/.exec(text);
+        if (named) {
+            name = named[1].replace(/^["']|["']$/g, "");
+            continue;
+        }
+        if (/^-?\s*uses:\s*\S/.test(text)) {
+            skipped.push(name ?? text.replace(/^-?\s*uses:\s*/, ""));
+            name = null;
+            continue;
+        }
+
+        const inline = /^-?\s*run:\s*(?!\|)(.+)$/.exec(text);
+        if (inline) {
+            run.push({ name: name ?? inline[1], run: inline[1].trim() });
+            name = null;
+            continue;
+        }
+        // A `run: |` block scalar: every following line indented deeper.
+        if (/^-?\s*run:\s*\|\s*$/.test(text)) {
+            const base = indentOf(line);
+            const body = [];
+            while (i + 1 < lines.length) {
+                const next = lines[i + 1];
+                if (next.trim() !== "" && indentOf(next) <= base) break;
+                body.push(next.trim());
+                i += 1;
+            }
+            const command = body.filter(Boolean).join(" && ");
+            if (command) run.push({ name: name ?? command, run: command });
+            name = null;
+        }
+    }
+    return { run, skipped };
+}
+
+/**
+ * Run every step, stopping at the first failure.
+ *
+ * Stopping is deliberate and mirrors the runner: a later step routinely depends
+ * on an earlier one having produced something.
+ *
+ * @returns {number} The exit code to leave with.
+ */
+function main() {
+    let steps;
+    try {
+        steps = ciSteps();
+    } catch (err) {
+        // A repository with no pull-request workflow is not broken, and its
+        // pushes must not be refused — it simply has nothing for this to check.
+        // Distinguished from a parse failure, which is a defect here and stays
+        // loud.
+        if (err instanceof NoWorkflow) {
+            console.error(`ci-steps: ${err.message}`);
+            return UNAVAILABLE;
+        }
+        console.error(`ci-steps: ${err.message}`);
+        return 1;
+    }
+
+    const { run, skipped } = steps;
+    console.log(`ci-steps: running ${run.length} step(s) from .github/workflows/build.yml`);
+    if (skipped.length) {
+        console.log(`ci-steps: not runnable here (published actions): ${skipped.join(", ")}`);
+    }
+
+    for (const [i, step] of run.entries()) {
+        console.log(`\nci-steps: [${i + 1}/${run.length}] ${step.name}\n  $ ${step.run}`);
+        const result = spawnSync(step.run, { cwd: ROOT, shell: true, stdio: "inherit" });
+        if (result.status !== 0) {
+            console.error(
+                `\nci-steps: FAILED at "${step.name}" — this is what GitHub would report.\n` +
+                    `  Fix it, or push with --no-verify if you mean to.`,
+            );
+            return result.status ?? 1;
+        }
+    }
+    console.log(`\nci-steps: all ${run.length} step(s) passed.`);
+    return 0;
+}
+
+// Compared as *real* paths: a consumer reaches this through
+// `node_modules/@heroiclands/package-build`, which npm may make a symlink, and
+// `import.meta.url` is symlink-resolved while `process.argv[1]` is not. Comparing
+// them raw makes the module exit 0 having done nothing — silently, which is the
+// worst way for a check to fail.
+const invokedDirectly = (() => {
+    try {
+        return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+    } catch {
+        return false;
+    }
+})();
+if (invokedDirectly) process.exit(main());