Assert tool versions in CI and document unsupported platforms

Addresses code review on #1775.

The `node --version` step added with the pnpm conversion only printed the
version, so a mise-shadowed Node would have gone undetected unless a human
read the log. test.yml now compares the running major against the matrix
value and fails on mismatch. The matrix value is passed through env rather
than interpolated into the run block, which is the form zizmor's
template-injection audit flags. lint.yml has no matrix, so its step is
relabelled as the smoke check it actually is.

Shadowing is also prevented outright: every mise-action step now sets
add_shims_to_path: false, so no mise shims directory reaches PATH. The
install step runs `mise install --locked` and fails if `mise which pnpm`
returns nothing, rather than appending an empty dirname -- which is `.`
-- to $GITHUB_PATH.

test.yml and lint.yml also set `cache: false` on mise-action. With
install: false, mise-action saves a cache only inside its install branch,
so nothing there ever writes one, and the restore it would otherwise
still attempt can never hit.

release.yml's publish job now asserts npm >= 11.5.1, the invariant that
lets it pin Node 24 and skip installing npm globally. A Node downgrade
would otherwise only surface during a real release. The step sits
immediately before `npm publish`, so nothing can change PATH in between.

mise.toml's lockfile_platforms comment claimed more than the setting
delivers. `mise lock` always locks the platform it runs on, even one
excluded from that list -- verified by dropping the current platform and
regenerating, which re-added it. So the list is not a hard guard, and the
comment now says so and points at the post-regeneration check.

Records that Intel macOS and Windows ARM64 are unsupported, so excluding
macos-x64 is not a loss of support. Intel macOS could not work regardless:
pnpm 11.0.5 and later ship no darwin-x64 binary, which is why mise falls
back to the release's unrelated source-maps.tgz there. README.dev.md
gains a supported platforms section.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: mm-jpoole

.github/workflows/lint.yml

@@ -20,20 +20,25 @@ jobs:
           node-version: 22
           package-manager-cache: false
       # Install only pnpm, not the repo's full toolchain — Node comes from
-      # actions/setup-node, which pins the version this job needs.
-      # Appending only pnpm's directory to PATH keeps mise's own Node
-      # (mise.toml pins "latest") from ever shadowing setup-node's.
+      # actions/setup-node. See mise.toml [tools] comment for why.
       - name: Setup mise
         uses: jdx/mise-action@7e36c90d9ab29c415a2384db3006f3ec8a8cc654 # v4.2.4
         with:
           install: false
+          add_shims_to_path: false
+          # mise-action saves a cache only inside its install branch, so with
+          # install: false nothing here ever writes one. The restore is gated
+          # separately and would still run, always missing, so turn it off.
+          cache: false
       - name: Install pnpm
         env:
           MISE_AUTO_INSTALL: 'false'
         run: |
-          mise install github:pnpm/pnpm
-          dirname "$(mise which pnpm)" >> "$GITHUB_PATH"
-      # Sanity check: pnpm resolves, and mise has not shadowed setup-node's Node.
+          mise install --locked github:pnpm/pnpm
+          pnpm_bin=$(mise which pnpm)
+          [ -x "$pnpm_bin" ] || { echo "mise which pnpm produced no usable path" >&2; exit 1; }
+          dirname "$pnpm_bin" >> "$GITHUB_PATH"
+      # Smoke check only; there is no matrix here to get wrong.
       - run: node --version && pnpm --version
       - name: Install packages
         run: pnpm install --frozen-lockfile

.github/workflows/release.yml

@@ -24,26 +24,26 @@ jobs:
           node-version: 22
           package-manager-cache: false
       # Install only pnpm, not the repo's full toolchain — Node comes from
-      # actions/setup-node, which pins the version this job needs.
-      # Appending only pnpm's directory to PATH keeps mise's own Node
-      # (mise.toml pins "latest") from ever shadowing setup-node's.
+      # actions/setup-node. See mise.toml [tools] comment for why.
       - name: Setup mise
         uses: jdx/mise-action@7e36c90d9ab29c415a2384db3006f3ec8a8cc654 # v4.2.4
         with:
           install: false
