@lenne.tech/nest-server 11.27.1 → 11.27.2

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-06-22 (v11.27.1)
+> Auto-generated from source code on 2026-06-22 (v11.27.2)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()

package/migration-guides/11.27.1-to-11.27.2.md

@@ -0,0 +1,191 @@
+# Migration Guide: 11.27.1 → 11.27.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | `scripts/check.mjs` no longer hides devDependency vulnerabilities for library packages. The audit step now runs the chain's own audit command verbatim (same scope / `--prod` flag / `--audit-level`) instead of a hardcoded `pnpm audit --prod --json`. Repo-internal tooling — no consumer impact. |
+| **Security** | 3 new / refreshed `pnpm.overrides` entries — `undici` range widened to `<7.28.0`, plus new entries for `piscina <4.9.3` and `@babel/core <7.29.6`. All transitive via the build/test toolchain. |
+| **Migration Effort** | 0 minutes (automatic) — `pnpm update` is enough. ~2 minutes optional to mirror the security overrides into your own project's `package.json`. |
+
+This is a **maintenance release**. No source-code or config changes are required.
+
+---
+
+## Quick Migration
+
+No code changes required.
+
+```bash
+# Update package
+pnpm add @lenne.tech/nest-server@11.27.2
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+
+# Re-run audit to confirm advisories cleared
+pnpm audit
+```
+
+---
+
+## What's New in 11.27.2
+
+### 1. Security overrides refreshed
+
+`pnpm.overrides` in this repo's `package.json` gained two new entries and
+widened one existing range. Every override targets a **fixed version** (per
+`.claude/rules/package-management.md` override rules — no `>=` / `^` / `~`):
+
+| Package | Override | Advisory | Pulled in via |
+|---------|----------|----------|---------------|
+| `undici` | `7.28.0` (was `7.25.0`) | Various CVEs `<7.28.0` (incl. high) | `@compodoc/compodoc > cheerio`, `better-auth` |
+| `piscina` | `4.9.3` *(new)* | High CVE in `piscina <4.9.3` | build/test toolchain |
+| `@babel/core` | `7.29.6` *(new)* | `@babel/core <7.29.6` advisory | `@compodoc/compodoc > @babel/preset-env` |
+
+#### Why your project may still see CVEs after upgrading
+
+`pnpm.overrides` is **scoped to the package that declares it**. The framework's
+overrides do **not** propagate into consumer projects' lockfiles. If your own
+`pnpm audit` flags `undici / piscina / @babel/core`, mirror the entries into
+your project's `package.json`:
+
+```jsonc
+// projects/api/package.json (or your project's package.json)
+"pnpm": {
+  "//overrides": {
+    "undici@>=7.0.0 <7.28.0": "Security: various CVEs <7.28.0 (incl. high) - transitive via @compodoc/compodoc>cheerio + better-auth",
+    "piscina@<4.9.3": "Security: high CVE in piscina <4.9.3 - transitive via the build/test toolchain",
+    "@babel/core@<7.29.6": "Security: @babel/core <7.29.6 advisory - transitive via @compodoc/compodoc>@babel/preset-env"
+  },
+  "overrides": {
+    "undici@>=7.0.0 <7.28.0": "7.28.0",
+    "piscina@<4.9.3": "4.9.3",
+    "@babel/core@<7.29.6": "7.29.6"
+  }
+}
+```
+
+After adding, run `pnpm install && pnpm audit && pnpm test`.
+
+### 2. `scripts/check.mjs` audit step is now chain-faithful
+
+The audit step in the `check.mjs` wrapper previously hardcoded
+`pnpm audit --prod --json` with a separate gate level extracted from the
+chain's `--audit-level` flag. For library packages where dev-only dependencies
+ship vulnerabilities, this **masked the vulnerabilities** that a bare
+`pnpm audit` would have surfaced — because `--prod` excludes devDependencies.
+
+The audit step now runs the **chain's own audit command verbatim** (same scope,
+same `--prod` flag if any, same `--audit-level` if any), only appending `--json`
+for the structured counts. The blocking gate becomes the command's own exit
+code, so `check` blocks **precisely when a bare `<auditCmd>` would** —
+never with a narrower scope than the chain.
+
+What this means in practice:
+
+- **Library packages** (this repo, plus any consumer that runs `pnpm audit` —
+  not `pnpm audit --prod` — in their `check` script) now see devDep vulns
+  surface in the wrapper run, matching what their bare audit command reports.
+- **Application packages** that use `pnpm audit --prod` keep the exact same
+  behaviour — their scope is unchanged.
+- The status header now shows the **full audit command** (e.g.
+  `audit: pnpm audit --audit-level=high`) instead of just `audit gate: high`,
+  so the gate is auditable at a glance.
+
+If your `check` chain has no audit step at all, the wrapper now correctly
+**skips** the audit phase (previously it ran a hardcoded one anyway).
+
+> **Consumer impact:** None unless you copied `scripts/check.mjs` into your
+> own project from 11.27.1. If you did, the upgrade fixes a silent gap in your
+> security gate — review the next `pnpm run check` for previously hidden
+> devDep findings.
+
+---
+
+## Breaking Changes
+
+None.
+
+---
+
+## Compatibility Notes
+
+- **`IServerOptions` / `CoreModule.forRoot()`:** unchanged.
+- **`FRAMEWORK-API.md`:** regenerated for the new version stamp only — no API
+  surface differences vs. 11.27.1.
+- **`config.env.ts`:** no new fields, no deprecations.
+- **Vendor-mode consumers:** nothing to sync. The override changes live in
+  `package.json` at the **repo root**, which is excluded from
+  `convertCloneToVendored`. The `scripts/check.mjs` wrapper also lives outside
+  `src/core/`, so vendor projects keep their existing `check` setup.
+- **Custom controllers / resolvers extending Core* classes:** no impact —
+  no Core method signatures changed.
+
+---
+
+## Verifying
+
+```bash
+# 1. Update + install
+pnpm add @lenne.tech/nest-server@11.27.2
+pnpm install
+
+# 2. Confirm advisories cleared (or only show unaffected residuals)
+pnpm audit
+
+# 3. Smoke-test the new check wrapper (only relevant in this repo)
+pnpm run check        # quiet, report-driven — audit now mirrors the chain
+pnpm run check:raw    # original chain, full noise
+
+# 4. Tests + build
+pnpm test
+pnpm run build
+```
+
+---
+
+## Troubleshooting
+
+### `pnpm audit` in my consumer project still reports `undici` / `piscina` / `@babel/core`
+
+Expected — `pnpm.overrides` is scoped to the declaring package. Mirror the
+entries listed under [Why your project may still see CVEs after upgrading](#why-your-project-may-still-see-cves-after-upgrading).
+
+### `pnpm run check` suddenly reports more vulnerabilities than 11.27.1
+
+Working as intended — the previous wrapper silently narrowed the audit to
+`--prod` scope. The new wrapper mirrors your chain's own audit command, so
+devDep vulnerabilities a bare `pnpm audit` would have flagged now appear in
+the wrapper run. Either:
+
+- Mirror the relevant overrides from this guide (recommended), or
+- Narrow your chain's audit command to `pnpm audit --prod --audit-level=high`
+  if devDep vulns are out of scope for your gate.
+
+### Audit step is skipped — "audit: none" in the header
+
+Your `check` chain has no audit step. Add `pnpm audit` (or
+`pnpm audit --prod --audit-level=high`) at the start of the chain in
+`package.json` to re-enable the gate.
+
+---
+
+## Module Documentation
+
+No module documentation changes in this release. Reference documentation:
+
+- **Package management rules:** [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version overrides only, never ranges
+- **Framework compatibility:** [`.claude/rules/framework-compatibility.md`](../.claude/rules/framework-compatibility.md) — what ships in the npm package
+
+---
+
+## References
+
+- [Migration Guide 11.27.0 → 11.27.1](./11.27.0-to-11.27.1.md) — Previous release (initial `scripts/check.mjs` introduction + 7 security overrides)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) — reference implementation

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.27.1",
+  "version": "11.27.2",
   "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",
@@ -192,7 +192,9 @@
       "minimatch@>=10.0.0 <10.2.5": "Security: RegExp DoS - transitive via @nestjs/apollo>ts-morph>@ts-morph/common and nodemon",
       "ajv@<6.14.0": "Security: prototype pollution - transitive via @getbrevo/brevo>rewire>eslint",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "Security: prototype pollution - transitive via @nestjs/cli>@angular-devkit",
-      "undici@>=7.0.0 <7.25.0": "Security: various CVEs - transitive via @compodoc/compodoc>cheerio",
+      "undici@>=7.0.0 <7.28.0": "Security: various CVEs <7.28.0 (incl. high) - transitive via @compodoc/compodoc>cheerio + better-auth",
+      "piscina@<4.9.3": "Security: high CVE in piscina <4.9.3 - transitive via the build/test toolchain",
+      "@babel/core@<7.29.6": "Security: @babel/core <7.29.6 advisory - transitive via @compodoc/compodoc>@babel/preset-env",
       "handlebars@>=4.0.0 <4.7.9": "Security: prototype pollution (GHSA-q42p-pg8m-cqh6) - transitive via @compodoc/compodoc",
       "brace-expansion@<1.1.13": "Security: RegExp DoS - transitive via eslint>minimatch",
       "brace-expansion@>=4.0.0 <5.0.6": "Security: RegExp DoS - Large numeric range defeats brace expansion (GHSA-jxxr-4gwj-5jf2) - transitive via nodemon>minimatch and @ts-morph/common>minimatch and @compodoc/compodoc>glob>minimatch",
@@ -225,7 +227,9 @@
       "minimatch@>=10.0.0 <10.2.5": "10.2.5",
       "ajv@<6.14.0": "6.14.0",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
-      "undici@>=7.0.0 <7.25.0": "7.25.0",
+      "undici@>=7.0.0 <7.28.0": "7.28.0",
+      "piscina@<4.9.3": "4.9.3",
+      "@babel/core@<7.29.6": "7.29.6",
       "handlebars@>=4.0.0 <4.7.9": "4.7.9",
       "brace-expansion@<1.1.13": "1.1.13",
       "brace-expansion@>=4.0.0 <5.0.6": "5.0.6",