@lenne.tech/nest-server 11.31.3 → 11.32.1

package/docs/REQUEST-LIFECYCLE.md

@@ -214,6 +214,7 @@ JWT-based authentication for existing projects:
 | **Error Code Module** | Centralized error registry with unique IDs |
 | **Permissions Report** | Interactive HTML dashboard, JSON, and Markdown reports |
 | **Hub (Operator Cockpit)** | Build-free ADMIN-gated dashboard at `/hub` (config-gated per environment). Adds an optional HTTP trace middleware (registered by `CoreHubModule.configure()` only when traces are enabled), a chaining `Logger.overrideLogger()` delegate for the log buffer, an optional `EmailService` capture hook (`HUB_EMAIL_CAPTURE` token) for the mailbox, and — when the query profiler is enabled — opts the MongoDB driver into `monitorCommands` from `core.module.ts`. See `src/core/modules/hub/README.md`. |
+| **Process Diagnostics** | Opt-in process-level exit diagnostics (`installProcessDiagnostics()` + `handleFatalBootstrapError`, `src/core/common/helpers/process-diagnostics.helper.ts`). Wired into `main.ts` — **NOT** into `CoreModule.forRoot()`, because it must run before `NestFactory.create()` and installs a `process.exit(1)` path that must never arm inside `Test.createTestingModule()`. Logs unhandled rejections without crashing (configurable), uncaught exceptions before the exit, non-zero exit codes, and labels SIGTERM/SIGINT/SIGHUP/SIGQUIT as external terminations. Pair with `server.enableShutdownHooks()` — see the helper docblock |
 | **System Setup Module** | Initial admin creation for fresh deployments |
 | **Cron Jobs** | `CoreCronJobsService` with timezone/UTC offset support |
 | **Model Documentation** | Auto-generated model docs via `ModelDocService` |

package/docs/brevo-manual-test.md

