@lenne.tech/nest-server 11.36.3 → 11.36.4

package/.claude/rules/testing.md

@@ -107,6 +107,38 @@ pnpm run test:cleanup
   `@UnifiedField` deprecation warnings filtered).
 - Database (E2E only): **one unique database per run** (`nest-server-e2e-run-<ts>-p<pid>`), created by `tests/global-setup.ts` so concurrent runs cannot interfere with each other. Specs needing an extra DB derive it via `deriveTestDbUri('<suffix>')` — never a hardcoded/`Date.now()` name (escapes the cleanup scheme).
 - DB lifecycle (`tests/db-lifecycle.reporter.ts`): run passes → DB dropped immediately + stale run DBs from crashed/failed runs collected; run fails → DB kept for debugging. Additionally `tests/global-setup.ts` runs a **startup sweep** (shared `isStaleTestDb()` predicate, dead-PID/age guarded) — leftovers are removed when the NEXT run starts, which survives SIGKILL (check watchdog) and `--reporter` CLI overrides. An externally set `MONGODB_URI` (CI) opts out of the scheme.
+- The drop guard (`SAFE_TEST_DB_PATTERN` + `NON_DISPOSABLE_DB_PATTERN`): nothing in the scheme drops
+  a database whose name does not carry `e2e`, `ci`, `test` or `acctest` as a **whole segment**
+  (`/(^|[-_])(e2e|ci|test|acctest)([-_]|$)/i`). It gates all three drop sites: the externally-set
+  `MONGODB_URI` branch, the startup sweep, and the reporter's post-run collection. **The anchoring
+  is the point, not decoration.** The original form matched the marker as a substring ANYWHERE, and
+  `ci` hides inside soCIal / speCIal / finanCIal / priCIng / muniCIpal, `test` inside laTEST /
+  conTEST / TESTimonials. `lt dev up` exports `MONGODB_URI` at the project's DEVELOPMENT database
+  (`<slug>-local`), so a developer on a project named e.g. `pricing-portal` who started the e2e
+  suite from that shell had their working data dropped BY the guard that exists to prevent exactly
+  that. It had never had a test.
+
+  Three things about it are load-bearing and easy to undo:
+
+  1. **`acctest` is a separate alternative BECAUSE of the anchoring** — `test` no longer matches
+     inside it, so deleting it as "redundant" silently stops acceptance-test databases from ever
+     being collected.
+  2. **The externally-set-URI branch is the only drop site with no second condition.** The other two
+     also require `isStaleTestDb()`, i.e. the name must belong to this project's own base. So that
+     one branch additionally applies `NON_DISPOSABLE_DB_PATTERN` (`-local`, `-dev`, `-prod`,
+     `-staging`, …) via `isDroppableTestDb()`: a project slug may legitimately carry a marker as a
+     whole word — `ci` is the German abbreviation for *Corporate Identity*, `test` a product noun
+     for an exam — and `ci-portal-local` passes the segment rule. It also refuses a URI that names
+     **no** database, because the driver would fall back to its default (`test`) and that name
+     passes the guard.
+  3. **The anchoring is a naming contract on the base DB name.** A base like `shope2e` or
+     `app-e2edb` satisfies nothing, and its databases would then accumulate with nothing collecting
+     them — silently, which is why both sweep loops now COUNT and log the stale candidates the
+     guard refused.
+
+  Pinned by `tests/unit/db-lifecycle-guard.spec.ts` (registered mutation
+  `safe-test-db-pattern-unanchored`; reverting the anchoring turns 13 cases red). **The refusal list
+  in that spec IS the specification** — extend it rather than loosening the pattern.
 - Run governor (`tests/e2e-run-slots.ts`): machine-wide slot dir (`<tmpdir>/lt-e2e-run-slots`) caps concurrent e2e runs across ALL lt projects/sessions (default 2 on ≥8 cores). Further runs wait, logging `[e2e-governor] waiting…` every 15s (keeps the check watchdog fed — a queued run is NOT hung). The e2e config counts foreign slots at load time and drops to low-resource mode (reduced forks, raised timeouts) when another run is active — deterministic, unlike the lagging 1-min load average (kept as second signal). Knobs: `LT_E2E_MAX_RUNS` (0 disables), `LT_E2E_SLOT_DIR`, `LT_E2E_SLOT_TIMEOUT` (fail-open).
 - `retry: 2` (e2e) is deliberate — with `retry: 5`, one spec file with broken app/socket state ground through 6 attempts × 30s timeout × 22 tests ≈ an hour at 0% CPU (looked like a deadlock; the check watchdog killed it). Never raise retry to paper over contention.
 - Infrastructure containers (E2E only, the **seven** specs listed under "Infrastructure containers"
@@ -234,7 +266,7 @@ pnpm run check:mutations -- --id=<id>       # one mutation
 pnpm run check:mutations -- --list          # the registry, without running anything
 pnpm run check:mutations -- --allow-dirty   # when the fix and its evidence share a working tree
 pnpm run check:mutations -- --jobs=4        # N mutations at a time (default: 2, or 4 on >=12 cores)
-pnpm run check:mutations -- --no-infra      # only the 21 that need no MongoDB
+pnpm run check:mutations -- --no-infra      # only the 22 that need no MongoDB
 pnpm run check:mutations -- --since=<ref>   # only mutations touching files changed since <ref>
 ```
 
@@ -252,17 +284,49 @@ when the registry, a vitest config or a setup file changed, since those can move
 **Why the gate does not cache per-mutation verdicts instead.** It runs ONCE PER RELEASE, not per
 commit, so selective re-running would save ~10 minutes a release. The price is a cache that has to
 model each spec's full dependency closure correctly, and getting that wrong produces a stale PASS
-for a test that has since gone vacuous — exactly what the gate is there to prevent. Bad trade at 51
+for a test that has since gone vacuous — exactly what the gate is there to prevent. Bad trade at 52
 mutations. Worth revisiting around 100, where the full run approaches half an hour.
 
 Not part of `pnpm run check` — it edits source and re-runs whole e2e suites. It belongs in review
-and on the publish path.
+and on the publish path. It is also reachable on demand, without cutting a release:
+
+```
+gh workflow run regression-evidence.yml --ref develop                      # the full registry
+gh workflow run regression-evidence.yml --ref develop -f args="--no-infra" # the unit subset
+```
+
+**Why that matters, and what it cost to learn (11.36.3).** The gate lived only in `publish.yml`,
+which triggers on `release: released`. So the only way to observe it on a CI runner was to cut a
+release — and when it reported `0/51 mutations confirmed`, diagnosing that required cutting another
+one. A gate you cannot run without shipping is a gate you cannot debug.
+
+**A verdict must carry its reason.** `INCONCLUSIVE` exists so a crashed, timed-out or starved run is
+not counted as evidence — but the first version reported the verdict and discarded the output that
+explained it. `classifyRun()` now attaches the last 25 lines (`tailOf`) and names the exit code.
+
+**The parser must strip ANSI, and this is the load-bearing part.** vitest COLOURS its summary on a CI
+runner, so the line carries escape sequences between `Tests` and the number; `\s+` matches whitespace,
+never an escape. The count therefore did not parse in CI — and it never had. The *previous* verdict
+was `failedCount ?? 'some'` with `ok: true` on any non-zero exit, so it never needed the count: on the
+publish path the gate had been accepting a crash, a timeout or a collection error as "went red".
+
+Two consequences worth stating plainly:
+
+1. Requiring a real failure count is what makes the gate a check rather than a rubber stamp. Do not
+   relax it back to "non-zero exit is enough" — that is the defect, not a convenience.
+2. **Mutation confirmations from CI runs before 11.36.3 are not evidence.** They were verified
+   locally (where output is colourless) and stamped in CI. The first trustworthy full-registry run on
+   a runner is the `51/51` from the 11.36.3 retag.
+
+Anything that PARSES a spawned run's output belongs behind `stripAnsi()`: the same command is
+colourless on a pipe and colourised on a runner, so a regex tested locally can be reliably wrong in
+exactly the environment where the answer matters.
 
 ### The cost is vitest's cold start, not the tests
 
 Worth knowing before optimising the wrong thing: the specs behind all 30 e2e mutations add up to
 **~40 seconds**. The step takes ~740s. The remaining ~700s is paying vitest's startup — process
-spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 51 times.
+spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 52 times.
 That work is largely single-threaded I/O and barely scales with cores: the full registry measures
 **744s on a 12-core laptop and 777s on a 4-vCPU CI runner**.
 

package/CLAUDE.md

@@ -24,6 +24,7 @@ The following documents must be kept up to date when making changes that affect
 | `.claude/rules/configurable-features.md` | Adding new configurable features |
 | `src/templates/*.ejs` + `tests/unit/email-templates.spec.ts` | Changing a mail template — a template is never imported, type-checked or linted, so the only thing binding it to its caller is the variable names inside it. Add the caller's data shape to the spec |
 | `FRAMEWORK-API.md` | Auto-regenerated by `pnpm run build` — verify after adding interfaces, CrudService methods, or core modules |
+| `.claude/rules/testing.md` | Changing the test-runner split, the per-run DB lifecycle or its **drop guard**, the run governor, the infrastructure containers, or the regression-evidence gate. This row exists because the drop guard — the one thing standing between a test run and a developer's data — went undocumented for its whole life: nothing in this table pointed at the file that describes everything around it |
 
 **Rule:** When a code change adds, removes, or modifies a feature listed in `docs/REQUEST-LIFECYCLE.md` (Features Overview, diagrams, decorator reference, configuration, etc.), update the document in the same commit or PR.
 

package/FRAMEWORK-API.md

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

package/migration-guides/11.36.3-to-11.36.4.md

@@ -0,0 +1,145 @@
+# Migration Guide: 11.36.3 → 11.36.4
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | None |
+| **Bugfixes** | **The test-database drop guard accepted ordinary project databases** — a name merely CONTAINING `ci`/`test` read as disposable, so an e2e run started from an `lt dev` shell could drop the developer's DEVELOPMENT database (§1). Framework-internal, but every starter-derived project carries a private copy of the same code |
+| **Migration Effort** | **None** for the framework itself — `tests/` is not published. **~1 minute, recommended**, if your project was generated from `nest-server-starter`: apply the one-line fix in §1 to your own `tests/db-lifecycle.reporter.ts` |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.4
+```
+
+Then read §1 — it is the only thing in this release that can affect you, and `pnpm update` does
+**not** deliver it, because the affected file lives in your repository, not in the package.
+
+---
+
+## 1. Recommended: tighten the test-database drop guard in your own `tests/`
+
+**Why this reaches you at all.** `tests/db-lifecycle.reporter.ts` is not part of the npm package
+(`package.json` → `files` does not include `tests/`) and not part of the vendor-mode file set. It is
+a **template** file: `nest-server-starter` ships it, and every project ever generated from the
+starter holds a private copy that no update channel ever touches. So this guide is the only way the
+fix reaches an existing project.
+
+**Were you affected?** Only if all three are true:
+
+1. Your project's slug contains `ci`, `test`, `e2e` or `acctest` **as a substring** — including
+   inside an ordinary word: `ci` hides in so**ci**al, spe**ci**al, finan**ci**al, invoi**ci**ng,
+   pri**ci**ng, muni**ci**pal; `test` hides in la**test**, con**test**, **test**imonials.
+2. You use `lt dev up`, which exports `MONGODB_URI` pointing at `<slug>-local` — your **development**
+   database.
+3. You started the e2e suite from that same shell.
+
+Then `tests/global-setup.ts` dropped that database. The guard meant to prevent exactly this accepted
+it, because it matched the marker anywhere in the name rather than as a delimited segment.
+
+### The fix
+
+```diff
+- export const SAFE_TEST_DB_PATTERN = /(e2e|ci|test|acctest)/i;
++ export const SAFE_TEST_DB_PATTERN = /(^|[-_])(e2e|ci|test|acctest)([-_]|$)/i;
+```
+
+The marker must now be a whole segment, delimited by `-`, `_`, or a string boundary.
+
+### Check your own database names before applying it
+
+The change is a strict narrowing — every name the new pattern accepts, the old one accepted too, so
+it cannot start dropping something it previously spared. The risk runs the other way: if your **base**
+test database name does not carry the marker as a delimited segment (`shope2e`, `app-e2edb`,
+`projecttest`), the guard now refuses it and **cleanup silently stops collecting** — the databases
+accumulate with nothing removing them.
+
+```bash
+# What does your suite actually name its databases?
+grep -n "mongodb://" src/config.env.ts
+```
+
+`myproject-e2e` and `myproject_ci` are fine. `myproje2e` is not — rename the database rather than
+loosening the pattern.
+
+Since 11.36.4 both sweep loops **count and log** the stale databases the guard refused, so this
+condition announces itself instead of leaking quietly:
+
+```
+Startup sweep: 3 stale database(s) skipped by the safety guard —
+"shope2e" needs a delimited e2e/ci/test/acctest segment for cleanup to work.
+```
+
+### Two further hardening steps, worth copying
+
+Both live in the same file and are optional, but they close the residual cases the pattern alone
+cannot:
+
+**A second guard for the one drop site that has no other condition.** The startup sweep and the
+post-run collection both additionally require `isStaleTestDb()` — the name must belong to your own
+base. The externally-supplied-`MONGODB_URI` branch has no such backstop, and a project slug may
+legitimately carry a marker as a *whole word*: `ci` is the ordinary German abbreviation for
+*Corporate Identity*, `test` a product noun for an exam. `ci-portal-local` passes the segment rule.
+
+```typescript
+export const NON_DISPOSABLE_DB_PATTERN
+  = /(^|[-_])(local|dev|develop|development|prod|production|staging|stage|live)([-_]|$)/i;
+
+export function isDroppableTestDb(name: string): boolean {
+  return SAFE_TEST_DB_PATTERN.test(name) && !NON_DISPOSABLE_DB_PATTERN.test(name);
+}
+```
+
+Then use `isDroppableTestDb(db.databaseName)` in place of `SAFE_TEST_DB_PATTERN.test(...)` in
+`tests/global-setup.ts` — **only there**. Applying it to the sweep paths could only turn a collected
+database into a leaked one.
+
+**Refuse a URI that names no database.** `mongodb://127.0.0.1` makes the driver fall back to its
+default database, `test` — a name the guard accepts, so a truncated `MONGODB_URI` dropped the
+server's `test` database instead of failing. Note that this needs the `splitMongoUri()` fix too: the
+previous greedy form reported the **host** as the database name for such a URI, so the check could
+never fire.
+
+```typescript
+const match = uri.match(/^(mongodb(?:\+srv)?:\/\/[^/?]*)(?:\/([^/?]*))?(\?.*)?$/i);
+```
+
+This also fixes a second case the greedy form got wrong: an option value containing a slash
+(`?tlsCAFile=/etc/ssl/ca.pem`) previously reported `ca.pem` as the database name.
+
+### Pin it
+
+The framework's own spec is `tests/unit/db-lifecycle-guard.spec.ts` — copy it alongside the fix. Its
+refusal list *is* the specification, and reverting the anchoring turns 13 cases red.
+
+---
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---------|--------|
+| npm-mode projects | Unaffected by the package update; apply §1 to your own `tests/` |
+| Vendor-mode projects | Same — `tests/` is outside the vendor file set |
+| CI pipelines that pin `MONGODB_URI` | Unaffected, unless the pinned URI names no database or carries an environment suffix. A CI database called `myproject-ci` is fine; one called `myproject-ci-staging` is now refused |
+| Projects not generated from `nest-server-starter` | Nothing to do |
+
+---
+
+## Troubleshooting
+
+**`Refusing to dropDatabase("…"): not a recognized disposable test database`**
+Your `MONGODB_URI` points at something the guard will not delete. That is the guard working. Check
+whether the URI is aimed at your development database — an `lt dev` shell exports it that way — and
+point it at a disposable test database instead. Do not loosen the pattern to get past this.
+
+**`Refusing to use MONGODB_URI="…": it names no database`**
+The URI has no path (`mongodb://host` rather than `mongodb://host/mydb`). Add the database name.
+
+**`N stale database(s) skipped by the safety guard`**
+Your base database name does not carry a delimited marker, so cleanup cannot collect its leftovers.
+Rename the database (see §1).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.3",
+  "version": "11.36.4",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",