Install the pinned node when the installed one is another major version (closes #118)

script/bootstrap used whatever node was installed, so on the CI runner
image, which ships node 24, the pinned yarn 1.22.22 printed the
deprecation warning DEP0169 on every bootstrap. It now uses the
installed node only when its major version is the pinned one, and
otherwise installs the pinned node with nvm, as it already did when node
was missing, with yarn and the packages under it. It prints the node
version it uses. Only the major is compared because the Dockerfile
stages use a node 22 alpine image that nvm cannot replace. script/fmt
and script/fmt-check carry the same test to pick their yarn: the yarn on
PATH, or yarn under the pinned node loaded through nvm.

Model: opus-5-5

TODO.md

@@ -24,14 +24,18 @@ fmt-check, and commit.
 - 2026-10-08: The canonical `script/bootstrap` now uses the installed node only
   when its major version is the pinned one (issue 118). Otherwise, as when node
   is missing, it installs the pinned node under nvm and installs yarn and the
-  packages under it. The CI runner image ships node 24, under which the pinned
+  packages under it. It prints the version of the node it uses either way. The
-  yarn 1.22.22 printed the deprecation warning DEP0169 on every bootstrap. Only
+  CI runner image ships node 24, under which the pinned yarn 1.22.22 printed the
-  the major is compared because the `Dockerfile` stages start from a node 22
+  deprecation warning DEP0169 on every bootstrap. Only the major is compared
-  alpine image whose exact version is not the pin, and nvm cannot install a
+  because the `Dockerfile` stages start from a node 22 alpine image whose exact
-  prebuilt node on alpine. `script/fmt` and `script/fmt-check` now run yarn
+  version is not the pin, and nvm cannot install a prebuilt node on alpine; the
-  under nvm's pinned node when nvm has it installed, and otherwise the `yarn` on
+  version-comparison rule in `REPO_POLICIES.md` names node as its exception.
-  `PATH`. `REPO_POLICIES.md` and both checklists say so. Not yet tried on the
+  `script/fmt` and `script/fmt-check` pick their yarn with the same test: the
-  shared runner. Repositories pick this up on their next re-vendor.
+  `yarn` on `PATH` when the installed node is the pinned major, and otherwise
+  yarn under the pinned node through nvm. `REPO_POLICIES.md` and both checklists
+  say so, and the checklists' final `script/cibuild` check names what the CI
+  runner image has: node 24 and no yarn. Not yet tried on the shared runner.
+  Repositories pick this up on their next re-vendor.
 - 2026-10-07: The `script/cibuild` item in `NEW_REPO_CHECKLIST.md` now matches
   the canonical `script/cibuild` (issue 125). Its image build carries the tag,
   `-t "$tag"`, and the item says that `$version` comes from

prompts/EXISTING_REPO_CHECKLIST.md

@@ -149,11 +149,13 @@ with your task.
       the image with `--no-cache`. Without the bootstrap the CI run dies in
       `script/fmt-check`, which runs the formatter on the host and finds nothing
       installed.
-- [ ] `script/fmt` and `script/fmt-check` run `yarn` under nvm's pinned node
+- [ ] `script/fmt` and `script/fmt-check` pick their `yarn` with the same test
-      when nvm has that version installed, and otherwise the `yarn` on `PATH`.
+      as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has
-      `script/bootstrap` leaves the node and yarn it installs under nvm off the
+      the pinned major version, and otherwise yarn under the pinned node, with
-      `PATH` of the shell that called it, so a bare `yarn` exits 127 on a runner
+      nvm loaded through `$HOME/.nvm/nvm.sh`. `script/bootstrap` leaves the node
-      carrying nothing but docker and git, or runs under another node.
+      and yarn it installs under nvm off the `PATH` of the shell that called it,
+      so a bare `yarn` exits 127 on a runner carrying nothing but docker and
+      git, or runs under another node.
 - [ ] `script/bootstrap` installs no linter of its own — delete the block, its
       version variables and its call site. A JS repo's `yarn install` stays; it
       brings a linter along with every other dependency, and no verdict is taken
@@ -206,10 +208,11 @@ with your task.
 # Final
 
 - [ ] `make check` passes
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
-      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
-      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      git and node 24, with no yarn on `PATH`), and demonstrably executed the
-      gate layer, means nothing ran
+      checks — a sub-second build, or `CACHED` on a gate layer, means nothing
+      ran
 - [ ] A planted lint violation fails both `make lint` and a plain
       `docker build .`; revert it afterwards
 - [ ] Commit and merge fixes before starting your actual task

prompts/NEW_REPO_CHECKLIST.md

