@heroiclands/package-build 23.4.1 → 23.5.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @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
+
+**Affiliations**
+
+- `package-build lint` requires every affiliation's ladder to have a level-0 rung for those it excludes, beside its level-1 members.
+
+**Provenance**
+
+- Every icon and image must be covered by a provenance record, and every record must state `ai: true` or `ai: false`; a package missing either now fails its build until it adds them.
+
+**What a Foundry package ships**
+
+- A package ships only the icons and images whose provenance says `ai: false` under a public-domain, CC0, CC-BY, CC-BY-SA or Noun Project Pro licence; everything else stays in the repository.
+- Shipped pictures sit flat at the package root as `icons/<file>` and `images/<file>`, and compendium documents and the website point there; remove any `packageBuild.assets` row copying `assets/icons` or `assets/images`, which is now refused.
+- `asset-sets/default.json` in the package lists the shipped pictures, and each release attaches `icons.zip` and `images.zip`.
+- A picture the package leaves out shows the package's `missing` stand-in, and every picture reference in a compiled document records which asset it is.
+- Items created without art get their default icon again, at its flat `icons/` location.
+- A package can ship pictures under further licences by listing them in `packageBuild.shippingLicenses`; the default list still applies and `ai: true` pictures never ship.
+
+### Patch Changes
+
+- New `package-build cdn publish --set <file> --name <name>` uploads every icon and image a package has to its CDN folder, flat, and publishes the art the package leaves out as a named asset set a world can add.
+- A second run uploads nothing, and `--dry-run` lists what would upload; the bucket is read from `CDN_ENDPOINT`, `CDN_BUCKET`, `CDN_ACCESS_KEY_ID` and `CDN_SECRET_ACCESS_KEY`.
+- The end-to-end container can run an S3-compatible server beside Foundry: set `FOUNDRYVTT_CONTAINER_S3=1` and a suite can exercise S3 storage.
+
 ## 23.4.1
 
 ### Patch Changes

package/README.md

@@ -20,34 +20,38 @@ The generated project includes a homepage, website and book targets, npm scripts
 
 The documentation lives in the Markdown files in this repository. Start with [the documentation home](docs/index.md). This toolchain does not build its own site or book. A Hugo theme dependency would form a cycle because the theme uses package-build for releases.
 