-          # Caching is disabled in this workflow only. zizmor's cache-poisoning
-          # audit flags a restorable cache in a job that publishes artifacts
-          # built at runtime, which is also why the setup-node steps here set
-          # package-manager-cache: false. test.yml and lint.yml leave the
-          # default, which zizmor does not flag -- though with install: false
-          # mise-action never writes a cache there either.
+          add_shims_to_path: false
+          # zizmor's cache-poisoning audit flags a restorable cache in a job
+          # that publishes artifacts built at runtime, which is also why the
+          # setup-node steps here set package-manager-cache: false. test.yml
+          # and lint.yml set it too, there just to skip a restore that can
+          # never hit: with install: false mise-action never saves one.
           cache: false
       - name: Install pnpm
         env:
           MISE_AUTO_INSTALL: 'false'
         run: |
-          mise install github:pnpm/pnpm
-          dirname "$(mise which pnpm)" >> "$GITHUB_PATH"
+          mise install --locked github:pnpm/pnpm
+          pnpm_bin=$(mise which pnpm)
+          [ -x "$pnpm_bin" ] || { echo "mise which pnpm produced no usable path" >&2; exit 1; }
+          dirname "$pnpm_bin" >> "$GITHUB_PATH"
       - run: pnpm install --frozen-lockfile
       - run: pnpm test
       - run: pnpm run lint
@@ -65,42 +65,44 @@ jobs:
           persist-credentials: false
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
-          # Node 24 bundles npm 11.17.0, above the 11.5.1 minimum for npm
-          # Trusted Publishing. On Node 22 (npm 10.9.8) this job had to run
-          # `npm install -g npm@latest`, which tripped zizmor's adhoc-packages
-          # rule for installing outside a lockfile.
+          # npm Trusted Publishing needs npm >= 11.5.1 and Node >= 22.14.0.
+          # Node 24 bundles a new enough npm; Node 22 does not, which is why
+          # `npm install -g npm@latest` is gone (zizmor adhoc-packages). The
+          # bundled version moves each 24.x, so it is asserted before publish.
           node-version: 24
           package-manager-cache: false
           # Writes the .npmrc that OIDC publishing needs.
           registry-url: 'https://registry.npmjs.org'
       # Install only pnpm, not the repo's full toolchain — Node comes from
-      # actions/setup-node, which pins the version this job needs.
-      # Appending only pnpm's directory to PATH keeps mise's own Node
-      # (mise.toml pins "latest") from ever shadowing setup-node's.
+      # actions/setup-node. See mise.toml [tools] comment for why.
       - name: Setup mise
         uses: jdx/mise-action@7e36c90d9ab29c415a2384db3006f3ec8a8cc654 # v4.2.4
         with:
           install: false
-          # Caching is disabled in this workflow only. zizmor's cache-poisoning
-          # audit flags a restorable cache in a job that publishes artifacts
-          # built at runtime, which is also why the setup-node steps here set
-          # package-manager-cache: false. test.yml and lint.yml leave the
-          # default, which zizmor does not flag -- though with install: false
-          # mise-action never writes a cache there either.
+          add_shims_to_path: false
+          # Same reason as the build job above.
           cache: false
       - name: Install pnpm
         env:
           MISE_AUTO_INSTALL: 'false'
         run: |
-          mise install github:pnpm/pnpm
-          dirname "$(mise which pnpm)" >> "$GITHUB_PATH"
+          mise install --locked github:pnpm/pnpm
+          pnpm_bin=$(mise which pnpm)
+          [ -x "$pnpm_bin" ] || { echo "mise which pnpm produced no usable path" >&2; exit 1; }
+          dirname "$pnpm_bin" >> "$GITHUB_PATH"
       - run: pnpm install --frozen-lockfile
       - run: pnpm run build
