@lenne.tech/nest-server 11.32.0 → 11.32.1

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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.32.0",
+  "version": "11.32.1",
   "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",

package/src/core/modules/hub/helpers/hub-mermaid.helper.spec.ts

@@ -1,6 +1,13 @@
 import { describe, expect, it } from 'vitest';
 
-import { buildErDiagram, type HubModelDescriptor } from './hub-mermaid.helper';
+// Value and type imports are deliberately split into two statements. The lt CLI's vendor
+// conversion drops an INLINE `type` specifier from a mixed import — `{ buildErDiagram, type
+// HubModelDescriptor }` arrives in a vendored project as `{ buildErDiagram }`, and the file then
+// fails to compile with TS2304. Keeping the two forms separate survives the conversion.
+// (The CLI defect is tracked separately; this keeps src/core/ vendor-safe meanwhile.)
+import type { HubModelDescriptor } from './hub-mermaid.helper';
+
+import { buildErDiagram } from './hub-mermaid.helper';
 
 describe('buildErDiagram', () => {
   const models: HubModelDescriptor[] = [

package/src/core/modules/migrate/migration-runner.ts

@@ -159,6 +159,23 @@ export class MigrationRunner {
    * compiled-production intent; the duplicate is skipped with a warning.
    */
   private async loadMigrationFiles(): Promise<MigrationFile[]> {
+    // A MISSING directory means the same thing as an EMPTY one: there are no migrations.
+    // Treat it that way instead of throwing ENOENT.
+    //
+    // This is a boot blocker otherwise: `pnpm start` is `migrate:up && start:local`, so the `&&`
+    // turns a readdirSync ENOENT into a server that will not start — with an error that does not
+    // point at the cause. And it is a state people produce routinely: "delete all migrations"
+    // reads to most as "throw the folder away".
+    //
+    // The runner already tolerates the RELATED case — a migration recorded in the database whose
+    // file is gone is non-fatal unless `NSC__MIGRATE__STRICT` is set. Only the wholly absent
+    // directory fell outside that tolerance. `down()` stays hard, consistent with its own
+    // reasoning. See DEV-2634.
+    if (!fs.existsSync(this.options.migrationsDirectory)) {
+      console.warn(`[migrate] migrations directory not found — treating as empty: ${this.options.migrationsDirectory}`);
+      return [];
+    }
+
     const files = fs
       .readdirSync(this.options.migrationsDirectory)
       .filter((file) => this.pattern.test(file))