@heroiclands/package-build 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,140 @@
+# @heroiclands/package-build
+
+## 0.2.1
+
+### Patch Changes
+
+- 4144291: **Release from merged changesets instead of a remembered command**
+  
+  Fixes [#4](https://github.com/HeroicLands/package-build/issues/4). Releasing was
+  hand-driven — bump `package.json` on a branch, merge, then remember
+  `gh release create`, because cutting the Release is what published. Nothing
+  enforced the last step, so a merged version could sit unpublished with no check
+  red; the sibling repository lost two versions that way.
+  
+  - Every pull request now declares its bump as a `.changeset/*.md` file, and CI's
+    **Changeset declared** job fails one that does not. `npx changeset add --empty`
+    is how a change says it needs no release — explicitly, rather than by omission.
+  - Merging to `main` opens a **Version Packages** pull request carrying the bump
+    and the rewritten `CHANGELOG.md`. An unreleased state is now a pull request
+    waiting in the queue rather than nothing at all.
+  - Merging that runs `changeset publish`: npm publish, the `v<version>` tag, and
+    the GitHub Release with the changelog section as its body. The OIDC Trusted
+    Publishing step is unchanged and still last; there is still no `NPM_TOKEN`, and
+    re-running on a published version is a no-op.
+  - `CHANGELOG.md` is seeded from the two hand-cut Releases so far and now ships
+    with the package. A changeset is also where a raised dependency floor gets
+    recorded — 0.2.0 raised one to `@heroiclands/content-build >= 0.15.0` and said
+    so nowhere.
+
+<!-- Sections at 0.2.1 and above are generated by `changeset version` from the
+     changesets merged into `main`. Sections at 0.2.0 and below predate that
+     pipeline and are the hand-written GitHub Release notes, kept verbatim
+     (headings demoted one level to sit under their version) so no history was
+     lost in adopting it. -->
+
+## 0.2.0
+
+_2026-08-22 — a command line, not a wrapper script per job_
+
+**A command line, so a consumer writes configuration instead of scripts.**
+
+This package was library-only, so every consuming repository wrote a wrapper script per job — six of them in the Song of Heroic Lands repository, 441 lines that between them contained no logic:
+
+| Wrapper | Lines | What was in it |
+| --- | --- | --- |
+| `build-system-json.mjs` | 143 | |
+| `push-stage.mjs` | 76 | argv, dotenv, then `packageKind: "systems"` and `packageId: "sohl"` hard-coded beside a configuration that already declared both |
+| `copy-assets.mjs` | 71 | a nine-entry data table, plus one genuine repository-specific transform |
+| `check-lang.mjs` | 69 | a glob, a call, and a help string |
+| `clean.mjs` | 47 | a `repoRoot` from `import.meta.url`, one flag, one call — no consumer-specific value at all |
+| `pack-release.mjs` | 35 | one call passing `{ artifact: "system" }`, which `packageKind` already decides |
+
+Every copy had drifted from its sibling in the other repositories, because copies do: `clean.mjs` was 47 lines in SoHL and 48 in `sohl-thalorna`, `copy-assets.mjs` 71 and 76. `sohl-thalorna`'s copy still reimplements the recursive directory copy this package has exported since it was extracted, because it was written before the extraction and nobody went back.
+
+It is the same shape the configuration had before it became data: not logic, but the boilerplate a code file needs in order to *state a literal*. So the literals moved into configuration, and the boilerplate lives here, once.
+
+#### The commands
+
+```
+npx package-build clean [--distclean]
+npx package-build assets
+npx package-build lang check
+npx package-build release
+npx package-build deploy <stage>
+```
+
+Wrapped as npm scripts:
+
+```json
+{
+  "clean": "package-build clean",
+  "build:assets": "package-build assets",
+  "lint:lang": "package-build lang check",
+  "build:pack-release": "package-build release",
+  "push:qa": "package-build deploy qa"
+}
+```
+
+#### One configuration file, not two
+
+Settings come from the reserved `packageBuild:` section of `content-build.config.yaml` — the file a repository already has — which requires **`@heroiclands/content-build` 0.15.0 or later**.
+
+```yaml
+packageKind: systems      # read from the top level, never restated below
+foundryPackage: sohl
+
+packageBuild:
+    assets:
+        - { from: lang, to: lang }
+    assetTransform: ./utils/svg-theme.mjs
+    clean:
+        extra: [site/content, site/public]
+    deploy:
+        envPrefix: SOHL
+```
+
+A second config file would have restated `packageKind` and `foundryPackage`, which is two places for one fact. content-build validates only that the section is a mapping and hands it back frozen; everything inside it is validated here, so neither package learns the other's schema.
+
+**Derived, never stated:** the repository root (the config file's own location), `packageKind` and `packageId` (the shared configuration's top level), and the release artifact — a system ships `system.json`, a module `module.json`, so the kind already decides it.
+
+**The one genuine piece of consumer code stays the consumer's.** SoHL rewrites each SVG's hard-coded fill so icons follow the Foundry theme; `packageBuild.assetTransform` names a module exporting `transform(sourcePath) -> string | null`.
+
+#### Also in this release
+
+- `exports["./config"]` now ships its type declaration. It was declared but never generated — `tsconfig.dts.json` lists its inputs explicitly and `config.mjs` was missing from the list — so the subpath would have pointed at a file that does not exist.
+- The library modules are unchanged. Every signature the CLI needed was already there.
+
+#### Notes
+
+`--version` and `--help` answer in a directory with no configuration at all. Failures report one line rather than a stack, whether the handler was synchronous or asynchronous. Localization findings follow the diagnostics contract, `file:line:column: severity: message`.
+
+**Full changelog:** https://github.com/HeroicLands/package-build/compare/v0.1.0...v0.2.0
+
+## 0.1.0
+
+_2026-08-22 — the Foundry package toolchain_
+
+The counterpart to [`@heroiclands/content-build`](https://github.com/HeroicLands/content-build). The two split by **input**, not by repository: content-build reads `assets/content/**` and answers for what a package *says*; this one reads `lang/`, `styles/`, `src/`, `assets/` and the manifest template, and answers for what a package *is* — the parts Foundry loads whether or not the package ships any content.
+
+A module uses either, or both. An adventure module that ships only notes needs no bundler; a variant module that ships only behavior needs no Markdown pipeline. The coupling runs one way: package-build asks content-build for the compiled `packs[]` block, never the reverse.
+
+### Seven modules — the whole of assemble → validate → ship
+
+- **`manifest`** — `system.json` / `module.json`. The artifact is inferred from the template's name, and every address is derived from `package.json`'s `repository` rather than transcribed. Handles the `git+https://….git` spelling npm writes, which yields a 404 on every Foundry update check if left in place.
+- **`stage`** — assembling the build stage and clearing it away. A listed asset that does not exist **fails the build** instead of shipping a package that quietly lacks its localization or templates; the whole list is checked before anything is copied.
+- **`lang`** — what a shippable localization file must satisfy: it parses, its top level is an object, no key is both a leaf and a dotted prefix of another (which makes Foundry discard the entire file), placeholders are single-braced, key segments carry no data.
+- **`bundle`** — whether the manifest agrees with the file it points at. Declared under `"esmodules"` the bundle must parse as a module; declared under `"scripts"` it must declare **nothing** at top level, because each top-level declaration in a classic script is a global lexical binding and one colliding with a non-configurable `window` property throws at parse time. That rule bricked SoHL v0.8.0.
+- **`release`** — the two assets a GitHub Release carries. Waits for the archive to be *written*, not merely finalized.
+- **`deploy`** — installing into a Foundry data directory, local or SFTP, always as a staged atomic swap: a running Foundry holds its LevelDB packs open, and replacing them in place leaves a directory LevelDB "repairs" to zero.
+- **`text`** — locating a literal, so a finding names its line and column.
+
+### Design
+
+The rules are pure functions over data; the functions that touch disk or a network are named for what they do. That is what makes them testable at all — the scripts they were extracted from each ran their work at import time and exported nothing.
+
+### Provenance
+
+Developed as a workspace inside the Song of Heroic Lands repository across six changes (SoHL#1680, #1682, #1684, #1685, #1686), exactly as content-build incubated before its own extraction, and extracted now that its shape has stopped changing.
+
+128 tests; declaration files are emitted from the JSDoc at pack time.

package/README.md

@@ -198,6 +198,43 @@ would let something reach for one.
 declared `dependency`. Inside a workspace a missing declaration is invisible;
 installed from npm it fails on the first import.
 
+## Releasing
+
+Releasing is not a command anyone runs. It is a consequence of merging, in two
+steps, and each step is visible while it is pending.
+
+**Every pull request declares its bump.** Run `npx changeset` and pick
+major/minor/patch; the summary you write becomes the changelog entry and the
+release note. If the change ships nothing a consumer can see, say so explicitly
+with `npx changeset add --empty`. CI's **Changeset declared** job fails a pull
+request that declares neither — `npm run changeset:check` is the same check,
+locally.
+
+**Merging to `main` opens a Version Packages pull request** carrying the version
+bump and the rewritten `CHANGELOG.md`. That pull request _is_ the pending
+release: as long as something is merged but unpublished, there is an open pull
+request saying so. The previous, hand-driven process failed by leaving _nothing_
+behind when its final step was forgotten (#4).
+
+**Merging that publishes.** `changeset publish` puts the version on npm through
+Trusted Publishing (OIDC — there is no `NPM_TOKEN`), tags the commit `v<version>`
+and cuts the GitHub Release with the changelog section as its body. It publishes
+only versions that are not already on the registry, so re-running it is a no-op;
+`workflow_dispatch` on **Publish to npm** is the recovery path if a run fails
+after versioning.
+
+A changeset is also where a **raised dependency floor** gets recorded. 0.2.0 began
+requiring `@heroiclands/content-build >= 0.15.0` and announced it nowhere; a
+changeset is the place that now happens.
+
+Below 1.0.0, `^0.x` never crosses a minor — a consumer on `^0.2.0` will not see
+`0.3.0` until it bumps the pin deliberately, and Dependabot raises that as its own
+pull request.
+
+> After a successful publish, `npm view @heroiclands/package-build version` can
+> report the _previous_ version for a minute or so. `dist-tags` is correct
+> immediately, and is what the workflow prints.
+
 ## Licence
 
 GPL-3.0-or-later.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.2.0",
-    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
+    "version": "0.2.1",
+    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
     "main": "./index.mjs",
@@ -55,6 +55,7 @@
         "stage.mjs",
         "text.mjs",
         "types",
+        "CHANGELOG.md",
         "README.md",
         "bin",
         "config.mjs"
@@ -66,6 +67,8 @@
         "build:types": "tsc -p tsconfig.dts.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
+        "changeset": "changeset",
+        "changeset:check": "changeset status --since=origin/main",
         "prepare": "git config core.hooksPath .githooks || true"
     },
     "dependencies": {
@@ -78,6 +81,7 @@
         "yargs": "^18.1.0"
     },
     "devDependencies": {
+        "@changesets/cli": "^3.0.0",
         "@types/node": "^26.2.0",
         "prettier": "^3.9.6",
         "typescript": "^6.0.3",