@heroiclands/package-build 18.1.1 → 18.2.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @heroiclands/package-build
 
+## 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/ci/ci-docker.mjs

@@ -0,0 +1,215 @@
+/*
+ * 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");
+    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());

package/githooks/commit-msg

@@ -0,0 +1,40 @@
+#!/usr/bin/env sh
+#
+# Reject commit messages that carry AI/assistant attribution.
+#
+# This project does not want Co-Authored-By trailers naming an AI assistant, nor
+# "Generated with Claude Code"-style signatures, in its history. The matching CI
+# guard is the shared HeroicLands/.github/actions/no-attribution action, which
+# this repository's .github/workflows/no-attribution.yml calls. That action holds
+# the pattern for every repository; this hook is the only other copy, because a
+# git hook runs from your checkout and cannot live in an action. Keep them in sync.
+#
+# Installed for everyone via the package.json "prepare" script, which points
+# git at this directory (`git config core.hooksPath .githooks`) on `npm install`.
+
+. "$(dirname "$0")/hook-enabled.sh"
+
+# On unless refused: it costs nothing, and the No Attribution workflow enforces
+# the same rule on GitHub, so opting out locally only moves the failure later.
+hook_enabled noAttribution true || exit 0
+
+msg_file="$1"
+
+# Scan only the real message: drop the diff appended by `commit --verbose` (from
+# the scissors comment onward) and strip remaining comment lines.
+content="$(sed '/^#.*>8/,$d' "$msg_file" | grep -v '^#')"
+
+# Anchored to the start of a line: real attribution is a trailer / signature at
+# column 0, so prose that merely *mentions* these phrases mid-sentence (e.g. this
+# hook's own docs) does not trip it. The generated-with branch tolerates a
+# leading emoji/space.
+pattern='^[[:space:]]*co-authored-by:.*(claude|anthropic)|^[^[:alpha:]]*generated with .*claude code'
+
+if printf '%s\n' "$content" | grep -iEq "$pattern"; then
+    echo "commit-msg: AI/assistant attribution is not allowed in commit messages." >&2
+    printf '%s\n' "$content" | grep -iEn "$pattern" | sed 's/^/    /' >&2
+    echo "Remove the 'Co-Authored-By: …' / 'Generated with Claude Code' line and commit again." >&2
+    exit 1
+fi
+
+exit 0

package/githooks/hook-enabled.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+#
+# Whether one hook is switched on, so every hook asks the same way.
+#
+# `hook_enabled <key> <default>` reads `hooks.<key>` with git's normal
+# precedence — a plain `git config` sets it for one clone, `--global` for a
+# machine — and falls back to the hook's own default when unset. Each hook has
+# its own key, so they are turned on and off individually rather than as a set:
+# a repository may well want the branch guard and not the workflow check, or
+# the reverse.
+#
+# Defaults differ by hook, and deliberately: a guard that costs nothing is on
+# unless refused, while one that runs a container for minutes is off unless
+# asked for.
+
+hook_enabled() {
+    _key="$1"
+    _default="$2"
+    _value="$(git config --bool "hooks.$_key" 2>/dev/null)"
+    if [ -z "$_value" ]; then
+        [ "$_default" = "true" ]
+        return $?
+    fi
+    [ "$_value" = "true" ]
+}

package/githooks/pre-commit

@@ -0,0 +1,11 @@
+#!/usr/bin/env sh
+#
+# Refuse to commit on a protected branch. See protected-branch.sh for the rule
+# and its opt-outs; pre-merge-commit is this hook's counterpart for merges.
+#
+# Installed for everyone via the package.json "prepare" script, which points git
+# at this directory (`git config core.hooksPath .githooks`) on `npm install`.
+
+. "$(dirname "$0")/protected-branch.sh"
+
+guard_protected_branch

package/githooks/pre-merge-commit

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+#
+# Refuse to create a *merge* commit on a protected branch — the `git pull` on
+# main case, which pre-commit never sees, because git runs this hook instead of
+# that one for a merge. See protected-branch.sh for the rule and its opt-outs.
+#
+# Installed for everyone via the package.json "prepare" script, which points git
+# at this directory (`git config core.hooksPath .githooks`) on `npm install`.
+
+. "$(dirname "$0")/protected-branch.sh"
+
+guard_protected_branch

package/githooks/pre-push

@@ -0,0 +1,109 @@
+#!/usr/bin/env sh
+#
+# Before pushing, run exactly what the Build & Test workflow runs — in a
+# container, over a clean export of HEAD — so a red GitHub check is something
+# you chose rather than something you discover.
+#
+# The steps are not listed here. `utils/ci-steps.mjs` reads them out of
+# `.github/workflows/build.yml`, because 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, since running four of five steps still exits 0.
+#
+# **On push rather than at `gh pr create`**, because a push is where this
+# repository's work reaches GitHub: normally one, just before the pull request.
+# Nothing to remember, no wrapper command, and no entry in package.json — the
+# hook is the whole mechanism.
+#
+# **In a container rather than on this machine**, which is not the obvious
+# choice until you time it. The workflow's first step is `npm ci`, so a local
+# run costs very nearly what the container costs (134s measured, cold) — and it
+# pays that by deleting and reinstalling your working tree's `node_modules`
+# every time. The container runs a `git archive` of HEAD instead: same price,
+# nothing of yours touched, plus the three classes this machine cannot catch —
+# a dirty environment, a case-sensitive filesystem, and the runner's own
+# architecture. It runs `linux/amd64` to match the runner, which costs nothing
+# measurable because Docker Desktop translates it with Rosetta rather than
+# QEMU; `ci/ci-docker.mjs` carries the timings and the `--native` opt-out.
+#
+# This hook ships in `@heroiclands/package-build`. A consuming repository points
+# git at it once, in its package.json "prepare" script:
+#
+#     git config core.hooksPath node_modules/@heroiclands/package-build/githooks
+#
+# so the hooks are the package's, not a copy per repository — there were twenty
+# copies of four identical files before this moved.
+#
+# **Off by default.** Turn it on where you want it:
+#
+#     git config hooks.prePushCi true            this clone
+#     git config --global hooks.prePushCi true   every repository on this machine
+#
+# **Docker is not required even then.** Without it the check reports that it
+# could not run, says so loudly, and lets the push through — the workflow itself
+# is what enforces this, and a contributor without Docker is still entitled to
+# open a pull request. First run pulls the image (~400MB), once.
+#
+# Skipping it once, when enabled: git push --no-verify
+#
+# Deleting a remote branch pushes no commits, so there is nothing to check and
+# the hook stands aside.
+
+# **Off unless asked for.** This runs a container for a couple of minutes, and
+# it ships to every repository that installs this package — so it cannot be
+# something a contributor discovers by having their push get slow. Opting in is
+# a deliberate act by whoever wants the check.
+#
+# Read with git's normal precedence, so `--global` opts a machine in and a plain
+# `git config` opts in one clone (and every worktree of it).
+#
+# Silent when off: a message on every push, to everyone who never asked for
+# this, is noise.
+. "$(dirname "$0")/hook-enabled.sh"
+
+hook_enabled prePushCi false || exit 0
+
+# Read the ref list on stdin; a delete has an all-zero local sha.
+has_commits=""
+while read -r _local_ref local_sha _remote_ref _remote_sha; do
+    case "$local_sha" in
+        *[!0]*) has_commits="yes" ;;
+    esac
+done
+if [ -z "$has_commits" ]; then
+    exit 0
+fi
+
+echo "pre-push: running the Build & Test workflow in a container over HEAD."
+echo "pre-push: to skip once, push with --no-verify."
+
+# The runner lives beside this hook inside the package. If it is not there,
+# this hook is being used from somewhere else — a global `core.hooksPath`, a
+# copy — in a repository that does not install the package. Nothing to run, and
+# certainly nothing to refuse a push over.
+runner="$(dirname "$0")/../ci/ci-docker.mjs"
+if [ ! -f "$runner" ]; then
+    echo "pre-push: no workflow runner alongside this hook; skipping the check."
+    exit 0
+fi
+
+node "$runner"
+status=$?
+
+# 2 means the check could not run — no Docker — which is not the same as a
+# failure and must not stop the push. Whoever is pushing may not be the
+# maintainer, may be on a machine without Docker, and is entitled to open a
+# pull request; GitHub is what enforces the workflow. Said loudly, though: a
+# skipped check that reads like a passed one is how a guard loses its meaning.
+# 127 is "could not execute it at all" — no node on PATH, package not
+# installed. Infrastructure, not a verdict, so it is handled the same way.
+if [ "$status" -eq 2 ] || [ "$status" -eq 127 ]; then
+    echo ""
+    echo "pre-push: pushing WITHOUT having checked the workflow locally."
+    exit 0
+fi
+
+if [ "$status" -ne 0 ]; then
+    echo ""
+    echo "pre-push: refusing to push — GitHub would report the same failure."
+    exit 1
+fi

package/githooks/protected-branch.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env sh
+#
+# Shared guard: refuse to create a commit while HEAD is on a protected branch.
+#
+# Sourced by the pre-commit and pre-merge-commit hooks, which are two hooks for
+# one rule: git runs pre-merge-commit *instead of* pre-commit when the commit is
+# a merge, so a repository that guards only pre-commit still lets a stray
+# `git pull` on main write a merge commit.
+#
+# Why guard at commit time at all: `main` is protected on GitHub in every
+# HeroicLands repository — changes land by pull request, squash-merged, never by
+# a direct push. That protection fires at *push* time, by which point the commit
+# already exists on the local branch and has to be moved off it. This moves the
+# refusal forward to the point where the fix is still just "branch first".
+#
+# It is an accident guard, not a security control. `git commit --no-verify`
+# bypasses it, and a repository that genuinely wants commits on its default
+# branch opts out with `git config hooks.allowCommitOnMain true`.
+#
+# Known gap: `git cherry-pick` and `git revert` run neither hook, and a rebase
+# replays commits with HEAD detached (deliberately allowed below).
+#
+# This file is copied verbatim into every HeroicLands repository, for the same
+# reason the commit-msg hook is: a hook runs from your checkout, so it cannot be
+# shared through a GitHub Action. Keep the copies identical.
+
+guard_protected_branch() {
+    . "$(dirname "$0")/hook-enabled.sh"
+
+    # Off where this repository says so. Two spellings: `hooks.protectedBranch`
+    # is this hook's key in the per-hook scheme, and `hooks.allowCommitOnMain`
+    # is the name that has always meant this — kept, and still honoured, so an
+    # existing opt-out does not quietly stop working.
+    if ! hook_enabled protectedBranch true; then
+        return 0
+    fi
+    if [ "$(git config --bool hooks.allowCommitOnMain 2>/dev/null)" = "true" ]; then
+        return 0
+    fi
+
+    # Detached HEAD — a rebase, a bisect, or an explicit checkout of a commit.
+    # There is no branch to protect, and refusing here would break `git rebase`.
+    branch="$(git symbolic-ref --quiet --short HEAD)" || return 0
+
+    case "$branch" in
+        main | master) ;;
+        *) return 0 ;;
+    esac
+
+    cat >&2 <<EOF
+$(basename "$0"): refusing to commit on the protected branch '$branch'.
+
+'$branch' is protected on GitHub, so this commit could never be pushed from
+here. Move it onto a branch first — this keeps everything you have staged:
+
+    git switch -c <type>/<issue_#>_<slug>
+
+To commit here anyway just this once, use 'git commit --no-verify'. To opt this
+repository out permanently, 'git config hooks.allowCommitOnMain true'.
+EOF
+    return 1
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "18.1.1",
+    "version": "18.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",
@@ -105,6 +105,7 @@
         "README.md",
         "bin",
         "bundle.mjs",
+        "ci",
         "config.mjs",
         "container.mjs",
         "content-config.mjs",
@@ -113,6 +114,7 @@
         "deploy.mjs",
         "e2e.mjs",
         "engine",
+        "githooks",
         "hm3",
         "index.mjs",
         "lang.mjs",