@heroiclands/package-build 23.1.0 → 23.2.0

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

@@ -54,6 +54,33 @@ also builds a PDF beside the archive. Book findings are reported without
 discarding the installable archive. `package-build release --no-pdf` skips the
 book step. The [book guide](book.md) covers selecting and checking its pages.
 
+### Release assets
+
+A package that declares several books in `pdf.books` publishes all of them
+with its release. Each book is its own PDF in `pdf.out` (default
+`build/dist`), named `<out stem>-<version>.pdf`: the stem is the book's `out`, which defaults to
+`<contentPackage>-<id>`, and the version is the package version. A package
+declaring `core` and `vedyara` under the content package `thalorna` releases
+`thalorna-core-1.4.0.pdf` and `thalorna-vedyara-1.4.0.pdf`, beside the Foundry
+archive and manifest. The release workflow attaches exactly the files
+`package-build pdf --list-assets` names. A declared book whose file is missing
+or empty fails the release; a package with one book attaches one.
+
+The release notes are the top section of `CHANGELOG.md`. When the package
+declares books, they end with a **Books** section: one line per book, in
+`pdf.books` order, giving its title and the file attached for it.
+
+```markdown
+**Books**
+
+- The World of Thalorna: `thalorna-core-1.4.0.pdf`
+- Vedyara: `thalorna-vedyara-1.4.0.pdf`
+```
+
+`package-build pdf --list-assets --book-version <version>` prints each book's
+`id`, `title` and output path as JSON without building anything, which is how
+the workflow derives both the attachments and the lines. A package with no books gets no Books section.
+
 The repository's build scripts decide how the staged tree is assembled. A
 typical content build runs `package-build content-index`,
 `package-build assets`, `package-build package compile`, and
@@ -89,6 +116,11 @@ for the package. Paths in `.env.local` are literal: `~` and shell variables
 are not expanded. Keep stage paths pointed at distinct Foundry data roots.
 The deploy command stages a complete copy beside the installed package and
 swaps it into place, so it does not rewrite open LevelDB files one by one.
+It then removes the previous tree, and any an earlier deploy left behind;
+files Foundry's container wrote there are
+removed through a throwaway container of the stage's image, and a tree that
+still cannot be removed is reported as a warning naming it, without failing the
+deploy.
 For a remote destination it uses the SSH agent unless the stage names an
 explicit key. The `container` command manages the Foundry Docker instance for
 the same stage;
@@ -105,12 +137,28 @@ change is minor; an optional command, flag, or key is patch. A major bump
 requires the maintainer's direct decision. `package-build changelog check`
 checks the quality of any pending changeset.
 