-      # Publishing stays on the npm CLI. pnpm has no native OIDC support — it
-      # shells out to npm for trusted publishing and provenance, and that path
-      # has known failures (pnpm/pnpm#9812). npm publish is safe in a
-      # pnpm-installed tree: it packs only `files: ["dist"]` and reads no
-      # lockfile.
+      # Assert rather than trust the npm that setup-node's `node-version` pin
+      # bundled: a Node downgrade would otherwise only surface during a real
+      # release. Sits immediately before the publish so nothing can change PATH.
+      - name: Verify npm supports trusted publishing
+        run: |
+          npm_version=$(npm --version)
+          echo "npm $npm_version (need >= 11.5.1 for OIDC trusted publishing)"
+          printf '11.5.1\n%s\n' "$npm_version" | sort -V -C
+      # Publishing deliberately stays on the npm CLI; adopting pnpm's own OIDC
+      # support is a separate follow-up issue. npm publish is safe in a
+      # pnpm-installed tree: it packs only `files: ["dist"]`, reads no lockfile.
       - run: npm publish --provenance
       - run: pnpm run build:docs
       - name: Deploy docs to gh-pages

.github/workflows/test.yml

@@ -23,25 +23,36 @@ jobs:
           node-version: ${{ matrix.version }}
           package-manager-cache: false
       # Install only pnpm, not the repo's full toolchain — Node comes from
-      # actions/setup-node so the version matrix stays in control.
-      # Appending only pnpm's directory to PATH keeps mise's own Node
-      # (mise.toml pins "latest") from ever shadowing setup-node's.
+      # actions/setup-node. See mise.toml [tools] comment for why.
       - name: Setup mise
         uses: jdx/mise-action@7e36c90d9ab29c415a2384db3006f3ec8a8cc654 # v4.2.4
         with:
           install: false
+          add_shims_to_path: false
+          # mise-action saves a cache only inside its install branch, so with
+          # install: false nothing here ever writes one. The restore is gated
+          # separately and would still run, always missing, so turn it off.
+          cache: false
       - name: Install pnpm
         env:
           MISE_AUTO_INSTALL: 'false'
         run: |
-          mise install github:pnpm/pnpm
-          dirname "$(mise which pnpm)" >> "$GITHUB_PATH"
-      # Guard: mise must not shadow the Node that setup-node selected, or the
-      # matrix would silently test one version twice and still pass.
-      - run: node --version && pnpm --version
-      # One root install links the workspace, so e2e/js and e2e/ts resolve
-      # @maxmind/geoip2-node through a symlink to the repo root. `build` must
-      # run before them so dist/ exists.
+          mise install --locked github:pnpm/pnpm
+          pnpm_bin=$(mise which pnpm)
+          [ -x "$pnpm_bin" ] || { echo "mise which pnpm produced no usable path" >&2; exit 1; }
+          dirname "$pnpm_bin" >> "$GITHUB_PATH"
+      # Assert, don't just print: if mise shadowed the Node that setup-node
+      # selected, every matrix leg would test the same version and still pass.
+      - name: Verify the matrix Node is active
+        env:
+          EXPECTED_MAJOR: ${{ matrix.version }}
+        run: |
+          actual=$(node -p 'process.versions.node.split(".")[0]')
+          echo "node major: $actual (expected $EXPECTED_MAJOR), pnpm $(pnpm --version)"
+          test "$actual" = "$EXPECTED_MAJOR"
+      # One root install links the workspace, so e2e/js and e2e/ts resolve the
+      # library through a symlink to the repo root. `build` must run before
+      # them so dist/ exists.
       - run: pnpm install --frozen-lockfile
       - run: pnpm run test:coverage
       - run: pnpm run build
@@ -50,12 +61,10 @@ jobs:
         working-directory: e2e/js
       - run: pnpm exec vitest run
         working-directory: e2e/ts