-| Topic                                             | Guide                                                        |
-| ------------------------------------------------- | ------------------------------------------------------------ |
-| Documentation landing                             | [Home](docs/index.md)                                        |
-| Project layout and scripts                        | [Project setup](docs/project-setup.md)                       |
-| Note model and output                             | [Content format](docs/content-format.md)                     |
-| Frontmatter and system blocks                     | [Frontmatter](docs/authoring/frontmatter.md)                 |
-| Addresses, links, anchors, SQL, and secret blocks | [Links and markup](docs/authoring/links-and-markup.md)       |
-| Images, icons, audio, and provenance              | [Assets](docs/authoring/assets.md)                           |
-| Dates, calendars, and eras                        | [Dates and calendars](docs/authoring/dates-and-calendars.md) |
-| Complete note fields and mappings                 | [Note types](docs/reference/note-types.md)                   |
-| Detailed format rules and examples                | [Format details](docs/reference/format-details.md)           |
-| Compendium routing and document builds            | [Packs](docs/guides/packs.md)                                |
-| Website build and publication                     | [Site](docs/guides/site.md)                                  |
-| What the theme draws on a page                    | [Theme pages](docs/reference/theme-pages.md)                 |
-| PDF book build                                    | [Book](docs/guides/book.md)                                  |
-| Icon generation and use                           | [Icons](docs/guides/icons.md)                                |
-| Reference pages and content indexes               | [Reference pages](docs/guides/reference-pages.md)            |
-| Localization and templates                        | [Localization](docs/guides/localization.md)                  |
-| Foundry integration testing                       | [End-to-end testing](docs/guides/e2e.md)                     |
-| Release and deployment                            | [Release and deploy](docs/guides/release-and-deploy.md)      |
-| Every CLI command                                 | [Commands](docs/commands.md)                                 |
-| Every build setting                               | [Configuration](docs/configuration.md)                       |
-| Programmatic exports                              | [API](docs/api.md)                                           |
-| Error locations and severities                    | [Diagnostics](docs/diagnostics.md)                           |
-| Architectural rationale                           | [Design](docs/design.md)                                     |
+| Topic                                             | Guide                                                                     |
+| ------------------------------------------------- | ------------------------------------------------------------------------- |
+| Documentation landing                             | [Home](docs/index.md)                                                     |
+| Project layout and scripts                        | [Project setup](docs/project-setup.md)                                    |
+| Note model and output                             | [Content format](docs/content-format.md)                                  |
+| Frontmatter and system blocks                     | [Frontmatter](docs/authoring/frontmatter.md)                              |
+| Addresses, links, anchors, SQL, and secret blocks | [Links and markup](docs/authoring/links-and-markup.md)                    |
+| Images, icons, audio, and provenance              | [Assets](docs/authoring/assets.md)                                        |
+| Dates, calendars, and eras                        | [Dates and calendars](docs/authoring/dates-and-calendars.md)              |
+| Complete note fields and mappings                 | [Note types](docs/reference/note-types.md)                                |
+| Detailed format rules and examples                | [Format details](docs/reference/format-details.md)                        |
+| Compendium routing and document builds            | [Packs](docs/guides/packs.md)                                             |
+| Website build and publication                     | [Site](docs/guides/site.md)                                               |
+| What the theme draws on a page                    | [Theme pages](docs/reference/theme-pages.md)                              |
+| PDF book build                                    | [Book](docs/guides/book.md)                                               |
+| Icon generation and use                           | [Icons](docs/guides/icons.md)                                             |
+| Reference pages and content indexes               | [Reference pages](docs/guides/reference-pages.md)                         |
+| Localization and templates                        | [Localization](docs/guides/localization.md)                               |
+| Foundry integration testing                       | [End-to-end testing](docs/guides/e2e.md), including an optional S3 server |
+| Release and deployment                            | [Release and deploy](docs/guides/release-and-deploy.md)                   |
+| Every CLI command                                 | [Commands](docs/commands.md)                                              |
+| Every build setting                               | [Configuration](docs/configuration.md)                                    |
+| Programmatic exports                              | [API](docs/api.md)                                                        |
+| Error locations and severities                    | [Diagnostics](docs/diagnostics.md)                                        |
+| Architectural rationale                           | [Design](docs/design.md)                                                  |
 
 Place notes may declare a governing affiliation with `data.government` (`Address`, default target type `affiliation`), or explicit `null` for complete anarchy. Positive population with an omitted government produces an advisory. See [place governments](docs/authoring/frontmatter.md#place-governments).
 
+Every icon and image is covered by a provenance record stating `attribution`, `license` and `ai`. A Foundry package ships only the pictures whose record says `ai: false` under a licence on the shipping list, staged flat at the package root as `icons/<basename>` and `images/<basename>` and listed in its asset set, `asset-sets/default.json`; a reference to a picture it leaves out draws the package's `missing` stand-in, and every compiled reference states its asset's address. See [assets](docs/authoring/assets.md#what-the-foundry-package-ships) and [what a package ships](docs/reference/format-details.md#what-a-package-ships).
+
+`package-build cdn publish --set <file> --name <display name>` uploads every icon and image the package has, shipped or not, to `<site.assets>/<contentPackage>/` in that flat layout, and writes the named set listing the pictures the package leaves out. It reads the bucket from `CDN_ENDPOINT`, `CDN_BUCKET`, `CDN_ACCESS_KEY_ID` and `CDN_SECRET_ACCESS_KEY`, in the environment or `.env.local`. See [publish pictures to the CDN](docs/guides/release-and-deploy.md#publish-pictures-to-the-cdn).
+
 Leading captions, generic fenced divs, inline spans, and poetry code fences are described in [links and markup](docs/authoring/links-and-markup.md).
 
 The package is GPL-3.0-or-later for code and CC-BY-SA-4.0 for original content. See [LICENSE.md](LICENSE.md).

package/assets/images/provenance.yaml

@@ -1,4 +1,5 @@
 attribution: Tom Rodriguez
 source: ""
 license: CC-BY-SA-4.0
+ai: true
 notes: ""

package/bin/package-build.mjs

@@ -61,6 +61,7 @@
  *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
+ *   npx package-build cdn publish --set <file> --name <display name> [--dry-run]
  *   npx package-build container <stage> <action>
  *   npx package-build e2e <seed|run|open|fast|sweep>
  *
@@ -87,13 +88,25 @@ import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
 import { checkForeignAssetBindings } from "../engine/asset-bindings.mjs";
-import { emitDiagnostic, formatDiagnostic } from "../engine/diagnostics.mjs";
+import { emitDiagnostic, formatDiagnostic, positionOfYamlPath } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
+import { rowsStagingPictureRoots, stagePackageAssets } from "../engine/asset-shipping.mjs";
 import { baseStyleStageEntry } from "../engine/base-styles.mjs";
+import {
+    CDN_ENV,
+    cdnCredentials,
+    noteArtFindings,
+    noteArtReferences,
+    planCdnPublish,
+    publicStore,
+    publishToCdn,
+    s3Store,
+    setFileProblem,
+} from "../engine/cdn-publish.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
 import { dateFromCalendar, dateToCalendar } from "../engine/date-conversion.mjs";
@@ -101,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";
@@ -421,6 +433,62 @@ function cleanCommand() {
     };
 }
 
+/**
+ * A finding for each `packageBuild.assets` row that would stage a picture root
+ * itself, located at the row's `from` when the configuration is YAML.
+ *
+ * @param {readonly {from: string, to: string}[]} rows - The configured rows.
+ * @param {{rootDir: string, assetsBase: string}} opts - Where they resolve.
+ * @returns {object[]} The findings.
+ */
+function pictureRootRowFindings(rows, { rootDir, assetsBase }) {
+    const offending = rowsStagingPictureRoots(rows, { rootDir, assetsBase });
+    if (!offending.length) return [];
+    const file = packConfigPath();
+    const text =
+        file.endsWith(".yaml") || file.endsWith(".yml") ? fs.readFileSync(file, "utf8") : "";
+    return offending.map(({ index, from, root }) => ({
+        file,
+        ...(text ? positionOfYamlPath(text, ["packageBuild", "assets", index, "from"]) : {}),
+        severity: "error",
+        message:
+            `\`packageBuild.assets[${index}]\` copies \`${from}\`, which reaches ${root}/ — ` +
+            "the stage copies the icon and image roots itself, flat and filtered by " +
+            "each file's provenance, so a row copying them would ship every file " +
+            "unfiltered. Remove the row",
+    }));
+}
+
+/**
+ * The repository's `packageBuild.assetTransform`, loaded.
+ *
+ * One loader for every command that writes a picture, so the stage and the CDN
+ * hold the same bytes for the same file.
+ *
+ * @param {object} config - The resolved package-build configuration.
+ * @returns {Promise<((sourcePath: string) => string|null|undefined)|undefined>}
+ *   The transform, or `undefined` when the repository names none.
+ */
+async function loadAssetTransform(config) {
+    if (!config.assetTransform) return undefined;
+    const module = await import(`file://${config.assetTransform}`).catch((err) =>
+        die(
+            `cannot load \`packageBuild.assetTransform\` ` +
+                `(${config.assetTransform}): ${err.message}`,
+        ),
+    );
+    const transform = module.transform;
+    if (typeof transform !== "function") {
+        die(
+            `\`packageBuild.assetTransform\` ` +
+                `(${config.assetTransform}) exports no \`transform\` ` +
+                `function. It must export ` +
+                `\`transform(sourcePath) -> string | null\`.`,
+        );
+    }
+    return transform;
+}
+
 /**
  * `assets` — stage the repository's static files into the package root.
  *
@@ -440,37 +508,22 @@ function assetsCommand() {
         builder: (y) => y,
         handler: handler(async () => {
             const config = loadPackageBuildConfig();
-            if (!config.assets.length && !config.baseStyles) {
-                console.log("package-build: no `packageBuild.assets` declared; nothing to stage.");
-                return;
-            }
-            const bindings = checkForeignAssetBindings(loadPackConfig(), {
-                assets: config.assets,
-            });
-            if (bindings.length) {
-                const error = new Error(bindings.map(formatDiagnostic).join("\n"));
+            const packConfig = loadPackConfig();
+            const assetsBase = packConfig.paths.assets;
+            const findings = [
+                ...pictureRootRowFindings(config.assets, {
+                    rootDir: config.rootDir,
+                    assetsBase,
+                }),
+                ...checkForeignAssetBindings(packConfig, { assets: config.assets }),
+            ];
+            if (findings.length) {
+                const error = new Error(findings.map(formatDiagnostic).join("\n"));
                 error.located = true;
                 die(error);
             }
 
-            let transform;
-            if (config.assetTransform) {
-                const module = await import(`file://${config.assetTransform}`).catch((err) =>
-                    die(
-                        `cannot load \`packageBuild.assetTransform\` ` +
-                            `(${config.assetTransform}): ${err.message}`,
-                    ),
-                );
-                transform = module.transform;
-                if (typeof transform !== "function") {
-                    die(
-                        `\`packageBuild.assetTransform\` ` +
-                            `(${config.assetTransform}) exports no \`transform\` ` +
-                            `function. It must export ` +
-                            `\`transform(sourcePath) -> string | null\`.`,
-                    );
-                }
-            }
+            const transform = await loadAssetTransform(config);
 
             // `to:` is relative to the staged package root, so a
             // repository's table reads `lang`, not `build/stage/lang`.
@@ -483,6 +536,35 @@ function assetsCommand() {
                 transform,
             });
 
+            // The picture roots, staged by the toolchain rather than by a row:
+            // flat, filtered by each file's provenance, and listed in the
+            // package's asset set.
+            const pictures = stagePackageAssets({
+                assetsBase,
+                contentPackage: packConfig.contentPackage,
+                stageDir: path.resolve(config.rootDir, config.stageDir),
+                // The manifest's title names the set; a package with none is
+                // named by its content package.
+                title:
+                    typeof config.manifest?.title === "string" && config.manifest.title.trim() ?
+                        config.manifest.title
+                    :   packConfig.contentPackage,
+                transform,
+                shippingLicenses: config.shippingLicenses,
+            });
+            if (pictures.findings.length) {
+                const error = new Error(pictures.findings.map(formatDiagnostic).join("\n"));
+                error.located = true;
+                die(error);
+            }
+            files += pictures.staged.length;
+            if (pictures.staged.length || pictures.excluded.length) {
+                console.log(
+                    `Pictures: ${pictures.staged.length} staged, ` +
+                        `${pictures.excluded.length} left out by provenance.`,
+                );
+            }
+
             // Staged in its own pass, without the repository's transform: the
             // sheet is this toolchain's file rather than one of the
             // repository's assets, and a `transform` written to retheme a
@@ -1245,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.
  *
@@ -1464,6 +1475,9 @@ function releaseCommand() {
                     }),
                 );
             }
+            for (const archive of result.pictures ?? []) {
+                console.log(`🖼  Pictures: ${path.relative(config.rootDir, archive)}`);
+            }
             for (const pdf of result.pdfs ?? []) {
                 console.log(`📕 Book: ${path.relative(config.rootDir, pdf)}`);
             }
@@ -1534,6 +1548,150 @@ function deployCommand() {
     };
 }
 
+/**
+ * `cdn publish` — upload every picture the package has to the CDN, and the art
+ * the package leaves out as a named asset set.
+ *
+ * The one writer to `<site.assets>/<package>/`. It is run by hand or by a
+ * dispatched workflow, never by a build or a release. The store is named by
+ * the `CDN_*` variables in `CDN_ENV`, read from the environment or
+ * `.env.local`; a dry run with none of them set compares against the public
+ * CDN instead.
+ *
+ * @returns {object} The yargs command module.
+ */
+function cdnPublishCommand() {
+    return {
+        command: "publish",
+        describe: "Upload every picture to the CDN and write a named asset set",
+        builder: (y) =>
+            y
+                .option("set", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "The set file's name under the package's CDN root, e.g. alt-art.json",
+                })
+                .option("name", {
+                    type: "string",
+                    demandOption: true,
+                    describe: "The set's display name",
+                })
+                .option("dry-run", {
+                    type: "boolean",
+                    default: false,
+                    describe: "List what would upload and what is skipped; write nothing",
+                }),
+        handler: handler(async (args) => {
+            const config = loadPackageBuildConfig();
+            const packConfig = loadPackConfig();
+            await loadEnvironment(config);
+
+            const setProblem = setFileProblem(args.set);
+            if (setProblem) die(setProblem);
+            const name = String(args.name ?? "").trim();
+            if (!name) die("`--name` is blank; a set needs a display name");
+            const host = String(packConfig.site?.assets ?? "").trim();
+            if (!host) {
+                die(
+                    "`site.assets` is not declared, and it is the CDN root every picture " +
+                        "is published under",
+                );
+            }
+            const credentials = cdnCredentials(process.env);
+            if (!credentials && !args.dryRun) {
+                die(
+                    `no CDN store is configured: set ${Object.values(CDN_ENV).join(", ")} ` +
+                        "in the environment or `.env.local`",
+                );
+            }
+
+            const plan = planCdnPublish({
+                assetsBase: packConfig.paths.assets,
+                contentPackage: packConfig.contentPackage,
+                host,
+                setFile: args.set,
+                setName: name,
+                transform: await loadAssetTransform(config),
+                shippingLicenses: config.shippingLicenses,
+            });
+            if (plan.findings.length) {
+                const located = plan.findings.map((finding) => ({
+                    ...finding,
+                    file:
+                        path.isAbsolute(finding.file) ?
+                            path.relative(process.cwd(), finding.file)
+                        :   finding.file,
+                }));
+                reportFindings(located, {});
+                process.exitCode = 1;
+                return;
+            }
+            const excluded = new Set(
+                plan.uploads.filter((upload) => !upload.shipped).map((upload) => upload.record),
+            );
+            const references = noteArtReferences({
+                contentBase: packConfig.paths.content,
+                skipDirectories: packConfig.skipDirectories,
+                contentPackage: packConfig.contentPackage,
+                records: plan.records,
+            });
+
+            const store = credentials ? s3Store(credentials) : publicStore(host);
+            console.log(
+                `${args.dryRun ? "Dry run: comparing" : "Publishing"} ${plan.uploads.length} ` +
+                    `pictures against ${store.describe}.`,
+            );
+            const result = await publishToCdn(plan, {
+                store,
+                dryRun: args.dryRun,
+                log: (line) => console.log(`  ${line}`),
+            });
+            const failures = result.failed.map(({ upload, message }) => ({
+                file: path.relative(
+                    process.cwd(),
+                    path.join(packConfig.paths.assets, ...upload.record.asset.path.split("/")),
+                ),
+                severity: "error",
+                message: `${upload.key} did not upload: ${message}`,
+            }));
+            const failedCount = reportFindings(
+                [
+                    ...failures,
+                    ...noteArtFindings(references, {
+                        contentPackage: packConfig.contentPackage,
+                        published: result.published,
+                        excluded,
+                    }),
+                ],
+                {},
+            );
+            if (failedCount > 0) process.exitCode = 1;
+            const set = /** @type {NonNullable<typeof plan.set>} */ (plan.set);
+            const setState =
+                result.set === "skipped" ? "unchanged"
+                : result.set === "withheld" ? "withheld"
+                : args.dryRun ? "would change"
+                : "written";
+            console.log(
+                `${args.dryRun ? "Would upload" : "Uploaded"} ${result.uploaded.length}, ` +
+                    `skipped ${result.skipped.length}, failed ${result.failed.length}; ` +
+                    `${plan.cdnRoot}${args.set} lists ` +
+                    `${set.set.assets.length} left-out pictures (${setState}).`,
+            );
+        }),
+    };
+}
+
+/** Publish the package's pictures to the CDN. */
+function cdnCommand() {
+    return {
+        command: "cdn <action>",
+        describe: "Publish the package's pictures to the CDN",
+        builder: (yargs) => yargs.command(cdnPublishCommand()).demandCommand(1).strict(),
+        handler: () => {},
+    };
+}
+
 /**
  * `container <stage> <action>` — run a stage's Foundry in a container.
  *
@@ -1742,13 +1900,13 @@ registerContentCommands(
         .command(typesCommand())
         .command(schemaCommand())
         .command(langCommand())
-        .command(labelsCommand())
         .command(bumpCommand())
         .command(yamlCommand())
         .command(changelogCommand())
         .command(bundleCommand())
         .command(releaseCommand())
         .command(deployCommand())
+        .command(cdnCommand())
         .command(containerCommand())
         .command(e2eCommand()),
 )

package/ci/prettier.mjs

@@ -0,0 +1,73 @@
+/*
+ * 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
+ */
+
+/**
+ * Runs this repository's Prettier over the paths given, or over the whole tree
+ * when none are.
+ *
+ * `npm run format -- a.mjs b.md` appends `a.mjs b.md` to the script's command
+ * line, so a script of `prettier --write .` formats everything regardless.
+ * This wrapper takes the mode first and treats whatever follows as the paths.
+ * A path that no longer exists, such as a file a branch deleted, is skipped
+ * rather than failing the run. Prettier still resolves the repository's own
+ * configuration and ignore file.
+ *
+ * ```text
+ * node ci/prettier.mjs --write [paths...]
+ * node ci/prettier.mjs --check [paths...]
+ * ```
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+/**
+ * The Prettier arguments for one invocation.
+ *
+ * @param {readonly string[]} args - The mode, `--write` or `--check`, then the
+ *   paths.
+ * @param {(path: string) => boolean} [exists] - Whether a path exists.
+ * @returns {string[]|null} The arguments, `.` when no path was given, or `null`
+ *   when paths were given and none exists, so there is nothing to run.
+ * @throws {Error} When the mode is missing or unknown.
+ */
+export function prettierArgs(args, exists = fs.existsSync) {
+    const [mode, ...paths] = args;
+    if (mode !== "--write" && mode !== "--check") {
+        throw new Error("the first argument must be --write or --check");
+    }
+    if (paths.length === 0) return [mode, "."];
+    const present = paths.filter((entry) => exists(entry));
+    return present.length ? [mode, ...present] : null;
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+    let args;
+    try {
+        args = prettierArgs(process.argv.slice(2));
+    } catch (error) {
+        console.error(error.message);
+        process.exit(2);
+    }
+    if (args === null) {
+        console.log("None of the given paths exist; nothing to format.");
+    } else {
+        const bin = createRequire(import.meta.url).resolve("prettier/bin/prettier.cjs");
+        const result = spawnSync(process.execPath, [bin, ...args], { stdio: "inherit" });
+        process.exit(result.status ?? 1);
+    }
+}