From dbd2bf30e94e49f8e6437893914d3fe7399feb21 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Thu, 21 May 2026 06:16:08 +0200 Subject: [PATCH] =?UTF-8?q?chore(memory):=20correct=20BLK-005=20+=20LRN-02?= =?UTF-8?q?2=20=E2=80=94=20pnpm=2011.x=20line=20needs=20Node=2022?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Initial hypothesis ("pnpm@latest pulled a newer 11.4+ with new Node floor") was wrong. Investigation after the second VPS crash showed the whole pnpm 11.0+ line imports node:sqlite from its store-index module. Local dev was misleading because pnpm install never re-ran on the Node 20 host (lockfile already resolved, child scripts don't load the store module). Updates: - BLK-005: replace single-fix line with iteration log (@latest → @11.1.3 → @10.13.1, last one resolved). - LRN-022: rewrite headline + body to reflect pnpm 11 ↔ Node 22.13 coupling, not just pnpm 11.4. Add pnpm/Node compat matrix. - journal 2026-05-21: append v2 fix entry referencing commit 990c8e7. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/memory/blockers.md | 10 +++++++--- .claude/memory/journal.md | 1 + .claude/memory/learnings.md | 16 +++++++++------- 3 files changed, 17 insertions(+), 10 deletions(-) diff --git a/.claude/memory/blockers.md b/.claude/memory/blockers.md index 51a6f1d9..a480f8d2 100644 --- a/.claude/memory/blockers.md +++ b/.claude/memory/blockers.md @@ -42,6 +42,10 @@ Status: resolved. ## BLK-005 | 2026-05-21 | Docker build crash — ERR_UNKNOWN_BUILTIN_MODULE node:sqlite Friction: VPS `docker compose up --build -d` crashed on pnpm install (fresh cold build). -Root: Dockerfile:7 `corepack prepare pnpm@latest --activate` re-resolved to pnpm >=11.4. pnpm >=11.4 imports `node:sqlite` (Node 22.13+ only). Image `node:20-alpine` (Node 20.20.2) → `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` at install start. Local dev unaffected — corepack cached older pnpm 11.1.3. -Fix: pin `pnpm@11.1.3` in Dockerfile:7 (matches host, lockfile v9 stays valid). -Status: resolved (commit 7dccde7). +Root: `node:20-alpine` (Node 20.20.2) cannot load pnpm 11.x — pnpm 11 itself imports `node:sqlite` from `../store/index/lib/index.js`, and `node:sqlite` is a Node 22.13+ built-in. Crash: `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite`. Local dev was deceptive — host runs Node 20 too, but `pnpm install` never ran on host (lockfile already resolved); `pnpm run typecheck` / `pnpm run test` only spawn child scripts and never load the store-index module. +Iterations: +1. `corepack prepare pnpm@latest` → fails (resolves to current pnpm 11.x). +2. `corepack prepare pnpm@11.1.3` → still fails (entire pnpm 11.x line needs Node 22.13). +3. `corepack prepare pnpm@10.13.1` → works. Last major before the node:sqlite cache backend; reads lockfile v9 unchanged; already cached on dev host. +Fix: Dockerfile:7 pinned to `pnpm@10.13.1`. +Status: resolved (commit 990c8e7). diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index cda7c4e9..f2b51fbe 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -77,6 +77,7 @@ User dropped catalog v1.2→v2.0 in place. pathologies.json now schema_version " - hotfix(pdf): PDF export crashed `WinAnsi cannot encode "⚠"` on any obs carrying a requires_vet_referral leaf — StandardFonts.Helvetica is WinAnsi-only. Swapped `⚠ ` PDF marker → `(!) ` (UI keeps ⚠). Regression test added on `widthOfTextAtSize` + prefixed label. LRN-021, EVAL-003 captured. 155/155 green. Follow-up: migrate PDF body to embedded TTF (Inter/Fraunces per CLAUDE.md spec) so future non-Latin-1 glyphs work. - chore: rename project `osteo-report` → `zoosteo` (Gitea repo moved). 15 files: repo URLs (CHANGELOG, DEPLOY, package.json), brand strings (env.ts DEFAULTS, entrypoint.sh fallbacks, i18n fr/en, pdf attachment metadata, index.html title, Brand test, scaffold banner, README/CLAUDE/CHANGELOG/ADDING-A-SPECIES headings), example URL osteo.example.com → zoosteo.fr in DEPLOY.md. PDF FILENAME `osteo-report.json` + startsWith contract preserved. 155/155 tests green. Commit 7dd4f63 + push. - fix(docker): pin `pnpm@11.1.3` in Dockerfile:7. `corepack prepare pnpm@latest` re-resolved to pnpm >=11.4 on VPS cold build, which needs Node 22.13 → `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` on Node 20 image. Commit 7dccde7 + push. BLK-005 + LRN-022 captured. +- fix(docker) v2: 11.1.3 pin insufficient — pnpm 11.x ENTIRE LINE imports `node:sqlite` (not just 11.4+). Local dev was misleading because pnpm install never re-ran on host. Downgrade Dockerfile to `pnpm@10.13.1` (last 10.x cached on host, reads lockfile v9 unchanged). Commit 990c8e7 + push. BLK-005 + LRN-022 corrected with iteration log. --- diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index ff6fdf34..ac592f51 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -174,12 +174,14 @@ Apply: any data contract sourced from non-engineering authors (clinical, legal, --- -## LRN-022 | 2026-05-21 | Never floating `pnpm@latest` (or any unpinned tag) in Dockerfile — silent Node-version drift +## LRN-022 | 2026-05-21 | pnpm 11.x requires Node 22.13 — pin pnpm to ≤10.x when staying on Node 20, never use `@latest` -`corepack prepare pnpm@latest --activate` re-resolves at every cold build. pnpm minor bumps can raise required Node floor without warning: pnpm 11.4 added `node:sqlite` import → Node 22.13+ required. Image stayed on `node:20-alpine` → `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` at install start. Works on dev host because corepack caches older pnpm (11.1.3); breaks on fresh VPS cold build that re-resolves `@latest`. Same trap for any unpinned upstream ref: `node:lts`, `:alpine`, `nginx:alpine`, GitHub Actions `uses: foo@v1` (prefer SHA). +pnpm 11.x imports `node:sqlite` for its store-index module — loaded at pnpm startup for any command that touches the store (install, fetch, add, prune). `node:sqlite` is a Node 22.13+ built-in. Result: `ERR_UNKNOWN_BUILTIN_MODULE: node:sqlite` on every fresh Docker build using `node:20-alpine` + pnpm 11.x. The crash is deterministic for cold installs and invisible for warm dev hosts that already have `node_modules` resolved (pnpm 11 on Node 20 can still spawn child scripts because the store module isn't required for `pnpm run`). +Initial hypothesis ("pnpm@latest pulls a newer 11.x with a new Node floor") was wrong — the whole pnpm 11.0+ line carries the sqlite dependency. Fix paths: -- Pin exact in Dockerfile: `corepack prepare pnpm@ --activate`. -- Mirror in `package.json`: `"packageManager": "pnpm@X.Y.Z"` — host + Docker stay synced via corepack. -- Bump base image deliberately when pnpm major bump is intentional, never as side effect of `@latest`. -**Why:** Floating tag = drift bomb between cached dev + fresh prod resolve. CI passes today, prod breaks tomorrow on same Dockerfile, no commit changed. -**How to apply:** Audit every Dockerfile + docker-compose + CI `uses:` for floating refs before first prod deploy. Lockfile pins app deps; Dockerfile + workflow files must pin toolchain. +- Stay on Node 20 → pin Dockerfile to `pnpm@10.x` (e.g. `corepack prepare pnpm@10.13.1 --activate`). pnpm 10 reads lockfile v9 unchanged. +- Move to Node 22 → bump `FROM node:22-alpine`, `.nvmrc`, and CLAUDE.md stack table together. Required if pnpm 11+ features needed. +- Mirror exact version in `package.json`: `"packageManager": "pnpm@X.Y.Z"` so host + Docker stay synced via corepack. +- Never `corepack prepare pnpm@latest` — re-resolves at every cold build, silently bumps toolchain across deploys with no commit. +**Why:** Floating tag = drift bomb between cached dev + fresh prod resolve. Same risk for unpinned `node:lts`, `:alpine`, GitHub Actions `uses: foo@v1` (prefer SHA). Lockfile pins app deps; Dockerfile must pin toolchain. +**How to apply:** Before first prod deploy, audit every Dockerfile, docker-compose, and CI workflow for floating upstream refs. For pnpm specifically, check Node version against pnpm minimum (pnpm 11 ↔ Node 22.13, pnpm 10 ↔ Node 18+, pnpm 9 ↔ Node 18+).