@heroiclands/package-build 23.4.0 → 23.5.0

package/docs/commands.md

@@ -58,7 +58,7 @@ The command entries below list only their own options.
 the walk up from the working directory the CLI otherwise does — the only
 environment variable the toolchain itself reads for configuration
 resolution. `deploy`, `container` and `e2e` additionally read `FOUNDRYVTT_*`,
-documented where each applies.
+and `cdn publish` reads `CDN_*`, documented where each applies.
 
 An option name recurring across commands is not a recurring meaning —
 `--out`, `--check`, `--from` and `--strict` each carry their own default and
@@ -300,6 +300,16 @@ names a module in `packageBuild.assetTransform`, exporting
 anything else replaces its content. Reads every `from` path; writes into
 `packageBuild.stageDir`.
 
+Then stages the package's pictures itself. Every file under `assets/icons/`
+and `assets/images/` whose provenance says `ai: false` and whose licence is on
+the shipping list (the default list plus `packageBuild.shippingLicenses`) is copied flat to `icons/<basename>` or `images/<basename>`
+at the package root, through the same transform, and the package's asset set,
+`asset-sets/default.json`, lists what was staged. Everything else stays in the repository. See
+[what a package ships](reference/format-details.md#what-a-package-ships).
+A `packageBuild.assets` row that copies a picture root, a directory inside
+one, or a directory holding one is refused, because it would ship every file
+unfiltered.
+
 **OPTIONS**
 
 None.
@@ -307,15 +317,20 @@ None.
 **EXIT STATUS**
 
 1 if `packageBuild.assetTransform` is declared but cannot be loaded, or
-exports no `transform` function. 1 on any other thrown error. Otherwise 0 —
-including when `packageBuild.assets` is empty, which logs and stages nothing
-rather than failing.
+exports no `transform` function. 1 when a row copies a picture root, and 1 on
+any asset finding — a file no provenance record covers, a record missing
+`attribution`, `license` or `ai`, two files claiming one address — with
+nothing staged. 1 on any other thrown error. Otherwise 0.
 
 **EXAMPLES**
 
 ```
 $ package-build assets
-✅ Static assets staged (1 entries, 1 files).
+Pictures: 4 staged, 2 left out by provenance.
+✅ Static assets staged (2 entries, 9 files).
+
+$ package-build assets
+package-build.config.yaml:14:17: error: `packageBuild.assets[6]` copies `assets/images`, which reaches assets/images/ — 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
 ```
 
 **SEE ALSO**
@@ -1138,7 +1153,9 @@ states it a second time. It also publishes the content index the manifest
 advertises (`flags.metadataUrl`) and, when the stage carries one,
 `schema.json` — a repository that names `build/schema.json` in
 `packageBuild.assets` gets it released beside the archive; one that does not
-gets none. When the content tree holds notes beyond its homepage, it
+gets none. When the stage carries `asset-sets/default.json`, it writes
+`icons.zip` and `images.zip` too, one per picture root the stage holds, each
+with that set. When the content tree holds notes beyond its homepage, it
 also builds the content-tree book (see `package-build pdf`) and reports it
 alongside the archive; `--no-pdf` skips that step for a release that has a
 tree but does not want the book this time. A book that fails to build is
@@ -1246,6 +1263,134 @@ Deployed stage 'test' successfully.
 `package-build container <stage> <action>`, `package-build e2e <action>`,
 [Configuration](configuration.md).
 
+### `package-build cdn publish`
+
+**NAME**
+
+Upload every picture the package has to the CDN, and publish the art the
+package leaves out as a named asset set.
+
+**SYNOPSIS**
+
+```
+package-build cdn publish --set <file> --name <display name> [--dry-run]
+```
+
+**DESCRIPTION**
+
+The one writer to `<site.assets>/<contentPackage>/`. It is run by hand, or by
+a manually dispatched workflow; no build or release runs it.
+
+Every icon and image under the package's picture roots is uploaded flat, as
+`icons/<basename>` or `images/<basename>` — shipped and left-out pictures
+alike, because the website draws every one of them from the same address the
+site build gives it. `packageBuild.assetTransform` runs on each file exactly
+as `package-build assets` runs it, so a picture on the CDN holds the bytes the
+staged package holds. SVG is served as `image/svg+xml`.
+
+The bucket is served at `site.assets`, so an object's key is its path below
+that address: `thalorna/images/thorn.webp` is
+`https://cdn.heroiclands.org/thalorna/images/thorn.webp`.
+
+`--set` names the set file, written at `<site.assets>/<contentPackage>/<file>`.
+It lists only the pictures the package leaves out — an address a set does not
+list resolves to the shipped copy — chosen by the same rule the stage applies,
+`packageBuild.shippingLicenses` included. Its shape is the shipped set's, with
+each `source` the file's absolute CDN address:
+
+```json
+{
+  "name": "Thalorna — illustrated",
+  "package": "thalorna",
+  "assets": [
+    {
+      "address": "thalorna-none-image-thorn",
+      "source": "https://cdn.heroiclands.org/thalorna/images/thorn.webp",
+      "target": "images/thorn.webp",
+      "size": 48213
+    }
+  ]
+}
+```
+
+Several sets may sit side by side under one package, each with its own file
+name. `default.json` is refused: it is the shipped set's name.
+
+A picture whose object already exists at the same size is skipped, and the set
+file is skipped when its bytes are unchanged, so a second run uploads nothing.
+A picture that fails to upload is reported and the rest carry on; the set file
+is then withheld, since it would list a file the CDN does not hold.
+
+**Refusals and reports.** A file under `icons/` or `images/` whose name is no
+address — a basename that is not a shortcode, or two files claiming one — and
+a provenance record that cannot be read stop the run before anything is
+uploaded, each reported against its file. A note naming a picture the package
+does not have, and a note naming left-out art that is not on the CDN when the
+run ends, are warnings at the note's line and column: an art slot under
+`data:`, an embed, or a body image.
+
+**Credentials.** The store is an S3-compatible bucket — Cloudflare R2 for
+`cdn.heroiclands.org` — signed with AWS Signature Version 4. Its settings are
+read from the environment, after `.env.local` and `.env` are loaded:
+
+| Variable                | What it is                                                                |
+| ----------------------- | ------------------------------------------------------------------------- |
+| `CDN_ENDPOINT`          | The S3 endpoint; for R2, `https://<account id>.r2.cloudflarestorage.com`. |
+| `CDN_BUCKET`            | The bucket served at `site.assets`.                                       |
+| `CDN_ACCESS_KEY_ID`     | The access key id of a token that can write the bucket.                   |
+| `CDN_SECRET_ACCESS_KEY` | That token's secret. Never printed.                                       |
+
+Setting some but not all of them is an error naming the missing ones. With
+none set, `--dry-run` compares against the public CDN at `site.assets`
+instead, read-only, and an upload is refused.
+
+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"
+  env:
+    CDN_ENDPOINT: ${{ secrets.CDN_ENDPOINT }}
+    CDN_BUCKET: ${{ secrets.CDN_BUCKET }}
+    CDN_ACCESS_KEY_ID: ${{ secrets.CDN_ACCESS_KEY_ID }}
+    CDN_SECRET_ACCESS_KEY: ${{ secrets.CDN_SECRET_ACCESS_KEY }}
+```
+
+**OPTIONS**
+
+| Option      | Type    | Default | Description                                                                 |
+| ----------- | ------- | ------- | --------------------------------------------------------------------------- |
+| `--set`     | string  | —       | Required. The set file's name under the package's CDN root, a `.json` file. |
+| `--name`    | string  | —       | Required. The set's display name.                                           |
+| `--dry-run` | boolean | `false` | List what would upload and what is skipped; write nothing.                  |
+
+**EXIT STATUS**
+
+1 when a picture's file has no address, when a picture fails to upload, when
+`--set` is `default.json` or a path, when `site.assets` is undeclared, and
+when an upload has no store configured. Warnings about notes do not change
+it. Otherwise 0.
+
+**EXAMPLES**
+
+```
+$ package-build cdn publish --set ai-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).
+
+$ 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
+```
+
+**SEE ALSO**
+
+`package-build assets`, `package-build release`,
+[Configuration](configuration.md#site),
+[Release and deploy](guides/release-and-deploy.md#publish-pictures-to-the-cdn).
+
 ### `package-build container <stage> <action>`
 
 **NAME**
@@ -1306,7 +1451,9 @@ exact pin takes the major tag of its pin or of `compatibility.minimum`
 mount), `FOUNDRYVTT_CONTAINER_USER` (passed to `docker run --user`; `0:0`
 under rootless Docker makes the data root's files belong to the host user,
 because the image otherwise runs Foundry as user 1000 and ignores
-`FOUNDRY_UID` and `FOUNDRY_GID`).
+`FOUNDRY_UID` and `FOUNDRY_GID`), `FOUNDRYVTT_CONTAINER_S3` (`1` or `true`
+runs an S3-compatible server beside the container; see
+[an S3 server for the container](guides/e2e.md#an-s3-server-for-the-container)).
 
 **EXIT STATUS**
 

package/docs/configuration.md

@@ -206,6 +206,9 @@ against — the one reader of it is `resolveImg`
 `packageKind` and `foundryPackage`.
 
 - For a `systems` or `modules` package, `<packageKind>/<foundryPackage>/assets`.
+  A picture under `icons/` or `images/` is served flat from
+  `<packageKind>/<foundryPackage>/<icons|images>/<basename>` instead, the
+  layout the stage gives it; every other file keeps its path under `assets/`.
 - For a `documentation` package, `null` — Foundry serves no files for a
   package of this kind, and `documentation/null/assets` would be an address
   that resolves nowhere. `resolveImg` refuses rather than rooting a path
@@ -901,6 +904,12 @@ resolves every relative asset against it:
 
 > ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
 
+`package-build cdn publish` uploads the package's pictures under the same
+host, at `<site.assets>/<contentPackage>/icons/<basename>` and
+`…/images/<basename>`, which is the address the website gives each one. The
+bucket behind the CDN is served at `site.assets`, so an object's key is its
+path below this value.
+
 The generated Hugo configuration carries the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
 The two are one value read by two readers: the toolchain emits it into a
@@ -1685,7 +1694,7 @@ validator.
 packageBuild:
   assets:
     - { from: lang, to: lang }
-    - { from: assets/icons, to: assets/icons }
+    - { from: assets/audio, to: assets/audio }
   assetTransform: ./utils/svg-theme.mjs
   stageDir: build/stage
   clean:
@@ -1701,6 +1710,7 @@ packageBuild:
 | [`packageBuild.stageDir`](#packagebuildstagedir-and-packagebuildassets)                    | string                                      | no       | `build/stage`                                              |
 | [`packageBuild.assets`](#packagebuildstagedir-and-packagebuildassets)                      | array                                       | no       | `[]`                                                       |
 | [`packageBuild.assetTransform`](#packagebuildassettransform-and-packagebuildmanifestflags) | string (path to a module)                   | no       | `null`                                                     |
+| [`packageBuild.shippingLicenses`](#packagebuildshippinglicenses)                           | array of strings                            | no       | `[]`                                                       |
 | [`packageBuild.baseStyles`](#packagebuildbasestyles)                                       | boolean                                     | no       | `true`                                                     |
 | [`packageBuild.manifest`](#packagebuildmanifest)                                           | object, pass-through                        | no       | `{}`                                                       |
 | [`packageBuild.manifestFlags`](#packagebuildassettransform-and-packagebuildmanifestflags)  | string (path to a module)                   | no       | `null`                                                     |
@@ -1715,7 +1725,7 @@ packageBuild:
 | [`packageBuild.proseLint`](#packagebuildproselint)                                         | object                                      | no       | `{age: 21, threshold: 5, minWords: 8, rules: readability}` |
 | [`packageBuild.proseScore`](#packagebuildprosescore)                                       | object                                      | no       | `{minWords: 80, bands: {}}`                                |
 
-> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
+> ``package-build config: `packageBuild.<key>` is not a recognised key (expected one of: stageDir, assets, assetTransform, shippingLicenses, baseStyles, manifest, manifestFlags, schema, clean, lang, deploy, release, bundle, container, e2e, proseLint, proseScore).``
 
 ### `packageBuild.proseLint`
 
@@ -1765,6 +1775,15 @@ table says `lang`, not `build/stage/lang`.
 `assets` is the table of staging copies: source path in the repository,
 destination under the staged package root.
 
+**The picture roots are not in it.** `package-build assets` stages
+`assets/icons/` and `assets/images/` itself — flat at the package root, and
+only the files whose provenance allows them to ship (see
+[what a package ships](reference/format-details.md#what-a-package-ships)). A
+row whose `from` is a picture root, a directory inside one, or a directory
+holding one is refused at the row:
+
+> ``package-build.config.yaml:<line>:<column>: error: `packageBuild.assets[<index>]` copies `<from>`, which reaches assets/images/ — 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``
+
 | Key                             | Type                       | Required |
 | ------------------------------- | -------------------------- | -------- |
 | `packageBuild.assets[].from`    | string                     | yes      |
@@ -1801,6 +1820,24 @@ repository has to compute. Neither declares anything, both default to
 
 > ``package-build config: `packageBuild.manifestFlags` must be a non-empty string.``
 
+### `packageBuild.shippingLicenses`
+
+Licences this package adds to the default shipping list. A picture ships in the
+Foundry package when its provenance says `ai: false` and its `license` is on the
+default list or on this one; the default list is never replaced, and `ai: true`
+never ships. Each entry is spelled exactly as provenance spells the licence.
+
+```yaml
+packageBuild:
+  shippingLicenses: [CC-BY-NC-SA-4.0]
+```
+
+> ``package-build config: `packageBuild.shippingLicenses` must be a list of licence identifiers.``
+
+> ``package-build config: `packageBuild.shippingLicenses` entry <index> must be a non-empty string.``
+
+> ``package-build config: `packageBuild.shippingLicenses` lists `<licence>` more than once.``
+
 ### `packageBuild.baseStyles`
 
 Whether the package takes the shared base stylesheet. It defaults to `true`,

package/docs/content-format.md

@@ -53,12 +53,36 @@ explains routing for documents and their prose journals.
 
 A note can also produce a system document: an Actor, Item, Scene, or Macro according to its type and system blocks. The `sohl:` and `hm3:` blocks supply game-specific mechanics and overrides; they do not create separate prose. The JournalEntry is shared between systems.
 
-An `affiliation` note declares `data.governance.ranks` with at least one rung at
-`level: 1`. Each rung states `level`, `title`, and `description`. A being's
-`data.affiliations` entry names a rank on that body's ladder; level 1 is the
-ordinary standing when no higher rank applies. A single level-1 rung is enough
-when the body expresses its hierarchy through `governance.offices` instead.
-Missing ranks, an empty list, or a ladder without level 1 are build errors.
+An `affiliation` note declares `data.governance.ranks` with at least two rungs:
+`level: 0`, those the body excludes, and `level: 1`, its ordinary members. Every
+body that can name its members can name those it shuts out, whether or not it
+ever does, so both are required. Each rung states `level`, `title`, and
+`description`, and the level-0 title is the body's own word for the excluded
+rather than a generic "Excluded". A being's `data.affiliations` entry names a
+rank on that body's ladder; level 1 is the ordinary standing when no higher
+rank applies.
+
+Add rungs above level 1 only where the body truly has them, generally no more
+than five. A rung is a **standing**, what a member is; an entry in
+`governance.offices` is a **post**, what a member does. Leadership is normally
+an office held by the top rank rather than a rank above it, and a rank never
+falls when an office is left: a bishop stays a bishop after being Presiding
+Bishop.
+
+```yaml
+data:
+  governance:
+    ranks:
+      - { level: 0, title: Apostate, description: Put out of the communion. }
+      - { level: 1, title: Layman, description: A baptised member of the faith. }
+      - { level: 2, title: Priest, description: Ordained to serve a parish. }
+      - { level: 3, title: Bishop, description: Consecrated to oversee a diocese. }
+    offices:
+      Presiding Bishop: Chairs the synod of bishops for a term.
+```
+
+Missing ranks, an empty list, or a ladder without level 0 or level 1 are build
+errors, reported at the `ranks` key.
 
 | Authored section | SoHL Actor          | HM3 Actor            |
 | ---------------- | ------------------- | -------------------- |

package/docs/guides/e2e.md

@@ -159,3 +159,41 @@ major version or moving tag is refused, because the result must name the
 build actually tested. A passing sweep provides evidence for choosing a
 new `compatibility.verified` value; a routine run exercises the pinned
 minimum build.
+
+## An S3 server for the container
+
+A suite that exercises S3 storage needs an S3-compatible server the browser and
+Foundry both reach. Setting `FOUNDRYVTT_CONTAINER_S3=1` when a container is
+created (`start`, `recreate`; through `e2e:fast --recreate` as well) provides one.
+Without it nothing changes: no network, no server, no extra environment.
+
+With it, before Foundry starts:
+
+- A user-defined network named `<container>-net` is created, and the Foundry
+  container is created on it.
+- A SeaweedFS server (`chrislusf/seaweedfs:3.80`) named `<container>-s3` joins
+  the network under the alias `s3.localhost` and publishes port 8333. Chromium
+  resolves every `*.localhost` name to loopback, so `http://s3.localhost:8333`
+  reaches the server from the browser and, through the alias, from the
+  container. Its CORS allows every origin.
+- The bucket `sohl-e2e` is created. Anonymous read and the test credentials come
+  from the identities file the server is started with.
+- The repository's `cypress/s3/aws-e2e.json` is copied into the data root's
+  `Config/`, and the container is created with `FOUNDRY_AWS_CONFIG=aws-e2e.json`.
+
+The repository supplies both files: `cypress/s3/s3-identities.json` (the
+SeaweedFS identities, including an `anonymous` identity with `Read`) and
+`cypress/s3/aws-e2e.json` (Foundry's `awsConfig`, pointing at
+`http://s3.localhost:8333`). The credentials are test-only. A missing file stops
+the start and names it.
+
+```bash
+FOUNDRYVTT_CONTAINER_S3=1 npm run e2e:fast -- --recreate
+```
+
+The container's environment is fixed when it is created, so an existing
+container started with the variable set joins the network but keeps the
+environment it was created with; `--recreate` applies `FOUNDRY_AWS_CONFIG`.
+`package-build container <stage> rm` with the variable set removes the server
+and the network along with the container. The server is otherwise left running
+between runs, bucket intact.

