@lenne.tech/nest-server 11.21.3 → 11.22.1

package/.claude/rules/core-modules.md

@@ -0,0 +1,205 @@
+---
+paths: src/core/modules/**
+---
+
+# Core Module Development Rules
+
+These rules apply when working in `src/core/modules/`.
+
+## Naming Conventions
+
+- Base classes: `Core` prefix (e.g., `CoreAuthService`, `CoreBetterAuthResolver`)
+- Interfaces: `I` prefix (e.g., `IBetterAuth`, `IServerOptions`)
+- Models: `*Model` suffix for GraphQL types
+- Inputs: `*Input` suffix for input types
+- Args: `*Args` suffix for query arguments
+
+## Method Visibility
+
+- Use `protected` for methods that should be overridable
+- Use `public` for API methods
+- Avoid `private` for methods that projects might need to customize
+
+## Module Registration
+
+### Override Pattern (Recommended)
+
+Core modules that support customization should accept `controller`/`resolver`/`service` parameters
+in their `forRoot()` method. `CoreModule.forRoot()` passes these through via the `ICoreModuleOverrides` parameter:
+
+```typescript
+// In core module
+static forRoot(config?: { controller?: Type; service?: Type }): DynamicModule {
+  const ControllerClass = config?.controller || CoreDefaultController;
+  const ServiceClass = config?.service || CoreDefaultService;
+  return { module: MyModule, controllers: [ControllerClass], providers: [...] };
+}
+```
+
+New modules must add their override fields to `ICoreModuleOverrides` in `server-options.interface.ts`
+and pass them through in `CoreModule.forRoot()`.
+
+### Auto-Registration
+
+Always support both registration modes:
+
+```typescript
+// In module class
+static forRoot(options: ModuleOptions): DynamicModule {
+  // Check autoRegister option
+  if (options.config?.autoRegister === true) {
+    // Auto-registration logic
+  }
+  // Manual registration is default
+}
+```
+
+## Export Requirements
+
+All public classes must be exported in `src/index.ts`:
+
+```typescript
+// src/index.ts
+export { CoreAuthService } from './core/modules/auth/services/core-auth.service';
+export { CoreBetterAuthResolver } from './core/modules/better-auth/core-better-auth.resolver';
+```
+
+## Documentation
+
+Each core module should have:
+
+1. README.md in module directory
+2. JSDoc comments on public methods
+3. Interface documentation in `server-options.interface.ts`
+
+## Logging
+
+Use NestJS Logger with module name:
+
+```typescript
+private readonly logger = new Logger(ModuleName.name);
+
+// Use appropriate log levels
+this.logger.log('Important info');      // Normal operations
+this.logger.warn('Warning message');    // Potential issues
+this.logger.error('Error occurred');    // Errors
+this.logger.debug('Debug info');        // Development only (sparingly)
+```
+
+## Optional Constructor Parameters
+
+Use the **options object pattern** for optional constructor parameters in Core classes:
+
+```typescript
+// Define options interface
+export interface CoreUserServiceOptions {
+  betterAuthUserMapper?: BetterAuthUserMapper;
+  // Future optional params can be added without breaking changes
+}
+
+// Core class constructor
+protected constructor(
+  // Required params first
+  protected readonly configService: ConfigService,
+  protected readonly emailService: EmailService,
+  // Options object last
+  protected readonly options?: CoreUserServiceOptions,
+) {
+  super();
+}
+
+// Usage in methods
+if (this.options?.betterAuthUserMapper) {
+  await this.options.betterAuthUserMapper.syncEmail(...);
+}
+```
+
+**Why this pattern:**
+- New optional parameters can be added without breaking existing implementations
+- No need to pass `null` or `undefined` for unused optional parameters
+- Order of optional parameters doesn't matter
+- Clear distinction between required and optional dependencies
+
+**Implementation in extending classes:**
+```typescript
+constructor(
+  // ... required params ...
+  @Optional() private readonly betterAuthUserMapper?: BetterAuthUserMapper,
+) {
+  super(configService, emailService, mainDbModel, mainModelConstructor, { betterAuthUserMapper });
+}
+```
+
+## Testing
+
+- Create story tests in `tests/stories/`
+- Test through API (REST/GraphQL), not direct service calls
+- Include security tests for authentication/authorization
+
+## Integration Documentation (Required for All Core Modules)
+
+Every core module that requires project integration MUST have an `INTEGRATION-CHECKLIST.md` file.
+
+### Purpose
+
+This checklist helps developers (and AI assistants like Claude Code) integrate the module into their projects. It should be optimized for:
+- Quick understanding of required steps
+- Clear references to working code (no duplicates)
+- Critical "WHY" explanations for non-obvious steps
+
+### Required Structure
+
+```markdown
+# [ModuleName] Integration Checklist
+
+## Reference Implementation
+- Local: `node_modules/@lenne.tech/nest-server/src/server/modules/[module]/`
+- GitHub: https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/[module]
+
+## Required Files (Create in Order)
+### 1. [FileName]
+**Create:** `src/server/modules/[module]/[file].ts`
+**Copy from:** Reference implementation
+[Optional: WHY explanation for critical/non-obvious steps]
+
+## Verification Checklist
+- [ ] Build succeeds
+- [ ] Tests pass
+- [ ] [Module-specific checks]
+
+## Common Mistakes
+| Mistake | Symptom | Fix |
+```
+
+### Key Principles
+
+1. **No Code Duplication**: Never include full code examples that duplicate `src/server/`
+   - Reference files exist in `src/server/modules/` and are included in the npm package
+   - Claude Code can read these files directly from `node_modules/`
+   - Only include small code snippets for DIFFs (changes to existing files)
+
+2. **Single Source of Truth**: The reference implementation in `src/server/` is always current
+   - Documentation never becomes outdated
+   - Copy-paste from reference is always correct
+
+3. **WHY Explanations**: Include for critical/non-obvious steps
+   - Example: "WHY must decorators be re-declared?" → GraphQL schema registration
+   - Example: "WHY inject this mapper?" → Bidirectional sync between systems
+
+4. **Verification Checklist**: Help verify successful integration
+   - Build/test commands
+   - Module-specific functional checks
+
+5. **Common Mistakes Table**: Document known pitfalls with symptoms and fixes
+
+### Example
+
+See `src/core/modules/better-auth/INTEGRATION-CHECKLIST.md` as the reference template.
+
+### When to Create
+
+Create an `INTEGRATION-CHECKLIST.md` when the module:
+- Requires files to be created in the consuming project
+- Has non-obvious integration steps
+- Extends Core classes that need decorator re-declaration
+- Requires changes to existing project files (UserService, ServerModule, etc.)

package/.claude/rules/framework-compatibility.md

@@ -0,0 +1,79 @@
+# Framework Compatibility for Claude Code
+
+This document defines the maintenance obligations that ensure Claude Code can effectively work with `@lenne.tech/nest-server` in consuming projects.
+
+## Architecture Overview
+
+The framework ships documentation alongside source code so that Claude Code can read it from `node_modules/`. Three layers work together:
+
+1. **npm package** ships `CLAUDE.md`, `FRAMEWORK-API.md`, `.claude/rules/`, `docs/`, `migration-guides/`
+2. **Consuming project** `CLAUDE.md` points Claude to read `node_modules/@lenne.tech/nest-server/`
+3. **Claude Code plugin** (`lt-dev`) detects nest-server and injects concrete source paths via hooks
+
+## Maintenance Obligations
+
+### When Adding/Changing Interfaces in `server-options.interface.ts`
+
+1. `FRAMEWORK-API.md` is auto-generated during `pnpm run build` via `scripts/generate-framework-api.ts`
+2. Verify the generated output includes the new interface and all fields
+3. Add JSDoc with `@default` tags for all config fields — these appear in the API reference
+
+### When Adding New Core Modules (`src/core/modules/`)
+
+1. Create `README.md` and `INTEGRATION-CHECKLIST.md` in the module directory
+2. The generator script automatically picks up new modules for the "Core Modules" table
+3. If the module has `forRoot()` config, add the interface to `server-options.interface.ts`
+4. Run `pnpm run build` to regenerate `FRAMEWORK-API.md`
+
+### When Changing CrudService Methods
+
+1. Add JSDoc to new methods — the generator extracts the first line as description
+2. Run `pnpm run build` to regenerate `FRAMEWORK-API.md`
+3. If the method signature pattern changes (standard/Force/Raw), update the "Variants" note
+
+### When Changing `CoreModule.forRoot()` Signatures
+
+1. Ensure JSDoc is complete on the new overload
+2. Run `pnpm run build` to regenerate `FRAMEWORK-API.md`
+3. If adding a new parameter, update the consuming project template (`nest-server-starter/CLAUDE.md`)
+
+### When Releasing New Versions
+
+1. Run `pnpm run build` — this regenerates `FRAMEWORK-API.md` with the new version number
+2. The file is included in the npm package via `package.json` `files` array
+3. Migration guides are separate (see `.claude/rules/migration-guides.md`)
+
+## Files Shipped with npm Package
+
+| File | Purpose | Auto-Updated |
+|------|---------|:------------:|
+| `CLAUDE.md` | Framework rules, architecture, debugging guide | Manual |
+| `FRAMEWORK-API.md` | Compact API reference (interfaces, methods) | Yes (`pnpm run build`) |
+| `.claude/rules/*.md` | 12 rule files covering all aspects | Manual |
+| `docs/REQUEST-LIFECYCLE.md` | Complete request lifecycle | Manual |
+| `migration-guides/*.md` | Version migration guides | Per release |
+
+## Generator Script
+
+`scripts/generate-framework-api.ts` extracts via ts-morph:
+- `CoreModule.forRoot()` overload signatures
+- All config interfaces (`IServerOptions`, `IBetterAuth`, `IMultiTenancy`, etc.)
+- `ServiceOptions` interface
+- `CrudService` public method signatures
+- Core module listing with documentation status
+
+Run manually: `npx tsx scripts/generate-framework-api.ts`
+
+## Cross-Repository Dependencies
+
+This framework compatibility strategy spans multiple repositories:
+
+| Repository | Role |
+|-----------|------|
+| `nest-server` | Ships documentation with npm package (this repo) |
+| `nest-server-starter` | `CLAUDE.md` points Claude to `node_modules/` source |
+| `nuxt-extensions` | Same pattern: `CLAUDE.md` shipped with npm package |
+| `nuxt-base-starter` | `CLAUDE.md` points Claude to nuxt-extensions source |
+| `claude-code/plugins/lt-dev` | Hooks detect frameworks, Skills reference source paths |
+
+The full strategy document is maintained in the claude-code plugin repository.

package/.claude/rules/migration-guides.md

@@ -0,0 +1,149 @@
+# Migration Guide Creation Process
+
+This document describes the process for creating migration guides when releasing new versions of @lenne.tech/nest-server.
+
+## When to Create a Migration Guide
+
+**Versioning Context:** The MAJOR version mirrors NestJS (e.g., `11.x.x` = NestJS 11). This means MINOR can contain breaking changes and PATCH can contain new features.
+
+**Create a migration guide when consuming projects need to:**
+- Change code, configuration, or usage to use new features
+- Modify anything to keep the application working after update
+- Adapt to breaking changes or new requirements
+
+**Examples:**
+- `11.6.x → 11.7.x` - Required (new BetterAuth module, new CoreModule signature)
+- `11.7.0 → 11.7.1` - Required if new features need configuration changes
+- `11.7.1 → 11.7.2` - Not required if purely internal bugfixes with no user action needed
+
+**Rule of thumb:** If a developer needs to do anything beyond `pnpm update` to benefit from or accommodate the changes, create a migration guide.
+
+## Migration Guide Location
+
+All migration guides are stored in `migration-guides/`:
+- `migration-guides/11.6.x-to-11.7.x.md`
+- `migration-guides/TEMPLATE.md` - Template for new guides
+
+## Creation Process
+
+### Step 1: Gather Project Information
+
+**Always analyze these sources:**
+1. Local `src/server/` - Internal test implementation
+2. [nest-server-starter](https://github.com/lenneTech/nest-server-starter) - Reference project
+
+**Ask developer for additional projects:**
+```
+Which projects should I analyze for migration compatibility?
+Please provide paths to projects using @lenne.tech/nest-server.
+```
+
+### Step 2: Analyze Projects
+
+Focus on files affected by the version changes:
+- Module files (`*.module.ts`)
+- Service files (`*.service.ts`)
+- Resolver files (`*.resolver.ts`)
+- Controller files (`*.controller.ts`)
+- Configuration files (`config.env.ts`)
+
+Look for:
+- Module inheritance patterns (extending Core* classes)
+- Method overrides
+- Custom implementations
+- Version-specific features in use
+
+### Step 3: Identify Changes
+
+Categorize all changes:
+
+| Category | Description |
+|----------|-------------|
+| **Breaking Changes** | Changes that require code modifications |
+| **New Features** | New functionality (opt-in) |
+| **Bugfixes** | Corrections to existing behavior |
+| **Deprecations** | Features marked for future removal |
+
+### Step 4: Write the Guide
+
+Use `migration-guides/TEMPLATE.md` as starting point.
+
+**Required Sections:**
+1. **Overview** - Summary table with categories and effort
+2. **Quick Migration** - For non-breaking updates
+3. **What's New** - New features with examples
+4. **Breaking Changes** - Before/after code samples
+5. **Compatibility Notes** - Common patterns and their status
+6. **Troubleshooting** - Known issues and solutions
+7. **Module Documentation** - Links to affected module docs (README.md, INTEGRATION-CHECKLIST.md)
+
+**Rules:**
+- **Write ALL content in English** - This includes section titles, descriptions, explanations, and code comments. Technical terms and code identifiers remain unchanged.
+- Do NOT name specific customer projects (except nest-server-starter as reference)
+- Keep information general and pattern-based
+- Include code examples for all changes
+- Mention `npm run update` if package.json dependencies changed
+
+### Step 5: Update References
+
+After creating the guide, verify references in:
+- `CLAUDE.md` - Should link to migration-guides/
+- `CHANGELOG.md` - If it exists
+
+### Step 6: Link Module Documentation
+
+For each affected module, check for and link to:
+- `src/core/modules/<module>/README.md` - Module overview and usage
+- `src/core/modules/<module>/INTEGRATION-CHECKLIST.md` - Integration steps
+- `src/server/modules/<module>/` - Reference implementation
+
+Find existing documentation:
+```bash
+# Find all module READMEs
+ls src/core/modules/**/README.md
+
+# Find all integration checklists
+ls src/core/modules/**/INTEGRATION-CHECKLIST.md
+```
+
+## Guide Quality Checklist
+
+- [ ] **Written entirely in English**
+- [ ] Overview table is complete
+- [ ] Quick migration path provided
+- [ ] All breaking changes documented with before/after
+- [ ] New features have usage examples
+- [ ] Compatibility notes cover common patterns
+- [ ] Troubleshooting section addresses likely issues
+- [ ] Module documentation section links to affected modules
+- [ ] No customer project names mentioned
+- [ ] Code examples are tested
+
+## Example Analysis Output
+
+```markdown
+## Analysis Summary
+
+### Pattern: AuthResolver Extension
+- Found in: 4/4 analyzed projects
+- Status: Compatible
+- Notes: Projects override signIn() calling authService directly
+
+### Pattern: Custom Role Enums
+- Found in: 1/4 analyzed projects
+- Status: Compatible
+- Notes: CompanyRoles used instead of RoleEnum
+
+### Potential Issues: None identified
+```
+
+## Automation
+
+When asked to create a migration guide, Claude Code should:
+
+1. Prompt for project paths (unless already provided)
+2. Read auth, user, and configuration files from each project
+3. Compare patterns against new version requirements
+4. Generate compatibility report
+5. Create migration guide using template
+6. Verify all tests pass with new version

package/.claude/rules/module-deprecation.md

@@ -0,0 +1,214 @@
+# Module Deprecation & Migration Roadmap
+
+This document describes the deprecation strategy for Legacy Auth and the migration path to BetterAuth (IAM).
+
+## Authentication System Roadmap
+
+### v11.x (Current - Backward Compatible)
+
+- **Legacy Auth** (CoreAuthService) is available for backwards compatibility
+- **BetterAuth** (IAM) can run standalone or alongside Legacy Auth
+- **GraphQL Subscriptions** work with both systems (IAM uses BetterAuth sessions)
+- Both systems share the same user database with bidirectional sync
+- Password hashes use different algorithms (Legacy: `bcrypt(sha256(pw))`, IAM: `scrypt(sha256(pw))`)
+
+**Key Configuration:**
+
+```typescript
+// config.env.ts
+{
+  // Legacy Auth configuration (optional, for backwards compatibility)
+  jwt: {
+    secret: 'YOUR_JWT_SECRET',
+    refresh: { secret: 'YOUR_REFRESH_SECRET' }
+  },
+
+  // BetterAuth configuration (optional, runs in parallel)
+  betterAuth: {
+    enabled: true,
+    secret: 'YOUR_BETTERAUTH_SECRET',
+    // ...
+  },
+
+  // NEW in v11.7.x: Disable legacy endpoints after migration
+  auth: {
+    legacyEndpoints: {
+      enabled: true  // Set to false after all users migrated
+    }
+  }
+}
+```
+
+**CoreModule.forRoot Signatures:**
+
+```typescript
+// IAM-Only (recommended for new projects)
+CoreModule.forRoot(envConfig)
+
+// Legacy + IAM (for existing projects during migration)
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig)
+```
+
+### Future Version (Planned - Breaking Change)
+
+- **BetterAuth** (IAM) becomes the default authentication system
+- **Legacy Auth** becomes optional (must be explicitly enabled)
+- Simplified CoreModule.forRoot signature becomes the only option
+- Legacy Auth removed from codebase
+
+**New Configuration:**
+
+```typescript
+// config.env.ts
+{
+  // BetterAuth is now the default
+  betterAuth: {
+    secret: 'YOUR_BETTERAUTH_SECRET',
+    // ...
+  },
+
+  // Legacy Auth is optional (enable only if needed)
+  auth: {
+    legacy: {
+      enabled: false  // Explicitly enable if still needed
+    }
+  }
+}
+```
+
+**Simplified CoreModule.forRoot Signature:**
+
+```typescript
+// Future version: Single parameter
+CoreModule.forRoot(envConfig)
+```
+
+## Migration Path for Projects
+
+### Phase 1: Enable BetterAuth (v11.x)
+
+1. Ensure `betterAuth` is configured in `config.env.ts`
+2. Integrate BetterAuthModule in your project (see INTEGRATION-CHECKLIST.md)
+3. Both auth systems run in parallel
+
+### Phase 2: Monitor Migration
+
+Use the `betterAuthMigrationStatus` GraphQL query (admin only):
+
+```graphql
+query {
+  betterAuthMigrationStatus {
+    totalUsers
+    fullyMigratedUsers
+    pendingMigrationUsers
+    migrationPercentage
+    canDisableLegacyAuth
+    pendingUserEmails
+  }
+}
+```
+
+Users migrate automatically when they:
+- Sign in via BetterAuth (IAM) endpoints
+- Use social login (if configured)
+- Use passkey authentication (if configured)
+
+### Phase 3: Disable Legacy Endpoints
+
+Once `canDisableLegacyAuth` is `true`:
+
+```typescript
+// config.env.ts
+auth: {
+  legacyEndpoints: {
+    enabled: false  // Disable all legacy endpoints
+    // Or disable selectively:
+    // graphql: false  // Disable only GraphQL endpoints
+    // rest: false     // Disable only REST endpoints
+  }
+}
+```
+
+Legacy endpoint calls will return HTTP 410 Gone.
+
+### Phase 4: Upgrade to Future Version
+
+When upgrading to the future version with BetterAuth as default:
+
+1. Update `package.json` dependency
+2. Simplify `CoreModule.forRoot` call:
+
+```typescript
+// Before (v11.x)
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig)
+
+// After (future version)
+CoreModule.forRoot(envConfig)
+```
+
+3. Remove Legacy Auth configuration if no longer needed
+
+## Password Hash Incompatibility
+
+**Why parallel operation is necessary:**
+
+| System | Hash Algorithm |
+|--------|----------------|
+| Legacy Auth | `bcrypt(sha256(password))` |
+| BetterAuth | `scrypt(sha256(password))` |
+
+These algorithms are **one-way** - there is no migration script possible.
+Users must sign in at least once via BetterAuth to create a new hash.
+
+## Configuration Reference
+
+### auth.legacyEndpoints (v11.7.x+)
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable all legacy endpoints |
+| `graphql` | boolean | inherits `enabled` | Enable/disable GraphQL endpoints only |
+| `rest` | boolean | inherits `enabled` | Enable/disable REST endpoints only |
+
+### Legacy Endpoints Affected
+
+**GraphQL Mutations:**
+- `signIn` - Sign in via email/password
+- `signUp` - Register new account
+- `logout` - Sign out
+- `refreshToken` - Refresh JWT tokens
+
+**REST Endpoints:**
+- `POST /auth/signin` - Sign in via email/password
+- `POST /auth/signup` - Register new account
+- `GET /auth/logout` - Sign out
+- `GET /auth/refresh-token` - Refresh JWT tokens
+
+## IAuthProvider Interface (v11.7.x+)
+
+The `IAuthProvider` interface abstracts authentication operations:
+
+```typescript
+interface IAuthProvider {
+  decodeJwt(token: string): JwtPayload;
+  validateUser(payload: JwtPayload): Promise<any>;
+  signToken(user: any, expiresIn?: string): string;
+}
+```
+
+In a future version, this interface will be used by CoreModule.forRoot to support
+both Legacy Auth and BetterAuth transparently.
+
+## Timeline
+
+| Version | Status | Changes |
+|---------|--------|---------|
+| v11.6.x | Released | BetterAuth introduced |
+| v11.7.x | Current | Legacy endpoint controls, IAuthProvider, migration status |
+| Future | Planned | BetterAuth default, simplified API, Legacy optional |
+
+## Related Documentation
+
+- [BetterAuth Integration Checklist](../../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- [Module Inheritance Pattern](./module-inheritance.md)
+- [Role System](./role-system.md)