11.7.1: Add BetterAuth parallel operation with migration status tracking, legacy endpoint controls, and bidirectional user sync

Author: kaihaase

.claude/commands/create-migration-guide.md

@@ -0,0 +1,113 @@
+# Create Migration Guide
+
+Create a migration guide for the current version changes.
+
+## Instructions
+
+### Step 1: Check Version Status
+
+First, check if the package version has been modified since the last release:
+
+```bash
+# Get current version from package.json
+CURRENT_VERSION=$(node -p "require('./package.json').version")
+
+# Get the last released version (latest git tag)
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
+
+# Check if package.json was modified
+git diff --name-only HEAD~10 | grep -q "package.json" && echo "package.json modified" || echo "package.json unchanged"
+```
+
+### Step 2: Determine Version
+
+Compare the current version with the last tag:
+
+- If versions match: Suggest incrementing PATCH version (e.g., 11.7.1 → 11.7.2)
+- If MINOR already incremented: Use current version for migration guide
+- Present options to the user:
+  - Use current version
+  - Increment PATCH (bugfix)
+  - Increment MINOR (breaking change / new features)
+
+### Step 3: Check for Existing Migration Guide
+
+Check if a migration guide already exists for this version range:
+
+```bash
+ls migration-guides/*.md
+```
+
+If a guide exists for the current MINOR version range (e.g., 11.6.x-to-11.7.x), ask user:
+- Update existing guide
+- Create new guide for next version
+
+### Step 4: Analyze Changes
+
+Analyze changes since last release:
+
+```bash
+# Get commits since last tag
+git log $LAST_TAG..HEAD --oneline
+
+# Get changed files
+git diff --name-only $LAST_TAG..HEAD
+```
+
+Focus on:
+- `src/core/` changes (breaking changes, new features)
+- `src/core/modules/` changes (module-specific updates)
+- `package.json` dependency changes
+
+### Step 5: Gather Project Information
+
+Ask the user:
+> Which projects should I analyze for migration compatibility?
+> Please provide paths to projects using @lenne.tech/nest-server.
+> (Leave empty to only analyze src/server/ and nest-server-starter)
+
+Always analyze:
+1. Local `src/server/`
+2. [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
+
+### Step 6: Create Migration Guide
+
+Use the template at `migration-guides/TEMPLATE.md` and follow the process in `.claude/rules/migration-guides.md`.
+
+Required sections:
+1. Overview table
+2. Quick Migration
+3. What's New
+4. Breaking Changes (if any)
+5. Compatibility Notes
+6. Troubleshooting
+7. Module Documentation (link to affected module READMEs and INTEGRATION-CHECKLISTs)
+
+### Step 7: Verify
+
+After creating the guide:
+1. Run `npm run build` to verify no build errors
+2. Run `npm test` to verify all tests pass
+3. Present summary to user
+
+## Output Format
+
+Present the analysis as:
+
+```
+## Version Analysis
+
+Current version: X.Y.Z
+Last release: X.Y.W (tag: vX.Y.W)
+Version status: [unchanged | patch needed | minor needed]
+
+## Suggested Version: X.Y.Z
+
+## Changes Since Last Release
+- [List of significant changes]
+
+## Migration Guide: X.Y.x → X.Z.x
+- Breaking Changes: [count]
+- New Features: [count]
+- Bugfixes: [count]
+```

.claude/rules/configurable-features.md

@@ -0,0 +1,122 @@
+# Configurable Features Pattern
+
+This document describes the standard pattern for implementing optional, configurable features in @lenne.tech/nest-server.
+
+## "Presence Implies Enabled" Pattern
+
+When implementing configurable features, follow this pattern for activation logic:
+
+### Rules
+
+1. **No configuration** (`undefined` or `null`): Feature is **disabled** (backward compatible)
+2. **Empty object** (`{}`): Feature is **enabled** with all default values
+3. **Partial configuration** (`{ max: 5 }`): Feature is **enabled**, missing values use defaults
+4. **Explicit disable** (`{ enabled: false, ... }`): Feature is **disabled**, allows pre-configuration
+
+### Benefits
+
+- **Backward Compatible**: Existing projects without config continue to work unchanged
+- **Efficient**: No need to set `enabled: true` redundantly when already providing config
+- **Flexible**: Can pre-configure without activating via `enabled: false`
+- **Intuitive**: Providing a config object signals intent to use the feature
+
+### Implementation Example
+
+```typescript
+interface IFeatureConfig {
+  enabled?: boolean;  // Optional - presence of config implies true
+  max?: number;
+  windowSeconds?: number;
+}
+
+const DEFAULT_CONFIG: Required<IFeatureConfig> = {
+  enabled: false,  // Default is false, but overridden by presence
+  max: 10,
+  windowSeconds: 60,
+};
+
+class FeatureService {
+  private config: Required<IFeatureConfig> = DEFAULT_CONFIG;
+
+  /**
+   * Configure the feature
+   *
+   * Follows the "presence implies enabled" pattern:
+   * - If config is undefined/null: feature stays disabled (backward compatible)
+   * - If config is an object (even empty {}): feature is enabled by default
+   * - Unless `enabled: false` is explicitly set
+   */
+  configure(config: IFeatureConfig | undefined | null): void {
+    // No config = stay disabled (backward compatible)
+    if (config === undefined || config === null) {
+      return;
+    }
+
+    // Presence of config implies enabled, unless explicitly disabled
+    const enabled = config.enabled !== false;
+
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+      enabled,
+    };
+  }
+}
+```
+
+### Usage Examples
+
+```typescript
+// config.env.ts
+
+// Feature disabled (no config)
+// rateLimit: undefined  // or just don't define it
+
+// Feature enabled with all defaults
+auth: {
+  rateLimit: {}
+}
+
+// Feature enabled with custom max
+auth: {
+  rateLimit: { max: 20 }
+}
+
+// Feature enabled with full configuration
+auth: {
+  rateLimit: {
+    max: 10,
+    windowSeconds: 60,
+    message: 'Too many requests'
+  }
+}
+
+// Pre-configured but disabled (for testing or gradual rollout)
+auth: {
+  rateLimit: {
+    enabled: false,
+    max: 10,
+    windowSeconds: 60
+  }
+}
+```
+
+## Applied Features
+
+This pattern is currently applied to:
+
+| Feature | Config Path | Default Values |
+|---------|-------------|----------------|
+| Legacy Auth Rate Limiting | `auth.rateLimit` | `max: 10`, `windowSeconds: 60` |
+| BetterAuth Rate Limiting | `betterAuth.rateLimit` | `max: 10`, `windowSeconds: 60` |
+
+## Checklist for New Configurable Features
+
+When adding a new configurable feature:
+
+- [ ] Define interface with `enabled?: boolean` as optional property
+- [ ] Set `enabled: false` in DEFAULT_CONFIG
+- [ ] Implement "presence implies enabled" logic in configure method
+- [ ] Document all default values in interface JSDoc
+- [ ] Add tests for: undefined config, empty object, partial config, explicit disable
+- [ ] Update this document with the new feature

.claude/rules/core-modules.md

@@ -67,8 +67,120 @@ 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.)