@@ -0,0 +1,166 @@
+# Brevo: manual test against the real API
+
+> **Framework repo only.** This page ships inside the npm package (because `docs/**` is in
+> `package.json` `files`), but the things it tells you to run do **not**: `scripts/` and
+> `.env.example` are excluded from the tarball, and `src/config.env.ts` is a path that only exists
+> in this repository. If you are reading this from
+> `node_modules/@lenne.tech/nest-server/docs/`, clone
+> [lenneTech/nest-server](https://github.com/lenneTech/nest-server) to follow along. For configuring
+> Brevo in *your* project, see the `brevo` block in `FRAMEWORK-API.md` instead.
+
+The unit spec (`src/core/common/services/brevo.service.spec.ts`) covers `BrevoService` against a
+mocked SDK. That proves the logic, not the wire format. This guide is the one-off manual check
+against the **live** Brevo endpoint — worth running once after an SDK upgrade, and any time you
+suspect a credential or sender problem.
+
+> Every send here costs one transactional email from your Brevo quota and really lands in a mailbox.
+
+## 1. Get the credentials
+
+| What                | Where to get it                                                                                          |
+| ------------------- | -------------------------------------------------------------------------------------------------------- |
+| **API key**         | <https://app.brevo.com/settings/keys/api> → *Generate a new API key*. Starts with `xkeysib-`.              |
+| **Verified sender** | <https://app.brevo.com/senders/list> → *Add a sender*, then confirm the mail Brevo sends to that address.  |
+| **Template ID**     | *(optional)* <https://app.brevo.com/templates/listing> → open a template, the numeric ID is in the URL.    |
+
+Two pitfalls, both of which produce a confusing failure:
+
+- **Use the API v3 key, not the SMTP key.** Brevo issues two kinds of credential on neighbouring
+  settings pages. The REST API — which `BrevoService` talks to — only accepts a key starting with
+  **`xkeysib-`**. A key starting with `xsmtpsib-` is the SMTP password for `smtp-relay.brevo.com`
+  and is rejected by every `api.brevo.com/v3/*` endpoint with `401 {"message":"Key not found"}`.
+- **The sender address must be verified in Brevo.** An unverified sender is the most common cause
+  of a send that fails with HTTP 400 despite a valid key.
+
+To check a key in isolation before spending a send, hit an endpoint that takes no payload:
+
+```bash
+curl -s -w '\nHTTP %{http_code}\n' -H "api-key: $BREVO_API_KEY" https://api.brevo.com/v3/account
+```
+
+`HTTP 200` plus your account JSON means the key is good; `401 "Key not found"` means it is the
+wrong kind of key or belongs to a deleted account.
+
+## 2. Put them in `.env`
+
+`src/config.env.ts` calls `dotenv.config()` at import time, so a `.env` in the repo root is picked
+up by both the server and the smoke script. There is no `.env` in the repo — create one from the
+template:
+
+```bash
+cp .env.example .env
+```
+
+Then set these four keys in `.env`. `EMAIL_DEFAULT_SENDER` is already an **active** line in the
+template; `EMAIL_DEFAULT_SENDER_NAME`, `BREVO_API_KEY`, `BREVO_SMOKE_TO` and
+`BREVO_SMOKE_TEMPLATE_ID` are there as comments — uncomment and fill them in:
+
+```dotenv
+# API key from app.brevo.com/settings/keys/api
+BREVO_API_KEY=xkeysib-your-real-key
+
+# Sender - must be a VERIFIED sender in Brevo
+EMAIL_DEFAULT_SENDER=noreply@your-verified-domain.tld
+EMAIL_DEFAULT_SENDER_NAME=Nest Server Manual Test
+
+# Recipient for the smoke script - a mailbox you can actually open
+BREVO_SMOKE_TO=you@your-mailbox.tld
+
+# Optional: only needed for the template send in step 3b
+# BREVO_SMOKE_TEMPLATE_ID=12
+```
+
+`.env` is git-ignored — never commit real keys.
+
+Config-wise this is all that is needed: `config.env.ts` only builds the `brevo` block **when
+`BREVO_API_KEY` is set** (`...(process.env.BREVO_API_KEY ? { brevo: {...} } : {})`). Without the
+key there is no `brevo` config, `BrevoService` refuses to construct, and everything falls back to
+SMTP.
+
+## 3. Run the smoke script
+
+```bash
+pnpm exec tsx scripts/brevo-smoke.ts
+```
+
+It builds a real `ConfigService` + `BrevoService` (no mocks, no Nest bootstrap) and sends through
+the same code path the server uses.
+
+### 3a. What you should see
+
+```
+[brevo-smoke] sender:    Nest Server Manual Test <noreply@your-verified-domain.tld>
+[brevo-smoke] recipient: you@your-mailbox.tld
+[brevo-smoke] sending HTML mail via sendHtmlMail() ...
+[brevo-smoke] sendHtmlMail result: { messageId: '<2026...@smtp-relay.mailin.fr>' }
+[brevo-smoke] OK - check the recipient mailbox and https://app.brevo.com/transactional/email/logs.
+```
+
+A `messageId` means Brevo accepted the mail. Confirm it twice:
+
+1. The mail arrives in the recipient mailbox (check spam on the first run).
+2. It shows up under **Transactional → Logs**: <https://app.brevo.com/transactional/email/logs>.
+
+### 3b. Also test a template (optional)
+
+Templates are what `sendMail()` uses in production (e.g. BetterAuth email verification via
+`betterAuth.emailVerification.brevoTemplateId`). Set `BREVO_SMOKE_TEMPLATE_ID` in `.env` and re-run
+— the script then additionally calls `sendMail(to, templateId, { smokeTestStamp })`. Put
+`{{ params.smokeTestStamp }}` somewhere in the template body to see the parameter substitution
+land.
+
+Note: template parameters only substitute when the template uses Brevo's **New Template Language**.
+Old-language templates silently ignore `params`.
+
+### 3c. Reading a failure
+
+`BrevoService` catches SDK errors, logs them and returns `null` — so the script prints the full
+error object above a `result: null`. The status code tells you which knob is wrong:
+
+| Status                       | Cause                                                                        |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| **401 Unauthorized**         | `BREVO_API_KEY` wrong, revoked, or from a different Brevo account.            |
+| **400 Bad Request**          | Usually an unverified sender, or an invalid/foreign `templateId`.            |
+| **402 Payment Required**     | Free-plan daily quota exhausted.                                              |
+| **`result: 'TEST_USER!'`**   | The recipient matched `config.brevo.exclude` — nothing was sent (see step 5). |
+
+A quick way to confirm the wiring without spending a send: run it with a bogus key. You should get
+a clean 401 from `https://api.brevo.com/v3/smtp/email` — which proves client construction, request
+build and error handling all work:
+
+```bash
+BREVO_API_KEY=xkeysib-invalid BREVO_SMOKE_TO=smoke@test.com \
+  EMAIL_DEFAULT_SENDER=noreply@test.com pnpm exec tsx scripts/brevo-smoke.ts
+```
+
+## 4. End-to-end through the server (optional)
+
+To test the path a real feature takes rather than the service in isolation, use BetterAuth's email
+verification, which is the framework's built-in `BrevoService` consumer
+(`core-better-auth-email-verification.service.ts:180`):
+
+1. In `src/config.env.ts`, set `betterAuth.emailVerification.brevoTemplateId` to your template ID
+   for the `local` environment.
+2. Start the server: `pnpm run start:local`.
+3. Sign up a user with an address you can read — the verification mail is sent through Brevo
+   instead of SMTP.
+
+If `brevoTemplateId` is unset or `BrevoService` is unavailable, the flow silently uses the SMTP
+transport instead — so seeing an SMTP mail is the expected signal that the Brevo overlay is *not*
+active.
+
+## 5. The `exclude` guard
+
+`config.brevo.exclude` is a `RegExp` that suppresses sends to matching addresses (returns the
+string `'TEST_USER!'` instead). It is unset by default and the smoke script deliberately does not
+set one. If you add one to `config.env.ts` for local work, remember the recipient you are testing
+with must **not** match it, or nothing will be sent.
+
+Note for maintainers: the guard is read from `configService.config`, never from
+`configFastButReadOnly`. A deep-frozen `RegExp` carrying the `g` flag throws on `.test()` because
+the call assigns `lastIndex`. The unit spec pins this behaviour.
+
+## 6. Clean up
+
+Remove the real key from `.env` when you are done, or delete the file. Revoke the key in Brevo if
+it was created only for this test.

package/docs/security-overrides.md

@@ -0,0 +1,90 @@
+# Security Overrides — and why yours are not inherited
+
+## The problem in one sentence
+
+**pnpm `overrides:` apply only to the ROOT project of an install.** The overrides declared in
+`@lenne.tech/nest-server`'s own `pnpm-workspace.yaml` therefore do **not** travel with the published
+package. Your project resolves its own dependency tree with *your* overrides — which, by default,
+are none.
+
+A green `pnpm audit` inside the framework repo says nothing about your tree.
+
+## What this concretely means for you
+
+The framework pulls in two transitive packages that resolve to a **vulnerable** version unless you
+override them yourself:
+
+| Package | Advisory | Why it cannot resolve forward on its own |
+|---------|----------|------------------------------------------|
+| `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | `@nestjs/graphql` declares `"ws": "8.20.1"` — an **exact pin**, not a caret. No amount of updating moves it |
+| `@hono/node-server` | [GHSA-frvp-7c67-39w9](https://github.com/advisories/GHSA-frvp-7c67-39w9) (static-file path traversal) + [GHSA-9mqv-5hh9-4cgg](https://github.com/advisories/GHSA-9mqv-5hh9-4cgg) (unauthenticated memory leak). Patched `>=2.0.10` | `@modelcontextprotocol/sdk` declares `^1.19.9` and ships **no 1.x fix line**, so the fix is only available across a major |
+
+`@nestjs/graphql` is a plain `dependencies` entry, so `ws` is installed even when you run with
+`graphQl: false`. Neither package is optional in practice.
+
+## The fix
+
+Add this to your project's `pnpm-workspace.yaml` (pnpm 11+; in pnpm 10 and earlier it lives under
+`pnpm.overrides` in `package.json`):
+
+```yaml
+overrides:
+  # @nestjs/graphql exact-pins ws@8.20.1 (GHSA-96hv-2xvq-fx4p, high, patched >=8.21.0).
+  # An exact pin cannot resolve forward — the override is the only fix.
+  # Remove once @nestjs/graphql stops pinning it.
+  'ws@>=8.0.0 <8.21.0': '8.21.1'
+
+  # @modelcontextprotocol/sdk declares @hono/node-server ^1.19.9 with no 1.x fix line
+  # (GHSA-frvp-7c67-39w9, GHSA-9mqv-5hh9-4cgg). Deliberately a CROSS-MAJOR override.
+  # Verified safe: the SDK's only consumed symbol is `getRequestListener`, whose signature
+  # `(fetchCallback, options?)` is unchanged in 2.x. Engines >=20 and peer hono@^4 both fit.
+  # Remove once @modelcontextprotocol/sdk moves its own range to ^2.
+  '@hono/node-server@<2.0.10': '2.0.11'
+```
+
+Then:
+
+```bash
+pnpm install
+pnpm audit          # must report no known vulnerabilities
+pnpm test           # nothing should regress
+```
+
+Commit `package.json`/`pnpm-workspace.yaml` **and** `pnpm-lock.yaml` together.
+
+> Projects generated from `nest-server-starter` or `lt-monorepo` already carry both entries. This
+> page is for projects that predate that, or that were assembled by hand.
+
+## Rules for writing your own overrides
+
+These are the same rules the framework applies to itself
+(`.claude/rules/package-management.md`):
+
+1. **The target must be a fixed version.** Never `>=x`, `^x`, `~x`, `*`. An unbounded target lets
+   pnpm install the newest match, which can silently cross a major version. This is not
+   hypothetical — an override written as `'vite@>=7.0.0 <=7.3.1': '>=7.3.2'` resolved to `vite@8.0.8`
+   and broke peer dependencies across three packages.
+
+2. **Prefer a bounded key.** `'pkg@>=2.0.0 <2.1.2': '2.1.2'` leaves non-vulnerable versions alone
+   and limits the blast radius. `'pkg': '2.1.2'` replaces *every* version in the tree.
+
+3. **Floor the key inside the major you mean.** A key like `'brace-expansion@>=3.0.0 <5.0.7'` also
+   matches a future 3.x or 4.x dependency and would force it across two majors. Write `>=5.0.0`.
+
+4. **An override is a hard pin, not a floor.** pnpm replaces the whole matched spec with your
+   target. `'hono@>=4.0.0 <4.12.27': '4.12.27'` does not mean "at least 4.12.27" — it pins to
+   exactly that, holding the package back from later patches. Remove an override as soon as the
+   package resolves patched on its own; otherwise today's fix is tomorrow's downgrade-lock.
+
+5. **Document each entry**: the advisory, which package pulls the vulnerable version in, and the
+   condition under which the entry can be deleted.
+
+6. **Verify it is load-bearing.** Resolve a lockfile with the entry removed. If the package still
+   lands on a patched version, the override is inert — keep it only deliberately, and re-check it
+   every maintenance run.
+
+## Related
+
+- [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version
+  policy, the pnpm pin contract, and the incident behind rule 1
+- `pnpm-workspace.yaml` in this package — the framework's own annotated override block

package/migration-guides/11.31.3-to-11.32.0.md

@@ -0,0 +1,254 @@
+# Migration Guide: 11.31.3 → 11.32.0
+
+## Overview
+
+| Category | Change | Effort |
+|----------|--------|--------|
+| **Breaking** | `@getbrevo/brevo` upgraded 3.x → 6.x — three public SDK symbols no longer exist | 5 min *(only if you import them)* |
+| **Breaking** | `BrevoService` now logs failures via the Nest `Logger` instead of `console.error` | 0 min *(unless you assert on stdout)* |
+| **Security** | pnpm `overrides:` do **not** reach your project — two entries you must add yourself | 5 min |
+| **New** | `installProcessDiagnostics()` / `handleFatalBootstrapError()` — make a silent crash diagnosable | 5 min *(opt-in, two lines in `main.ts`)* |
+| **New** | `server.enableShutdownHooks()` recommendation — without it a container hangs on `docker stop` | 1 min |
+| **New** | `brevo.maxRetries`, `brevo.timeoutInSeconds`, `brevo.throwOnError` config | 0 min *(safe defaults)* |
+| **Changed** | The Brevo SDK is now imported lazily — faster cold start for everyone not using Brevo | 0 min |
+
+**Why MINOR and not PATCH:** `@getbrevo/brevo` is a direct `dependencies` entry of this package, so
+`pnpm update` pulls v6 into your tree. Its v3 symbols are gone. Per
+[`.claude/rules/versioning.md`](../.claude/rules/versioning.md), a breaking change increments MINOR.
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+pnpm run build   # surfaces the Brevo symbol removals, if any apply to you
+```
+
+If the build is clean and you do not use `BrevoService`, you are done — but please still read
+[Security: add two overrides](#security-add-two-overrides), which applies to every project.
+
+---
+
+## Breaking Changes
+
+### 1. `@getbrevo/brevo` 3.x → 6.x: three symbols removed
+
+v6 is a full rewrite around a `BrevoClient` facade. These no longer exist:
+
+| Removed in v6 | Replacement |
+|---------------|-------------|
+| `TransactionalEmailsApi` | `BrevoClient` (`client.transactionalEmails.*`) |
+| `TransactionalEmailsApiApiKeys` | `new BrevoClient({ apiKey })` |
+| `SendSmtpEmail` | `Brevo.SendTransacEmailRequest` |
+
+**Before**
+
+```typescript
+import { SendSmtpEmail, TransactionalEmailsApi, TransactionalEmailsApiApiKeys } from '@getbrevo/brevo';
+
+const api = new TransactionalEmailsApi();
+api.setApiKey(TransactionalEmailsApiApiKeys.apiKey, apiKey);
+
+const mail: SendSmtpEmail = { templateId, to: [{ email }] };
+const result = await api.sendTransacEmail(mail);
+return result.body;                       // <- v3 wrapped the payload in an envelope
+```
+
+**After**
+
+```typescript
+import { BrevoClient } from '@getbrevo/brevo';
+import type { Brevo } from '@getbrevo/brevo';
+
+const client = new BrevoClient({ apiKey });
+
+const request: Brevo.SendTransacEmailRequest = { templateId, to: [{ email }] };
+return await client.transactionalEmails.sendTransacEmail(request);   // <- payload directly
+```
+
+**The awaited data shape is unchanged.** v3's `.body` was `{ messageId?, messageIds? }`; v6's
+awaited result is `SendTransacEmailResponse`, which is the same shape. Only the envelope is gone.
+If you need the raw HTTP response, v6 offers `.withRawResponse()`.
+
+**The thrown error type changed** from an axios-shaped `{ response, body }` to
+`BrevoError { statusCode, body, rawResponse, requestId }`. Adjust any `catch` block that reached
+into `error.response`.
+
+> If you only ever call `BrevoService`, nothing changes for you — its method signatures and return
+> values are unchanged.
+
+### 2. `BrevoService` failures now go through the Nest `Logger`
+
+`console.error(error)` was replaced with `this.logger.error(...)`. The return contract is
+unchanged, but the output now carries the `[BrevoService]` context and participates in whatever log
+transport you configured. Only relevant if you assert on raw stdout in tests.
+
+---
+
+## Security: add two overrides
+
+**This applies to every project, whether or not you use Brevo.**
+
+pnpm `overrides:` are honoured only for the **root** project of an install. The overrides declared
+inside `@lenne.tech/nest-server` therefore do **not** travel with the published package — your
+project resolves its own tree, with your overrides. Two transitive dependencies land on a
+known-vulnerable version without help:
+
+```yaml
+# pnpm-workspace.yaml (pnpm 11+; pnpm.overrides in package.json for pnpm 10 and earlier)
+overrides:
+  # @nestjs/graphql exact-pins ws@8.20.1 (GHSA-96hv-2xvq-fx4p, high). An exact pin
+  # cannot resolve forward — the override is the only fix.
+  'ws@>=8.0.0 <8.21.0': '8.21.1'
+
+  # @modelcontextprotocol/sdk declares @hono/node-server ^1.19.9 with no 1.x fix line
+  # (GHSA-frvp-7c67-39w9, GHSA-9mqv-5hh9-4cgg). Deliberately cross-major; verified safe
+  # (the SDK's only consumed symbol, `getRequestListener`, is unchanged in 2.x).
+  '@hono/node-server@<2.0.10': '2.0.11'
+```
+
+Then `pnpm install && pnpm audit` — it must report no known vulnerabilities.
+
+Projects generated from `nest-server-starter` or `lt-monorepo` already carry these.
+Full rationale and the rules for writing your own:
+[`docs/security-overrides.md`](../docs/security-overrides.md).
+
+---
+
+## What's New
+
+### Process diagnostics (opt-in, two lines)
+
+A Node API can die *silently*: the dev runner prints only `app crashed` with no stacktrace, and in a
+container the process just vanishes. A missing stacktrace means a SIGNAL killed it, not a throw.
+
+`installProcessDiagnostics()` makes the reason visible — unhandled rejections are logged without
+killing the server, uncaught exceptions are logged before the exit, non-zero exit codes are
+reported, and SIGTERM/SIGINT/SIGHUP/SIGQUIT are labelled as *external* terminations so they stop
+masquerading as in-process crashes.
+
+**Consumers own their own `main.ts`, so this does not arrive automatically.** Add it:
+
+```typescript
+// src/main.ts
+import { handleFatalBootstrapError, installProcessDiagnostics } from '@lenne.tech/nest-server';
+
+async function bootstrap() {
+  // FIRST statement — it must run before NestFactory.create() to catch module-construction failures
+  installProcessDiagnostics();
+
+  const server = await NestFactory.create<NestExpressApplication>(ServerModule);
+
+  // ... your configuration ...
+
+  server.enableShutdownHooks();   // see below — required for a clean container stop
+  await server.listen(envConfig.port);
+}
+
+// A rejection here is a fatal startup failure (EADDRINUSE, DB unreachable). Without the .catch it
+// becomes a mere unhandledRejection and leaves a zombie process, "alive" but listening on nothing.
+bootstrap().catch(handleFatalBootstrapError);
+```
+
+Do **not** call it from a module. It must run before `NestFactory.create()`, and it installs a
+`process.exit(1)` path that would otherwise arm inside `Test.createTestingModule()` and kill your
+whole test runner instead of failing one spec.
+
+Options:
+
+```typescript
+installProcessDiagnostics({
+  onUnhandledRejection: 'exit',   // default 'log' — 'exit' restores Node's own fail-fast
+  shutdownTimeoutMs: 30_000,      // watchdog when another handler owns the shutdown; 0 disables
+});
+```
+
+### `server.enableShutdownHooks()` — fixes a container that will not stop
+
+Independent of the diagnostics, and worth doing even if you skip them.
+
+In a container Node usually runs as **PID 1**. A PID-namespace init is `SIGNAL_UNKILLABLE`: a signal
+with the default disposition is silently discarded by the kernel. The listening HTTP server keeps
+the event loop non-empty, so nothing exits on its own — `docker stop` waits out its **full grace
+period** and then SIGKILLs. In-flight requests are dropped and every `onModuleDestroy()` is skipped.
+
+`enableShutdownHooks()` closes the app and drains the loop, so the process exits normally.
+Belt-and-braces: run a real init in the image (`docker run --init`, or `tini` as `ENTRYPOINT`).
+
+### New `brevo` config
+
+```typescript
+brevo: {
+  apiKey: '...',
+  sender: { email: '...', name: '...' },
+  maxRetries: 0,          // default 0 — see below
+  timeoutInSeconds: 10,   // default 10
+  throwOnError: false,    // default false
+}
+```
+
+The v6 SDK introduced a retry policy v3 did not have: 2 retries on 408/429/5xx, honouring
+`Retry-After` with a cap of **60 seconds per attempt**, and no request timeout. Since
+`BrevoService.sendMail()` is awaited inside request handlers (e.g. the BetterAuth
+email-verification hook), those defaults would let a rate-limited Brevo park a user-facing HTTP
+request for roughly two minutes. This framework therefore defaults to `maxRetries: 0` and
+`timeoutInSeconds: 10`. Raise them deliberately if you want SDK-level retrying.
+
+`throwOnError: true` makes a failed send throw instead of resolving to `null` — useful on
+security-critical delivery paths.
+
+### Brevo SDK is now lazily imported
+
+`@getbrevo/brevo` is ~580 CommonJS modules and `BrevoService` is re-exported from the package
+barrel, so every consumer paid that cold-start cost whether or not Brevo was configured. The SDK is
+now loaded on first send. No API change.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status | Notes |
+|---------|:------:|-------|
+| Calling `BrevoService.sendMail()` / `sendHtmlMail()` | Compatible | Signatures and return values unchanged |
+| Extending `BrevoService` | Compatible | `getClient()`, `handleSendError()`, `buildIdempotencyHeaders()` are `protected` and overridable |
+| Importing `TransactionalEmailsApi` / `SendSmtpEmail` / `TransactionalEmailsApiApiKeys` | **Breaking** | Removed in v6 — see above |
+| Reading `result.body` from a direct SDK call | **Breaking** | v6 resolves the payload directly |
+| Not using Brevo at all | Compatible | Cold start improves |
+| Existing `main.ts` without the diagnostics | Compatible | Purely opt-in; nothing regresses |
+
+### Checking whether a failed send was silently swallowed
+
+`BrevoService` resolves to `null` on failure rather than throwing (unless `throwOnError` is set).
+If you call it directly, check for it — "did not throw" is not "was delivered":
+
+```typescript
+const result = await this.brevoService.sendMail(email, templateId, params);
+if (result === null) {
+  // log, fall back to SMTP, retry — but do NOT record this as a successful send
+}
+```
+
+The framework's own email-verification path was fixed to do exactly this: it now falls through to
+the SMTP fallback instead of marking the address as mailed.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `Module '"@getbrevo/brevo"' has no exported member 'TransactionalEmailsApi'` | v6 removed it | Use `BrevoClient` — see [Breaking Changes](#1-getbrevobrevo-3x--6x-three-symbols-removed) |
+| `pnpm audit` reports `ws` / `@hono/node-server` | Overrides are not inherited | [Add the two entries](#security-add-two-overrides) |
+| `docker stop` takes the full grace period, then kills the container | No `enableShutdownHooks()`, node is PID 1 | Add the call; optionally `--init` / `tini` |
+| Sign-up request hangs ~2 minutes when Brevo is rate-limited | v6 retry defaults | Already fixed by the `maxRetries: 0` default — verify you did not override it |
+| Verification mail silently never arrives, logs say "sent" | Pre-11.32.0 swallow bug | Fixed; on custom callers, check for `null` |
+| `[exit] process exiting with code 0` no longer logged | Intentional | A clean exit is not a diagnostic; only non-zero codes are logged |
+| Process warnings no longer double-printed | Intentional | Node prints them itself, with more detail — use `--trace-warnings` for a stack |
+
+---
+
+## Module Documentation
+
+- [`docs/security-overrides.md`](../docs/security-overrides.md) — why overrides are not inherited, and the rules for writing them
+- [`docs/REQUEST-LIFECYCLE.md`](../docs/REQUEST-LIFECYCLE.md) — Process Diagnostics row under "Development & Operations"
+- `src/core/common/helpers/process-diagnostics.helper.ts` — full rationale in the module docblock
+- [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) — fixed-version policy for overrides

package/migration-guides/11.32.0-to-11.32.1.md

@@ -0,0 +1,84 @@
+# Migration Guide: 11.32.0 → 11.32.1
+
+## Overview
+
+| Category | Change | Effort |
+|----------|--------|--------|
+| **Bugfix** | A missing `migrations/` directory no longer blocks the server boot | None — automatic |
+| **Bugfix** | A spec in `src/core/` no longer breaks vendor-mode projects | None — automatic |
+
+**No code changes required.** Both fixes are internal.
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects: `/lt-dev:backend:update-nest-server-core`.
+
+---
+
+## What was fixed
+
+### A missing `migrations/` directory no longer blocks the boot
+
+`MigrationRunner.loadMigrationFiles()` called `fs.readdirSync()` without checking that the
+directory exists. A missing directory threw `ENOENT` — and because the standard start script is
+`migrate:up && start:local`, the `&&` turned that into a server that never starts, with an error
+that does not point at the cause.
+
+This is a state people produce routinely: *"delete all migrations"* reads to most as *"throw the
+folder away"*.
+
+A missing directory now means the same thing as an empty one — there are no migrations:
+
+```
+[migrate] migrations directory not found — treating as empty: ./migrations
+```
+
+`up()` and `status()` continue and exit 0. **`down()` is unchanged and still fails hard** —
+rollback is an explicit operator action, never a boot path, and an exit 0 with no rollback
+performed would mislead scripted rollbacks. `NSC__MIGRATE__STRICT=true` still turns a
+recorded-but-missing migration into a hard error, so the integrity guard is intact.
+
+If your project kept a `migrations/.gitkeep` purely to work around this, you can drop it — though
+keeping it does no harm.
+
+> Tracked as DEV-2634.
+
+### A `src/core/` spec no longer breaks vendor-mode projects
+
+`hub-mermaid.helper.spec.ts` mixed a value and a type import in one statement
+(`import { buildErDiagram, type HubModelDescriptor } from …`). The lt CLI's vendor conversion drops
+the inline `type` specifier, so the file arrived in vendored projects as
+`import { buildErDiagram }` and failed to compile with `TS2304: Cannot find name
+'HubModelDescriptor'` — breaking `pnpm run check` in every freshly generated vendor-mode project.
+
+The import is now split into two statements, which survives the conversion. Only vendor-mode
+projects were affected; npm-mode consumers never saw it.
+
+> The underlying CLI defect is tracked separately. Splitting the import keeps `src/core/`
+> vendor-safe regardless.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|:------:|
+| Everything from 11.32.0 | Unchanged |
+| `MigrationRunner` public API | Unchanged |
+| `down()` behaviour on a missing rollback file | Unchanged (still hard error) |
+| `NSC__MIGRATE__STRICT` | Unchanged |
+
+Still relevant from the previous release: **[the two security overrides your project needs](11.31.3-to-11.32.0.md#security-add-two-overrides)** — pnpm `overrides:` are not inherited from this package. If you skipped that step, do it now.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `ENOENT: no such file or directory, scandir './migrations'` on start | Pre-11.32.1 | Update; no code change needed |
+| `TS2304: Cannot find name 'HubModelDescriptor'` in a vendored core | Pre-11.32.1 vendored copy | Re-sync the core, or split the import in that one spec by hand |