Dockerfile

@@ -1,11 +1,15 @@
 # node 22-alpine, 2026-02-22
 FROM node@sha256:e4bf2a82ad0a4037d28035ae71529873c069b13eb0455466ae0bc13363826e34
 
-RUN apk add --no-cache make
-
 WORKDIR /app
-COPY package.json yarn.lock ./
-RUN yarn install --frozen-lockfile
-COPY . .
 
+# script/bootstrap installs all prerequisites (make via apk here; node
+# and yarn are already in the base image, so those steps are skipped).
+# Dependency manifests are copied first so the bootstrap layer is
+# cached until they change.
+COPY script/ script/
+COPY package.json yarn.lock ./
+RUN script/bootstrap
+
+COPY . .
 RUN make check

prompts/NEW_REPO_CHECKLIST.md

@@ -73,7 +73,11 @@ are thin shims calling them. Model scripts:
 
 - [ ] scripts are POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run on
       alpine images without bash
-- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies
+- [ ] `script/bootstrap` / `make bootstrap` — installs all dependencies,
+      idempotently, assuming nothing (pkg manager detection nix/apt/brew/apk;
+      node used if present, else pinned version via nvm from a hash-verified
+      archive; pinned yarn via corepack); Dockerfile runs it instead of inline
+      installs
 - [ ] `script/setup` / `make setup` — readies a fresh clone: runs `bootstrap`,
       then `install-precommit`, plus repo-specific init
 - [ ] `script/test` / `make test` — runs real tests, not a no-op (30-second

prompts/REPO_POLICIES.md

@@ -48,10 +48,18 @@ style conventions are in separate documents:
   scripts must be POSIX sh (`#!/bin/sh`, `set -eu`, no bashisms) so they run in
   minimal containers (e.g. alpine images have no bash); locate the repo root
   with `$(cd "$(dirname "$0")/.." && pwd -P)` and `cd` there before acting. From
-  the standard's canonical set we use `bootstrap` (install all dependencies),
-  `setup` (make the repo ready for development after a fresh clone: runs
-  `bootstrap`, then `install-precommit`, plus any repo-specific initialization),
-  `test`, and `cibuild`. `script/cibuild` runs the CI build: it changes to the
+  the standard's canonical set we use `bootstrap`, `setup` (make the repo ready
+  for development after a fresh clone: runs `bootstrap`, then
+  `install-precommit`, plus any repo-specific initialization), `test`, and
+  `cibuild`. `script/bootstrap` installs all dependencies idempotently and
+  assumes nothing is present: base tools come from nix, apt, brew, or apk
+  (detected in that order; apt runs noninteractive). For node it uses the
+  installed node if present; otherwise it installs a PINNED node version via
+  nvm, first installing nvm itself if missing — from a hash-verified GitHub
+  release archive (never `curl | sh`), with bash installed as an explicit
+  prerequisite since nvm requires bash. yarn is then pinned via
+  `corepack prepare yarn@<version> --activate`. Never install "latest" or "lts";
+  always exact versions. `script/cibuild` runs the CI build: it changes to the
   repo root and runs `docker build .`; the Gitea workflow calls it. Four further
   scripts are our own extensions to the standard: `script/check` runs
   `script/test`, `script/lint`, and `script/fmt-check`; `script/precommit` is
@@ -85,7 +93,11 @@ style conventions are in separate documents:
   as a build step so the build fails if the branch is not green. For non-server
   repos, the Dockerfile should bring up a development environment and run
   `make check`. For server repos, `make check` should run as an early build
-  stage before the final image is assembled.
+  stage before the final image is assembled. Dockerfiles install development
+  prerequisites by running `script/bootstrap` rather than duplicating installs
+  inline; COPY `script/` and the dependency manifests (`package.json` +
+  `yarn.lock`, `go.mod` + `go.sum`, etc.) before running it so the bootstrap
+  layer stays cached until dependencies change.
 
 - **Dockerfiles must use a separate lint stage for fail-fast feedback.** Go
   repos use a multistage build where linting runs in an independent stage based

script/bootstrap

@@ -1,24 +1,37 @@
 #!/bin/sh
 # script/bootstrap: install all dependencies needed to build and develop
 # this repo. Idempotent: every install is guarded by a check so already
