chore/enforce-node-22-types

.npmrc

@@ -0,0 +1,4 @@
+# Enforce the engines range from package.json.
+# Blocks unsupported versions (e.g. Node 18, 20, 23) but still allows
+# Node 24+ since engines includes ">=24.10.0" for local development.
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+22.14.0

AGENTS.md

@@ -60,6 +60,24 @@ architecture-as-code/
 - Docusaurus for main docs
 - Astro for advent-of-calm website
 
+## Node Version Requirements
+
+**CRITICAL**: This project targets **Node 22** as its CI baseline. All CI workflows run on Node 22, and lockfiles must be compatible with Node 22.
+
+The `engines` field in `package.json` (`^22.14.0 || >=24.10.0`) also permits Node 24+ for local development, but **Node 22 is the canonical version** used to validate builds and tests.
+
+- **`.nvmrc`** pins `22.14.0` — run `nvm use` to switch automatically
+- **`.npmrc`** has `engine-strict=true` — `npm install` will refuse to run on Node versions outside the `engines` range (e.g. Node 18, 20, or 23)
+- **`@types/node`** is overridden to `^22.0.0` in root `package.json` to prevent transitive dependencies from pulling in a different major version
+- **Renovate** is configured with `allowedVersions: "<23.0.0"` for `@types/node`
+
+### Why this matters
+
+Running `npm install` on a different Node major version (e.g. Node 25) causes:
+1. **Native binding failures** — platform-specific packages (`@swc/core`, `@tailwindcss/oxide`) resolve for the wrong Node ABI, breaking CI builds
+2. **`@types/node` version drift** — transitive deps with loose constraints (`>=18`, `*`) allow `@types/node@25` to be hoisted to root, masking usage of APIs unavailable in Node 22
+3. **Noisy lockfile diffs** — Renovate's `npmDedupe` recalculates the dependency tree, producing large spurious changes
+
 ## Quick Navigation
 
 ### Package-Specific Guides

calm-models/package.json

@@ -43,7 +43,7 @@
     "ajv": "^8.17.1"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^22.0.0",
     "eslint": "^9.39.2",
     "rimraf": "^5.0.0",
     "typescript": "^5.0.0"

package.json

@@ -57,6 +57,7 @@
         "vitest": "^3.1.1"
     },
     "overrides": {
+        "@types/node": "^22.0.0",
         "on-headers": "^1.1.0",
         "node-forge": "^1.3.2",
         "qs": "^6.14.1",

renovate.json

@@ -155,6 +155,11 @@
       "description": "Ignore pre-release versions",
       "matchCurrentVersion": "/^0\\./",
       "automerge": false
+    },
+    {
+      "description": "Pin @types/node to v22 to match CI Node version",
+      "matchPackageNames": ["@types/node"],
+      "allowedVersions": "<23.0.0"
     }
   ]
 }