@@ -171,11 +171,13 @@ are thin shims calling them. Model scripts:
       on its own line before the build. The bootstrap is required: CI checks out
       and runs this alone, and `script/fmt-check` runs the formatter on the
       host.
-- [ ] `script/fmt` and `script/fmt-check` run `yarn` under nvm's pinned node
+- [ ] `script/fmt` and `script/fmt-check` pick their `yarn` with the same test
-      when nvm has that version installed, and otherwise the `yarn` on `PATH`.
+      as `script/bootstrap`: the `yarn` on `PATH` when the node on `PATH` has
-      `script/bootstrap` leaves the node and yarn it installs under nvm off the
+      the pinned major version, and otherwise yarn under the pinned node, with
-      `PATH` of the shell that called it, so a bare `yarn` exits 127 on a runner
+      nvm loaded through `$HOME/.nvm/nvm.sh`. `script/bootstrap` leaves the node
-      carrying nothing but docker and git, or runs under another node.
+      and yarn it installs under nvm off the `PATH` of the shell that called it,
+      so a bare `yarn` exits 127 on a runner carrying nothing but docker and
+      git, or runs under another node.
 - [ ] No `docker build` in `script/` leaves a dangling image behind:
       `script/lint` and `script/test` write no image, and `script/docker` and
       `script/cibuild` tag theirs
@@ -190,10 +192,11 @@ are thin shims calling them. Model scripts:
 
 - [ ] `make check` passes
 - [ ] `make docker` succeeds
-- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying nothing but
+- [ ] `script/cibuild` succeeds in a fresh clone on a host carrying what CI has
-      docker and git, with no node or yarn on `PATH`, which is what CI has, and
+      (the runner image `docker.gitea.com/runner-images:ubuntu-latest`: docker,
-      demonstrably executed the checks — a sub-second build, or `CACHED` on a
+      git and node 24, with no yarn on `PATH`), and demonstrably executed the
-      gate layer, means nothing ran
+      checks — a sub-second build, or `CACHED` on a gate layer, means nothing
+      ran
 - [ ] Plant a lint violation and confirm both `make lint` and a plain
       `docker build .` fail on it; revert. A plain build that passes proves the
       final stage is missing its `COPY --from=` edge to the gate phases.

prompts/REPO_POLICIES.md

@@ -73,17 +73,18 @@ style conventions are in separate documents:
   `script/bootstrap` installs node and yarn under nvm it leaves neither on the
   `PATH` of the shell that called it, so a bare `yarn` either exits 127 or runs
   under another node. The host entrypoints that need yarn — `script/fmt` and
-  `script/fmt-check` — therefore run it under nvm's pinned node when nvm has
+  `script/fmt-check` — therefore use the same test as `script/bootstrap`: when
-  that version installed, and otherwise run the `yarn` on `PATH`. A runner
+  the node on `PATH` has the pinned major version they run the `yarn` on `PATH`,
-  carrying nothing but docker and git then gets through `script/check`. Four
+  and otherwise they load nvm through `$HOME/.nvm/nvm.sh` and run yarn under the
-  further scripts are our own extensions to the standard: `script/check` runs
+  pinned node. A runner carrying nothing but docker and git then gets through
-  `script/test`, `script/lint` and `script/fmt-check`; `script/precommit` is
+  `script/check`. Four further scripts are our own extensions to the standard:
-  what the git pre-commit hook runs, and it calls `script/check`;
+  `script/check` runs `script/test`, `script/lint` and `script/fmt-check`;
-  `script/install-precommit` installs the git pre-commit hook (the `make hooks`
+  `script/precommit` is what the git pre-commit hook runs, and it calls
-  target shims to it); and `script/projectname` (literally that filename) simply
+  `script/check`; `script/install-precommit` installs the git pre-commit hook
-  outputs the project's name. Scripts that need the name call
+  (the `make hooks` target shims to it); and `script/projectname` (literally
-  `script/projectname` — e.g. `script/docker` assembles its image tag from it —
+  that filename) simply outputs the project's name. Scripts that need the name
-  so those scripts stay byte-identical across all repos. Repo-type-specific
+  call `script/projectname` — e.g. `script/docker` assembles its image tag from
+  it — so those scripts stay byte-identical across all repos. Repo-type-specific
   pre-commit extras (e.g. `go mod tidy` verification in Go repos) belong in
   `script/precommit`, not in the hook itself. Model scripts are at
   `https://git.eeqj.de/sneak/prompts/raw/branch/main/script/<name>`. The README
@@ -553,6 +554,11 @@ style conventions are in separate documents:
       function defined and never invoked has the same exit status and the same
       empty output as one that worked.
 
