@heroiclands/package-build 23.5.0 → 23.5.1

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @heroiclands/package-build
 
+## 23.5.1
+
+### Patch Changes
+
+`cdn publish` skips SVGs the CDN already holds, so a re-run uploads only what changed.
+
+`package-build labels check` is gone, because issue labels are defined once for the whole organisation; remove any `lint:labels` script and `.github/labels.yml`. A project created by `package-build init` no longer gets a label registry.
+
 ## 23.5.0
 
 ### Minor Changes

package/bin/package-build.mjs

@@ -114,7 +114,6 @@ import { walkMarkdownTree } from "../engine/helpers.mjs";
 import { reckoningContext } from "../engine/reckoning-markers.mjs";
 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 { lintChangesetText, lintReleaseText } from "../engine/changelog-lint.mjs";
 import { groupChangelogText } from "../engine/changelog-group.mjs";
@@ -1328,77 +1327,6 @@ function changelogGroup(args) {
     console.log(`package-build: ${files.length} file(s) grouped · ${warnings} warning(s)`);
 }
 
-/**
- * `labels check` — do the machine registry and the documented table agree?
- *
- * `.github/labels.yml` is synced to GitHub and the §3 table in
- * `.github/ISSUE_REPORTING.md` is what a person reads. Neither derives from the
- * other, so either can drift, and nothing notices until an issue is filed
- * against a label that does not exist.
- *
- * Every repository wants this and only the paths ever differed, which is why it
- * is here rather than copied into each as a `utils/` script.
- *
- * @returns {object} The yargs command module.
- */
-function labelsCommand() {
-    return {
-        command: "labels <action>",
-        describe: "Issue-label registry checks",
-        builder: (y) =>
-            y
-                .positional("action", {
-                    choices: ["check"],
-                    describe: "check: the registry and the documented table name the same labels",
-                })
-                .option("registry", {
-                    type: "string",
-                    default: ".github/labels.yml",
-                    describe: "The machine registry synced to GitHub",
-                })
-                .option("doc", {
-                    type: "string",
-                    default: ".github/ISSUE_REPORTING.md",
-                    describe: "The documented reference whose §3 table lists the same labels",
-                }),
-        handler: handler(async (args) => labelsCheck(args)),
-    };
-}
-
-/**
- * Read both faces of the registry and report where they disagree.
- *
- * Findings are reported against the file each belongs to, so a missing row is
- * located in the documentation and a missing entry in the registry, rather than
- * both being attributed to whichever file was read first.
- *
- * @param {object} args - Parsed CLI arguments.
- */
-function labelsCheck(args) {
-    for (const target of [args.registry, args.doc]) {
-        if (!fs.existsSync(target)) die(`labels check: ${target} does not exist.`);
-    }
-    const registryText = fs.readFileSync(args.registry, "utf8");
-    const docText = fs.readFileSync(args.doc, "utf8");
-
-    const { registry, doc, count } = checkLabelRegistry({
-        registryText,
-        docText,
-        docPath: args.doc,
-    });
-
-    const errors =
-        reportFindings(registry, { file: args.registry }) + reportFindings(doc, { file: args.doc });
-    if (errors) {
-        console.error(
-            `\nThe registry and ${args.doc} §3 are edited together — ` +
-                `change one and change the other.`,
-        );
-        process.exit(1);
-    }
-    console.log(`package-build: registry and §3 agree (${count} labels).`);
-}
-
 /**
  * `lang <action>` — the three localization guards.
  *
@@ -1641,7 +1569,7 @@ function cdnPublishCommand() {
                 .option("set", {
                     type: "string",
                     demandOption: true,
-                    describe: "The set file's name under the package's CDN root, e.g. ai-art.json",
+                    describe: "The set file's name under the package's CDN root, e.g. alt-art.json",
                 })
                 .option("name", {
                     type: "string",
@@ -1972,7 +1900,6 @@ registerContentCommands(
         .command(typesCommand())
         .command(schemaCommand())
         .command(langCommand())
-        .command(labelsCommand())
         .command(bumpCommand())
         .command(yamlCommand())
         .command(changelogCommand())

package/docs/commands.md

@@ -789,50 +789,6 @@ package-build: 1 template(s) fully localized and compiling.
 `package-build lang check`, `package-build lang coverage`,
 [Diagnostics](diagnostics.md), [Configuration](configuration.md).
 
-### `package-build labels check`
-
-**NAME**
-
-Compare the machine label registry against the documented reference table
-(`check` is the only action).
-
-**SYNOPSIS**
-
-```
-package-build labels check [--registry <path>] [--doc <path>]
-```
-
-**DESCRIPTION**
-
-Compares the machine label registry synced to GitHub against the documented
-reference table, and reports where they disagree — a label the registry has
-that the table does not, or the reverse. Neither derives from the other, so
-nothing else notices when they drift. Reads both files named below; writes
-nothing.
-
-**OPTIONS**
-
-| Option       | Type   | Default                      | Description                                                    |
-| ------------ | ------ | ---------------------------- | -------------------------------------------------------------- |
-| `--registry` | string | `.github/labels.yml`         | The machine registry synced to GitHub.                         |
-| `--doc`      | string | `.github/ISSUE_REPORTING.md` | The documented reference whose §3 table lists the same labels. |
-
-**EXIT STATUS**
-
-1 if either file does not exist. 1 if the registry and the table disagree on
-any label. Otherwise 0.
-
-**EXAMPLES**
-
-```
-$ package-build labels check --registry .github/labels.yml --doc .github/ISSUE_REPORTING.md
-package-build: registry and §3 agree (11 labels).
-```
-
-**SEE ALSO**
-
-None.
-
 ### `package-build bump [packages..]`
 
 **NAME**
@@ -1348,7 +1304,7 @@ A workflow calls the command the same way, passing the four values as named
 secrets in the step's environment:
 
 ```yaml
-- run: npx package-build cdn publish --set ai-art.json --name "Thalorna — illustrated"
+- run: npx package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
   env:
     CDN_ENDPOINT: ${{ secrets.CDN_ENDPOINT }}
     CDN_BUCKET: ${{ secrets.CDN_BUCKET }}
@@ -1374,12 +1330,12 @@ it. Otherwise 0.
 **EXAMPLES**
 
 ```
-$ package-build cdn publish --set ai-art.json --name "Thalorna — illustrated" --dry-run
+$ package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
 Dry run: comparing 582 pictures against https://cdn.heroiclands.org, read-only.
   would upload thalorna/icons/anvilbdg.svg (969 bytes)
   …
-  would upload thalorna/ai-art.json (582 assets)
-Would upload 582, skipped 0, failed 0; https://cdn.heroiclands.org/thalorna/ai-art.json lists 582 left-out pictures (would change).
+  would upload thalorna/alt-art.json (582 assets)
+Would upload 582, skipped 0, failed 0; https://cdn.heroiclands.org/thalorna/alt-art.json lists 582 left-out pictures (would change).
 
 $ package-build cdn publish --set default.json --name Shipped
 package-build: `--set default.json` is refused: `default.json` is the shipped set's name, the fallback every other set is read against. Name the set for its art

package/docs/diagnostics.md

@@ -284,7 +284,7 @@ when it reports at least one `error`-severity diagnostic. A `warning` alone
 never fails a run.** `bin/report.mjs`'s `reportFindings` draws this line once
 for the commands built from the package's pure rule functions (`package-build
 lint`, `package-build lang check`, `package-build lang coverage`,
-`package-build yaml`, `package-build labels check`): it emits every finding
+`package-build yaml`): it emits every finding
 and returns only the count whose `severity` is `error`, and the command sets
 `process.exitCode = 1` exactly when that count is nonzero. Commands whose
 findings are hand-assembled — `package-build links`, `package-build
@@ -335,7 +335,6 @@ over one would teach people to stop reading the report.
 | `package-build lang check`                       | any localization finding is `error`-severity                                                                                                                                                                                                                       |
 | `package-build lang coverage`                    | a referenced key is missing (`error`-severity); an unreferenced key is always advisory and never fails the run                                                                                                                                                     |
 | `package-build yaml [paths..]`                   | any YAML finding is `error`-severity                                                                                                                                                                                                                               |
-| `package-build labels check`                     | the label registry and the documented table disagree on any label                                                                                                                                                                                                  |
 
 Every command also fails on a thrown error unrelated to a
 diagnostic — a missing configuration, an unreadable file, a network failure —

package/docs/guides/module-project.md

@@ -861,7 +861,7 @@ everything that reads the tree runs before everything that writes the stage.
 
 [`project-setup.md`](../project-setup.md) turns this into npm scripts, and covers
 everything a repository carries beyond the build itself: the git hooks, the
-changeset directory, the label registry, and what each script in the chain is
+changeset directory, and what each script in the chain is
 for.
 
 ## What comes next

package/docs/guides/release-and-deploy.md

@@ -139,13 +139,13 @@ reaches a world from there as a named asset set. `package-build cdn publish`
 is the one command that writes there:
 
 ```bash
-package-build cdn publish --set ai-art.json --name "Thalorna — illustrated" --dry-run
-package-build cdn publish --set ai-art.json --name "Thalorna — illustrated"
+package-build cdn publish --set alt-art.json --name "Thalorna — illustrated" --dry-run
+package-build cdn publish --set alt-art.json --name "Thalorna — illustrated"
 ```
 
 It uploads every icon and image flat, transformed as the stage transforms
 them, skips what the CDN already holds at the same size, and writes
-`<site.assets>/<contentPackage>/ai-art.json` listing the left-out pictures.
+`<site.assets>/<contentPackage>/alt-art.json` listing the left-out pictures.
 Run it after the pictures or their provenance change; it is not part of a
 build or a release.
 

package/docs/project-setup.md

@@ -30,8 +30,7 @@ acme-bestiary/
 │   ├── config.json
 │   └── *.md                      # one per unreleased change
 ├── .github/
-│   ├── labels.yml                # the closed label registry
-│   ├── ISSUE_REPORTING.md        # §3 lists the same labels
+│   │   ├── ISSUE_REPORTING.md        # how issues are filed
 │   └── workflows/
 ├── assets/
 │   └── content/                  # authored Markdown notes
@@ -161,19 +160,18 @@ anything to remove.
 
 ### `lint:*` — the checks, one per question
 
-Seven checks, each answering one question and blind to what the others see.
+Six checks, each answering one question and blind to what the others see.
 They are separate scripts rather than one because a failing chain stops at its
 first failure, and knowing _which_ question failed is most of the diagnosis.
 
 ```json
-"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:labels lint:changelog",
+"lint": "run-s lint:format lint:markdown lint:addresses lint:content-links lint:lang lint:changelog",
 "lint:format": "package-build format",
 "lint:markdown": "package-build markdown",
 "lint:markdown:fix": "package-build markdown --fix",
 "lint:addresses": "package-build lint",
 "lint:content-links": "package-build links",
 "lint:lang": "package-build lang check",
-"lint:labels": "package-build labels check",
 "lint:changelog": "package-build changelog check"
 ```
 
@@ -194,9 +192,6 @@ first failure, and knowing _which_ question failed is most of the diagnosis.
   `package-build lang coverage` and `package-build lang hardcoded`; a
   content-only package has nothing for those two to read, and each dies naming
   the glob that matched nothing rather than passing vacuously.
-- **`lint:labels`** — do `.github/labels.yml` and §3 of
-  `.github/ISSUE_REPORTING.md` still list the same labels? Neither derives from
-  the other, so nothing else notices when they drift.
 - **`lint:changelog`** — does every pending `.changeset/*.md` read like a
   release note rather than a pasted pull-request description? Passes
   trivially when nothing is pending: no pull request is required to carry a
@@ -499,46 +494,9 @@ tool:
 
 ## `.github/`
 
-Two files the toolchain reads, and they must agree.
-
-**`.github/labels.yml`** is the closed label registry — the machine-readable
-source of truth, synced to GitHub by the org-wide `labels` action. A label on
-GitHub that is not listed there is deleted on the next sync, which is what makes
-the set closed and why nothing invents one.
-
-```yaml
-- name: documentation
-  color: "0075ca"
-  description: Documentation about this repository — README, process, authoring guides.
-
-- name: devops
-  color: "e07b31"
-  description: Build, tooling, CI, release, repo config.
-```
-
-**`.github/ISSUE_REPORTING.md`** §3 is the same list in prose, for a human
-filing an issue. `package-build labels check` compares the two and fails when
-they disagree:
-
-```console
-$ npx package-build labels check
-package-build: registry and §3 agree (2 labels).
-```
-
-Neither file derives from the other, so this check is the only thing standing
-between them and a silent divergence. Editing the registry means editing both.
-
-Labels are **subject matter only**. Work shape — bug, feature, epic, task, spike
-— is an issue _type_, shared across the organization, so there is no `bug` label
-and filtering on one returns nothing.
-
-Neither file exists in a fresh repository, and `labels check` says so rather
-than passing vacuously:
-
-```console
-$ npx package-build labels check
-package-build: labels check: .github/labels.yml does not exist.
-```
+**`.github/ISSUE_REPORTING.md`** says how issues are filed. Labels are
+organisation-level and defined in `HeroicLands/.github`, so the repository
+carries no label registry of its own.
 
 `.github/workflows/` then carries the repository's own CI. The org-wide
 `HeroicLands/.github` repository supplies the shared composite actions those
@@ -549,17 +507,16 @@ site-deploy workflow, so a fix to any of them reaches every repository at once.
 
 A summary, because "where does this come from" is the question that recurs.
 
-| Read                                               | By                                                                                                        |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `package.json`                                     | The Foundry package id, the version, the release addresses; the site's `baseURL`, description and author. |
-| `package-build.config.yaml`                        | Everything else about the build.                                                                          |
-| `assets/content/**/*.md`                           | Every content command.                                                                                    |
-| `.gitignore`                                       | `package-build format`, `package-build markdown`.                                                         |
-| `.prettierignore`                                  | `package-build format`.                                                                                   |
-| `.github/labels.yml`, `.github/ISSUE_REPORTING.md` | `package-build labels check`.                                                                             |
-| `lang/*.json`                                      | `package-build lang`.                                                                                     |
-| `.env.local`                                       | `package-build deploy`.                                                                                   |
-| `.github/workflows/build.yml`                      | The `pre-push` hook, for its step list.                                                                   |
+| Read                          | By                                                                                                        |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `package.json`                | The Foundry package id, the version, the release addresses; the site's `baseURL`, description and author. |
+| `package-build.config.yaml`   | Everything else about the build.                                                                          |
+| `assets/content/**/*.md`      | Every content command.                                                                                    |
+| `.gitignore`                  | `package-build format`, `package-build markdown`.                                                         |
+| `.prettierignore`             | `package-build format`.                                                                                   |
+| `lang/*.json`                 | `package-build lang`.                                                                                     |
+| `.env.local`                  | `package-build deploy`.                                                                                   |
+| `.github/workflows/build.yml` | The `pre-push` hook, for its step list.                                                                   |
 
 Everything written goes under `build/`. Nothing the toolchain generates is
 committed.

package/engine/cdn-publish.mjs

@@ -179,7 +179,8 @@ export function cdnCredentials(env) {
  *
  * @typedef {object} CdnStore
  * @property {(key: string) => Promise<number|undefined>} size - An object's
- *   size in bytes, `undefined` when there is none.
+ *   size in bytes, `undefined` when there is none or the store does not state
+ *   it.
  * @property {(key: string) => Promise<Buffer|undefined>} read - An object's
  *   bytes, `undefined` when there is none.
  * @property {((key: string, body: Buffer, contentType: string) => Promise<void>)|undefined} write -
@@ -188,6 +189,26 @@ export function cdnCredentials(env) {
  *   secret.
  */
 
