Upgrade Node, NX and Vite

[cteyton]

Runtime Stack Upgrade Plan

Runtime stack upgrade plan

Generated: 2026-06-01 by the upgrade-runtime-stack skill.

Summary

Tool	Current	Latest stable	Bump	Action
Node.js 24.x	24.15.0	24.16.0	minor	Upgrade
Nx	22.7.2	22.7.5	patch	Upgrade
Vite	^8.0.3	8.0.15	patch	Upgrade

All three tools have stable updates available. Node is a minor bump (24.15.0 → 24.16.0) with no documented breaking changes — mostly new features like randomUUIDv7(), test runner improvements, and CLI additions. Nx is a patch bump (22.7.2 → 22.7.5) with performance improvements (7x daemon memory reduction, faster cache replay). Vite is a patch bump (8.0.3 → 8.0.15) with bug fixes and minor enhancements. All three are low-risk and can ship in a single PR.

Node.js

• Current: 24.15.0 (from .nvmrc)
• Latest stable: 24.16.0, released 2026-05-21 (LTS 'Krypton')
• Bump type: minor
• Changelog highlights:
  • Crypto: implement randomUUIDv7() and support for raw key formats in KeyObject APIs
  • Debugger: add edit-free runtime expression probes to node inspect
  • File system: signal option added to fs.stat() and frsize field exposed in statfs
  • HTTP: harden ClientRequest options merge and add req.signal to IncomingMessage
  • Streams: propagate destruction in duplexPair
  • Test runner: test order randomization, mock timeout alignment, AbortSignal.timeout support
  • CLI: --max-heap-size option and --require-module/--no-require-module flags
  • HTTP/2: add http1Options for HTTP/1 fallback configuration
  • Network: add setTOS and getTOS to Socket
  • SQLite: add limits property to DatabaseSync (release candidate)
• Breaking changes: none documented

Files to modify

Engine / runtime pins:

• .nvmrc — change 24.15.0 → 24.16.0
• package.json (root) — engines.node: "24.15.0" → "24.16.0"
• apps/api/docker-package.json — engines.node: "24.15.0" → "24.16.0"

Docker images:

• dockerfile/Dockerfile.api — FROM node:24.15.0-alpine3.23@sha256:... → FROM node:24.16.0-alpine3.23@sha256:<new-digest>
• dockerfile/Dockerfile.mcp — same change
• docker-compose.yml — 6 occurrences of image: node:24.15.0-alpine3.23 → node:24.16.0-alpine3.23 (services: nx-daemon, install-dependencies, run-migrations, frontend, backend, mcp-server)
• docker-compose.production.yml — 4 occurrences of image: node:24.15.0-alpine3.23 → node:24.16.0-alpine3.23 (services: install-dependencies, build-mcp-server, install-mcp-server, mcp-server)

CI workflows:

• .github/workflows/main.yml — 4 occurrences of node-version: 24.15.0 → 24.16.0 (lines 26, 36, 53, 84)
• .github/workflows/publish-cli-release.yml — NODE_VERSION: '24.15.0' → '24.16.0' (line 29)
• .github/workflows/tmp-cli-lint-windows.yml — node-version: '24.15.0' → '24.16.0' (line 24)
• .github/workflows/build.yml — receives node-version as input (no default to change; callers updated above)
• .github/workflows/docker.yml — receives node-version as input (no default to change; callers updated above)

Docker image pin

• New tag: node:24.16.0-alpine3.23
• Action: look up the sha256 digest for that tag on Docker Hub before editing dockerfile/Dockerfile.api and dockerfile/Dockerfile.mcp. Do not reuse the previous digest (d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f).
• Sample lookup: docker manifest inspect node:24.16.0-alpine3.23 | jq -r '.manifests[0].digest' or use the Docker Hub UI.

Nx

• Current: 22.7.2
• Latest stable: 22.7.5, released 2026-04-24
• Bump type: patch
• Changelog highlights:
  • Worktree-aware caching — cache shared across git worktrees for consistent hits
  • 7x daemon memory reduction — footprint from 1.5–1.6 GB down to ~200 MB
  • Faster cache replay — restoring 1110 cached tasks from ~17s to 1.16s
  • JSON input type for selective field hashing in cache invalidation
  • Source map annotations for nx show target command
  • NX_BAIL environment variable to stop on first failure
• Breaking changes: none documented
• Migration command:

  npx nx migrate 22.7.5
  npm install
  npx nx migrate --run-migrations
  

Files to modify

