Feature/node lts versions

[pablojmarti]

Description of the Change

Node: install the three latest LTS versions

The container used to install only the current Node LTS (24). Projects on other versions had to run nvm install <version>, which downloads Node on every pipeline run. With this change, the three latest Node LTS versions (currently 20, 22 and 24) are installed by default. Projects on those versions can switch instantly with nvm use <version>. 24 remains the default.

• build/install-node.sh now takes a count (default 3) and installs nvm's relative LTS aliases oldest first: lts/-2, lts/-1, lts/*. The versions are resolved at build time, so the weekly no-cache rebuild rolls the set forward automatically. When Node 26 becomes LTS (late October), the image will move to 22/24/26, the default will become 26, and 20 will be dropped.
• The script rejects a count that isn't a positive integer (e.g. 0, -1, abc), and the build stops at the first failed install.
• In the Dockerfile, the unused NODE_VERSION build arg is replaced with NODE_LTS_COUNT=3.
• Drawback: the nvm directory grows to about 654 MB (estimated +430 MB), and the full image is about 3.9 GB. Node 20 is already end-of-life (Apr 2026) and stays in the set until 26 becomes LTS. That was a deliberate choice, to match "the latest 3 LTS".

PHP 8.1: move to Debian bookworm

Debian bullseye support ended on Aug 31, 2026. The bullseye-security package list still resolves, but the package files return 404, so every bullseye image fails at the first apt-get install (exit code 100). This has been failing the weekly trunk builds since at least Sep 20, and none of our tags have been updated since Sep 4, because the failure cancelled every other job in the matrix.

• PHP 8.1 was moved to bookworm in April (573bf0d), but 9dfc8e4 reverted it back to bullseye. That looks accidental: the commit message says 8.2, but the diff changes 8.1. This PR moves it to php:8.1-bookworm again.
• 7.4 and 8.0 are unchanged and will still fail. php:7.4-bookworm and php:8.0-bookworm don't exist. Dropping those versions is a separate decision that's being discussed with the team.
• Temporary: fail-fast: false is set on the matrix so 8.1–8.4 finish and report their own results instead of being cancelled by 7.4/8.0. Remove it before merging, or once 7.4/8.0 are dropped.

Docs

• Adds CLAUDE.md, which documents the repo architecture, commands, test approach and the CI and release process.
• Updates the README's Node section and its PHP matrix example, which now matches the workflow.

Verification done locally (arm64, colima)

• The new unit test tests/test-install-node.sh failed before the change and passes after it. The existing tests/test-virus-scan.sh still passes.
• The lts/-2, lts/-1 and lts/* aliases resolve to 20.20.2, 22.23.3 and 24.21.0 with nvm v0.40.5.
• Full image builds succeed for php:8.3-bookworm and php:8.1-bookworm. In both, nvm use 20/22/24 switches correctly and runs JS, and a new non-interactive shell defaults to v24.
• The 8.1 bookworm image has PHP 8.1.34 on Debian 12.12, with opentelemetry, gd, intl, zip, ClamAV 1.4.3 and Composer 2. virus-scan and php-syntax both pass inside it.
• I reproduced the bullseye 404s on amd64 php:8.1-bullseye, and I checked that all 71 apt packages resolve on amd64 php:8.1-bookworm.
• Not yet verified: the amd64 builds for 8.1–8.4. That's what this PR's CI run covers.

Closes #

How to test the Change

1. Run the unit tests (no Docker needed):

   bash tests/test-install-node.sh
   bash tests/test-virus-scan.sh   # macOS only (uses /private/tmp)

2. Build an image:

   docker build --build-arg PHP_IMG=php:8.1-bookworm --build-arg COMPOSER_VERSION=2 -t wordpress-ci:test .

3. Check the Node versions:

   docker run --rm --entrypoint bash wordpress-ci:test -c '
     nvm ls --no-colors | head -3
     for v in 20 22 24; do nvm use "$v" >/dev/null && node --version; done
     bash -c "node --version"   # expect the default, v24'

4. Check that the image's tools work:

   docker run --rm -v "$PWD/scripts":/work -w /work --entrypoint bash wordpress-ci:test -c 'virus-scan && php-syntax'

5. CI: the 8.1, 8.2, 8.3 and 8.4 jobs should pass. The 7.4 and 8.0 jobs are expected to fail at apt-get install with bullseye-security 404s.

Changelog Entry

Changed - Install the three latest Node LTS versions (currently 20, 22 and 24) by default; the newest LTS remains the default and the set rolls forward automatically on rebuild.
Fixed - Build the PHP 8.1 image on Debian bookworm, since bullseye security packages are no longer downloadable.

Checklist:

• [ x] I agree to follow this project's Code of Conduct.
• I have updated the documentation accordingly.
• I have added Critical Flows, Test Cases, and/or End-to-End Tests to cover my change.
• All new and existing tests pass.

🤖 Generated with Claude Code

[felipeelia]

As Claude now supports AGENTS.md, we should switch to it. We should also make this AI-agnostic, so no mention of Claude Code, but rather AI agents in general.

We should likely address this Known doc drift section at the bottom, no?