-Merging a changeset to `main` makes the **Version Packages** pull request. Its
-generated changelog section is reviewed as the release note. Merging that
-pull request runs the **Publish to npm** workflow: npm Trusted Publishing
-publishes the version, and the workflow creates its version tag and GitHub
-Release. The workflow's manual dispatch can retry publishing a version already
-merged to `main`. The [npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
+The repository's primary forge is Gitea, and GitHub is its push mirror. The
+release runs in two halves, one on each:
+
+1. **Version, on Gitea.** Merging a changeset to `main` runs
+   `.gitea/workflows/release.yml`, which opens or updates the **Version
+   Packages** pull request. Its generated changelog section is reviewed as the
+   release note. Merging that pull request runs the same workflow again, which
+   pushes the tag `v<version>` at the merged version commit. Releasing from
+   Gitea is switched on by the repository variable `HL_RELEASE_ENABLED`.
+2. **Publish, on GitHub.** The push mirror carries the tag to GitHub, where it
+   starts the **Publish to npm** workflow, `.github/workflows/release.yml`. It
+   refuses a tag that names a commit outside `main` or that is not
+   `v<version>` of the tagged `package.json`. When npm does not have the
+   version yet, it runs the tests and publishes through npm Trusted Publishing
+   with provenance. It then creates the GitHub Release from the version's
+   changelog section, unless one exists.
+
+Nothing on Gitea publishes to npm, and nothing on GitHub runs for a branch
+push. Every step of the GitHub half is safe to repeat: re-running it, or
+dispatching it with the tag as its ref, finishes a release whose publish or
+Release step failed and changes nothing for one that completed. The
+[npm package page](https://www.npmjs.com/package/@heroiclands/package-build)
 shows the published version and README.
 
 Two scripts in this repository's own `package.json` run the same steps at a

package/docs/guides/site.md

@@ -153,7 +153,7 @@ tree rather than about one note, so the build replaces whatever a note wrote.
 
 Artwork addresses are rewritten in place under `data`. A page's `data.icon`,
 `data.tokenIcon` and `data.banner` carry the URLs the site serves rather than the
-addresses the note authored, and there are four cases to tell apart:
+addresses the note authored, and there are five cases to tell apart:
 
 | The note writes              | The page carries |
 | ---------------------------- | ---------------- |
@@ -161,12 +161,15 @@ addresses the note authored, and there are four cases to tell apart:
 | an address nothing answers   | no key at all    |
 | `null`                       | `null`           |
 | `""`                         | `""`             |
+| `data.banner: none`          | `""`             |
 
 An address nothing answers is deleted rather than written through, so an absent
 key is the ordinary case for a theme to render nothing against, and no page
 reaches a reader carrying a broken image source. The two empties are distinct
 and both survive: `null` is a note naming no art, where a default may apply,
-and `""` is a note refusing art, where no default may replace it.
+and `""` is a note refusing art, where no default may replace it. A note
+writes `none` to refuse a hero image, since `""` is an error in authored
+frontmatter.
 
 The build writes these keys; [what the theme draws](../reference/theme-pages.md)
 describes the panel each one feeds — the infobox, the hero band, the related

package/docs/project-setup.md

@@ -229,7 +229,7 @@ git worktree where `node_modules` is already correct.
 
 `build:stage-reset` clears only the assembled Foundry package. Keep it before
 every stage writer, including a repository's own code or stylesheet bundle
-step. This keeps renamed and deleted files out of the next package while
+step. This keeps moved and deleted files out of the next package while
 preserving the content index and other generated outputs.
 
 Within the chain, two orderings are real:
@@ -349,15 +349,35 @@ options the toolchain applies — without it they fall back to Prettier's own
 defaults, and a print width that differs from the project's turns every
 save into a diff the lint chain reverts.
 
-`package-build markdown` needs no equivalent file: it hands the shared rule set
-to markdownlint directly, and a repository that declares nothing gets it. A
-`.markdownlint-cli2.jsonc` is for the editor's markdownlint extension, and
-[`@heroiclands/package-build/markdownlint`](api.md) is the export it re-uses —
-with one trap worth knowing before writing one. A consumer file overrides the
-shared configuration **key by key, and each key wholesale**: declaring only
-`ignores` keeps every rule intact but _replaces_ the shared ignore list rather
-than extending it, so such a file must restate `CHANGELOG.md` if it still wants
-that file excluded. The command always excludes `node_modules`.
+`package-build markdown` needs no equivalent file: it applies the shared rule
+set through the markdownlint library, and a repository that declares nothing
+gets it. A `.markdownlint-cli2.jsonc` (or `.yaml`, `.cjs`, `.mjs`) at the
+repository root overrides it and is what the editor's markdownlint extension
+reads, and [`@heroiclands/package-build/markdownlint`](api.md) is the export it
+re-uses — with one trap worth knowing before writing one. A consumer file
+overrides the shared configuration **key by key, and each key wholesale**:
+declaring only `ignores` keeps every rule intact but _replaces_ the shared ignore
+list rather than extending it, so such a file must restate `CHANGELOG.md` if it
+still wants that file excluded. The command always excludes `node_modules` and
+`.git`.
+
+The options file accepts a closed set of keys, and any other key is refused with
+a located diagnostic:
+
+| Key              | Where                | Meaning                                                                   |
+| ---------------- | -------------------- | ------------------------------------------------------------------------- |
+| `config`         | any directory        | Rule settings, merged rule by rule over the settings above it.            |
+| `customRules`    | any directory        | Module ids (resolved from that directory) or rule objects to add.         |
+| `frontMatter`    | any directory        | Regular expression source matching a front matter block.                  |
+| `ignores`        | any directory        | Globs, relative to that directory, whose files are skipped.               |
+| `noInlineConfig` | any directory        | `true` to disregard `<!-- markdownlint-... -->` comments.                 |
+| `globs`          | repository root only | Globs of files to lint, in addition to `**/*.md` when no paths are named. |
+| `gitignore`      | repository root only | `false` to lint files that `.gitignore` files exclude; `true` by default. |
+
+An options file in a subdirectory applies to that directory and below, merged
+over the root's. A `.markdownlint.jsonc`, `.json`, `.yaml`, `.yml`, `.cjs` or
+`.mjs` file holds a rule `config` directly and replaces the merged `config` for
+its directory.
 
 ## `.prettierignore`