nest-server-updating

What this skill does

# @lenne.tech/nest-server Update Knowledge Base

This skill provides **knowledge and resources** for updating @lenne.tech/nest-server. For automated execution, use the `lt-dev:nest-server-updater` agent via `/lt-dev:backend:update-nest-server`.

**Important:** After updating nest-server, also check if `@lenne.tech/nuxt-extensions` in `projects/app/` needs a compatible update, as nuxt-extensions is aligned with nest-server.

## Gotchas

- **Crossing the jest→vitest boundary** — At some point on the upstream `nest-server-starter` timeline the test runner migrated from jest+ts-jest to vitest+unplugin-swc (check the starter's `package.json` for the current truth — if `vitest-e2e.config.ts` exists, the boundary is behind you). Updating an existing project across that boundary needs more than a `pnpm install`: every `@Prop` whose property is a TypeScript union (`'a' | 'b'`, `null | string`, an alias for either) must add `type: String` (or `type: Object` for record-likes), every `import * as supertest` must become a default import, every `jest.*` call must become `vi.*`, and `jest-e2e.json` + `babel.config.js` must be removed. Without these, vitest fails with "Cannot determine a type for the X field" from Mongoose, or "is not a function" from supertest. The full recipe lives in the `modernizing-toolchain` skill — apply Phases 2 and 3 before running `pnpm test`.
- **`useDefineForClassFields` mismatch** — When migrating to vitest, both the `tsconfig.json` `compilerOptions.useDefineForClassFields` AND the swc plugin in `vitest-e2e.config.ts` MUST be set to `true`. Mixing them (e.g. swc=false, ts=true) silently breaks NestJS DI: `securityCheck` gets the wrong `currentUser`, so user `signUp` returns `createdBy: null` even though the override service set it. There is no error, only test failures that look like business logic regressions.
- **Minor version bumps are treated as MAJOR** — `@lenne.tech/nest-server` follows a "stepwise update" policy even on minor versions. Jumping from `7.5.x` directly to `7.9.x` in one step is likely to miss breaking changes that were introduced sub-minor. Always run the update step-by-step via `pnpm run update`, even if the version gap looks small.
- **`pnpm run update` requires the target version in `package.json` FIRST** — The update script reads the current/target from `package.json`. Running it before bumping the version does nothing or produces confusing errors. Order: (1) bump `package.json` → (2) `pnpm install` → (3) `pnpm run update`.
- **`nuxt-extensions` alignment breaks silently** — `@lenne.tech/nuxt-extensions` is version-aligned with `@lenne.tech/nest-server`. Updating nest-server to `7.19.0` without also updating nuxt-extensions to `7.19.x` leaves the frontend consuming an outdated API contract. Types generated via `generate-types` may still pass locally but break at runtime on production.
- **Migration guides are cumulative — read ALL between old and new version** — If you jump from `7.12` to `7.19`, migration guides for `7.13`, `7.14`, `7.15`, `7.16`, `7.17`, `7.18`, `7.19` ALL apply. Don't skip reading them — each introduces non-trivial behavior changes.
- **Starter project is the ground truth for constellations** — When a migration is ambiguous (e.g., which package.json override to add, which config value to change), check `nest-server-starter`'s current `package.json` via GitHub raw. It reflects the canonical working constellation for the target version.

## Scope: npm mode vs vendored mode

This skill covers the **npm-mode** update flow (bumping `@lenne.tech/nest-server` in `package.json`, applying migration guides from the upstream repo, re-running tests). Its companion for **vendored projects** (those where `<api-root>/src/core/VENDOR.md` exists) is the `nest-server-core-vendoring` skill + the `nest-server-core-updater` agent via `/lt-dev:backend:update-nest-server-core`.

**The two flows share one migration-guide corpus** (the upstream `migration-guides/` directory applies to code regardless of consumption mode — it describes API deltas in the framework, not in the distribution channel). Everything in this skill about per-version breaking changes, error patterns, and error messages is equally valid in vendored mode. What differs is:

| Aspect | npm mode | vendored mode |
|--------|----------|---------------|
| Detection | no `src/core/VENDOR.md` | `src/core/VENDOR.md` exists |
| Bump command | `pnpm update @lenne.tech/nest-server` | `/lt-dev:backend:update-nest-server-core --target <v>` |
| Framework source location | `node_modules/@lenne.tech/nest-server/src/core/...` | `<api-root>/src/core/...` |
| Baseline version lookup | `pnpm list @lenne.tech/nest-server --depth=0` | `grep Baseline-Version <api-root>/src/core/VENDOR.md` |
| Source of truth for framework code | npm package `dist/` + shipped `src/` | local `src/core/` (committed, may carry patches) |
| Local patches | not persisted (lost on `pnpm install`) | expected; logged in `VENDOR.md` |
| Import statements in consumer code | `from '@lenne.tech/nest-server'` | relative: `from '../../src/core'` etc. |

The `nest-server-updater` agent auto-detects the project mode (Phase 0 in its workflow) and delegates to `nest-server-core-updater` when `VENDOR.md` is present, so users only ever need to invoke `/lt-dev:backend:update-nest-server` — the right flow kicks in automatically.

## When This Skill Activates

- Discussing nest-server updates or upgrades
- Asking about breaking changes between versions
- Troubleshooting update-related errors
- Planning migration strategies
- Comparing versions or checking compatibility

## Skill Boundaries

| User Intent | Correct Skill |
|------------|---------------|
| "Update nest-server to v14" | **THIS SKILL** |
| "Migrate to latest nest-server" | **THIS SKILL** |
| "Breaking changes in nest-server" | **THIS SKILL** |
| "Create a NestJS module" | generating-nest-servers |
| "Update all npm packages" | maintaining-npm-packages |
| "npm audit fix" | maintaining-npm-packages |

## Related Skills

| Element | Purpose |
|---------|---------|
| **Agent**: `lt-dev:nest-server-updater` | Automated execution of updates |
| **Command**: `/lt-dev:backend:update-nest-server` | User invocation |
| **Skill**: `generating-nest-servers` | Code modifications after update |
| **Skill**: `maintaining-npm-packages` | Package optimization |

---

## Core Resources

### GitHub Repositories

| Resource | URL | Purpose |
|----------|-----|---------|
| **nest-server** | https://github.com/lenneTech/nest-server | Main package repository |
| **Releases** | https://github.com/lenneTech/nest-server/releases | Release notes, changelogs |
| **Migration Guides** | https://github.com/lenneTech/nest-server/tree/main/migration-guides | Version-specific migration instructions |
| **Reference Project** | https://github.com/lenneTech/nest-server-starter | Current compatible code & package versions |

### npm Package

```bash
# Package info
pnpm view @lenne.tech/nest-server

# Current installed version
pnpm list @lenne.tech/nest-server --depth=0

# All available versions
pnpm view @lenne.tech/nest-server versions --json
```

---

## Migration Guide System

**Complete guide selection logic, fallback strategy, and fetch commands: [reference/migration-guides.md](reference/migration-guides.md)**

---

## Version Update Strategies

**IMPORTANT:** In @lenne.tech/nest-server, **Major versions are reserved for NestJS Major versions**.
Therefore, **Minor versions are treated like Major versions** and may contain breaking changes.

### Patch Updates (X.Y.Z → X.Y.W)

- Usually safe, no breaking changes
- Use the standard update workflow (see Quick Reference → Update Workflow)
- Run tests to verify
- **Example:** `11.6.0 → 11.6.5` - direct update OK

### Minor Updates (X.Y.Z → X.W.0) ⚠️ Treat as Major!

- **May contain breaking changes** (Minor = Major in this package)
- **Always stepwise**: Update through each minor version
- Each minor step requires full validation cyc