build(pnpm): migrate to pnpm 11 + add minimumReleaseAge + pin Node 22

.github/actions/setup-env/action.yml

@@ -68,7 +68,7 @@ runs:
     # ask pnpm for the actual store path.
     - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093 # v6.0.8
       with:
-        version: "10.33.0"
+        version: "11.1.3"
         run_install: false
 
     - name: Resolve pnpm store directory

.nvmrc

@@ -0,0 +1 @@
+22

AGENTS.md

@@ -129,9 +129,10 @@ Tooling notes:
   auto-installed to `.bin/<os>_<arch>/` on first `make lint` (or via
   `make tools`). Not in `go.mod` — its dependency tree conflicts with the
   main module.
-- `pnpm` (>= 10.33) and `Node.js` (>= 20) must be on your PATH; the SDK and
-  E2E test harnesses both shell out to `pnpm`. `make tools` runs
-  `pnpm install --frozen-lockfile` in `clients/ts/` and `tests/e2e/sdk/`.
+- `pnpm` (>= 11.1) and `Node.js` (22 LTS — pinned via `.nvmrc` at the repo
+  root, matches CI) must be on your PATH; the SDK and E2E test harnesses
+  both shell out to `pnpm`. `make tools` runs `pnpm install
+  --frozen-lockfile` in `clients/ts/` and `tests/e2e/sdk/`.
 - `GNU Make 4+` is required (uses `--output-sync=target`); macOS ships BSD
   Make 3.81 which will not parse the Makefile. See `docs/development.md` §
   Prerequisites for the full setup checklist.

README.md

@@ -116,7 +116,7 @@ WaveHouse is built as an application, not a library — `internal/` packages are
 
 ## 💻 Local Development
 
-You'll need **Go 1.26+, GNU Make 4+, Docker (or Podman) with Compose v2, Node.js 20+, and pnpm 10+** on your PATH — see [docs/development.md § Prerequisites](docs/development.md#prerequisites) for the full list, version requirements, and macOS gotchas (BSD Make 3.81 won't work).
+You'll need **Go 1.26+, GNU Make 4+, Docker (or Podman) with Compose v2, Node.js 22 LTS (pinned via `.nvmrc`, matches CI), and pnpm 11+** on your PATH — see [docs/development.md § Prerequisites](docs/development.md#prerequisites) for the full list, version requirements, and macOS gotchas (BSD Make 3.81 won't work).
 
 For building and testing WaveHouse locally with hot-reload:
 

clients/ts/package.json

@@ -2,7 +2,7 @@
   "name": "@wavehouse/sdk",
   "version": "0.1.0",
   "description": "TypeScript SDK for WaveHouse — schema-aware real-time API gateway for ClickHouse",
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@11.1.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -48,10 +48,5 @@
     "sse",
     "query-builder",
     "typescript"
-  ],
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  }
+  ]
 }

clients/ts/pnpm-workspace.yaml

@@ -0,0 +1,21 @@
+# pnpm 11+ moved settings out of package.json#pnpm into this file.
+# This is a single-package "workspace" — only used for settings, no
+# `packages:` field. (Each WaveHouse pnpm project ships its own copy
+# of this file; they're not one shared monorepo.)
+
+# Build scripts pnpm is allowed to run during install. Without this,
+# pnpm 11 errors out with ERR_PNPM_IGNORED_BUILDS on any postinstall
+# script for an unlisted package.
+#   esbuild — postinstall fetches the platform-native binary; tsup +
+#     vitest both depend on it.
+# To add a new entry: `pnpm approve-builds <pkg>` (interactive) or
+# edit this file directly with `<pkg>: true`.
+allowBuilds:
+  esbuild: true
+
+# Refuse packages published in the last 7 days (10080 minutes) so npm
+# has time to surface compromised releases before they land in our
+# lockfile. Use `minimumReleaseAgeExclude: [pkg-name]` for one-off
+# overrides if a hotfix release needs to land before the window
+# expires.
+minimumReleaseAge: 10080

docs/package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "0.0.1",
   "private": true,
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@11.1.3",
   "scripts": {
     "dev": "astro dev",
     "start": "astro dev",
@@ -33,12 +33,5 @@
   },
   "engines": {
     "node": ">=20.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp",
-      "workerd"
-    ]
   }
 }

docs/pnpm-workspace.yaml

@@ -0,0 +1,12 @@
+# See clients/ts/pnpm-workspace.yaml for full rationale. Kept in sync
+# across all three WaveHouse pnpm projects manually.
+#
+# Docs needs extra build scripts beyond esbuild:
+#   sharp   — native image pipeline used by Astro's image optimizer.
+#   workerd — Cloudflare Workers runtime fetched by wrangler.
+allowBuilds:
+  esbuild: true
+  sharp: true
+  workerd: true
+
+minimumReleaseAge: 10080

