@heroiclands/package-build 18.1.1 → 19.0.0

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/hm3/actors.mjs

@@ -259,16 +259,13 @@ export class Hm3Actors extends SystemActorCompiler {
                 locateFrontmatterKey(this.currentNote?.absPath, field.legacyKey),
             );
 
-        // Both spellings, as everywhere else: `packFolder` is a folder note's
-        // address and `folder` a Foundry id, and which one applies comes from
-        // the field it was written in rather than from the string (#251, #255).
-        // This pass read only the id, so an HM3 tree could not file an actor by
-        // address at all — which its own sweep needs.
-        const packFolderAddress = blockField(fm, block, "packFolder", null);
-        const folder =
-            packFolderAddress ?
-                this.folderResolver(packFolderAddress, { isAddress: true })
-            :   this.folderResolver(blockField(fm, block, "folder", null));
+        // One spelling, as everywhere else: `packFolder` names a folder note
+        // by its address. This pass once read only the Foundry id, so an HM3
+        // tree could not file an actor by address at all — which its own sweep
+        // needs; the id spelling is retired outright (#251, #255, #260).
+        const folder = this.folderResolver(blockField(fm, block, "packFolder", null), {
+            isAddress: true,
+        });
 
         const system = {
             // Nullish, not `||` (#218): a note that names no portrait gets the

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "18.1.1",
+    "version": "19.0.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",

package/types/content-config.d.mts

@@ -214,12 +214,6 @@ export type PackSpec = {
      * Whether the pack is GM-only. Default `false`.
      */
     private?: boolean | undefined;
-    /**
-     * The pack's folder-hierarchy file, relative
-     *     to `paths.content`. Default `null` — no
-     *     folder documents are emitted.
-     */
-    folders?: string | null | undefined;
     /**
      * Directory holding this pack's per-document
      *        JSON, already built. Declaring it skips
@@ -268,7 +262,6 @@ export type ResolvedPackSpec = {
     type: PackDocumentType;
     label: string;
     private: boolean;
-    folders: string | null;
     prebuilt: string | null;
     system: string | null;
     companions: readonly Readonly<ResolvedPackSpec>[];

package/types/engine/folder-notes.d.mts

@@ -77,6 +77,45 @@ export function buildFolderNoteIndex(folders: FolderNote[]): {
  * @returns {object} The Folder document.
  */
 export function folderDocument(folder: FolderNote, parent: FolderNote | null, documentType: string, stats: object): object;
+/**
+ * Refuse a note that declares the retired `folder:` spelling.
+ *
+ * `folder:` named a compendium folder by the raw Foundry id declared in a
+ * per-pack `*-folders.yaml`. Both halves are retired together (#260): the id
+ * spelling has nothing left to resolve against once the YAML is gone, and the
+ * YAML has no reader once the spelling is refused.
+ *
+ * **Presence is the whole test.** An empty `folder:` — which parses as `null`
+ * — 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 the message says what to write instead rather than which value
+ * to change.
+ *
+ * **Both positions**, because notes wrote it both ways: top-level, and inside
+ * the `sohl:` block. Checking only the more common one is how a sweep leaves
+ * a tail behind.
+ *
+ * Refused rather than ignored, on the pattern `package:` set: 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.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @param {string} [options.absPath] - The note's file on disk, read only on
+ *   the failing path to locate the offending line and column. The position
+ *   rides on the thrown error as `position`, for a caller that emits a
+ *   diagnostic.
+ * @returns {void}
+ * @throws {Error} When the note declares the field.
+ */
+export function assertNoDeclaredFolder(fm: object | null | undefined, { file, absPath }?: {
+    file?: string | undefined;
+    absPath?: string | undefined;
+}): void;
 /**
  * The note type a folder is authored as.
  *

package/types/engine/helpers.d.mts

@@ -428,41 +428,12 @@ export function expandNoteTables(body: string, { docs, name, fm, bodyLine, sqlTa
         generated: boolean;
     }>;
 };
-/**
- * Loads a folders.yaml file as an array of folder entries. Returns []
- * when the file is missing (logging a warning) so packs without folders
- * can opt out simply by not committing the file.
- */
-export function loadFolders(foldersFile: any): any[];
-/**
- * Validates folder invariants and returns a resolver function that maps a
- * folder id to the same id (after verifying it exists). Returns `null` for
- * a null/empty input; throws for an unknown id.
- *
- * Invariants:
- *   - Every folder must have a non-empty id
- *   - Every folder must have a name
- *   - Sibling folders (same parentFolderId) must have unique names
- *   - Every parentFolderId must match an existing folder id (or be "")
- *
- * Returns { resolver, folders } where folders is the validated list.
- */
-export function buildFolderResolver(folders: any): {
-    resolver: (value: string | null | undefined) => string | null;
-    folders: any;
-};
 /**
  * Builds a compendium-source filename for a folder JSON document:
  * `folder_Name_id.json` with non-alphanumeric runs replaced by
  * underscores.
  */
 export function folderFilename(name: any, id: any): string;
-/**
- * Writes one JSON document per folder into `destDir`. `documentType`
- * determines the folder's Foundry `type` field — `"Item"` for the items
- * pack, `"JournalEntry"` for the journals pack.
- */
-export function writeFolderDocs(folders: any, stats: any, destDir: any, documentType: any): void;
 export const md: import("markdown-it").MarkdownIt;
 export { slugify } from "./content-slug.mjs";
 export { makeId } from "./ids.mjs";