@lenne.tech/nest-server 11.43.2 → 12.0.0

package/migration-guides/11.43.x-to-12.0.x.md

@@ -0,0 +1,828 @@
+# Migration Guide: 11.43.x → 12.0.x
+
+## Why this is a MAJOR
+
+Per `.claude/rules/versioning.md` the MAJOR digit mirrors NestJS and moves only when NestJS does. `12.0.0` is
+the release that targets **NestJS 12**. It carries the breaking changes of NestJS 12 and of its ecosystem
+packages, plus the TypeScript 6 upgrade NestJS 12's tooling requires. The framework's own API is unchanged:
+no `Core*` signature, decorator, config key or default changed in this release.
+
+**What every project has to do:** raise the NestJS family and TypeScript together with this package (§1), and
+make its `tsconfig.json` explicit for TypeScript 6 (§2). Everything else applies only if a project uses the
+specific feature: deep imports into `@nestjs/*/dist` (§3), the legacy `subscriptions-transport-ws` protocol
+or a playground config object (§4), a subclass that redeclares a constructor with optional dependencies (§5),
+a custom Terminus health indicator (§6), `@All()` routes in Swagger (§7), or Jest as test runner (§12).
+**Vendor-mode projects** additionally move their dev start and their migration bootstrap
+(`migrations-utils/ts-compiler.js`) from ts-node to the framework's loader (§14).
+
+**nest-server ships as an ES module, like every NestJS 12 package — and CommonJS projects stay CommonJS** (§17).
+ESM projects, what `nest new` generates since NestJS 12, are supported in npm and vendor mode. All NestJS 12 packages
+and nest-server ship as ESM only, but Node loads them from CommonJS through `require(esm)` (Node 20.19+ / 22.12+, unflagged). This package keeps `engines.node: ">= 22.15"`,
+which is above that floor, so nothing about the runtime requirement changes. The **CLI's generators** need more:
+`@nestjs/schematics` 12 (through the Angular devkit 22.2.3) requires Node **^22.22.3, ^24.15 or >= 26** for
+`nest new` / `nest generate` / `nest upgrade` — an older 22.x or 24.x runs the application and `nest build` fine,
+but `pnpm install` reports unsupported engines for those packages. The latest active LTS satisfies everything.
+
+## Overview
+
+| Category             | Details |
+| -------------------- | ------- |
+| **Breaking Changes** | NestJS 12 family required (§1). TypeScript 6 changes compiler defaults (`strict` on, `rootDir`, `types`) (§2). Deep imports into `@nestjs/*/dist` no longer resolve (§3). `subscriptions-transport-ws` removed, playground settings object removed (§4). A redeclared constructor no longer inherits its parent's `@Optional()` flags (§5). Terminus: legacy `HealthIndicator` API removed, a thrown indicator error is a 500 (§6). Vendor mode: ts-node can no longer load the core — the dev start (`nodemon.json`) and `migrations-utils/ts-compiler.js` must use the framework's loader (§14) |
+| **Behaviour changes** | `ConsoleLogger` prints objects after the message as structured params (§8). Lifecycle hooks run by component hierarchy level; the Express adapter drains in-flight requests on shutdown (§9). Swagger drops `SEARCH`/`QUERY` operations of `@All()` routes from OpenAPI 3.0 documents (§7). Duplicate `@Cron`/`@Interval`/`@Timeout` names fail the boot (§10). TypeScript migrations and `config.env.ts` are compiled with SWC instead of ts-node — the `migrate:*` scripts are unchanged, the project needs `@swc/core` (§14). A refused GraphQL WebSocket handshake closes with 4401 instead of 4500 (§4). Behaviour changes of NestJS 12.0.2 – 12.2.0 (§15). The framework's own log output goes through Nest's `Logger`, and `new ConfigService()` no longer prints the merged configuration (§16) |
+| **Bugfixes**         | `setupSwagger()` handles OpenAPI 3.2 `additionalOperations` (§7). The health check translates the deprecated `database.options.timeout` into Terminus' `.withTimeout()` (§6). Vendor mode: `migrate create` no longer writes migrations that import `@lenne.tech/nest-server` (it points them at the vendored core), and the migration runner no longer uses a relative dynamic `import()` that a source run cannot resolve (§2). Boot and shutdown logs are clean: the AI connection preference no longer triggers Mongoose's deprecated `new` option, the legacy-auth deprecation report appears once per application (it ran twice when `AuthModule.forRoot()` is both passed to `CoreModule.forRoot()` and imported), and an IAM migration-status read interrupted by the application closing is logged at debug level instead of as an ERROR. **IAM password routes accept a plaintext password everywhere** (§16): `/iam/two-factor/*`, `/iam/delete-user`, `/iam/verify-password` and `/iam/change-password` no longer refuse the right plaintext password — and `change-password` no longer stores a plaintext new password in a shape the next sign-in rejects. A reset mail never carries a relative link from an unusable `redirectTo` (§16). `loadLocalConfig` reads the project's `config.json` (it searched inside the package and merged too late), and `uploadFileToGridFS()` resolves a relative path against the calling migration (§17) |
+| **New features**     | `GraphQLUpload` exported from nest-server (§13). nest-server ships as an ES module like every `@nestjs/*` package — CommonJS projects load it through `require(esm)` and change nothing; ESM projects (`"type": "module"`) are supported in npm and vendor mode, including running TypeScript from source (§17) |
+| **Dependencies**     | See §1 |
+| **Migration Effort** | Moderate for a starter-based project: dependency bump, `tsconfig.json`, a grep for deep imports. Vendor mode adds the loader switch (§14) |
+
+## Quick Migration
+
+```bash
+# npm mode: raise the framework, then let the starter's sync script align the shared pins
+pnpm add @lenne.tech/nest-server@12.0.0
+pnpm run update          # raises every pin the project shares with nest-server (see §1)
+
+# make tsconfig.json explicit for TypeScript 6 (§2), then
+pnpm run build
+pnpm test
+
+# the migrate:* scripts now compile TypeScript with @swc/core (§14) — starter-based projects have it
+pnpm run migrate:list
+```
+
+Vendor-mode projects pick the core up through `/lt-dev:backend:update-nest-server-core`; §1 and §2 apply to their
+`package.json` and `tsconfig.json` all the same, because the vendored core is compiled with the project's own config.
+**Vendor mode also has to move off ts-node** (§14): ts-node cannot load the 12.0.0 core. That concerns the dev start
+(`nodemon.json`) and, in projects converted by an lt CLI up to 1.51.5, `migrations-utils/ts-compiler.js` — otherwise
+every `migrate:*` script fails:
+
+```bash
+# vendor mode, CommonJS project: the migration bootstrap becomes the core's loader
+echo "module.exports = require('../src/core/modules/migrate/helpers/ts-compiler.js');" > migrations-utils/ts-compiler.js
+```
+
+---
+
+## 1. Dependencies
+
+Raise every pin the project shares with nest-server **together with it**. A project that keeps
+`@nestjs/common` 11 next to nest-server 12 installs two copies of NestJS, and the build fails with type errors
+that look unrelated (`Class 'CronJobs' incorrectly extends base class 'CoreCronJobs'`).
+
+| Package | 11.43.x | 12.0.0 |
+|---------|---------|--------|
+| `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express`, `@nestjs/testing` | 11.2.7 | **12.2.0** |
+| `@nestjs/apollo`, `@nestjs/graphql` | 13.4.5 | **14.0.3** |
+| `@nestjs/jwt` | 11.0.2 | **12.0.3** |
+| `@nestjs/mongoose` | 11.0.4 | **12.0.0** |
+| `@nestjs/passport` | 11.0.5 | **12.0.0** |
+| `@nestjs/schedule` | 6.1.3 | **12.0.2** (there is no 7.x) |
+| `@nestjs/swagger` | 11.4.7 | **12.0.4** |
+| `@nestjs/terminus` | 11.1.1 | **12.1.0** |
+| `@nestjs/cli`, `@nestjs/schematics` | 11.0.24 / 11.1.0 | **12.0.10** |
+| `typescript` | 5.9.3 | **6.0.3** |
+| `express` | 5.2.1 | **5.3.0** (the version `@nestjs/platform-express` 12.2.0 pins) |
+| `ws` | 8.21.3 | **8.22.0** (the version `@nestjs/graphql` 14.0.3 pins) |
+| `graphql-ws` | 6.2.1 | **6.3.0** (the version `@nestjs/graphql` 14.0.3 pins) |
+| `multer` | 2.4.0 | **2.5.0** (GHSA-q7qp-rjg7-q26m, high — see "Security overrides" below) |
+| `dotenv` | 17.4.2 | **18.0.9** |
+| `ejs` | 6.0.1 | **7.0.2** |
+| `nodemailer` | 10.1.2 | **10.2.1** (three `addressparser` advisories) |
+| `mongoose` | 9.11.2 | **9.11.4** |
+| `better-auth`, `@better-auth/core`, `@better-auth/passkey` | 1.7.7 | **1.7.12** — the **peer range** moves to `>=1.7.12 <1.8.0` (was `>=1.7.7 <1.8.0`), in lockstep with `@lenne.tech/nuxt-extensions`; the project owns the version, api and app must resolve the same one. 1.7.12 verifies JWTs with the algorithm of the stored key. nest-server's own tests run on **1.7.13** (inside the range; a type-declaration fix, no security change), so a project may take it together with its app, but does not have to |
+| `vitest`, `@vitest/coverage-v8` (dev) | 4.1.12 | **5.0.5** (§12) |
+| `vite` (dev) | 8.3.4 | **8.3.4** — deliberately not 8.3.5 while vitest is 5.0.5 (§12) |
+| `oxlint` / `oxfmt` (dev) | 1.88.0 / 0.73.0 | **1.89.0 / 0.74.0** |
+| `@swc/core` (dev) | 1.16.18 | **1.16.20** — also what the TypeScript loader now compiles with (§14) |
+
+`pnpm run update` in a starter-based project applies the table: it raises a pin the project already declares to
+the framework's version when that is newer (`extras/sync-packages.mjs`). It never adds a package.
+
+**`dotenv` 18 and `ejs` 7** are majors, but only matter if a project uses what they removed: dotenv 18 drops the
+`-r dotenv/config` preload, `.env.vault` support and the `dotenv/lib/cli-options` / `lib/env-options` subpaths
+(`dotenv.config({ … })` is unchanged); ejs 7 no longer reads render options from the **data** object, which only
+`ejs.render(str, data)` / `ejs.renderFile()` ever did — nest-server's `TemplateService` uses `ejs.compile(src)(data)`
+and is unaffected.
+
+### Security overrides
+
+`overrides:` in `pnpm-workspace.yaml` apply only to the ROOT project of an install, so nest-server's entries do
+not reach a consumer's tree (`docs/security-overrides.md`). Two of them are load-bearing again with the NestJS 12
+pins, so mirror them:
+
+```yaml
+# pnpm-workspace.yaml of the project
+overrides:
+  # @nestjs/platform-express 12.2.0 exact-pins multer 2.4.0 (GHSA-q7qp-rjg7-q26m, fixed 2.5.0)
+  'multer@>=2.0.0 <2.5.0': '2.5.0'
+  # @nestjs/graphql 14.0.3 exact-pins @graphql-tools/utils 12.0.1 (GHSA-c4qx-w738-7hr3, fixed 12.0.2)
+  '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'
+```
+
+An entry the project already carries for one of them must have its key and target raised — a target below the
+fix pins the vulnerable version in place. Three more advisories of the same weeks need no override, only a
+lockfile refresh: `pnpm update --depth Infinity body-parser fast-uri zod`. **But a project that already carries
+an entry for `body-parser` or `fast-uri`** (starter-based projects do) must raise it, for the same reason:
+
+```yaml
+  'body-parser@>=2.0.0 <2.4.0': '2.4.0'   # was '<2.3.0': '2.3.0' — GHSA-27r3-jxmh-p828, high
+  'fast-uri@<3.1.9': '3.1.9'              # was '<3.1.8': '3.1.8' — four advisories up to moderate
+```
+
+`pnpm run check:overrides`, where a project has it, reports each of these as `TOO LOW`. A mirrored
+`@nestjs/cli>webpack` entry can go (see below).
+
+**TypeScript 7 is not an option yet.** `@nestjs/graphql` 14 and `@nestjs/swagger` 12 declare `typescript`
+`^5.5.0 || ^6.0.0` as peer, and `@nestjs/schematics` 12 requires `>=6.0.0` — 6.0.x is the only line both accept.
+
+**Overrides.** A project that mirrors nest-server's `@nestjs/cli>webpack` override can remove it: `@nestjs/cli` 12
+no longer depends on webpack (it is an optional peer there), and with it the `browserslist@<4.28.7` entry, whose
+package left the tree together with webpack. A `ws` or `js-yaml` override can go too: `@nestjs/graphql` 14 and
+`@nestjs/swagger` 12 pin patched versions (`ws` 8.22.0, `js-yaml` 5.5.0) themselves. A `ws` entry that stays must
+target **8.22.0**: pnpm rewrites `graphql-ws`'s `ws` peer range to the override target, so an entry still targeting
+8.21.3 makes `pnpm peers check` report `unmet peer ws — Installed: 8.22.0, Wanted: 8.21.3 (graphql-ws@6.3.0)`.
+nest-server itself now carries only the two entries below; see `docs/security-overrides.md`.
+
+---
+
+## 2. TypeScript 6 — make `tsconfig.json` explicit
+
+TypeScript 6 changes several compiler **defaults**. A tsconfig that relied on them compiles differently, or not at
+all, without a single line of source having changed:
+
+| Default | TypeScript 5.9 | TypeScript 6 | Symptom |
+|---------|----------------|--------------|---------|
+| `strict` | `false` | **`true`** | hundreds of `TS2322` / `TS18048` errors (`Type 'null' is not assignable…`, `…is possibly 'undefined'`) |
+| `rootDir` | common directory of the inputs | **directory of the tsconfig** | `TS5011 The common source directory … is './src'. The 'rootDir' setting must be explicitly set` — or, where the error does not fire, output moves from `dist/main.js` to `dist/src/main.js` |
+| `types` | every `@types/*` package | **`[]`** | `Cannot find name 'process'` / `'Buffer'` |
+| `moduleResolution` with `module: commonjs` | `node10` | **`bundler`** | `exports` maps are now enforced at type level — deep imports fail (§3) |
+| explicit `moduleResolution: "node"` / `"node10"` | fine | **error** | `TS5107 Option 'moduleResolution=node10' is deprecated and will stop functioning in TypeScript 7.0` |
+
+The settings nest-server itself uses since 12.0.0 match the CommonJS template `nest new` generates for NestJS 12:
+
+```jsonc
+// tsconfig.json
+{
+  "compilerOptions": {
+    "module": "nodenext",            // was "commonjs"; emits CommonJS for a package.json without "type"
+    "moduleResolution": "nodenext",  // resolves exactly like Node, `exports` maps included
+    "resolvePackageJsonExports": true,
+    "strict": false,                 // TypeScript 6 turns it on by default
+    "types": ["node", "vitest/globals"],
+    // …the rest unchanged
+  }
+}
+```
+
+```jsonc
+// tsconfig.build.json — only when the build does not set it already
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": "./src" }   // keeps dist/main.js where `start:prod` expects it
+}
+```
+
+A project whose build already sets `rootDir` (the starter uses `"./"` and starts `dist/src/main.js`) keeps it.
+
+### What `nodenext` changes beyond resolution
+
+Two things are worth knowing before switching, both visible in the emitted JavaScript:
+
+- **A dynamic `import()` stays a native `import()`** in the CommonJS output (under `module: commonjs` TypeScript
+  rewrote it to `require()`). It therefore follows ESM rules, and a package with separate CommonJS and ESM
+  builds is loaded as its **ESM build**. **Avoid relative dynamic imports altogether**: no specifier works
+  everywhere — `tsc` output needs `./x.js`, while a source run of a CommonJS project turns the `import()` into a
+  `require()`, which ts-node does not map from `.js` to `.ts` without `experimentalResolver`. Use a static import,
+  or move what a cycle needs into a module of its own; nest-server's own source has no relative dynamic import (guarded by
+  `tests/unit/module-format-invariants.spec.ts`). Do not mix a lazy `import()` and a
+  static import of the same dual package in one process: the two builds are two module instances, and an
+  `instanceof` across them fails. nest-server's own lazy imports (`ioredis`, `bullmq`, `@aws-sdk/*`,
+  `@modelcontextprotocol/sdk`, `@getbrevo/brevo`) are lazy everywhere, so each loads one build.
+- **`esModuleInterop` is always on** (TypeScript 6 refuses `false`). `import * as x from 'cjs-package'` now
+  compiles to `__importStar(require('cjs-package'))` — a namespace object that COPIES the module's properties
+  instead of being the module itself. A namespace import that is *called* (`express()`) becomes a type error;
+  switch it to a default import. One that is *used as a value* compiles without an error and is the wrong object at
+  runtime: `import * as GraphQLUpload from 'graphql-upload/GraphQLUpload.js'` with `type: () => GraphQLUpload` is no
+  longer a `GraphQLScalarType`, and the boot fails with `Cannot determine a GraphQL input type for the "file"` (§13).
+  `import x = require('cjs-package')` keeps the plain `require()` and is unaffected — in a CommonJS project; it is not
+  valid in an ES module (§17).
+
+**Test files** run through vitest, which resolves like a bundler (extensionless relative imports, the `import`
+condition). If `tsc` over the tests complains about missing extensions on `await import('../src/…')`, give the
+test tsconfig `"module": "preserve", "moduleResolution": "bundler"` — that is what nest-server's
+`tsconfig.tests.json` does, and it describes the resolver the tests actually run under.
+
+**Minimal alternative.** Keeping `module: commonjs` and only adding `"strict": false` (plus `rootDir` / `types`
+where needed) also compiles under TypeScript 6 — it then resolves with `bundler` semantics (see the table) and
+keeps the old dynamic-import emit. `"ignoreDeprecations": "6.0"` silences TS5107 for an explicit `node10`, but
+TypeScript 7 removes that resolution mode entirely; treat it as a stopgap, not a target.
+
+**Vendor mode.** The vendored core is compiled with the project's tsconfig. It compiles — declarations
+included — under the `nodenext` settings above, under the minimal alternative, and under TypeScript 5.9 with
+`module: commonjs` (verified 2026-10-24; nest-server's `check` now runs a `module: commonjs` type-check of
+`src/` for exactly this). It contains no relative dynamic `import()`, so it also runs from source (§14).
+
+---
+
+## 3. Deep imports into `@nestjs/*` no longer resolve
+
+The NestJS 12 packages declare `exports` maps. A path that is not listed there fails at runtime with
+`ERR_PACKAGE_PATH_NOT_EXPORTED`, and — under `nodenext` or `bundler` resolution — at compile time with `TS2307`.
+
+| Package | What still resolves |
+|---------|---------------------|
+| `@nestjs/common`, `@nestjs/core`, `@nestjs/platform-express` | the root and any subpath (`./*`), e.g. `@nestjs/common/constants`, `@nestjs/core/router/route-path-factory` |
+| `@nestjs/graphql` | the root, `@nestjs/graphql/plugin`, and explicit file paths (`./*`) |
+| `@nestjs/swagger` | the root and `@nestjs/swagger/plugin` |
+| `@nestjs/jwt`, `@nestjs/mongoose`, `@nestjs/passport`, `@nestjs/schedule`, `@nestjs/terminus` | **the root only** |
+
+```bash
+# find what needs changing
+grep -rnE "from '@nestjs/(jwt|mongoose|passport|schedule|swagger|terminus)/" src tests
+```
+
+What nest-server changed, as examples of the replacements:
+
+```typescript
+// Before (11.x)
+import type { JwtSignOptions } from '@nestjs/jwt/dist/interfaces/index.js';
+import type { MongoosePingCheckSettings } from '@nestjs/terminus/dist/health-indicator/database/mongoose.health.js';
+import type { EnumAllowedTypes } from '@nestjs/swagger/dist/interfaces/schema-object-metadata.interface.js';
+
+// After (12.0)
+import type { JwtSignOptions } from '@nestjs/jwt';
+import type { MongoosePingCheckSettings } from '@nestjs/terminus';
+type EnumAllowedTypes = NonNullable<ApiPropertyOptions['enum']>;   // not exported at the root — derive it
+```
+
+Internals that are not exported at all (`@nestjs/passport`'s `defaultOptions` and `memoize`) have to be inlined.
+
+---
+
+## 4. GraphQL: `subscriptions-transport-ws` and the playground are gone
+
+`@nestjs/graphql` 14 removed the unmaintained `subscriptions-transport-ws` transport. `graphql-ws` is the only
+subscription protocol, and `CoreModule` no longer configures the old one.
+
+- **Clients** that still speak the legacy `graphql-ws` *subprotocol* — Apollo Client 2, or anything built on the
+  `subscriptions-transport-ws` package — can no longer subscribe. Move them to the `graphql-transport-ws`
+  protocol (the `graphql-ws` client library).
+- **Server config** that passes `graphQl.driver.subscriptions['subscriptions-transport-ws']` is now ignored
+  without an error. Remove it; put `onConnect` etc. under `'graphql-ws'`. A custom `onConnect` must still call
+  `registerWsConnection()` to keep the open-socket re-check (unchanged since 11.42.3).
+- **A refused handshake is closed with 4401 Unauthorized** (missing, expired or unknown token). Until 12.0.0
+  `CoreModule`'s `onConnect` threw, which graphql-ws's ws adapter answers with **4500** and the log line
+  "Internal error occurred during message handling. Please check your implementation." plus a stack trace — in
+  production too, for every expired token. The graphql-ws client retries neither code, so reconnect behaviour is
+  unchanged; only a client that inspected `4500` must look for `4401`. A custom `onConnect` should refuse the same
+  way: `return refuseWsHandshake(extra.socket, 'reason')` (exported) — returning plain `false` closes with 4403,
+  which the client RETRIES with the same refused credential.
+
+The **GraphQL Playground** was removed too. GraphiQL is the built-in IDE and is enabled by default outside
+production. `playground: true | false` still works as a deprecated alias; the settings **object** form is
+rejected:
+
+```typescript
+// Before
+graphQl: { driver: { playground: envName !== 'production' } }
+
+// After — same behaviour, current option name
+graphQl: { driver: { graphiql: envName !== 'production' } }
+```
+
+---
+
+## 5. `@Optional()` on a redeclared constructor
+
+NestJS 11 read the optional-dependency markers with `Reflect.getMetadata`, which returns the nearest class in the
+prototype chain that has any. A subclass that **redeclared its constructor** without a single `@Optional()` took
+over its parent's optional *indices* — whatever its own parameters at those positions were.
+
+NestJS 12 (12.1+) reads them from the class whose constructor is actually called:
+
+| Subclass | NestJS 11 | NestJS 12 |
+|----------|-----------|-----------|
+| no constructor of its own | inherits parameters and their `@Optional()` | **same** |
+| own constructor, own `@Optional()` | uses its own | **same** |
+| own constructor, **no** `@Optional()` | inherited the parent's indices | **nothing is optional** — a missing provider throws `UnknownDependenciesException` |
+
+```typescript
+// Before — worked in 11.x only because CoreXService marks index 2 optional
+@Injectable()
+export class XService extends CoreXService {
+  constructor(configService: ConfigService, emailService: EmailService, mapper?: SomeMapper) {
+    super(configService, emailService, mapper);
+  }
+}
+
+// After — mark it where the constructor is declared
+constructor(configService: ConfigService, emailService: EmailService, @Optional() mapper?: SomeMapper) {
+```
+
+`nest-server-starter` is not affected: every subclass there that redeclares a constructor either marks its
+optional parameters itself or extends a class without optional ones. `tests/unit/optional-dependency-inheritance.spec.ts`
+pins all three rows. (NestJS 12.0.x inherited no flags at all; 12.1 restored them for constructor-less subclasses,
+and nest-server pins 12.2.0.)
+
+---
+
+## 6. Health check (Terminus 12)
+
+`CoreHealthCheckService` and its config are unchanged for projects. What changed underneath:
+
+- The deprecated `HealthIndicator` base class, `getStatus()` and the error classes (`HealthCheckError`, …) are
+  removed. A **custom** indicator in a project must use `HealthIndicatorService`:
+  `this.healthIndicatorService.check(key).up(data)` / `.down(data)`, or `.attempt(fn)` for "up unless it throws".
+- An error **thrown** inside an indicator is now a **500**, not a 503. Only a returned `down` result marks the
+  check unhealthy.
+- The `timeout` option on the database indicator is deprecated in favour of `.withTimeout(ms)`. nest-server
+  translates `healthCheck.configs.database.options.timeout` (default 300 ms) into `.withTimeout()` itself, so the
+  config keeps working after Terminus drops the option.
+- The Mongoose indicator now pings the database instead of reading `readyState`; results carry `responseTime`,
+  and an indicator may report `degraded` (HTTP 200).
+- **Use Terminus 12.1.0 or later.** 12.0.0 leaks memory in `attempt().withTimeout()` (nestjs/terminus#2767) —
+  exactly the path nest-server's database check uses. nest-server pins 12.1.0; a project that pins Terminus itself
+  must not stay on 12.0.x.
+
+---
+
+## 7. Swagger (`@nestjs/swagger` 12)
+
+- **`@All()` routes.** Swagger 12 emits `@All()` handlers for `search` and `query` as well, and normalises the
+  document: in an OpenAPI **3.0** document (the default) the methods outside the fixed path-item set are
+  dropped — 11.x wrote a bare `search` key, which no OpenAPI version allows. In a **3.2** document
+  (`setupSwagger(app, { configureBuilder: (b) => b.setOpenAPIVersion('3.2.0') })`) `QUERY` is a regular method
+  and `SEARCH` goes into `additionalOperations`. `setupSwagger()` enriches those like every other operation
+  (API-token line, tenant header) and keeps them in the API-token view.
+- **Nullable schemas** are spelled per document version: `nullable: true` in 3.0 documents (also for responses,
+  which emitted `oneOf … type: 'null'` before), type unions / `anyOf … null` in 3.1+. Snapshot tests of the
+  document need updating.
+- `lodash` is no longer a dependency of `@nestjs/swagger` — only relevant if a project relied on it arriving
+  transitively.
+
+---
+
+## 8. Logger output (`ConsoleLogger`)
+
+`ConsoleLogger` now treats plain objects after the message as **structured params of the same entry**
+(`logger.log('User created', { userId: 1 })`); in JSON mode they are nested under `params`. Before, each was
+printed as a separate line. Log parsers that split on that behaviour need adjusting, or opt out with
+`new ConsoleLogger({ structuredParams: false })`. The Hub's log capture is unaffected — it records the raw
+arguments, not the formatted line.
+
+---
+
+## 9. Lifecycle hooks and shutdown
+
+- `onModuleInit`, `onApplicationBootstrap` and the shutdown hooks are called **by component hierarchy level**.
+  The order between providers that depend on each other can change. nest-server's own initializers do not rely
+  on a cross-module order, and its whole suite passes unchanged, but review project hooks that assumed one.
+- The Express adapter **drains in-flight requests** on shutdown. `installGracefulShutdown(app)` and
+  `shutdownDelayMs` work as before (the graceful-shutdown e2e suite covers them against real Redis and S3).
+- HTTP error mapping in the adapters was reworked upstream; nest-server's exception filters and every status-code
+  assertion in its suite are unchanged.
+
+---
+
+## 10. `@nestjs/schedule` 12
+
+Two `@Cron` / `@Interval` / `@Timeout` declarations with the **same explicit name** now fail at startup
+(`DUPLICATE_SCHEDULER`) instead of conflicting later. `CoreCronJobs` is not affected (it does not use those
+decorators); a project that does should check its names.
+
+---
+
+## 11. `nest build`: an asset glob for a missing directory fails
+
+`@nestjs/cli` 12 (the `glob` package left in 12.0.0) matches asset patterns itself, and returns the literal base
+of a pattern like `assets/**` even when `src/assets` does not exist — and then fails:
+
+```
+Error  An error occurred during the assets copying process. ENOENT: no such file or directory, stat '…/src/assets'
+```
+
+Remove the entry from `nest-cli.json` → `compilerOptions.assets`, or create the directory. Patterns with a
+wildcard in the last segment (`**/*.json`) are not affected. Every `nest build` / `nest start` runs this code —
+including a project whose `build` uses `tsc`: the starter builds with `tsc`, but its `start:dev:swc` and
+`start:local:swc` call `nest start`, and its `nest-cli.json` lists `templates/**` without a `src/templates`
+directory. For a directory that exists only in some layouts, end the pattern with a wildcard segment —
+`templates/**/*` builds whether `src/templates` exists or not (verified with CLI 11.0.24 and 12.0.10), and still
+copies it where it does; the starter keeps it that way, because in vendor mode the lt CLI puts the core's mail
+templates there. Remove entries whose directory never exists.
+
+---
+
+## 12. Test runners
+
+- **vitest** (the starter's runner) works with NestJS 12 unchanged. nest-server itself moved to **vitest 5.0.5**
+  (with `@vitest/coverage-v8` 5.0.5), and `pnpm run update` raises a project's vitest pins to it as well. vitest 5
+  requires Node 22.12+ and Vite 6.4+, and changes test behaviour in ways a suite can notice:
+  - **mocks are cleared before every test** (`clearMocks` on by default) — a test that counted calls a mock
+    received in a `beforeAll` or in a previous test now sees zero;
+  - **an asynchronous assertion that is not awaited fails the test** (`expect(p).rejects…` without `await`);
+  - `vi.mock()` / `vi.hoisted()` outside the top level of a file **throw** instead of being hoisted;
+  - the `sequential` test/suite option is gone (use `concurrent: false`), `-t` uses `>` between suite and test
+    names, and the config file is no longer looked up in parent directories;
+  - `disableConsoleIntercept` still exists and still prevents the `Closing rpc while "onUserConsoleLog" was
+    pending` teardown error described in nest-server's `.claude/rules/testing.md`.
+
+  - **keep `vite` at 8.3.4 with vitest 5.0.5.** vitest 5.0.5 evaluates `globalSetup` and reporter modules as a
+    Buffer, and Vite 8.3.5 calls `code.charCodeAt()` on it while mapping a stack trace — from then on reading the
+    `.stack` of any error in the vitest MAIN process throws `TypeError: code.charCodeAt is not a function`, and the run
+    exits 1 after every test passed (here: the MongoDB driver's monitor while the DB reporter closes its connection).
+    vitest-dev/vitest#11682, fixed upstream but not in 5.0.5. A project with a `globalSetup` or its own reporter that
+    does not pin `vite` resolves 8.3.5 on a fresh install — add `"vite": "8.3.4"` to its devDependencies.
+
+  nest-server's suites (3706 unit + 1994 e2e tests, its custom DB-lifecycle reporter and the mutation gate that
+  parses vitest's summary) needed no change beyond the `vite` pin (guarded by `tests/unit/toolchain-compat.spec.ts`).
+  Keep vitest 4 by not raising the pin if a project's suite needs time.
+- **Jest 30** loads ESM-only packages only on **Node 24.9+**; older versions fail with `ERR_REQUIRE_ASYNC_MODULE`.
+  Run the tests on Node 24.9+ or move to vitest.
+- **AWS Lambda** disables `require(esm)` on its Node 20/22/24 runtimes — set
+  `NODE_OPTIONS=--experimental-require-module`.
+
+---
+
+## 13. GraphQL uploads: import the `Upload` scalar from nest-server (new)
+
+`@lenne.tech/nest-server` now exports `GraphQLUpload`. Use it instead of importing the scalar from
+`graphql-upload` yourself:
+
+```typescript
+// Before — breaks as soon as nest-server moves graphql-upload to another major
+import GraphQLUpload = require('graphql-upload/GraphQLUpload.js');
+
+// Before — BROKEN under TypeScript 6 (§2): tsc compiles it without an error, the boot then fails with
+// "Cannot determine a GraphQL input type for the "file"". nest-server's own CoreFileResolver used this form up to
+// 11.43.3 (so does a core vendored from it); a project built, tested or started through tsc, ts-node or ts-jest
+// must switch. The lt CLI generates the import in the right form for the installed framework.
+import * as GraphQLUpload from 'graphql-upload/GraphQLUpload.js';
+
+// After
+import { GraphQLUpload } from '@lenne.tech/nest-server';
+
+@Mutation(() => FileInfo)
+async uploadFile(@Args({ name: 'file', type: () => GraphQLUpload }) file: FileUpload) { … }
+```
+
+Why it matters: the scalar accepts a value only if it is `instanceof Upload` of **its** copy of graphql-upload,
+and the `Upload` instances come from the multipart middleware `CoreModule` installs — nest-server's copy. With two
+copies every upload is refused. graphql-upload's import paths also change across majors (15: `GraphQLUpload.js`,
+16+: `GraphQLUpload.mjs`), so a direct import ties the project to nest-server's choice of major. A project that no
+longer imports `graphql-upload` anywhere can drop it from its own `package.json`.
+
+## 14. TypeScript sources: SWC instead of ts-node
+
+`dist/core/modules/migrate/helpers/ts-compiler.js` — the file every `migrate:*` script names in
+`--compiler ts:…` — no longer registers ts-node. It is now a small CommonJS `require` hook that compiles `.ts` /
+`.cts` with **SWC** (`@swc/core`), with the options of the `tsc` build: target `es2022`, legacy decorators with
+`design:*` metadata, define semantics for class fields, class names kept. Path, file name and the
+`--compiler ts:<file>` contract are unchanged, so **the scripts need no edit**. nest-server's own dev start,
+`docs:ci` and the migrate CLI's source fallback run through the same file, and ts-node left its devDependencies.
+
+**What a project needs:** `@swc/core` as devDependency, resolvable from the project directory. Starter-based
+projects have had it since NestJS 10 (vitest's `unplugin-swc` and `nest start -b swc` use it). nest-server
+declares it as an optional peer (`>=1.10.0 <2`), so `pnpm peers check` reports an incompatible version. Without
+it the loader stops with `Running TypeScript sources needs @swc/core … pnpm add -D @swc/core`.
+
+**Why:** ts-node is unmaintained (10.9.2, December 2023). Under TypeScript 6 it fails on options it inherits from
+the project (`TS5011` without `rootDir`, `TS5107` for its bundled `node` resolution, `TS5110` for `commonjs` on a
+`nodenext` config), and it type-checks what it loads on every start. Measured 2026-10-24 (Node 24.12) to "Server
+started": nest-server's own dev server, which compiles the whole framework from source, 13.5 s → 3.7 s; the starter,
+which loads the framework from `dist/`, 4.8 s → 3.4 s. It also depends on
+TypeScript's JavaScript API, which TypeScript 7 (now `latest` on npm) no longer ships in that form. The same holds
+for `@swc-node/register` (peer `typescript <7`), which is why the framework did not switch to it. The SWC loader
+does not touch TypeScript at all.
+
+**What you give up:** the source run checks no types — a type error no longer stops `migrate up` or the dev
+server. `tsc` (`pnpm run build`, `check`) and the IDE report it as before. Where checking while watching matters,
+`nest start -b swc -w --type-check` (the starter's `start:local:swc`) does it; note that `@nestjs/cli`'s SWC
+defaults use `useDefineForClassFields: false`, unlike the `tsc` build and this loader. ES modules (`"type": "module"`, `.mts`) are
+supported through Node module hooks the loader registers (§17). Not supported: tsconfig `paths` (the starter has
+none) and a project `.swcrc` (ignored on purpose).
+
+**The dev start: REQUIRED in vendor mode, optional in npm mode.** The 12.0.0 core writes every relative import as
+`./x.js` (§17), and ts-node does not map `./x.js` to `x.ts` — not even with `TS_NODE_EXPERIMENTAL_RESOLVER`. A
+vendor-mode project, which runs the core from source, therefore fails at `pnpm start` with
+`Error: Cannot find module './core.module.js'` (or another `.js` file of the core) as long as nodemon starts ts-node —
+while `build` and the tests pass. Switch the dev start to the loader:
+
+```jsonc
+// nodemon.json
+{ "exec": "node -r ./src/core/modules/migrate/helpers/ts-compiler.js src/main.ts" }        // vendor mode
+{ "exec": "node -r ./node_modules/@lenne.tech/nest-server/dist/core/modules/migrate/helpers/ts-compiler.js src/main.ts" } // npm mode
+// nodemon-debug.json: the same with node --inspect-brk -r … — the same path in CommonJS and ESM projects (§17)
+```
+
+Keep a `-r tsconfig-paths/register` the command carried, if the project declares `paths`. Replace the other
+`ts-node <file>.ts` scripts that load the core (`docs:ci`, `start:nodemon`) with `node -r <same path> <file>.ts`. The
+lt CLI does this when it converts a project to vendor mode with a 12.0.0+ core; a project already in vendor mode that
+takes the core update needs the edit above. In npm mode the core comes compiled from `dist/`, so ts-node keeps working
+there — switching is optional and saves the type check on every start.
+
+**The migration bootstrap: REQUIRED in vendor mode.** The `migrate:*` scripts of a vendor-mode project name
+`--compiler ts:./migrations-utils/ts-compiler.js`, a file the lt CLI writes once when it converts the project. Up to
+lt CLI 1.51.5 that file registers ts-node, which fails on the 12.0.0 core like the dev start does:
+`Cannot find module '../migration.helper.js'` (the old helper path forwards to the moved helper, §17), or `TS5110` /
+`TS5011` before that when `tsconfig.json` is `nodenext` (§2) — ts-node reads it. Point the file at the core's loader:
+
+```js
+// migrations-utils/ts-compiler.js (CommonJS project)
+module.exports = require('../src/core/modules/migrate/helpers/ts-compiler.js');
+```
+
+The scripts themselves stay as they are: the CLI requires this file and calls its export, and the core's loader
+exports the same idempotent function. `lt fullstack update` of lt CLI 1.52.0 or newer replaces the file
+automatically while it is still the generated version; a file the project changed is left alone and needs the line
+above. In an ESM project, where this file would be an ES module, name the loader in the scripts directly:
+`--compiler ts:./src/core/modules/migrate/helpers/ts-compiler.js` — CommonJS in every project (§17).
+
+Remove `ts-node` from devDependencies only once nothing registers it any more — no script, no `nodemon*.json`, no
+`migrations-utils/ts-compiler.js` (`grep -rn ts-node package.json nodemon*.json migrations-utils/`) — and
+`tsconfig-paths` with it when `tsconfig.json` declares no `paths`.
+
+**Jest with ts-jest (vendor mode)** resolves `./x.js` to nothing as well. Map it:
+`moduleNameMapper: { '^(\\.{1,2}/.*)\\.js$': '$1' }` — or move to vitest (§12), which resolves it as it is.
+
+## 15. NestJS 12.0.2 – 12.2.0: changes a project can notice
+
+nest-server pins `@nestjs/*` 12.2.0. Beyond the 12.0.0 release, these patch and minor releases changed behaviour
+that a nest-server project can run into (from the NestJS release notes; microservice, Fastify and gateway changes
+omitted):
+
+| Since | Change | What to do |
+|-------|--------|------------|
+| 12.0.2 | An `Error` that merely carries a `statusCode` property is no longer treated as an HTTP error — it answers **500** (nestjs/nest#17709). Express's own body-parser errors are still mapped (malformed JSON → 400, too large → 413) | Throw `HttpException` subclasses from project code, not plain errors with a `statusCode` |
+| 12.2.0 | Multipart: `fieldNestingDepth` 32 and `fieldArrayIndexLimit` 1000 by default | Only deeply nested or very long form-field arrays are affected; raise them in the upload options |
+| 12.2.0 | Files uploaded with a request that a pipe rejected are removed from storage | Nothing — previously they were left behind |
+| 12.2.0 | Object error bodies are sent as `application/json` also on routes with a non-JSON `Content-Type` | A client that parsed such an error as text gets JSON |
+| 12.2.0 | `BaseExceptionFilter` answers `http-errors` errors with `expose: false` (the default from 500) with the standard reason phrase, not their message | Nothing for nest-server's filters |
+| 12.2.0 | A global enhancer the injector failed to instantiate now **fails the startup** | A boot that used to log and continue now stops — fix the enhancer |
+| 12.2.0 | `MiddlewareConsumer.exclude()` compiles excluded routes with the router's case and trailing-slash matching | Review exclusions that relied on the looser match |
+| 12.2.0 | `@nestjs/platform-express` 12.2.0 needs `@nestjs/core` 12.2.0: with an older core it does not load and the app stops with "No driver (HTTP) has been selected" (nestjs/nest#18251, fixed upstream, unreleased) | Keep every `@nestjs/*` pin in lockstep — `pnpm run update` does |
+| `@nestjs/passport` 12 | `getAuthenticateOptions()` changed its signature | Only for project guards that override it |
+| 12.x | Pipe `transform()` signatures refined; `ArgumentMetadata` is generic | Only project pipes with hand-written signatures — nest-server's pipes compile unchanged |
+
+## 16. Log output, IAM passwords and other corrections
+
+**Framework log output goes through Nest's `Logger`.** These wrote to `console` directly — no context, no respect
+for the application's log levels, JSON mode or a custom logger — and now use a `Logger` with the context shown:
+
+| Source | Context | Level |
+|--------|---------|-------|
+| `CoreCronJobs` (job registration, lease and BullMQ messages, shutdown wait) | `CronJobs` | as before (`log` for info, `warn`, `error` with the stack) |
+| `CoreModule.forRoot()` configuration warnings (equal JWT secrets, ignored overrides, unguarded Hub) | `CoreModule` | `warn` |
+| `HttpExceptionLogFilter` (the stack of each handled exception, with `logExceptions`) | `HttpExceptionLogFilter` | `debug` — still printed with Nest's default levels; hidden where a project narrows them |
+| `InMemoryRateLimitStore` capacity warning | `InMemoryRateLimitStore` | `warn` |
+| Better-Auth's own messages (failed sign-ins, refused CSRF attempts) | `BetterAuth` | as Better-Auth classifies them; its `level` filter still applies. A project's `betterAuth.options.logger` is merged over it, its own `log` handler wins |
+| AWS SDK warnings (e.g. "non-retryable streaming request" on an aborted upload) | `CoreS3Service` | `warn`; the SDK's debug/info/error stay silent as before |
+| Passkey auto-detection ("Using rpId=…") | `BetterAuthConfig` | **`log`** (was `warn`) — only "Passkey disabled" is still a warning |
+
+A project that filters its logs by these exact `console` lines must match the Nest format instead.
+
+**`new ConfigService(config)` no longer prints the configuration.** The constructor defaulted to `warn: true`, so
+every construction after the first — `CoreModule.forRoot()` running a second time in one process: tests, scripts,
+a second application — wrote the whole merged config, **secrets included**, to stdout. It now defaults to `false`
+like `setConfig()` and `mergeConfig()`; pass `{ warn: true }` for the dump while debugging.
+
+**IAM password routes accept a plaintext password everywhere.** Sign-in, sign-up and the reset routes normalized a
+plaintext password to sha256 (the shape every credential is stored in); the other native Better-Auth routes did
+not. A plaintext password was refused as "Invalid password" by `/iam/two-factor/enable`, `/disable`,
+`/generate-backup-codes`, `/get-totp-uri`, `/iam/delete-user` and `/iam/verify-password`, and
+`/iam/change-password` stored a plaintext `newPassword` unnormalized — the account was locked out at its next
+sign-in. nuxt-extensions hashes in the browser and was never affected; apps, scripts and API clients were. A new
+plaintext password on `change-password` is now also held to `minPasswordLength` / `maxPasswordLength`, like a
+reset. A password outside those bounds is answered with **400** and the bounds in the message — on the reset routes
+this refusal used to come back as a 500 "Authentication handler error" with an ERROR log line. A client that treated
+that 500 as "password rejected" should check for the 400. No other action needed; an already hashed password passes
+through unchanged.
+
+**The reset link ignores an unusable `redirectTo`.** A `redirectTo` that is neither an absolute http(s) URL nor a
+path starting with `/` (`'reset'`, or a template literal over an unset variable: `'undefined/reset'`) was mailed
+verbatim as a relative link that resolves nowhere. The mail now points at the default page,
+`<appUrl>/auth/reset-password`.
+
+**Smaller corrections:** the legacy-auth deprecation report appears once per application (it ran twice, with two
+status reads, when `AuthModule.forRoot()` is passed to `CoreModule.forRoot()` and imported again); a migration-status
+read interrupted by the application closing is logged at debug level; the AI connection preference no longer uses
+Mongoose's deprecated `new: true` option (a `[MONGOOSE] Warning` on every call); `CoreBetterAuthMiddleware` is bound
+with path-to-regexp 8's `{*path}` instead of the legacy `(.*)`, which only worked through Nest's route converter.
+
+## 17. ES modules: nest-server is ESM, projects may be either (new)
+
+`nest new` generates ESM projects (`"type": "module"`) since NestJS 12, every `@nestjs/*` package ships as ESM only,
+and more and more other packages do too. **nest-server follows NestJS: since 12.0.0 the package is an ES module**
+(`"type": "module"`, one ESM build, no CommonJS build). **A CommonJS project changes nothing for that** — it loads
+nest-server through Node's `require(esm)` exactly as it already loads every `@nestjs/*` package (Node 20.19+ /
+22.12+; nest-server requires 22.15+).
+
+| Project | What it gets |
+|---------|--------------|
+| CommonJS, npm mode | unchanged: `require('@lenne.tech/nest-server')` / `import … from` compiled to `require()` returns all exports. Verified against the unchanged nest-server-starter: type check, all unit and e2e tests, build, `migrate:list`, production start |
+| ESM, npm mode | one module graph with NestJS: `import { CoreModule } from '@lenne.tech/nest-server'`. Packages that ship separate builds (`@apollo/server`, `graphql-ws`, `nodemailer`) are loaded once instead of twice |
+| vendor mode, either | the vendored core compiles with the project's own settings — as CommonJS in a CommonJS project, as ESM in an ESM project. nest-server's `check` proves both (`typecheck:vendor`, `check:esm`) |
+
+Paths projects reference stay where they are: `dist/core/modules/migrate/helpers/ts-compiler.js` (the loader of §14),
+`bin/migrate.js` (the `migrate` binary) and `dist/core/modules/migrate/templates/migration-project.template.ts`. The
+first two remain **CommonJS in every project** — `helpers/package.json` and `bin/package.json` declare
+`"type": "commonjs"` for their directory — so `--compiler ts:…/ts-compiler.js`, `node -r …/ts-compiler.js` and the
+loader's function export work as before, in CommonJS and ESM projects alike. The migration helpers moved from
+`migrate/helpers/migration.helper` to `migrate/migration.helper`; the old path forwards, so a
+`migrations-utils/migrate.js` that requires it keeps working.
+
+**What a CommonJS project may notice:** the same as for NestJS 12 itself — Jest needs Node 24.9+ to load ESM packages
+(§12), and AWS Lambda needs `NODE_OPTIONS=--experimental-require-module`. Nothing beyond that: if `@nestjs/core`
+loads, nest-server loads.
+
+**Deployment is unchanged.** The starter's Docker image, its entrypoint (migrations, then `node dist/…/main.js`) and
+the way TurboOps and Kubernetes start it do not depend on the module format. Verified with the starter image, as
+CommonJS and as ESM project: compiled migrations ran from the entrypoint, the container reported healthy and
+`/health-check` answered 200.
+
+### Converting a project to ESM (optional)
+
+Worth it when a project needs a package that only loads from an ES module (one with top-level `await`, which
+`require(esm)` refuses with `ERR_REQUIRE_ASYNC_MODULE`), or to match what `nest new` generates. lt CLI 1.52.0 or newer
+converts the api project with `lt server convert-esm` (npm and vendor mode; `--dry-run` shows the changes first);
+these are the steps it takes, measured on a copy of nest-server-starter:
+
+1. `"type": "module"` in `package.json`; `tsconfig.json`: `"module": "nodenext"`, `"moduleResolution": "nodenext"`,
+   `"isolatedModules": true`.
+2. Every relative import names the emitted file: `./x.js`, `./dir/index.js` — including dynamic `import()`.
+   [`ts2esm`](https://www.npmjs.com/package/ts2esm) does the static ones (run it after step 1, otherwise it asks
+   about a bundler).
+3. `import x = require('pkg')` becomes `import x from 'pkg'`; a JSON import gets `with { type: 'json' }`;
+   `__dirname` / `__filename` become `import.meta.dirname` / `import.meta.filename`; a file that must load another
+   file synchronously uses `createRequire(import.meta.url)`.
+4. `migrations-utils/*.js` become ES modules (`import { createMigrationStore } from '@lenne.tech/nest-server'`,
+   `export default createMigrationStore(…)`) — the migrate CLI reads the default export. **Vendor mode:** the store
+   must not `import` the vendored core. The migrate CLI loads the store with `require()`, and `require()` of an ES
+   module does not run the loader's ESM hooks, so `import … from '../src/core/index.js'` fails with
+   `Cannot find module …/src/core/index.js` in development. Require the helper instead — the loader's require hook
+   compiles it in development, and in the image the same line loads the compiled helper:
+
+   ```js
+   // migrations-utils/migrate.js — vendor mode, ESM project
+   import { createRequire } from 'node:module';
+
+   const require = createRequire(import.meta.url);
+   const { createMigrationStore } = require('../src/core/modules/migrate/migration.helper');
+
+   export default createMigrationStore(/* the MongoDB URI and collection name, as before */);
+   ```
+
+   The scripts name the core's loader directly (`--compiler ts:./src/core/modules/migrate/helpers/ts-compiler.js`,
+   §14) instead of `migrations-utils/ts-compiler.js`, which would be an ES module now.
+5. A type used in a decorated signature that is not a class (`ServiceOptions`, `FileUpload`, `CoreModelConstructor`)
+   moves to `import type` — `isolatedModules` reports each one as `TS1272`. Never do this for a class whose type
+   drives dependency injection.
+6. **A named import of a CommonJS package that Node cannot see.** ESM learns a CommonJS module's names by static
+   analysis, which misses some: `import { Connection } from 'mongoose'` and `import { cloneDeep } from 'lodash'` fail
+   with `does not provide an export named …`. Use `import type` for a type, the default import for a value. **The
+   tests do not show this** — vitest is more lenient than Node; on the starter all 489 tests passed and the
+   production start failed. Start the built server (`check:server-start`) after converting.
+7. **Import cycles.** A decorated property or constructor parameter whose type comes from a module on an import
+   cycle (two models that reference each other) reads that class while the cycle is still loading. CommonJS reads
+   `undefined` and carries on; ESM throws `ReferenceError: Cannot access 'X' before initialization` at start-up. Type
+   such a declaration as `WrapperType<X>` (exported by nest-server, NestJS's name for it) — the decorator keeps the
+   real type through its thunk:
+
+   ```typescript
+   @UnifiedField({ type: () => User })
+   owner?: WrapperType<User>;
+   ```
+
+   Our own projects carry between 2 and 11 import cycles each; only those with a decorated declaration on them fail.
+8. The dev start keeps `node -r …/helpers/ts-compiler.js src/main.ts` (§14): the loader compiles ES modules too,
+   including decorators, `.js` specifiers and JSON import attributes, which Node's own type stripping cannot.
+
+### Tests: vitest must resolve like Node
+
+Add to every vitest config of the project (unit and e2e):
+
+```ts
+resolve: { extensions: ['.js', '.mjs', '.mts', '.ts', '.jsx', '.tsx', '.json'] },
+```
+
+graphql declares an extensionless `main: "index"` next to an `index.mjs`. Node loads `index.js`; Vite probes `.mjs`
+first and loads a SECOND, ESM copy of graphql for every `import` it resolves itself — the vendored core in vendor
+mode, and any test that imports graphql. Schema objects from one copy are refused by the other: subscriptions close
+with 4500, and the server log says "Cannot use GraphQLSchema from another module or realm". The order above is Vite's
+default with `.js` moved before `.mjs`.
+
+### Corrected along the way
+
+Two settings a project may have relied on without them ever working:
+
+- **`loadLocalConfig`** loaded its file with an `import()` relative to the config helper's own directory: `true`
+  searched `dist/core/common/helpers` (inside `node_modules` in npm mode) instead of the project, and the merge landed
+  after the configuration had been returned. Now `true` reads `config.json` from the working directory, then
+  `src/config.json`; a path resolves against the working directory (`.json` as JSON, anything else as a module, its
+  default export used); the merge happens before `getEnvironmentConfig()` returns. A project that set
+  `loadLocalConfig` and has such a file gets its values applied for the first time — check what is in it.
+- **`uploadFileToGridFS(url, relativePath)`** resolved a relative path against the helper's own directory, inside
+  `node_modules/@lenne.tech/nest-server/dist` in npm mode. It now resolves against the calling migration's directory,
+  and falls back to the helper's directory when the file is not there, so a migration written for the old anchoring
+  keeps working.
+
+### Lint (optional, recommended)
+
+NestJS 12's template lints with `oxlint --type-aware` and
+`typescript/no-floating-promises: "error"`; nest-server does the same since 12.0.0 (`oxlint-tsgolint` as a
+devDependency). An un-awaited promise's rejection is unhandled, and Node ends the process on that by default. The
+rule found eight places in nest-server; one could actually reject — stopping a cron job from the Hub while its tick
+was still running, now logged instead. Type-aware mode also turns on
+every other type-aware rule of the enabled categories; under `strict: false` most of them only report "requires
+strictNullChecks" or flag deliberate idioms, so nest-server switches those off by name (see its `.oxlintrc.json`).
+
+---
+
+## Not in this release, on purpose
+
+| Package | Stays at | Why |
+|---------|----------|-----|
+| `graphql-upload` | 15.0.2 | 16+ exports only `.mjs` paths, so every project importing `GraphQLUpload.js` would break with no way to prepare under 11.x. 17.1.0 follows in **12.1.0**, once projects import the scalar from nest-server (§13) — then it changes nothing for them. 18 requires graphql 17 |
+| `undici` | 7.30.1 (still patched) | undici 8 replaces the global dispatcher of Node's built-in `fetch` as soon as it is loaded: afterwards a plain `fetch(url, { method: 'POST', headers: { 'Content-Length': '0' } })` anywhere in the process fails with `UND_ERR_INVALID_ARG` (reproduced on Node 24.12 with 8.12.3). nest-server would bring that into every project's process. 8 also requires Node ≥ 22.19 |
+| `graphql` 17 | 16.14.2 | `@apollo/server` 5 and `graphql-subscriptions` 3 peer `^16` only |
+| `typescript` 7 | 6.0.3 | `@nestjs/graphql` 14 and `@nestjs/swagger` 12 peer `^5.5 \|\| ^6` |
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| CommonJS project (`package.json` without `"type": "module"`) | works unchanged — it loads the ESM package through `require(esm)`, as it does every `@nestjs/*` package. Switching the project to ESM is optional (§17) |
+| ESM project (`"type": "module"`), npm or vendor mode | supported (§17) |
+| `CoreModule.forRoot(envConfig)` / the three-argument legacy form | unchanged |
+| Extending `Core*` services, resolvers, controllers | unchanged, except §5 |
+| `class X extends AuthGuard('…') {}` without a constructor | works (§5, first row) |
+| GraphQL subscriptions over `graphql-ws`, tenant context on the WebSocket, open-socket re-check | unchanged |
+| `setupSwagger()` | unchanged API; see §7 for the document |
+| `healthCheck` config | unchanged (§6) |
+| `nest start -b swc` / `check:swc-tdz` | unchanged |
+| `migrate:*` scripts with `--compiler ts:…/helpers/ts-compiler.js` | unchanged scripts; the file compiles with `@swc/core` now (§14) |
+| Vendor mode: `migrate:*` scripts with `--compiler ts:./migrations-utils/ts-compiler.js` | unchanged scripts; the file must load the core's loader instead of ts-node (§14) |
+| Compiled migrations in the production image (`dist/migrations`, no `--compiler`) | unchanged — no TypeScript loader involved |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Hundreds of `TS2322` / `TS18048` after the upgrade | TypeScript 6 turned `strict` on | `"strict": false` (§2) |
+| `TS5011 … The 'rootDir' setting must be explicitly set` | TypeScript 6 `rootDir` default | set `rootDir` (§2) |
+| `node dist/main.js` → `Cannot find module` | output moved to `dist/src/` | set `rootDir` (§2) |
+| `TS5107 Option 'moduleResolution=node10' is deprecated` | explicit `"moduleResolution": "node"` | `nodenext` (§2) |
+| `Cannot find name 'process'` | TypeScript 6 `types: []` default | add `"node"` to `types` (§2) |
+| `TS2307 Cannot find module '@nestjs/…/dist/…'` or `ERR_PACKAGE_PATH_NOT_EXPORTED` | deep import (§3) | import from the package root |
+| `TS2835 Relative import paths need explicit file extensions` | relative dynamic `import()` under `nodenext` | a static import (§2); bundler resolution for test files (§2) |
+| `Class 'X' incorrectly extends base class 'CoreX'` | two copies of a NestJS package | align the pins (§1), `pnpm run update` |
+| `Nest can't resolve dependencies of the XService (…, ?)` | §5 | `@Optional()` on the redeclared constructor |
+| Subscriptions never connect from an old client | legacy protocol (§4) | `graphql-ws` client |
+| Every GraphQL upload fails with `Upload value invalid.` | the scalar and the multipart middleware come from two graphql-upload copies | `import { GraphQLUpload } from '@lenne.tech/nest-server'` (§13) |
+| Boot fails with `Cannot determine a GraphQL input type for the "file"` although `tsc` passed | `import * as GraphQLUpload from 'graphql-upload/…'` — TypeScript 6 wraps it in `__importStar` (§2) | `import { GraphQLUpload } from '@lenne.tech/nest-server'` (§13) |
+| `ENOENT … stat '…/src/assets'` (or `…/src/templates`) during `nest build` / `nest start` | §11 | remove the asset entry or create the directory |
+| `No driver (HTTP) has been selected` at startup | `@nestjs/platform-express` 12.2.0 next to an older `@nestjs/core` (§15) | align all `@nestjs/*` pins, `pnpm run update` |
+| WebSocket closed with `4401` | the handshake's token authenticates nobody (§4) | sign in again; was `4500` before 12.0.0 |
+| `Invalid password` from `/iam/two-factor/enable` (or `/delete-user`, `/change-password`) with the right password, on 11.x | the route did not normalize a plaintext password (§16) | fixed in 12.0.0; on 11.x send the sha256 of the password |
+| Log lines of cron jobs, Better-Auth or the exception filter look different | they go through Nest's `Logger` now (§16) | match the Nest format (`[Nest] … [CronJobs] …`) |
+| Jest: `ERR_REQUIRE_ASYNC_MODULE` | §12 | Node 24.9+ or vitest |
+| Vendor mode: `pnpm start` fails with `Cannot find module './core.module.js'` (or another `.js` of the core) | nodemon still starts ts-node, which does not map `.js` to `.ts` (§14) | `node -r ./src/core/modules/migrate/helpers/ts-compiler.js src/main.ts` in `nodemon.json` (§14) |
+| Vendor mode, Jest: `Cannot find module './….js' from 'src/core/…'` | ts-jest does not map `.js` to `.ts` (§14) | `moduleNameMapper` (§14) or vitest |
+| Vendor mode: every `migrate:*` fails with `Cannot find module '../migration.helper.js'` (or another `.js` of the core) | `migrations-utils/ts-compiler.js` still registers ts-node (§14) | `module.exports = require('../src/core/modules/migrate/helpers/ts-compiler.js');` in that file (§14) |
+| Vendor mode: `TS5110` / `TS5011` / `TS5107` from a `migrate:*` script | the ts-node bootstrap in `migrations-utils/ts-compiler.js` reads the project's `tsconfig.json` (§14) | the same one-line bootstrap (§14) |
+| ESM vendor-mode project: `migrate:*` fails with `Cannot find module …/src/core/index.js` | `migrations-utils/migrate.js` imports the vendored core; the migrate CLI's `require()` does not run the loader's ESM hooks (§17, step 4) | load the helper with `createRequire(import.meta.url)` (§17, step 4) |
+| `Running TypeScript sources needs @swc/core, which this project does not have` | a `migrate:*` script or `node -r …/ts-compiler.js` in a project without `@swc/core` (§14) | `pnpm add -D @swc/core` |
+| Tests only: subscriptions close with `4500`, log says `Cannot use GraphQLSchema from another module or realm` | vitest loaded a second, ESM copy of graphql (§17) | `resolve.extensions` in Node's order in every vitest config (§17) |
+| ESM vendor-mode project: `require is not defined in ES module scope` from `bin/migrate.js` | the project's `bin/` lacks the `package.json` that keeps the migrate binary CommonJS (§17) | copy `bin/package.json` (`{ "type": "commonjs" }`) next to `bin/migrate.js` |
+| CommonJS project, Jest: `ERR_REQUIRE_ESM` / `ERR_REQUIRE_ASYNC_MODULE` for `@lenne.tech/nest-server` | Jest loads ES modules from CommonJS only on Node 24.9+ — the same applies to `@nestjs/*` (§12) | Node 24.9+ or vitest |
+| ESM project: `ReferenceError: Cannot access 'X' before initialization` at start-up | a decorated declaration on an import cycle (§17, step 7) | type it as `WrapperType<X>` |
+| `The requested module 'x' does not provide an export named 'y'` in an ESM project | a named import of a CommonJS package Node cannot detect (§17, step 6) | `import type` for a type, otherwise the default import: `import x from 'x'`, then `x.y` |
+| Values from `config.json` suddenly apply | `loadLocalConfig` reads the project's file now (§17) | review the file, or remove `loadLocalConfig` |
+| Dev server starts although the code has a type error | the SWC loader strips types without checking them (§14) | `pnpm run build` / the IDE report it; `nest start -b swc -w --type-check` checks while watching |
+
+## Module Documentation
+
+### Health Check
+
+- **Key Files:** `src/core/modules/health-check/core-health-check.service.ts` (indicator wiring, timeout translation)
+
+### Auth (Legacy)
+
+- **README:** [src/core/modules/auth/README.md](../src/core/modules/auth/README.md)
+- **Key Files:** `src/core/modules/auth/guards/auth.guard.ts` (the passport defaults are inlined, §3)
+
+### GraphQL WebSocket wiring
+
+- **Key Files:** `src/core.module.ts` (the three driver builders, `'graphql-ws'` only), `src/core/common/helpers/graphql-ws-connection.helper.ts`
+
+### Swagger
+
+- **Key Files:** `src/core/common/helpers/swagger.helper.ts` (`operationsOf()`, `additionalOperations`)
+
+## References
+
+- [NestJS v12 migration guide](https://docs.nestjs.com/migration-guide)
+- [TypeScript 6.0 release notes](https://devblogs.microsoft.com/typescript/announcing-typescript-6-0/)
+- Release notes: [@nestjs/graphql 14.0.0](https://github.com/nestjs/graphql/releases/tag/v14.0.0),
+  [@nestjs/swagger 12.0.0](https://github.com/nestjs/swagger/releases/tag/12.0.0),
+  [@nestjs/terminus 12.0.0](https://github.com/nestjs/terminus/releases/tag/12.0.0),
+  [@nestjs/passport 12.0.0](https://github.com/nestjs/passport/releases/tag/12.0.0)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)