Merge pull request #462 from lenneTech/develop

Release 11.7.0

Author: kaihaase

.claude/rules/architecture.md

@@ -0,0 +1,69 @@
+# Code Architecture
+
+## Framework Stack
+
+- **NestJS** - Server framework
+- **GraphQL** - API layer (Apollo Server)
+- **MongoDB** - Database (Mongoose ODM)
+
+## Two-Layer Structure
+
+1. **Core Layer** (`src/core/`) - Reusable framework components (exported to consumers)
+2. **Server Layer** (`src/server/`) - Internal test/demo implementation (not exported)
+
+## Core Module (`src/core.module.ts`)
+
+- Dynamic module providing base functionality
+- Configures GraphQL with Apollo Server, MongoDB with Mongoose
+- Provides global services: ConfigService, EmailService, TemplateService
+- Sets up security interceptors, validation pipes, complexity plugins
+- Handles GraphQL subscriptions with authentication
+
+## Configuration System (`src/config.env.ts`)
+
+Environment-based configuration (development, local, production) with multiple sources:
+
+- Direct environment variables in config file
+- `NEST_SERVER_CONFIG` JSON environment variable
+- `NSC__*` prefixed single environment variables
+
+Key areas: JWT, MongoDB, GraphQL, email, security, static assets
+
+## Core Common Components (`src/core/common/`)
+
+| Type | Components |
+|------|------------|
+| **Decorators** | `@Restricted()`, `@Roles()`, `@CurrentUser()`, `@UnifiedField()` |
+| **Helpers** | Database, GraphQL, filtering, validation utilities |
+| **Security** | Response/security interceptors, input validation pipes |
+| **Scalars** | Custom GraphQL scalars (Date, JSON, Any) |
+| **Services** | CRUD operations, email (Mailjet/SMTP), template rendering |
+
+## Core Modules (`src/core/modules/`)
+
+| Module | Purpose |
+|--------|---------|
+| **Auth** | JWT authentication, refresh tokens, role-based access |
+| **BetterAuth** | Modern auth integration (2FA, Passkey, Social) |
+| **File** | File upload/download with GridFS storage |
+| **User** | Core user management functionality |
+| **HealthCheck** | Application health monitoring |
+
+## Security Implementation
+
+- `@Restricted()` - Field-level access control
+- `@Roles()` - Method-level authorization
+- `CheckResponseInterceptor` - Filters restricted fields
+- `CheckSecurityInterceptor` - Processes `securityCheck()` methods
+
+## Model Inheritance
+
+- `CorePersistenceModel` - Base for database entities
+- `CoreModel` - Base for GraphQL types
+- Automatic ID handling with custom Mongoose plugin
+
+## Input Validation
+
+- `MapAndValidatePipe` - Automatic validation
+- class-validator decorators on input classes
+- Core args classes for filtering/pagination

.claude/rules/core-modules.md