+/**
+ * Request headers that keep the CDN from compressing a HEAD answer: a
+ * gzip-encoded answer carries no content-length.
+ */
+const IDENTITY = { "accept-encoding": "identity" };
+
+/**
+ * The object size a HEAD answer states.
+ *
+ * @param {Response} response - A successful HEAD response.
+ * @returns {number|undefined} The content-length, `undefined` when the answer
+ *   states none.
+ */
+function contentLength(response) {
+    const header = response.headers.get("content-length");
+    if (header === null || header.trim() === "") return undefined;
+    const length = Number(header);
+    return Number.isFinite(length) && length >= 0 ? length : undefined;
+}
+
 /**
  * Throw for a response the store refused.
  *
@@ -224,10 +245,10 @@ export function s3Store({ endpoint, bucket, accessKeyId, secretAccessKey, fetch:
     return {
         describe: `bucket ${bucket} at ${new URL(endpoint).host}`,
         async size(key) {
-            const response = await send(key, { method: "HEAD" });
+            const response = await send(key, { method: "HEAD", headers: IDENTITY });
             if (response.status === 404) return undefined;
             if (!response.ok) refused(`HEAD ${key}`, response);
-            return Number(response.headers.get("content-length"));
+            return contentLength(response);
         },
         async read(key) {
             const response = await send(key, { method: "GET" });
@@ -256,14 +277,18 @@ export function s3Store({ endpoint, bucket, accessKeyId, secretAccessKey, fetch:
  */
 export function publicStore(host, fetchImpl) {
     const base = host.replace(/\/+$/, "");
-    const get = (key, method) => (fetchImpl ?? fetch)(`${base}/${key}`, { method });
+    const get = (key, method) =>
+        (fetchImpl ?? fetch)(`${base}/${key}`, {
+            method,
+            headers: method === "HEAD" ? IDENTITY : undefined,
+        });
     return {
         describe: `${base}, read-only`,
         async size(key) {
             const response = await get(key, "HEAD");
             if (response.status === 404 || response.status === 403) return undefined;
             if (!response.ok) refused(`HEAD ${key}`, response);
-            return Number(response.headers.get("content-length"));
+            return contentLength(response);
         },
         async read(key) {
             const response = await get(key, "GET");

package/engine/project-init.mjs

@@ -20,7 +20,6 @@ import prettier from "prettier";
 import prettierConfig from "../prettier-config.mjs";
 import { CONFIG_FILENAMES, configFromData } from "./pack-config.mjs";
 import { positionOfYamlPath } from "./diagnostics.mjs";
-import { checkLabelRegistry } from "../labels.mjs";
 import { formatNoteFrontmatter } from "./note-format.mjs";
 
 /** Package kinds the initializer can create. */
@@ -94,13 +93,12 @@ function projectScripts(answers) {
         "serve:site": "run-s build:deps build:content-index build:site-content serve:site-html",
         "serve:site-html": "hugo server --source build/hugo",
         "build:book": "package-build pdf",
-        lint: "run-s lint:format lint:markdown lint:addresses lint:content-links lint:labels",
+        lint: "run-s lint:format lint:markdown lint:addresses lint:content-links",
         "lint:format": "package-build format",
         "lint:markdown": "package-build markdown",
         "lint:markdown:fix": "package-build markdown --fix",
         "lint:addresses": "package-build lint",
         "lint:content-links": "package-build links",
-        "lint:labels": "package-build labels check",
         format: "package-build format --write",
         "format:check": "package-build format",
         changeset: "changeset",
@@ -125,8 +123,7 @@ function projectScripts(answers) {
         "push:qa": "package-build deploy qa",
         "push:prod": "package-build deploy prod",
     });
-    scripts.lint =
-        "run-s lint:format lint:markdown lint:lang lint:addresses lint:content-links lint:labels";
+    scripts.lint = "run-s lint:format lint:markdown lint:lang lint:addresses lint:content-links";
     return scripts;
 }
 
@@ -295,14 +292,6 @@ function projectText(answers) {
             updateInternalDependencies: "patch",
             ignore: [],
         }),
-        ".github/labels.yml": YAML.stringify([
-            {
-                name: "documentation",
-                color: "0075ca",
-                description: "Documentation and author guides.",
-            },
-            { name: "devops", color: "e07b31", description: "Build, CI, and release work." },
-        ]),
         ".github/ISSUE_REPORTING.md": [
             "# Issue reporting",
             "",
@@ -314,12 +303,9 @@ function projectText(answers) {
             "",
             "Use the organization issue type for a bug, feature, task, spike, or epic.",
             "",
-            "## 3. Labels — the closed registry",
+            "## 3. Labels",
             "",
-            "| Label | Use it for |",
-            "| ----- | ---------- |",
-            "| `documentation` | Documentation and author guides. |",
-            "| `devops` | Build, CI, and release work. |",
+            "Labels are organization-level, defined in `HeroicLands/.github`.",
             "",
         ].join("\n"),
         ".github/workflows/build.yml": [
@@ -437,7 +423,6 @@ export function checkProject(rootDir) {
         "README.md",
         "LICENSE.md",
         ".changeset/config.json",
-        ".github/labels.yml",
         ".github/ISSUE_REPORTING.md",
         ".github/workflows/build.yml",
     ];
@@ -525,15 +510,5 @@ export function checkProject(rootDir) {
     } else if (!fs.readdirSync(contentRoot).some((file) => file.endsWith(".md"))) {
         add("assets/content", "the content tree has no notes");
     }
-    const labelsPath = path.join(root, ".github/labels.yml");
-    const reportingPath = path.join(root, ".github/ISSUE_REPORTING.md");
-    if (fs.existsSync(labelsPath) && fs.existsSync(reportingPath)) {
-        const result = checkLabelRegistry({
-            registryText: fs.readFileSync(labelsPath, "utf8"),
-            docText: fs.readFileSync(reportingPath, "utf8"),
-        });
-        for (const finding of result.registry) add(".github/labels.yml", finding.message);
-        for (const finding of result.doc) add(".github/ISSUE_REPORTING.md", finding.message);
-    }
     return findings;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "23.5.0",
+    "version": "23.5.1",
     "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",
@@ -120,7 +120,6 @@
         "hugo-theme",
         "index.mjs",
         "lang.mjs",
-        "labels.mjs",
         "manifest.mjs",
         "markdownlint-config.mjs",
         "prettier-config.mjs",
@@ -192,11 +191,10 @@
         "build:asset-index": "node ci/emit-asset-index.mjs",
         "format": "node ci/prettier.mjs --write",
         "format:check": "node ci/prettier.mjs --check",
-        "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:labels lint:image-roles lint:banners lint:content-format lint:docs-links",
+        "lint": "run-p --aggregate-output -c --max-parallel 4 format:check lint:markdown lint:yaml lint:image-roles lint:banners lint:content-format lint:docs-links",
         "lint:markdown": "node bin/package-build.mjs markdown",
         "lint:docs-links": "node bin/package-build.mjs docs links",
         "lint:yaml": "node bin/package-build.mjs yaml",
-        "lint:labels": "node bin/package-build.mjs labels check",
         "lint:image-roles": "vitest run tests/theme-image-roles.test.ts",
         "lint:banners": "node ci/check-banners.mjs",
         "lint:markdown:fix": "node bin/package-build.mjs markdown --fix",

package/types/engine/cdn-publish.d.mts

@@ -220,31 +220,6 @@ export const CDN_ENV: Readonly<{
     accessKeyId: string;
     secretAccessKey: string;
 }>;
-/**
- * A store holding the CDN's objects.
- */
-export type CdnStore = {
-    /**
-     * - An object's
-     * size in bytes, `undefined` when there is none.
-     */
-    size: (key: string) => Promise<number | undefined>;
-    /**
-     * - An object's
-     * bytes, `undefined` when there is none.
-     */
-    read: (key: string) => Promise<Buffer | undefined>;
-    /**
-     * -
-     * Store an object; absent on a read-only store.
-     */
-    write: ((key: string, body: Buffer, contentType: string) => Promise<void>) | undefined;
-    /**
-     * - What the store is, for the log. Never a
-     * secret.
-     */
-    describe: string;
-};
 /**
  * One picture to publish.
  */
@@ -309,3 +284,29 @@ export type CdnPlan = {
      */
     cdnRoot: string;
 };
+/**
+ * A store holding the CDN's objects.
+ */
+export type CdnStore = {
+    /**
+     * - An object's
+     * size in bytes, `undefined` when there is none or the store does not state
+     * it.
+     */
+    size: (key: string) => Promise<number | undefined>;
+    /**
+     * - An object's
+     * bytes, `undefined` when there is none.
+     */
+    read: (key: string) => Promise<Buffer | undefined>;
+    /**
+     * -
+     * Store an object; absent on a read-only store.
+     */
+    write: ((key: string, body: Buffer, contentType: string) => Promise<void>) | undefined;
+    /**
+     * - What the store is, for the log. Never a
+     * secret.
+     */
+    describe: string;
+};

package/labels.mjs

@@ -1,191 +0,0 @@
-/*
- * 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
- */
-
-/**
- * The label registry has two faces that must agree.
- *
- * `.github/labels.yml` is the machine source synced to GitHub, and the §3 table
- * in `.github/ISSUE_REPORTING.md` is the documented reference a person reads.
- * Neither is derived from the other, so either can drift — or invent a label
- * the other has never heard of — and nothing notices until someone files an
- * issue against a label that does not exist, or the sync pushes a label the
- * documentation never mentions.
- *
- * **This lives here because every repository wants it and only the paths ever
- * differed.** It was a `utils/check-labels.mjs` copied per repository, which is
- * the shape a shared check takes just before it starts drifting between copies
- * — the same argument that moved the no-attribution check to a shared action.
- *
- * The checks are pure and text-in: the caller reads the two files and decides
- * what to do with the findings, so this module needs no filesystem and is
- * testable without one.
- *
- * @module
- */
-
-import { parse } from "yaml";
-
-/** GitHub rejects a label description beyond this with a 422. */
-export const MAX_DESCRIPTION = 100;
-
-/**
- * The line a label's `name:` entry sits on, 1-based.
- *
- * Located rather than tracked, because `yaml`'s document API would have to be
- * threaded through the parse for a value this simple to recover: a registry is
- * a flat list of `- name: <label>`, so the first line declaring that name is
- * the entry. A name that cannot be found yields no position, which
- * `reportFindings` drops rather than guessing.
- *
- * @param {string} text - The registry file's contents.
- * @param {string} name - The label name.
- * @returns {{line?: number, column?: number}} Spreadable position fields.
- */
-function positionOfLabel(text, name) {
-    const lines = text.split("\n");
-    for (let i = 0; i < lines.length; i += 1) {
-        const m = lines[i].match(/^\s*-?\s*name:\s*["']?(.+?)["']?\s*$/);
-        if (m && m[1] === name) return { line: i + 1, column: lines[i].indexOf(name) + 1 };
-    }
-    return {};
-}
-
-/**
- * The line a label's row sits on in the documented table, 1-based.
- *
- * @param {string} text - The documentation file's contents.
- * @param {string} name - The label name.
- * @returns {{line?: number, column?: number}} Spreadable position fields.
- */
-function positionOfDocRow(text, name) {
-    const lines = text.split("\n");
-    for (let i = 0; i < lines.length; i += 1) {
-        const m = lines[i].match(/^\|\s*`([a-z][a-z0-9-]*)`\s*\|/);
-        if (m && m[1] === name) return { line: i + 1, column: lines[i].indexOf(name) + 1 };
-    }
-    return {};
-}
-
-/**
- * The label names the documented §3 table lists.
- *
- * A registry row is a table row whose first cell is a backticked label name,
- * which is narrow on purpose: §3 carries prose and other tables, and a looser
- * match would read a heading or an example as a label.
- *
- * @param {string} text - The documentation file's contents.
- * @returns {{names: Set<string>, found: boolean}} The names, and whether §3 was
- *   located at all — an absent section is a different failure from an empty one.
- */
-export function documentedLabels(text) {
-    const lines = text.split("\n");
-    const start = lines.findIndex((l) => /^##\s+3\./.test(l));
-    if (start < 0) return { names: new Set(), found: false };
-    const after = lines.findIndex((l, i) => i > start && /^##\s+\d/.test(l));
-    const section = lines.slice(start, after < 0 ? lines.length : after);
-    const names = new Set();
-    for (const line of section) {
-        const m = line.match(/^\|\s*`([a-z][a-z0-9-]*)`\s*\|/);
-        if (m) names.add(m[1]);
-    }
-    return { names, found: true };
-}
-
-/**
- * Check the machine registry against the documented table.
- *
- * Findings are returned per file rather than merged, because each names a
- * position in a different document and the caller reports them against the
- * file they belong to.
- *
- * @param {object} sources
- * @param {string} sources.registryText - `.github/labels.yml`.
- * @param {string} sources.docText - `.github/ISSUE_REPORTING.md`.
- * @param {string} [sources.docPath] - The doc's path, for the message naming it.
- * @returns {{registry: object[], doc: object[], count: number}} Findings for
- *   each file, and how many labels the registry declares.
- */
-export function checkLabelRegistry({
-    registryText,
-    docText,
-    docPath = ".github/ISSUE_REPORTING.md",
-}) {
-    const registryFindings = [];
-    const docFindings = [];
-
-    let entries;
-    try {
-        entries = parse(registryText);
-    } catch (error) {
-        registryFindings.push({
-            severity: "error",
-            message: `label registry is not valid YAML — ${error.message}`,
-        });
-        return { registry: registryFindings, doc: docFindings, count: 0 };
-    }
-    if (!Array.isArray(entries)) {
-        registryFindings.push({
-            severity: "error",
-            message: "label registry must be a list of `{ name, description }` entries",
-        });
-        return { registry: registryFindings, doc: docFindings, count: 0 };
-    }
-
-    // Caught here rather than mid-sync, where it surfaces as a bare 422 from
-    // the GitHub API naming neither the label nor the limit.
-    for (const entry of entries) {
-        const length = (entry?.description ?? "").length;
-        if (length > MAX_DESCRIPTION) {
-            registryFindings.push({
-                ...positionOfLabel(registryText, entry.name),
-                severity: "error",
-                message:
-                    `"${entry.name}" has a ${length}-character description; ` +
-                    `GitHub rejects anything over ${MAX_DESCRIPTION}`,
-            });
-        }
-    }
-
-    const registryNames = new Set(entries.map((e) => e?.name).filter(Boolean));
-    const { names: docNames, found } = documentedLabels(docText);
-    if (!found) {
-        docFindings.push({
-            severity: "error",
-            message: `no §3 section found in ${docPath}, so the registry has nothing to agree with`,
-        });
-        return { registry: registryFindings, doc: docFindings, count: registryNames.size };
-    }
-
-    for (const name of registryNames) {
-        if (docNames.has(name)) continue;
-        registryFindings.push({
-            ...positionOfLabel(registryText, name),
-            severity: "error",
-            message:
-                `"${name}" is in the registry but not in ${docPath} §3; ` +
-                `the two are edited together, so add the row`,
-        });
-    }
-    for (const name of docNames) {
-        if (registryNames.has(name)) continue;
-        docFindings.push({
-            ...positionOfDocRow(docText, name),
-            severity: "error",
-            message:
-                `"${name}" is documented in §3 but absent from the registry, ` +
-                `so it is never synced and an issue cannot carry it`,
-        });
-    }
-
-    return { registry: registryFindings, doc: docFindings, count: registryNames.size };
-}

package/types/labels.d.mts

@@ -1,40 +0,0 @@
-/**
- * The label names the documented §3 table lists.
- *
- * A registry row is a table row whose first cell is a backticked label name,
- * which is narrow on purpose: §3 carries prose and other tables, and a looser
- * match would read a heading or an example as a label.
- *
- * @param {string} text - The documentation file's contents.
- * @returns {{names: Set<string>, found: boolean}} The names, and whether §3 was
- *   located at all — an absent section is a different failure from an empty one.
- */
-export function documentedLabels(text: string): {
-    names: Set<string>;
-    found: boolean;
-};
-/**
- * Check the machine registry against the documented table.
- *
- * Findings are returned per file rather than merged, because each names a
- * position in a different document and the caller reports them against the
- * file they belong to.
- *
- * @param {object} sources
- * @param {string} sources.registryText - `.github/labels.yml`.
- * @param {string} sources.docText - `.github/ISSUE_REPORTING.md`.
- * @param {string} [sources.docPath] - The doc's path, for the message naming it.
- * @returns {{registry: object[], doc: object[], count: number}} Findings for
- *   each file, and how many labels the registry declares.
- */
-export function checkLabelRegistry({ registryText, docText, docPath, }: {
-    registryText: string;
-    docText: string;
-    docPath?: string | undefined;
-}): {
-    registry: object[];
-    doc: object[];
-    count: number;
-};
-/** GitHub rejects a label description beyond this with a 422. */
-export const MAX_DESCRIPTION: 100;