• package.json (root) — devDependencies.nx and all devDependencies["@nx/*"]: "22.7.2" → "22.7.5". Scopes: @nx/devkit, @nx/esbuild, @nx/eslint, @nx/eslint-plugin, @nx/jest, @nx/js, @nx/nest, @nx/node, @nx/playwright, @nx/plugin, @nx/react, @nx/storybook, @nx/vite, @nx/vitest, @nx/web, @nx/webpack
• tools/packmind-plugin/package.json — dependencies["@nx/devkit"]: "22.7.2" → "22.7.5"
• nx.json — review for schema/plugin changes (likely none for a patch bump)
• package-lock.json — regenerated by npm install after version bumps
• migrations.json — created by npx nx migrate 22.7.5; run npx nx migrate --run-migrations then delete

ESLint coupling: patch bump — no flat-config changes expected. Review eslint.config.mjs only if the migration generates edits.

Vite

• Current: ^8.0.3
• Latest stable: 8.0.15, released 2026-06-01
• Bump type: patch
• Changelog highlights:
  • HTTP/2 support for proxy features
  • Request timeout handling with 408 status codes
  • Rolldown bundler updates (1.0.0 through 1.0.3)
  • Native plugin v2 support and Oxc-based transformations
  • Enhanced error messaging and code frame generation
  • CSS minification improvements for various build targets
  • Worker bundle consistency improvements
  • Full module runner and SSR enhancements
  • Fixed HTML proxy cache key mismatches for virtual filesystem paths
  • Fixed dependency optimization and scanning issues
• Breaking changes: none between 8.0.3 and 8.0.15 (the 8.0.0 breaking changes — removal of import.meta.hot.accept resolution fallback, updated default browser target, Rolldown merge — were already adopted with 8.0.3)
• Nx / Vite compatibility note: same major (8.x) — @nx/vite 22.7.x supports Vite 8. No blocking constraint.

Files to modify

• package.json (root) — devDependencies.vite: "^8.0.3" → "^8.0.15" (or keep ^8.0.3 since the caret range already covers 8.0.15 — run npm update vite to pull the latest within the range and update the lockfile)
• apps/frontend/vite.config.ts — review for deprecated config options (none expected for patch)
• packages/ui/vite.config.ts — same
• package-lock.json — regenerated by npm install / npm update vite

Note: Since the current pin is ^8.0.3, running npm update vite will resolve to 8.0.15 without changing package.json. Optionally bump the floor to ^8.0.15 for explicitness.

Drift detected

The following files reference Node/Nx/Vite versions but are not in the canonical file map. Review whether they should be updated:

File	Line	Content	Notes
apps/frontend/src/domain/setup/components/AutomateUpdatesStep/yaml.ts	32	image: node:22.17.0	Template/example YAML for user-facing setup wizard — uses Node 22.x intentionally (user-facing, not repo infra)
apps/doc/playbook-maintenance/auto-update-artifacts.mdx	104	image: node:22.17.0	Documentation example — uses Node 22.x intentionally (docs for external users)
auto-update/.gitlab-ci.yml	6	image: node:22.17.0	GitLab CI template for auto-update — uses Node 22.x (external-facing template, not repo infra)

All three drift hits reference Node 22.x in user-facing templates/docs, not in repo infrastructure. They do not need to change as part of this upgrade. However, the team may want to evaluate whether these templates should be bumped to 24.x independently.

Validation harness

After the upgrade plan is applied, these steps must all succeed before merging. The order matters — fail fast on cheap checks before paying for full builds.

Local

1. Node + npm match the pins

   node --version           # expect: v24.16.0
   npm --version            # expect: 11.12.1
   

   If nvm is in use: nvm use should read the new .nvmrc automatically.

2. Clean install

   npm install
   

   For this patch/minor bump, prefer npm install against the existing lockfile so the diff stays auditable.

3. Build the heaviest targets

   ./node_modules/.bin/nx build api
   ./node_modules/.bin/nx build frontend
   ./node_modules/.bin/nx build cli
   ./node_modules/.bin/nx build mcp-server
   

CI

The GitHub Actions workflows already test against the node-version matrix entries. After the plan is applied, the Main CI/CD Pipeline must be green on the branch before merging:

• .github/workflows/build.yml
• .github/workflows/main.yml
• .github/workflows/docker.yml

If any workflow runs nx affected, it picks up the changed files automatically and runs the relevant projects.

Manual smoke (post-merge)

• Spin up the local stack: docker compose up -d.
• Open the frontend on its dev URL and confirm the app loads.
• Hit the API health endpoint.
• Run one MCP server interaction end-to-end.

