@lenne.tech/nest-server 11.29.0 → 11.30.0

package/migration-guides/11.29.0-to-11.29.1.md

@@ -0,0 +1,311 @@
+# Migration Guide: 11.29.0 → 11.29.1
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **Bugfixes** | None — no runtime code changed. `src/core/` is byte-identical to 11.29.0. |
+| **New Features** | None |
+| **Maintenance** | **Toolchain only.** `package.json#packageManager` is restored as the *single* place the pnpm version is pinned. `corepack` is gone from the `Dockerfile` (Node >= 25 no longer ships it); every pnpm-running build stage now provisions the pinned pnpm itself. `pnpm/action-setup` reads the pin instead of carrying its own `version` input. A contract test (`tests/unit/pnpm-pin-contract.spec.ts`) guards the whole chain. |
+| **Migration Effort** | **0 minutes for npm-mode and vendor-mode consumers** — nothing in your project changes. **~10 minutes if you adopt the pattern**, which you should do *before* moving any build to Node >= 25. |
+
+This release changes **how the framework repo builds itself**. It ships no API change, no
+configuration change, and no behavioral change. Update with `pnpm add @lenne.tech/nest-server@11.29.1`
+and you are done.
+
+The reason to read further: **the `Dockerfile` is not part of the npm package** (it is not in
+`package.json#files`). Your project's own `Dockerfile` and CI came from the starter template, so you
+do **not** inherit this fix automatically. If they still run `corepack enable`, they will break the
+day you move to Node >= 25 — see [Adopting the pattern](#adopting-the-pattern-in-your-project-recommended).
+
+---
+
+## Quick Migration (npm mode)
+
+No code changes required.
+
+```bash
+# Update the package
+pnpm add @lenne.tech/nest-server@11.29.1
+
+# Verify
+pnpm run build
+pnpm test
+```
+
+---
+
+## Why this release exists: corepack is going away
+
+`corepack` was the mechanism that read `package.json#packageManager` and materialized the right
+package-manager binary. It shipped with Node for years, which is why the framework's `Dockerfile`
+could simply say `corepack enable` and trust that pnpm appeared.
+
+**Node >= 25 no longer ships corepack.** A build stage that runs `corepack enable` on such an image
+fails outright:
+
+```
+/bin/sh: corepack: not found
+```
+
+So the framework needed a way to provision an exact pnpm version that does not depend on corepack
+existing — without giving up the single-source-of-truth pin.
+
+### What 11.29.0 did, and why it is reverted here
+
+11.29.0 removed the `packageManager` field and introduced `engines.pnpm: "^11.0.0"`. That left the
+repo with **no exact pin at all**, so the version had to be restated wherever pnpm was needed — the
+workflows grew a hardcoded `with: version: 11`, and Docker's `corepack enable` (with no
+`packageManager` field to follow) would resolve to whatever it considered current.
+
+Two sources of truth, neither exact. 11.29.1 collapses them back into one:
+
+| | 11.29.0 | 11.29.1 |
+|---|---|---|
+| `package.json#packageManager` | *(removed)* | `pnpm@11.13.1+sha512.…` — **the** pin |
+| `package.json#engines.pnpm` | `^11.0.0` | `^11.0.0` — unchanged, a soft major gate |
+| `.github/workflows/*` | `with: version: 11` | *(no `version` input — reads the pin)* |
+| `Dockerfile` | `corepack enable` | derive-line (below) |
+
+`engines.pnpm` stays, but understand what it is: a **soft major-range guard**, not a pin. It warns a
+pnpm 10 user; it does not tell CI which version to install. Only `packageManager` does that.
+
+---
+
+## What Changed
+
+### 1. `packageManager` is back — exact, with an integrity hash
+
+```jsonc
+// package.json
+{
+  "packageManager": "pnpm@11.13.1+sha512.b2fc7683b8a6525414e7d13e1ba28caaddde96bf66ec540bfaeb7e702b81f3e0be4d1f295edf7f9fe0396740a8dce4509c582ddf79891f4543fea32d37645f25",
+  "engines": {
+    "node": ">= 22",
+    "pnpm": "^11.0.0"
+  }
+}
+```
+
+**This field has no effect on your project.** `packageManager` is only ever read from the *root*
+`package.json` of the project being built — never from a dependency's. You inherit nothing from the
+framework's pin.
+
+Note that pnpm itself honours the field, with no corepack involved: run any `pnpm` command in a
+directory whose `package.json` pins a different pnpm, and pnpm switches to it
+(`managePackageManagerVersions`, on by default since pnpm 10). Corepack was never the only thing
+reading this field — which is exactly why dropping it costs nothing.
+
+### 2. The Dockerfile provisions pnpm without corepack
+
+Every stage that runs `pnpm` now provisions the pinned version itself, from the pin:
+
+```dockerfile
+# Provision the exact pnpm declared in package.json (single source of truth).
+# No corepack: Node >= 25 no longer ships it. The +sha512 suffix is stripped;
+# npm enforces registry integrity for the tarball itself.
+RUN npm install -g "$(node -p "require('./package.json').packageManager.split('+')[0]")"
+```
+
+The `.split('+')[0]` turns `pnpm@11.13.1+sha512.b2fc…` into `pnpm@11.13.1`, because `npm install -g`
+takes a plain spec. The dropped hash is not a loss of integrity: npm verifies the tarball against the
+registry's own integrity metadata on install.
+
+The line appears **once per pnpm-running stage** (`deps` and `builder`) — Docker stages do not inherit
+each other's globally installed binaries, only what is explicitly `COPY --from=`'d.
+
+### 3. `pnpm/action-setup` no longer carries a `version` input
+
+```yaml
+- name: Install pnpm
+  # No version input: the exact version is read from package.json's packageManager field.
+  uses: pnpm/action-setup@v6
+```
+
+The action reads `packageManager` on its own. Specifying **both** is not redundant-but-harmless — the
+action treats a mismatch as a hard error, so the two sources cannot silently drift.
+
+### 4. A contract test guards the chain
+
+`tests/unit/pnpm-pin-contract.spec.ts` (11 assertions, unit suite, no MongoDB) fails the build if
+anyone re-introduces the drift this release removes:
+
+- the pin is exact (`x.y.z` + `sha512` hash — never a range),
+- `engines.pnpm` tracks the pin's major,
+- `devEngines.packageManager` never (re)appears — npm/npx abort with `EBADDEVENGINES` on it,
+- the `Dockerfile` contains no `corepack` in any `RUN`,
+- **every** pnpm-running stage runs the derive-line *before* its first `pnpm` command, and only after
+  a `COPY` has put `package.json` in place,
+- no workflow passes a `version:` to `pnpm/action-setup` or hardcodes `npm install -g pnpm@…`.
+
+A twelfth test proves the chain end-to-end — it derives the spec exactly as the Dockerfile does,
+installs it into a throwaway prefix, and asserts the provisioned binary reports the pinned version.
+It needs network and ~10 MB, so it is gated to `CI` / `PIN_PROVISION_TEST=1` and stays out of your way
+locally.
+
+---
+
+## Breaking Changes
+
+**None.** No public API, config key, decorator, or exported symbol changed.
+
+---
+
+## Adopting the pattern in your project (recommended)
+
+Do this **before** you move any build to Node >= 25 — not after it breaks. If your project was
+generated from a recent `nest-server-starter` / `lt fullstack init`, check whether it is already done.
+
+### Step 1: Pin pnpm in your root `package.json`
+
+```bash
+# Writes packageManager with the integrity hash for the version you actually use
+pnpm self-update
+```
+
+Or set it by hand — the exact form matters (`pnpm@x.y.z+sha512.<hash>`):
+
+```jsonc
+{
+  "packageManager": "pnpm@11.13.1+sha512.b2fc7683…",
+  "engines": { "node": ">= 22", "pnpm": "^11.0.0" }
+}
+```
+
+> **Monorepo:** this belongs in the **workspace root** `package.json`, not only in `projects/api/`.
+> The Dockerfile's derive-line reads `/app/package.json`, which in monorepo mode
+> (`--build-arg API_DIR=projects/api`) is the root manifest. See
+> [Troubleshooting](#docker-build-fails-with-typeerror-cannot-read-properties-of-undefined-reading-split).
+
+### Step 2: Replace corepack in your Dockerfile
+
+**Before:**
+```dockerfile
+RUN apk add --no-cache python3 make g++ && corepack enable
+```
+
+**After:**
+```dockerfile
+RUN apk add --no-cache python3 make g++
+
+# … COPY the manifests first — the derive-line reads package.json …
+
+# Provision the exact pnpm declared in package.json (single source of truth).
+# No corepack: Node >= 25 no longer ships it. The +sha512 suffix is stripped;
+# npm enforces registry integrity for the tarball itself.
+RUN npm install -g "$(node -p "require('./package.json').packageManager.split('+')[0]")"
+```
+
+Two ordering rules, both easy to get wrong:
+
+1. The derive-line must come **after** the `COPY` that puts `package.json` into the WORKDIR — it
+   reads that file.
+2. It must be repeated in **each** stage that runs `pnpm`. A global install in `deps` does not reach
+   `builder`.
+
+### Step 3: Drop the hardcoded version in CI
+
+**GitHub Actions** — remove the `version` input:
+
+```yaml
+- name: Install pnpm
+  uses: pnpm/action-setup@v6      # reads packageManager; no `with: version:`
+```
+
+**GitLab CI** (or any runner without the action) — use the same derive-line:
+
+```yaml
+before_script:
+  # Provision the exact pnpm pinned in package.json (single source of truth).
+  - npm install -g "$(node -p "require('./package.json').packageManager.split('+')[0]")"
+  - pnpm install --frozen-lockfile
+```
+
+### Step 4 (optional): Guard it with a test
+
+Copy `tests/unit/pnpm-pin-contract.spec.ts` from this repo and trim it to the files your project has.
+The value is not the assertions — it is that the next person who "helpfully" re-adds
+`with: version: 11` or a second `npm install -g pnpm@…` gets a red build instead of a silent drift
+that surfaces months later as an unreproducible container.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| Any application code, decorator, service, or config using the framework | ✅ Unaffected — no runtime code changed |
+| **npm-mode** consumers (`@lenne.tech/nest-server` as a dependency) | ✅ Unaffected — `pnpm add …@11.29.1` and done |
+| **Vendor-mode** consumers (`src/core/` copied in) | ✅ Unaffected — `src/core/` is byte-identical to 11.29.0; a sync produces no delta |
+| The framework's `packageManager` pin leaking into your project | ✅ Impossible — the field is read only from the root manifest, never from a dependency |
+| Your project's `Dockerfile` still using `corepack enable` | ⚠️ Works on Node <= 24, **breaks on Node >= 25** — apply Step 2 |
+| Your CI passing both `with: version:` **and** having a `packageManager` field | ⚠️ Hard error on version mismatch — apply Step 3 |
+| Node version | ✅ Unchanged (`engines.node: ">= 22"`); the framework's own images stay on Node 24 LTS |
+| pnpm 10 or older as your project's package manager | ⚠️ `engines.pnpm: "^11.0.0"` warns (`EBADENGINE`); a hard failure only with `engine-strict=true` |
+
+---
+
+## Troubleshooting
+
+### `corepack: not found` in a Docker build or CI job
+
+You moved to a Node >= 25 image while your build still calls `corepack enable`. This is exactly the
+failure this release prevents — apply [Step 2](#step-2-replace-corepack-in-your-dockerfile). Do not
+"fix" it with `npm install -g corepack`: that reintroduces the indirection the derive-line removes.
+
+### Docker build fails with `TypeError: Cannot read properties of undefined (reading 'split')`
+
+The derive-line found a `package.json` **without** a `packageManager` field. Almost always a
+monorepo: in monorepo mode the build context is the workspace root, so `/app/package.json` is the
+**root** manifest — and the pin was only added to `projects/api/package.json`.
+
+Fix: add `packageManager` to the workspace **root** manifest (Step 1). Keeping the root and the API
+package on the same pin is the point — one pnpm builds the whole workspace.
+
+### `ERR_PNPM_BAD_PM_VERSION`, or the action reports multiple pnpm versions
+
+Two sources disagree about the version. Either your workflow still passes `with: version:` alongside
+a `packageManager` field (remove the input — [Step 3](#step-3-drop-the-hardcoded-version-in-ci)), or a
+stray `npm install -g pnpm@<other>` runs before the derive-line.
+
+### `EBADENGINE` / `ERR_PNPM_UNSUPPORTED_ENGINE` warning mentioning pnpm
+
+Unchanged from 11.29.0 — `engines.pnpm: "^11.0.0"` warns when installing with pnpm 10 or older.
+Upgrade with `npm i -g pnpm@11`, or pin your project via `packageManager` and let pnpm switch itself.
+The framework's *runtime* does not depend on pnpm; this concerns the install step only.
+
+### `EBADDEVENGINES` from npm or npx
+
+Something added a `devEngines.packageManager` block. npm and npx abort on it, and corepack rejects
+ranges inside it. Use `packageManager` (exact pin) plus `engines.pnpm` (soft range) instead — the
+contract test asserts `devEngines.packageManager` stays absent.
+
+---
+
+## Affected Files
+
+No core module changed in this release, so there is no module documentation to revisit. For
+completeness, the full change surface:
+
+| File | Change |
+|------|--------|
+| `package.json` | `packageManager` restored (exact pin + `sha512`); version → 11.29.1 |
+| `Dockerfile` | `corepack enable` removed; derive-line added to the `deps` and `builder` stages |
+| `.github/workflows/build.yml`, `publish.yml` | `with: version: 11` removed from `pnpm/action-setup` |
+| `tests/unit/pnpm-pin-contract.spec.ts` | **New** — 11 structural assertions + 1 CI-gated provisioning proof |
+| `spectaql.yml`, `FRAMEWORK-API.md` | Version bump only (kept in sync per the release process) |
+| `.claude/rules/package-management.md` | Documents the corepack-free pin contract |
+
+---
+
+## References
+
+- [Package Management Rules — fixed versions, overrides, the pnpm pin contract](../.claude/rules/package-management.md)
+- [Versioning Strategy — release process, `package.json` / `spectaql.yml` version sync](../.claude/rules/versioning.md)
+- Contract test: `tests/unit/pnpm-pin-contract.spec.ts`
+- [Migration Guide 11.28.1 → 11.29.0](./11.28.1-to-11.29.0.md) — previous release (introduced the `engines.pnpm` gate this guide keeps)
+- [Migration Guide 11.27.6 → 11.27.7](./11.27.6-to-11.27.7.md) — the pnpm 11 move, when corepack was still the mechanism
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
+</content>
+</invoke>

package/migration-guides/11.29.x-to-11.30.x.md

@@ -0,0 +1,98 @@
+# Migration Guide: 11.29.x → 11.30.x
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None in nest-server's own API. Two transitive changes may affect projects: `@nestjs/websockets` removed from dependencies; `@nestjs/swagger` 11.4.6 blocks deep imports |
+| **New Features** | None (dependency maintenance release) |
+| **Bugfixes** | Dependency updates incl. security-relevant `ws` 8.21.1 override; 6 obsolete pnpm overrides removed |
+| **Migration Effort** | Very Low (~5 minutes) — most projects need no changes |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+npm install @lenne.tech/nest-server@11.30.x
+
+# Verify build
+npm run build
+
+# Run tests
+npm test
+```
+
+Most projects need no code changes. Read the two notes below only if your
+project uses `@WebSocketGateway` or deep-imports from `@nestjs/swagger`.
+
+---
+
+## What Changed in 11.30.x
+
+Dependency maintenance across the board (all checks green, 2157 tests, 0 audit
+findings):
+
+- **dependencies:** `@getbrevo/brevo` 3.0.4, `@nestjs/swagger` 11.4.6,
+  `jose` 6.2.3, `ws` 8.21.1, `graphql-ws` 6.1.0, `ejs` 6.0.1,
+  `ts-morph` 28.0.0
+- **removed:** `@nestjs/websockets` (unused by the framework itself — see below)
+- **devDependencies:** `@nestjs/cli` 11.0.24, `vite` 8.1.5, `oxfmt` 0.59.0,
+  `@compodoc/compodoc` 2.0.0, `@types/node` 26.1.1
+- **pnpm overrides:** 6 obsolete entries removed (`ajv`, `picomatch`,
+  `js-yaml`, `uuid`, `@babel/core`, `websocket-driver` — all resolved
+  upstream); the `ws` override stays (load-bearing against
+  GHSA-96hv-2xvq-fx4p)
+
+---
+
+## Notes for Consuming Projects
+
+### 1. `@nestjs/websockets` is no longer a nest-server dependency
+
+The framework itself never used it. If your project uses `@WebSocketGateway`
+(or anything else from `@nestjs/websockets`) it previously worked only as a
+phantom dependency — add it explicitly now:
+
+```bash
+npm install @nestjs/websockets@^11.1.28
+```
+
+GraphQL subscriptions are NOT affected (`@nestjs/graphql` uses
+`graphql-ws`/`ws` directly).
+
+### 2. `@nestjs/swagger` 11.4.6 ships an `exports` map — deep imports fail at runtime
+
+**Before:**
+```typescript
+import { DECORATORS } from '@nestjs/swagger/dist/constants';
+```
+
+**After:**
+```typescript
+import { DECORATORS } from '@nestjs/swagger';
+```
+
+Deep imports like `@nestjs/swagger/dist/*` now throw
+`ERR_PACKAGE_PATH_NOT_EXPORTED` at runtime (type-only imports still compile).
+Everything you need is available from the root export.
+
+### 3. `ejs` 5 → 6 (framework-internal)
+
+The framework's own template rendering (`ejs.compile`) is unchanged and fully
+tested. Only if your project passes removed legacy ejs options to its own
+templates would you be affected — unlikely; check the ejs 6 changelog if you
+use custom ejs options.
+
+---
+
+## Detailed Migration Steps
+
+1. Update the package (`npm install @lenne.tech/nest-server@11.30.x` or
+   `pnpm run update` in starter-based projects).
+2. Search your project for `@nestjs/swagger/dist` deep imports and replace
+   them with root imports.
+3. If you use `@WebSocketGateway`: add `@nestjs/websockets` to your own
+   dependencies.
+4. `npm run build` + `npm test` — both should pass without further changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.29.0",
+  "version": "11.30.0",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -79,11 +79,12 @@
     "node": ">= 22",
     "pnpm": "^11.0.0"
   },
+  "packageManager": "pnpm@11.13.1+sha512.b2fc7683b8a6525414e7d13e1ba28caaddde96bf66ec540bfaeb7e702b81f3e0be4d1f295edf7f9fe0396740a8dce4509c582ddf79891f4543fea32d37645f25",
   "dependencies": {
     "@apollo/server": "5.5.1",
     "@as-integrations/express5": "1.1.2",
     "@better-auth/passkey": "1.6.23",
-    "@getbrevo/brevo": "3.0.1",
+    "@getbrevo/brevo": "3.0.4",
     "@modelcontextprotocol/sdk": "1.29.0",
     "@nestjs/apollo": "13.4.2",
     "@nestjs/common": "11.1.28",
@@ -94,9 +95,8 @@
     "@nestjs/passport": "11.0.5",
     "@nestjs/platform-express": "11.1.28",
     "@nestjs/schedule": "6.1.3",
-    "@nestjs/swagger": "11.4.2",
+    "@nestjs/swagger": "11.4.6",
     "@nestjs/terminus": "11.1.1",
-    "@nestjs/websockets": "11.1.28",
     "@tus/file-store": "2.1.0",
     "@tus/server": "2.4.1",
     "@types/supertest": "7.2.1",
@@ -108,14 +108,14 @@
     "cookie-parser": "1.4.7",
     "cron": "4.4.0",
     "dotenv": "17.4.2",
-    "ejs": "5.0.2",
+    "ejs": "6.0.1",
     "express": "5.2.1",
     "graphql": "16.14.0",
     "graphql-query-complexity": "1.1.1",
     "graphql-subscriptions": "3.0.0",
     "graphql-upload": "15.0.2",
-    "graphql-ws": "6.0.8",
-    "jose": "6.2.1",
+    "graphql-ws": "6.1.0",
+    "jose": "6.2.3",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
     "lodash": "4.18.1",
@@ -130,13 +130,13 @@
     "rfdc": "1.4.1",
     "rxjs": "7.8.2",
     "supertest": "7.2.2",
-    "ts-morph": "27.0.2",
-    "ws": "8.21.0",
+    "ts-morph": "28.0.0",
+    "ws": "8.21.1",
     "yuml-diagram": "1.2.0"
   },
   "devDependencies": {
-    "@compodoc/compodoc": "1.2.1",
-    "@nestjs/cli": "11.0.21",
+    "@compodoc/compodoc": "2.0.0",
+    "@nestjs/cli": "11.0.24",
     "@nestjs/schematics": "11.1.0",
     "@nestjs/testing": "11.1.28",
     "@swc/cli": "0.8.1",
@@ -147,7 +147,7 @@
     "@types/express": "5.0.6",
     "@types/lodash": "4.17.24",
     "@types/multer": "2.2.0",
-    "@types/node": "25.9.1",
+    "@types/node": "26.1.1",
     "@types/nodemailer": "8.0.1",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.10",
@@ -158,7 +158,7 @@
     "nodemon": "3.1.14",
     "npm-watch": "0.13.0",
     "otpauth": "9.5.1",
-    "oxfmt": "0.51.0",
+    "oxfmt": "0.59.0",
     "oxlint": "1.74.0",
     "rimraf": "6.1.3",
     "ts-node": "10.9.2",
@@ -167,7 +167,7 @@
     "tus-js-client": "4.3.1",
     "typescript": "5.9.3",
     "unplugin-swc": "1.5.9",
-    "vite": "8.1.4",
+    "vite": "8.1.5",
     "vite-plugin-node": "8.0.0",
     "vitest": "4.1.10"
   },

package/src/core/modules/ai/README.md

@@ -273,9 +273,7 @@ export class FindUsersAiTool extends AiTool {
     // Routes through CrudService with the caller's serviceOptions → permissions apply.
     const users = await this.userService.find(
       {
-        filterQuery: {
-          /* … */
-        },
+        filterQuery: {/* … */},
       },
       context.serviceOptions,
     );

package/src/core/modules/better-auth/README.md

@@ -297,13 +297,14 @@ const localConfig = {
 - **Graceful Degradation**: If auto-detection fails (no baseUrl), Passkey is disabled with a warning - other auth methods (Email/Password, 2FA) continue to work
 
 **Auto-Detection Resolution:**
-| Value | Priority | Source |
-|-------|----------|--------|
-| `baseUrl` | 1. Explicit `betterAuth.baseUrl` → 2. Root-level `baseUrl` → 3. Localhost default (env: 'local') |
-| `appUrl` | 1. Root-level `appUrl` → 2. Derived from `baseUrl` (removes `api.` prefix) → 3. Localhost default |
-| `rpId` | 1. Explicit `passkey.rpId` → 2. Auto-detect from appUrl hostname |
-| `origin` | 1. Explicit `passkey.origin` → 2. Auto-detect from appUrl |
-| `trustedOrigins` | 1. Explicit `trustedOrigins` → 2. Auto-detect from appUrl |
+
+| Value            | Priority                                                                                          | Source |
+| ---------------- | ------------------------------------------------------------------------------------------------- | ------ |
+| `baseUrl`        | 1. Explicit `betterAuth.baseUrl` → 2. Root-level `baseUrl` → 3. Localhost default (env: 'local')  |
+| `appUrl`         | 1. Root-level `appUrl` → 2. Derived from `baseUrl` (removes `api.` prefix) → 3. Localhost default |
+| `rpId`           | 1. Explicit `passkey.rpId` → 2. Auto-detect from appUrl hostname                                  |
+| `origin`         | 1. Explicit `passkey.origin` → 2. Auto-detect from appUrl                                         |
+| `trustedOrigins` | 1. Explicit `trustedOrigins` → 2. Auto-detect from appUrl                                         |
 
 ### Explicit Passkey Configuration (Advanced)