@@ -0,0 +1,74 @@
+---
+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
+
+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)
+```
+
+## Testing
+
+- Create story tests in `tests/stories/`
+- Test through API (REST/GraphQL), not direct service calls
+- Include security tests for authentication/authorization

.claude/rules/module-inheritance.md

@@ -0,0 +1,64 @@
+# Module Inheritance Pattern
+
+**This is a fundamental architectural pattern that MUST be followed for all new modules in `src/core/modules/`.**
+
+## Why Inheritance Over Hooks/Events
+
+Core modules (like `AuthModule`, `BetterAuthModule`, `FileModule`) are designed to be **extended through inheritance** in consuming projects, not manipulated through hooks, events, or other workarounds. This provides:
+
+1. **Full Control**: Projects can override methods and precisely define what happens before/after `super()` calls
+2. **Flexibility**: Parts of the parent implementation can be skipped entirely for custom logic
+3. **Type Safety**: TypeScript inheritance ensures proper typing and IDE support
+4. **Robustness**: No runtime event systems or hooks that can fail silently
+
+## Pattern Structure
+
+```typescript
+// src/core/modules/example/core-example.resolver.ts (in nest-server)
+@Resolver()
+export class CoreExampleResolver {
+  async someMethod() { /* base implementation */ }
+}
+
+// src/server/modules/example/example.resolver.ts (in consuming project)
+@Resolver()
+export class ExampleResolver extends CoreExampleResolver {
+  override async someMethod() {
+    // Custom pre-processing
+    const result = await super.someMethod();  // Or skip for full override
+    // Custom post-processing
+    return result;
+  }
+}
+```
+
+## Module Registration Options
+
+Core modules should support both:
+
+1. **Auto-registration** (`autoRegister: true`) - For simple projects without customization
+2. **Manual registration** (`autoRegister: false`, default) - Projects integrate via extended module
+
+```typescript
+// config.env.ts - auto-registration for simple projects
+betterAuth: { autoRegister: true }
+
+// server.module.ts - manual registration with custom resolver (recommended)
+BetterAuthModule.forRoot({ config, resolver: CustomResolver })
+```
+
+## Examples in Codebase
+
+- `CoreAuthService` → extended by project's `AuthService`
+- `CoreBetterAuthResolver` → extended by project's `BetterAuthResolver`
+- `CoreUserService` → extended by project's `UserService`
+
+## Checklist for New Core Modules
+
+When adding new core modules, ensure:
+
+- [ ] Base classes in `src/core/modules/` with `Core` prefix
+- [ ] Methods are `protected` or `public` (not `private`) to allow override
+- [ ] `autoRegister` option defaults to `false`
+- [ ] Clear documentation for extension points
+- [ ] Export base classes via `src/index.ts`

.claude/rules/role-system.md

@@ -0,0 +1,51 @@
+# Role System (RoleEnum)
+
+The role system distinguishes between **real roles** and **system roles**.
+
+## Real Roles
+
+Actual roles stored in `user.roles` array in the database:
+
+- `RoleEnum.ADMIN` - Administrator role
+
+## System Roles (S_ Prefix)
+
+System roles are used for **runtime checks only** and must **NEVER** be stored in `user.roles`:
+
+| Role | Purpose | Check Logic |
+|------|---------|-------------|
+| `S_USER` | User is logged in | `currentUser` exists |
+| `S_VERIFIED` | User is verified | `user.verified \|\| user.verifiedAt \|\| user.emailVerified` |
+| `S_CREATOR` | User created the object | `object.createdBy === user.id` |
+| `S_SELF` | User is accessing own data | `object.id === user.id` |
+| `S_EVERYONE` | Public access | Always true |
+| `S_NO_ONE` | Locked access | Always false |
+
+## Critical Rule
+
+```typescript
+// CORRECT: Using S_ roles in decorators (runtime checks)
+@Roles(RoleEnum.S_USER)
+@Restricted(RoleEnum.S_VERIFIED)
+
+// WRONG: Storing S_ roles in user.roles array
+roles: [RoleEnum.S_USER]  // NEVER do this!
+
+// CORRECT: Empty roles or real roles only
+roles: []                  // Empty array
+roles: [RoleEnum.ADMIN]    // Real role
+```
+
+The `S_` prefix indicates a **system check**, not an actual role. These are evaluated dynamically at runtime based on context (current user, request, object being accessed).
+
+## Role Decorators
+
+- `@Roles(RoleEnum.ADMIN)` - Method-level authorization
+- `@Restricted(RoleEnum.S_VERIFIED)` - Field-level access control
+
+## Role Check Implementation
+
+The role system is evaluated in:
+- `RolesGuard` - Checks method-level `@Roles()` decorators
+- `CheckResponseInterceptor` - Filters fields based on `@Restricted()` decorators
+- `CheckSecurityInterceptor` - Processes `securityCheck()` methods

.claude/rules/testing.md

@@ -0,0 +1,79 @@
+# Testing Configuration
+
+## Test Framework
+
+- **Vitest** - Primary test framework (migrated from Jest)
+- Configuration: `vitest.config.ts`
+- Test files: `tests/` directory with `.e2e-spec.ts` suffix
+
+## Running Tests
+
+```bash
+# Run all E2E tests (default)
+npm test
+
+# Run with coverage
+npm run test:cov
+
+# Run in CI mode
+npm run test:ci
+
+# Debug open handles
+npm run test:e2e-doh
+```
+
+## Test Environment
+
+- Environment: `NODE_ENV=local`
+- Database: Local MongoDB instance (`mongodb://127.0.0.1/nest-server-local`)
+- Test helper: `src/test/test.helper.ts`
+- Coverage: Collected from `src/**/*.{ts,js}`
+
+## Test Best Practices
+
+1. **Always run tests before completing changes**: `npm test`
+2. **Production-ready = all tests pass** without errors
+3. **Use TestHelper** for GraphQL and REST API testing
+4. **Clean up test data** in `afterAll` hooks
+5. **Unique test data** - Use timestamps/random strings to avoid conflicts
+
+## Test File Structure
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { TestHelper } from '../../src';
+
+describe('Feature Name', () => {
+  let testHelper: TestHelper;
+
+  beforeAll(async () => {
+    const moduleFixture = await Test.createTestingModule({
+      imports: [ServerModule],
+    }).compile();
+
+    const app = moduleFixture.createNestApplication();
+    await app.init();
+    testHelper = new TestHelper(app);
+  });
+
+  afterAll(async () => {
+    // Cleanup test data
+    await app.close();
+  });
+
+  it('should do something', async () => {
+    const result = await testHelper.graphQl({
+      name: 'someQuery',
+      type: TestGraphQLType.QUERY,
+      fields: ['id', 'name'],
+    });
+    expect(result.data.someQuery).toBeDefined();
+  });
+});
+```
+
+## Common Test Issues
+
+- **Tests timeout**: Ensure MongoDB is running
+- **Open handles**: Use `npm run test:e2e-doh` to debug
+- **Data conflicts**: Use unique identifiers per test

.claude/rules/versioning.md

@@ -0,0 +1,53 @@
+# Versioning Strategy
+
+## Version Schema: `MAJOR.MINOR.PATCH`
+
+| Part    | Meaning                                                            |
+|---------|--------------------------------------------------------------------|
+| `MAJOR` | Mirrors the NestJS major version (e.g., `11.x.x` = NestJS 11)      |
+| `MINOR` | Breaking changes or significant restructuring                      |
+| `PATCH` | Improvements (bugfixes) or additions (new features) - non-breaking |
+
+## Examples
+
+- `11.0.0` → Initial release for NestJS 11
+- `11.1.0` → Breaking change or major restructuring within NestJS 11
+- `11.1.5` → Bugfix or new feature (backward compatible)
+
+## Important Rules
+
+1. **Document breaking changes** clearly in commit messages when incrementing MINOR version
+2. **Update nest-server-starter** with migration instructions for breaking changes
+3. **Consider downstream impact** - this package is used by multiple projects
+
+## Release Process
+
+1. Make changes and ensure all tests pass (`npm test`)
+2. Update version in `package.json`
+3. Build the package (`npm run build`)
+4. Publish to npm
+5. Update and test in [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
+6. Commit changes to starter with migration notes
+
+## Package Distribution
+
+- **NPM Package**: `@lenne.tech/nest-server`
+- **Main entry**: `dist/index.js`
+- **Types**: `dist/index.d.ts`
+- **Public APIs**: Exported from `src/index.ts`
+
+## Package Development Commands
+
+```bash
+# Build and push to yalc for local testing
+npm run build:dev
+
+# Create tarball for integration testing
+npm run build:pack
+
+# Clean reinstall with tests and build
+npm run reinit
+
+# Watch for changes
+npm run watch
+```