package/docs/guides/icons.md

@@ -68,6 +68,11 @@ defaults point into the system's `assets/images/` and `assets/icons/` trees,
 introduced by [HM3's asset-path migration](https://git.pupluppy.org/HeroicLands/HarnMaster-3-FoundryVTT/pulls/60).
 Use these defaults with an HM3 release that includes those assets.
 
+A compiled document reaches each icon in the deployed layout — the type root
+and the basename, `systems/sohl/icons/person.svg` — whatever directories hold
+it in the repository, and states its address in `flags.<system>.assets`. See
+[what a package ships](../reference/format-details.md#what-a-package-ships).
+
 ## Write an inline icon in prose
 
 Declare the glyph vocabulary in `package-build.config.yaml` or a separate YAML

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

@@ -47,7 +47,10 @@ manifest under `build/dist/`. The ZIP contains the staged tree at its root,
 which is the shape Foundry installs. When the manifest advertises a content
 index, the corresponding metadata JSONL is also placed beside the ZIP. A
 manifest that advertises an index the build has not produced fails the
-release. An opted-in staged `schema.json` is published beside it too.
+release. An opted-in staged `schema.json` is published beside it too. A
+package whose stage holds pictures also gets `icons.zip` and `images.zip`:
+each holds one picture root of the stage, flat, with the package's asset
+set `asset-sets/default.json`, so a GM can place the files by hand.
 
 When the package publishes content and has a book configuration, the release
 also builds a PDF beside the archive. Book findings are reported without
@@ -128,6 +131,38 @@ the same stage;
 [container command](../commands.md#package-build-container-stage-action) for
 the other actions and environment variables.
 
+## Publish pictures to the CDN
+
+The website draws every picture a package has from
+`<site.assets>/<contentPackage>/`, and the art a Foundry package leaves out
+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"
+```
+
+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.
+Run it after the pictures or their provenance change; it is not part of a
+build or a release.
+
+The bucket's credentials go in `.env.local` beside the stage paths:
+
+```dotenv
+CDN_ENDPOINT=https://<account id>.r2.cloudflarestorage.com
+CDN_BUCKET=<bucket>
+CDN_ACCESS_KEY_ID=<access key id>
+CDN_SECRET_ACCESS_KEY=<secret access key>
+```
+
+A dry run with none of them set compares against the public CDN instead. A
+dispatched workflow passes the same four values as named secrets. See the
+[command reference](../commands.md#package-build-cdn-publish) for the set
+file's shape, the refusals and the exit status.
+
 ## Publish a package-build npm version
 
 For this toolchain's own npm release, a pull request with a change installers