# Migration Guide: 11.16.x → 11.17.0

## Overview

| Category | Details |
|----------|---------|
| **Breaking Changes** | None |
| **New Features** | Permissions Report Module, Configurable endpoint path |
| **Bugfixes** | None |
| **Migration Effort** | < 5 minutes (optional feature) |

---

## Quick Migration (No Breaking Changes)

```bash
# Update package
npm install @lenne.tech/nest-server@11.17.0

# Verify build
npm run build

# Run tests
npm test
```

---

## What's New in 11.17.0

### 1. Permissions Report Module

A development tool that scans your project for `@Roles`, `@Restricted`, and `securityCheck()` usage, generating an interactive HTML dashboard at runtime.

**Setup (optional):**

```typescript
// config.env.ts - local/development only
permissions: true,
```

This adds the following endpoints to your server:

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/permissions` | Interactive HTML dashboard |
| `GET` | `/permissions/json` | JSON report with stats |
| `GET` | `/permissions/markdown` | Markdown report |
| `POST` | `/permissions/rescan` | Force rescan |

**Features:**
- Lazy scanning (only on first request)
- File watcher auto-invalidates cache on `.ts` file changes
- Coverage metrics (endpoint coverage, security coverage)
- Warning detection (missing `@Roles`, `@Restricted`, `securityCheck()`)
- Role-based access control (admin-only by default)

**Advanced configuration:**

```typescript
// Custom role
permissions: { role: 'S_EVERYONE' },

// No authentication
permissions: { role: false },

// Custom endpoint path
permissions: { path: 'admin/permissions' },

// Explicitly disabled
permissions: { enabled: false },
```

### 2. Standalone Permissions Scanner

The scanning logic has been extracted into `permissions-scanner.ts` as a standalone module with no NestJS dependencies. This enables:

- The `lt server permissions` CLI command to use the same scanner via dynamic import
- External tools to import `scanPermissions()` directly from `@lenne.tech/nest-server`

```typescript
import { scanPermissions, findProjectRoot } from '@lenne.tech/nest-server';

const projectRoot = findProjectRoot();
const report = scanPermissions(projectRoot, {
  log: (msg) => console.log(msg),
  warn: (msg) => console.warn(msg),
});
```

---

## Detailed Migration Steps

### Step 1: Update Package

```bash
npm install @lenne.tech/nest-server@11.17.0
```

### Step 2: Adopt New Features (Optional)

Add `permissions: true` to your `config.env.ts` in local/development environments. See the [Permissions README](../src/core/modules/permissions/README.md) for details.

---

## Compatibility Notes

- The permissions module is entirely opt-in. Existing projects are unaffected.
- The `lt server permissions` CLI command now requires `@lenne.tech/nest-server >= 11.17.0` in the target project.

---

## Module Documentation

### Permissions Report

- **README:** [src/core/modules/permissions/README.md](../src/core/modules/permissions/README.md)
- **Integration Checklist:** [src/core/modules/permissions/INTEGRATION-CHECKLIST.md](../src/core/modules/permissions/INTEGRATION-CHECKLIST.md)
- **Key Files:**
  - `permissions-scanner.ts` - Standalone AST scanning (shared with CLI)
  - `core-permissions.service.ts` - Caching, file watching, HTML generation
  - `core-permissions.controller.ts` - REST endpoints
  - `core-permissions.module.ts` - DynamicModule with forRoot()

---

## References

- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
