build(release): install the packed release on its own before publishing, and on pull requests

.github/workflows/ci.yml

@@ -57,3 +57,44 @@ jobs:
       # later PR's qualification.
       - name: Test unforced (work in flight at stop)
         run: node --test dist/test/stop-with-work-in-flight.test.js dist/test/stop-with-host-operations.test.js dist/test/conversation-routing.test.js
+
+  # The release as npm would pack it, installed on its own and loaded, as
+  # the publish workflow checks before it publishes (see
+  # scripts/pack-installs-alone.mjs): here a change that leaves a file out
+  # of the package, or imports what only devDependencies supply, fails
+  # before it merges, not after a tag and its release notes are out. The
+  # install resolves dependencies from the registry as it stands, so a new
+  # upstream release can turn it red on a change that touched nothing it
+  # installs: when it fails, rerunning it on main tells a change's own break
+  # from the registry's drift.
+  pack-check:
+    name: Packed release installs on its own
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+
+      # As publish installs, so a build that came to need a dependency's
+      # install script fails here, before a tag, rather than in publish.
+      - name: Install dependencies
+        run: npm install --ignore-scripts
+
+      - name: Build
+        run: npm run build
+
+      # bun loads the package's `bun` export target, which Node never reads.
+      # 1.3.14 is the bun connectome-host's CI runs this package under.
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.14
+
+      - name: Packed release installs on its own
+        run: node scripts/pack-installs-alone.mjs

.github/workflows/publish.yml

@@ -52,10 +52,54 @@ jobs:
       - name: Test
         run: npm test
 
+  # The tarball npm publish makes from this tree, installed alone into an
+  # empty directory with its dependencies from npm (nested, so the package
+  # reaches only its own), and loaded under Node and under bun: a file
+  # missing from `files`, a dependency only devDependencies supplied, or a
+  # bin npm's link can't run fails here, not for whoever installs the
+  # release. A job of its own, so the install scripts it runs never see
+  # the publish job's id-token; publish needs it, the GitHub release notes
+  # don't. It runs on a dispatch too, which publishes nothing.
+  pack-check:
+    name: Packed release installs on its own
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 24
+
+      # As publish installs, so a build that came to need a dependency's
+      # install script fails here rather than in publish.
+      - name: Install dependencies
+        run: npm install --ignore-scripts
+
+      # npm publish builds again first, through prepublishOnly, from the
+      # same sources.
+      - name: Build
+        run: npm run build
+
+      # bun loads the package's `bun` export target, which Node never reads.
+      # 1.3.14 is the bun connectome-host's CI runs this package under.
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.14
+
+      - name: Packed release installs on its own
+        run: node scripts/pack-installs-alone.mjs
+
   publish:
     name: Publish to npm
     runs-on: ubuntu-latest
-    needs: build-and-test
+    needs: [build-and-test, pack-check]
     if: startsWith(github.ref, 'refs/tags/v')
 
     # OIDC trusted publishing: GitHub mints a short-lived id-token, npm CLI
@@ -89,12 +133,19 @@ jobs:
           node-version: 24
           registry-url: https://registry.npmjs.org
 
+      # --ignore-scripts: this job holds the id-token, and neither the build
+      # nor npm publish needs a dependency's install script. The pack-check
+      # job's install of the packed release runs them, as an install from
+      # npm does, without the id-token.
       - name: Install dependencies
-        run: npm install
+        run: npm install --ignore-scripts
 
       - name: Build
         run: npm run build
 
+      # This publishes from the tree, not the tarball pack-check checked: npm
+      # skips a package's own lifecycle scripts for a tarball, so publishing
+      # one would also skip prepublishOnly's release-hold check.
       - name: Publish
         run: npm publish --access public --provenance
         env:

CONTRIBUTING.md

@@ -135,15 +135,23 @@ never do.
   (subsections emitted in `### Breaking` / `### Added` / `### Changed` /
   `### Fixed` order), deletes the consumed fragments, keeps a fresh empty
   `Unreleased` above, and refuses to release when there is nothing to
-  release; npm then commits and tags. `git push --follow-tags` triggers
-  CI, which refuses a tag with no matching changelog section, publishes
-  `@animalabs/agent-framework` to npm, and creates the GitHub release with
-  that section as its notes. The two release jobs are independent: some
-  consumers run github-clone checkouts, so release notes must exist even
-  when npm publish fails. Both need the build job, so a failed build stops
-  both; past it, so do a tag with no changelog section, which neither can
-  release, and an open release hold (below), which each checks. Version
-  bumps are a maintainer release-time action, not part of feature PRs.
+  release; npm then commits and tags. `git push --follow-tags` triggers CI,
+  which refuses a tag with no matching changelog section, checks in a job
+  of its own that the packed release installs on its own
+  (`node scripts/pack-installs-alone.mjs` packs it, installs the tarball
+  alone into an empty directory with its dependencies from npm, nested so
+  the package reaches only its own, and checks the installed package, as
+  the script's header lists; to run it by hand, `npm run build` first, for
+  example before `git push --follow-tags`, or dispatch the workflow on a
+  branch, where it publishes nothing), publishes
+  `@animalabs/agent-framework` to npm once that check has passed, and
+  creates the GitHub release with that section as its notes. The two
+  release jobs are independent: some consumers run github-clone checkouts,
+  so release notes must exist even when npm publish fails. Both need the
+  build job, so a failed build stops both; past it, so do a tag with no
+  changelog section, which neither can release, and an open release hold
+  (below), which each checks. Version bumps are a maintainer release-time
+  action, not part of feature PRs.
 - **Breaking changes.** A dependent's caret range takes the later
   versions of its line (0.22.x before 1.0, 1.x from 1.0, and 0.0.z alone),
   so a breaking change released as a patch reaches each dependent whose
@@ -194,7 +202,11 @@ branches. The `pretest` hook copies `test/fixtures/*.mjs` into `dist/`.
 
 Push-time CI (`ci.yml`) builds, typechecks and tests every push and PR on
 ubuntu and macos. Lockfiles are deliberately gitignored in this repo, so CI
-installs with plain `npm install` and there is no lock to keep in sync.
+installs with `npm install` rather than `npm ci`, and there is no lock to
+keep in sync. It also runs the pack check the publish workflow runs before
+publishing (`node scripts/pack-installs-alone.mjs`, on ubuntu, with bun set
+up), so a file left out of the package, or an import only `devDependencies`
+supply, fails the PR.
 
 When working against local sibling checkouts rather than published versions,
 see the ecosystem workspace setup — `bun install` at the `rust-connectome`