Failure handling

If any harness step fails:

1. Capture the exact error in the upgrade PR description.
2. Revert with git revert <upgrade-commit> rather than amending — keeps history auditable.
3. Re-run the skill on the reverted branch to regenerate a fresh plan once the upstream fix lands.

Risks

• Node 24.16.0 — SEMVER-MINOR additions only; no removals or breaking behavioral changes documented. The repo does not use the newly added APIs (randomUUIDv7, --max-heap-size, etc.), so no interaction risk.
• Nx 22.7.5 — patch-only bug fixes and performance improvements. The worktree-aware caching is opt-in behavior. No migration scripts expected for a patch bump, but npx nx migrate should still be run to confirm.
• Vite 8.0.15 — patch-only. The Rolldown bundler updates (1.0.0 → 1.0.3) are internal to Vite's build pipeline. CSS minification changes could theoretically affect output — verify frontend builds look correct.
• Alpine 3.23 base — keeping the same Alpine version. No change needed.
• npm version — npm 11.12.1 ships with Node 24.15.0. Verify that Node 24.16.0 still bundles npm 11.12.1 or update engines.npm in both package.json and apps/api/docker-package.json if it changed.

Rollback

• Revert the upgrade commit and run npm install to regenerate the lockfile.
• For a Node major rollback, downgrade_node22.sh exists for the 22 ↔ 24 transition; on later majors a similar helper must be created before applying.
• Docker images are pinned by @sha256:... so previous deploys are reproducible.

Suggested commit split

A single PR is fine for patch/minor bumps of all three tools combined. None of the tools have a major bump, and the Nx/Vite bumps do not interact. Suggested approach: one commit for Node (engine pins + Docker + CI), one commit for Nx (nx migrate output), one commit for Vite (lockfile update). All three can go in the same PR.

Mandatory proof for the Pull Request

• Run docker-local.sh until docker compose -f dockerfile/local/docker-compose.yml ps shows that packmind is up and running for more than 30 secs.
• Upload the last 30 lines of logs of the api and mcp containers as proof
• Upload a screenshot of the welcome page of the frontend run wih this stack

[cteyton]

✅ Michel — READY, starting implementation

Issue #345 is a fully-specified runtime stack upgrade plan: bump Node 24.15.0 → 24.16.0 (minor), Nx 22.7.2 → 22.7.5 (patch), and Vite to 8.0.15 (patch within existing ^8.0.3 range). Every file to edit is enumerated, no breaking changes are documented, and the validation harness (lint/test/build + docker-local.sh proof) is spelled out. No product/UX ambiguity remains.

I'll open a PR against agent/issue-345 when done.

My analysis & plan

Verified state of the repo

All "current" values in the issue match the repo as it stands today:

• .nvmrc → 24.15.0 ✅
• package.json root → engines.node: "24.15.0", engines.npm: "11.12.1", all @nx/* and nx at 22.7.2, vite: "^8.0.3" ✅
• apps/api/docker-package.json → engines.node: "24.15.0", engines.npm: "11.12.1" ✅
• tools/packmind-plugin/package.json → @nx/devkit: "22.7.2" ✅
• dockerfile/Dockerfile.api and dockerfile/Dockerfile.mcp → FROM node:24.15.0-alpine3.23@sha256:d1b3b4da11eefd5941e7f0b9cf17783fc99d9c6fc34884a665f40a06dbdfc94f ✅
• docker-compose.yml → 6 occurrences of node:24.15.0-alpine3.23 at lines 14, 96, 118, 142, 188, 244 ✅
• docker-compose.production.yml → 4 occurrences at lines 20, 28, 39, 50 ✅
• .github/workflows/main.yml → 4 occurrences of node-version: 24.15.0 at lines 26, 36, 53, 84 (plus a comment at line 6) ✅
• .github/workflows/publish-cli-release.yml line 29 → NODE_VERSION: '24.15.0' ✅
• .github/workflows/tmp-cli-lint-windows.yml lines 21+24 → node-version: '24.15.0' ✅
• dockerfile/local/docker-compose.yaml / .override.yaml → contain no direct node: pin (they build from Dockerfile.api/Dockerfile.mcp, so bumping the Dockerfiles is sufficient for the production-like local stack used by docker-local.sh). ✅

The issue's "drift detected" table (user-facing setup YAML / docs / external GitLab CI template using node:22.17.0) is correctly flagged as out-of-scope.

Additional documentation references I confirmed exist but are also out of scope (template/historical artifacts):

• scripts/michel/michel-run-local-dev-stack/SKILL.md mentions node:24.15.0-alpine as a description of current state.
• migrate_node24.sh is a one-off 22→24 migration helper that references 24.15.0.
• .github/skills/upgrade-runtime-stack/..., .cursor/skills/..., .gitlab/duo/skills/... use 24.15.0 only as example strings in the upgrade-runtime-stack skill itself.

These are skill/doc/historical content — touching them is not implied by the upgrade plan.

Implementation plan (sub-tasks → one commit each)

Commit 1 — Node 24.15.0 → 24.16.0

1. Look up the Docker Hub digest for node:24.16.0-alpine3.23 (docker manifest inspect node:24.16.0-alpine3.23 | jq -r '.manifests[0].digest'). Do not reuse the old d1b3b4da… digest.
2. Edit .nvmrc → 24.16.0.
3. Edit package.json root → engines.node: "24.16.0". Confirm engines.npm is still 11.12.1 (Node 24.16.0 should still ship npm 11.12.1; if release notes say otherwise, sync engines.npm here and in apps/api/docker-package.json).
4. Edit apps/api/docker-package.json → engines.node: "24.16.0".
5. Edit dockerfile/Dockerfile.api and dockerfile/Dockerfile.mcp → FROM node:24.16.0-alpine3.23@sha256:<new-digest>.
6. Edit docker-compose.yml — replace all 6 node:24.15.0-alpine3.23 with node:24.16.0-alpine3.23.
7. Edit docker-compose.production.yml — replace all 4 occurrences.
8. Edit .github/workflows/main.yml — bump all 4 node-version: 24.15.0 lines and the version comment at line 6.
9. Edit .github/workflows/publish-cli-release.yml line 29 → NODE_VERSION: '24.16.0'.
10. Edit .github/workflows/tmp-cli-lint-windows.yml lines 21+24 → 24.16.0.
11. Validate locally: node --version shows v24.16.0 (after nvm install 24.16.0 && nvm use), npm install against existing lockfile is clean.

Commit 2 — Nx 22.7.2 → 22.7.5

1. Run npx nx migrate 22.7.5. This rewrites every nx/@nx/* version in root package.json and creates migrations.json.
2. Manually verify tools/packmind-plugin/package.json @nx/devkit was bumped to 22.7.5 (it may not be picked up by the migrate; bump by hand if missing).
3. npm install to refresh package-lock.json.
4. npx nx migrate --run-migrations (none expected for a patch, but run anyway). Delete migrations.json.
5. Sanity-check nx.json and eslint.config.mjs for any auto-generated edits (none expected).
6. Validate touched projects sequentially (memory constraint): ./node_modules/.bin/nx lint <project> && ./node_modules/.bin/nx test <project> --testTimeout=30000 for projects most exercised by the build — at minimum frontend, api, cli, mcp-server, plus any package whose nx config was touched.

Commit 3 — Vite → 8.0.15

1. Bump package.json root vite: "^8.0.3" → "^8.0.15" (explicit floor, per the plan's recommendation).
2. npm install (or npm update vite) — only package-lock.json should change beyond the package.json line.
3. Skim apps/frontend/vite.config.ts and packages/ui/vite.config.ts for any deprecated options (none expected for a patch).
4. Validate: ./node_modules/.bin/nx build frontend and ./node_modules/.bin/nx build packages-ui (or the equivalent ui project name from nx show projects) succeed.

Final validation gate (before opening the PR)

• Targeted lint+test on each touched project sequentially with --testTimeout=30000. Never run test:staged/lint:staged/nx affected here — the worker is memory-constrained.
• Build the heavyweight targets: api, frontend, cli, mcp-server.
• Run docker-local.sh until docker compose -f dockerfile/local/docker-compose.yaml ps shows packmind up >30s.
• Capture: last 30 lines of api and mcp container logs; screenshot of the frontend welcome page.
• Embed those artifacts in the PR description (per michel-create-pr-with-screenshots).

Risks already accounted for in the plan

• All three bumps are non-breaking patch/minor.
• The local production-like stack (dockerfile/local/docker-compose.yaml) does not need direct edits — it builds from Dockerfile.api/Dockerfile.mcp.
• The dockerfile/local/docker-compose.override.yaml carries sandbox workarounds that must not be hand-patched per CLAUDE-style guidance.
• npm version may drift; verify before assuming engines.npm stays at 11.12.1.

No product, UX, or scope decisions remain — this is a deterministic, mechanical version bump with a clearly defined proof step.

[cteyton]

@michel take it

[cteyton]

@michel go