-      # Vitest transpiles without checking types, and neither root tsconfig
-      # covers e2e -- both use include: ["src"] -- so nothing else type-checks
-      # the TypeScript consumer. That matters here because the failure mode a
-      # non-hoisting package manager introduces is exactly a type-resolution
-      # break in the published surface. Must run after `build`: the import
-      # resolves through the workspace symlink to dist/src/index.d.ts, so with
-      # no dist/ this reports TS2307 instead of checking anything.
+      # Nothing else type-checks the TypeScript consumer: vitest transpiles
+      # without checking, and both root tsconfigs use include: ["src"]. That
+      # matters because a non-hoisting package manager breaks exactly this --
+      # type resolution in the published surface. Must run after `build`, or
+      # the workspace symlink to dist/src/index.d.ts gives TS2307.
       - run: pnpm exec tsc --noEmit
         working-directory: e2e/ts

README.dev.md

@@ -20,6 +20,27 @@
 Note: Publishing is done via GitHub Actions using npm Trusted Publishing
 (OIDC). Manual `npm publish` is not supported.
 
+## Development setup
+
+Dependencies are managed with pnpm, pinned in `mise.toml`. Run `mise install`
+to get it, then `pnpm install`. Do not use npm or corepack: the repo is a pnpm
+workspace (`e2e/js` and `e2e/ts` are members) with a single root
+`pnpm-lock.yaml`, and npm cannot resolve their `workspace:*` dependency.
+
+Publishing is the one exception. `release.yml` calls `npm publish --provenance`.
+pnpm 11 supports OIDC trusted publishing, but that change will be made in a
+future issue.
+
+## Supported development platforms
+
+Linux on x64 and arm64, Apple Silicon macOS on arm64, and Windows on x64.
+**Intel macOS and Windows ARM64 are not supported.** Intel macOS in particular
+cannot be: pnpm 11.0.5 and later ship no `darwin-x64` binary, so there is
+nothing for mise to install. `mise.toml` restricts `lockfile_platforms`
+accordingly, but note that `mise lock` always locks whichever platform it runs
+on -- so if you regenerate `mise.lock`, verify `grep -c source-maps mise.lock`
+prints 0 before committing.
+
 ## Set up Precious to tidy and lint
 
 1. Run `mkdir -p local && ./bin/install-precious local` to set up Precious locally

mise.toml

@@ -6,9 +6,16 @@ disable_backends = [
     "vfox",
 ]
 
-# Excludes macos-x64 only. pnpm 11 ships no darwin-x64 binary at all, so mise
-# mis-resolves that platform to the release's unrelated source-maps.tgz asset.
-# Every other platform the tools actually support is kept.
+# The platforms we support. Intel macOS (macos-x64) and Windows ARM64
+# (windows-arm64) are absent because we do not support either. Intel macOS also
+# cannot work: pnpm 11.0.5 and later ship no darwin-x64 binary, so mise
+# mis-resolves that platform to the release's unrelated source-maps.tgz asset,
+# producing a lock entry that verifies but contains no pnpm.
+#
+# This list is not a hard guard: `mise lock` always locks the platform it runs
+# on, excluded or not -- verified by dropping the current platform and
+# regenerating, which re-added it. After any regeneration, check
+# `grep -c source-maps mise.lock` prints 0.
 lockfile_platforms = [
     "linux-arm64",
     "linux-arm64-musl",
@@ -19,6 +26,10 @@ lockfile_platforms = [
 ]
 
 [tools]
+# CI never installs this. Every workflow runs mise-action with install: false
+# and add_shims_to_path: false, then puts only pnpm's install directory on
+# PATH. So two things independently keep this "latest" pin out of jobs whose
+# Node actions/setup-node fixed: no shims directory, and no node in that dir.
 node = "latest"
 lychee = "latest"
 # pnpm is on the github backend because aqua-registry's pnpm config keeps