-# installed tools are skipped. Installs base tooling with nix, apt, or
-# brew (detected in that order); assumes nothing is present.
+# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# or apk (detected in that order); assumes nothing is present. Node is
+# used directly if installed; otherwise it is installed at a pinned
+# version via nvm (installing nvm itself first, from a hash-verified
+# release archive, never curl | sh).
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
+# Pinned versions, 2026-07-06
+NODE_VERSION="22.17.0"
+NVM_VERSION="0.40.3"
+# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
+NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
+YARN_VERSION="1.22.22"
+
 PKGMGR=""
 SUDO=""
 
 detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
     if command -v nix-env >/dev/null 2>&1; then
         PKGMGR="nix"
     elif command -v apt-get >/dev/null 2>&1; then
         PKGMGR="apt"
     elif command -v brew >/dev/null 2>&1; then
         PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
     else
-        echo "bootstrap: no supported package manager (nix, apt, brew)" >&2
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
         exit 1
     fi
     if [ "$PKGMGR" = "apt" ]; then
@@ -29,12 +42,14 @@ detect_pkgmgr() {
     fi
 }
 
-# pkg_install <nix-attr> <apt-pkg> <brew-formula>
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
 pkg_install() {
+    detect_pkgmgr
     case "$PKGMGR" in
         nix) nix-env -iA "nixpkgs.$1" ;;
         apt) $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2" ;;
         brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
     esac
 }
 
@@ -42,23 +57,79 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
+# verify_sha256 <file> <expected-hash>
+verify_sha256() {
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual="$(sha256sum "$1" | cut -d' ' -f1)"
+    else
+        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
+    fi
+    if [ "$actual" != "$2" ]; then
+        echo "bootstrap: sha256 mismatch for $1" >&2
+        echo "  expected: $2" >&2
+        echo "  actual:   $actual" >&2
+        exit 1
+    fi
+}
+
+# nvm is a bash script; run a command in a bash with nvm loaded
+nvm_sh() {
+    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
+}
+
+ensure_nvm() {
+    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
+    # nvm prerequisites; nvm itself requires bash
+    if missing bash; then pkg_install bash bash bash bash; fi
+    if missing curl; then pkg_install curl curl curl curl; fi
+    if missing git; then pkg_install git git git git; fi
+    tmp="$(mktemp -d)"
+    curl -fsSL -o "$tmp/nvm.tar.gz" \
+        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz"
+    verify_sha256 "$tmp/nvm.tar.gz" "$NVM_SHA256"
+    mkdir -p "$HOME/.nvm"
+    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
+    rm -rf "$tmp"
+}
+
+ensure_node() {
+    if ! missing node; then return 0; fi
+    ensure_nvm
+    nvm_sh "nvm install $NODE_VERSION"
+}
+
+ensure_yarn() {
+    if ! missing yarn; then return 0; fi
+    if ! missing corepack; then
+        corepack enable
+        corepack prepare "yarn@$YARN_VERSION" --activate
+    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && corepack enable && \
+            corepack prepare yarn@$YARN_VERSION --activate"
+    else
+        npm install -g "yarn@$YARN_VERSION"
+    fi
+}
+
+install_js_deps() {
+    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
+        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
+            yarn install --frozen-lockfile"
+    else
+        yarn install --frozen-lockfile
+    fi
+}
+
 main() {
     cd "$ROOT"
-    detect_pkgmgr
 
-    if missing git; then pkg_install git git git; fi
-    if missing make; then pkg_install gnumake make make; fi
-    if missing node; then pkg_install nodejs nodejs node; fi
-    if missing yarn; then
-        # corepack ships with node >= 16 and provides yarn
-        if command -v corepack >/dev/null 2>&1; then
-            corepack enable
-        else
-            pkg_install yarn yarnpkg yarn
-        fi
-    fi
+    if missing make; then pkg_install gnumake make make make; fi
+    if missing git; then pkg_install git git git git; fi
+
+    ensure_node
+    ensure_yarn
+    install_js_deps
 
-    yarn install --frozen-lockfile
     echo "bootstrap complete"
 }