docs/src/content/docs/development.md

@@ -17,8 +17,8 @@ You need these on your `PATH` before any `make` recipe will work end-to-end:
 | **GNU Make** | **4.0+** | The Makefile uses `--output-sync=target` (Make 4 only) and bash-pinned recipes. macOS ships with BSD Make 3.81, which **will not work** | macOS: `brew install make` then use `gmake` or put `$(brew --prefix make)/libexec/gnubin` on your PATH. Linux: usually already installed |
 | **bash** | 4+ recommended | Recipes are pinned to `bash`; the helper scripts under `scripts/` use `set -euo pipefail` and bash arrays | macOS default is bash 3.2 (works for current recipes, but `brew install bash` is safer); Linux distros ship 4+ |
 | **Docker** *(or Podman)* | Engine 20.10+ with the Compose **v2** plugin (`docker compose`, no hyphen) | Compose stacks under `deployments/compose/` and `tests/e2e/compose.yaml`; integration tests boot a ClickHouse testcontainer | [Docker Desktop](https://docs.docker.com/get-docker/), [colima](https://github.com/abiosoft/colima), or [Podman](https://podman.io) with `podman-compose` / the `podman compose` plugin. The testcontainers Go library also honors `DOCKER_HOST` for rootless Podman setups |
-| **Node.js** | 20+ | Runtime for pnpm and the Vitest suites | [nodejs.org](https://nodejs.org/) or `nvm`/`fnm`/`volta` |
-| **pnpm** | 10.33+ (pinned via `packageManager` in `clients/ts/package.json`, `tests/e2e/sdk/package.json`, and `docs/package.json`) | Package manager for the TypeScript SDK, E2E test harness, and docs site; `make build-sdk`, `make test-sdk`, `make test-e2e`, `make build-docs`, `make dev-docs`, `make preview-docs` all shell out to `pnpm` | `corepack enable && corepack prepare pnpm@10.33.0 --activate` (recommended), or `npm i -g pnpm` |
+| **Node.js** | 22 LTS — pinned via `.nvmrc` at the repo root | Runtime for pnpm and the Vitest suites. Pinned to match CI (`setup-node` uses 22) and to avoid Node-major surprises; older Vitest versions in this repo were known to crash on Node 26 with a V8 heap-allocation abort | [nodejs.org](https://nodejs.org/) or `nvm use` / `fnm use` / `volta` (all read `.nvmrc`) |
+| **pnpm** | 11.1+ (pinned via `packageManager` in `clients/ts/package.json`, `tests/e2e/sdk/package.json`, and `docs/package.json`) | Package manager for the TypeScript SDK, E2E test harness, and docs site; `make build-sdk`, `make test-sdk`, `make test-e2e`, `make build-docs`, `make dev-docs`, `make preview-docs` all shell out to `pnpm` | `corepack enable && corepack prepare pnpm@11.1.3 --activate` (recommended), or `npm i -g pnpm` |
 | **git** + **curl** | any recent | `git` for source + version metadata in builds; `curl` is used by the Makefile to fetch the pinned `golangci-lint` binary into `.bin/` | usually preinstalled |
 
 ### Auto-installed by `make tools`
@@ -36,8 +36,8 @@ Run `make tools` once after cloning to populate everything that doesn't have to
 go version          # go1.26+
 make --version      # GNU Make 4.x
 docker compose version
-node --version      # v20+
-pnpm --version      # 10.33+
+node --version      # v22.x (matches .nvmrc and CI)
+pnpm --version      # 11.1+
 ```
 
 If any of those are wrong/missing, the Makefile recipes will fail with confusing errors (e.g. `--output-sync` is unrecognized on Make 3.81; `pnpm: command not found` on `make test-sdk`).

tests/e2e/sdk/package.json

@@ -1,7 +1,7 @@
 {
   "private": true,
   "name": "wavehouse-e2e",
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@11.1.3",
   "type": "module",
   "scripts": {
     "test": "vitest run",
@@ -14,10 +14,5 @@
     "eventsource": "^4.1.0",
     "typescript": "^5.5.0",
     "vitest": "^3.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
   }
 }

tests/e2e/sdk/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+# See clients/ts/pnpm-workspace.yaml for full rationale. Kept in sync
+# across all three WaveHouse pnpm projects manually.
+
+allowBuilds:
+  esbuild: true
+
+minimumReleaseAge: 10080