+    Node is the exception to the whole-token comparison: the canonical
+    `script/bootstrap` compares only its major version, because the node 22
+    alpine image the `Dockerfile` stages start from is not the exact pin, and
+    nvm cannot install a prebuilt node on alpine.
+
     Keep it POSIX sh: no arrays, no `[[`, no `grep -P`.
 
     A Go tool a repo needs on the host is installed with `go install` pinned to

script/bootstrap

@@ -106,18 +106,25 @@ ensure_nvm() {
 # major is compared: the Dockerfile stages start from a node 22 alpine
 # image whose exact version is not the pin, and nvm cannot install a
 # prebuilt node on alpine. Another major is not used: the pinned yarn 1
-# prints a deprecation warning under node 24.
+# prints a deprecation warning under node 24. script/fmt and
+# script/fmt-check carry this function unchanged, to run the yarn
+# installed here.
 node_is_pinned_major() {
-    if missing node; then return 1; fi
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
     installed="$(node --version)"
     installed="${installed#v}"
     [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
 }
 
 ensure_node() {
-    if node_is_pinned_major; then return 0; fi
+    if node_is_pinned_major; then
+        echo "bootstrap: using node $(node --version)"
+        return 0
+    fi
     ensure_nvm
     nvm_sh "nvm install $NODE_VERSION"
+    nvm_sh "nvm use $NODE_VERSION >/dev/null && \
+        echo \"bootstrap: using node \$(node --version)\""
 }
 
 ensure_yarn() {

script/fmt

@@ -7,21 +7,30 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 # Must match the pin in script/bootstrap.
 NODE_VERSION="22.17.0"
 
-# When the installed node is not the pinned major version,
+# True when the node on PATH has the pinned major version: the same
-# script/bootstrap installs the pinned node and yarn under nvm and
+# function as in script/bootstrap, which uses it to decide where it
-# leaves neither on the PATH of the shell that called it. So yarn runs
+# installs yarn.
-# under nvm's pinned node when nvm has it installed, and otherwise is
+node_is_pinned_major() {
-# the yarn on PATH. nvm is a bash script, hence the subshell.
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
+    installed="$(node --version)"
+    installed="${installed#v}"
+    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
+}
+
+# Run the yarn script/bootstrap installed: the yarn on PATH when the
+# node on PATH has the pinned major version, and otherwise yarn under
+# the pinned node in nvm, which bootstrap leaves off the PATH of the
+# shell that called it. nvm is a bash script, hence the subshell.
 run_yarn() {
-    if [ -d "$HOME/.nvm/versions/node/v$NODE_VERSION" ]; then
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
-        exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        exec yarn "$@"
-            shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
     fi
-    if ! command -v yarn >/dev/null 2>&1; then
+    if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
         echo "fmt: no yarn; run script/bootstrap first" >&2
         exit 1
     fi
-    exec yarn "$@"
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
 }
 
 main() {

script/fmt-check

@@ -7,21 +7,30 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 # Must match the pin in script/bootstrap.
 NODE_VERSION="22.17.0"
 
-# When the installed node is not the pinned major version,
+# True when the node on PATH has the pinned major version: the same
-# script/bootstrap installs the pinned node and yarn under nvm and
+# function as in script/bootstrap, which uses it to decide where it
-# leaves neither on the PATH of the shell that called it. So yarn runs
+# installs yarn.
-# under nvm's pinned node when nvm has it installed, and otherwise is
+node_is_pinned_major() {
-# the yarn on PATH. nvm is a bash script, hence the subshell.
+    if ! command -v node >/dev/null 2>&1; then return 1; fi
+    installed="$(node --version)"
+    installed="${installed#v}"
+    [ "${installed%%.*}" = "${NODE_VERSION%%.*}" ]
+}
+
+# Run the yarn script/bootstrap installed: the yarn on PATH when the
+# node on PATH has the pinned major version, and otherwise yarn under
+# the pinned node in nvm, which bootstrap leaves off the PATH of the
+# shell that called it. nvm is a bash script, hence the subshell.
 run_yarn() {
-    if [ -d "$HOME/.nvm/versions/node/v$NODE_VERSION" ]; then
+    if node_is_pinned_major && command -v yarn >/dev/null 2>&1; then
-        exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        exec yarn "$@"
-            shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
     fi
-    if ! command -v yarn >/dev/null 2>&1; then
+    if node_is_pinned_major || [ ! -s "$HOME/.nvm/nvm.sh" ]; then
         echo "fmt-check: no yarn; run script/bootstrap first" >&2
         exit 1
     fi
-    exec yarn "$@"
+    exec bash -c '. "$HOME/.nvm/nvm.sh" && nvm use "$1" >/dev/null &&
+        shift && exec yarn "$@"' bash "$NODE_VERSION" "$@"
 }
 
 main() {