opencode-skills-collection 4.0.53 → 4.0.54

package/bundled-skills/nestjs-expert/SKILL.md

@@ -26,531 +26,9 @@ You are an expert in Nest.js with deep knowledge of enterprise-grade Node.js app
 3. Apply appropriate solutions following Nest.js best practices
 4. Validate in order: typecheck → unit tests → integration tests → e2e tests
 
-## Domain Coverage
+## Detailed Guide
 
-### Module Architecture & Dependency Injection
-- Common issues: Circular dependencies, provider scope conflicts, module imports
-- Root causes: Incorrect module boundaries, missing exports, improper injection tokens
-- Solution priority: 1) Refactor module structure, 2) Use forwardRef, 3) Adjust provider scope
-- Tools: `nest generate module`, `nest generate service`
-- Resources: [Nest.js Modules](https://docs.nestjs.com/modules), [Providers](https://docs.nestjs.com/providers)
-
-### Controllers & Request Handling
-- Common issues: Route conflicts, DTO validation, response serialization
-- Root causes: Decorator misconfiguration, missing validation pipes, improper interceptors
-- Solution priority: 1) Fix decorator configuration, 2) Add validation, 3) Implement interceptors
-- Tools: `nest generate controller`, class-validator, class-transformer
-- Resources: [Controllers](https://docs.nestjs.com/controllers), [Validation](https://docs.nestjs.com/techniques/validation)
-
-### Middleware, Guards, Interceptors & Pipes
-- Common issues: Execution order, context access, async operations
-- Root causes: Incorrect implementation, missing async/await, improper error handling
-- Solution priority: 1) Fix execution order, 2) Handle async properly, 3) Implement error handling
-- Execution order: Middleware → Guards → Interceptors (before) → Pipes → Route handler → Interceptors (after)
-- Resources: [Middleware](https://docs.nestjs.com/middleware), [Guards](https://docs.nestjs.com/guards)
-
-### Testing Strategies (Jest & Supertest)
-- Common issues: Mocking dependencies, testing modules, e2e test setup
-- Root causes: Improper test module creation, missing mock providers, incorrect async handling
-- Solution priority: 1) Fix test module setup, 2) Mock dependencies correctly, 3) Handle async tests
-- Tools: `@nestjs/testing`, Jest, Supertest
-- Resources: [Testing](https://docs.nestjs.com/fundamentals/testing)
-
-### Database Integration (TypeORM & Mongoose)
-- Common issues: Connection management, entity relationships, migrations
-- Root causes: Incorrect configuration, missing decorators, improper transaction handling
-- Solution priority: 1) Fix configuration, 2) Correct entity setup, 3) Implement transactions
-- TypeORM: `@nestjs/typeorm`, entity decorators, repository pattern
-- Mongoose: `@nestjs/mongoose`, schema decorators, model injection
-- Resources: [TypeORM](https://docs.nestjs.com/techniques/database), [Mongoose](https://docs.nestjs.com/techniques/mongodb)
-
-### Authentication & Authorization (Passport.js)
-- Common issues: Strategy configuration, JWT handling, guard implementation
-- Root causes: Missing strategy setup, incorrect token validation, improper guard usage
-- Solution priority: 1) Configure Passport strategy, 2) Implement guards, 3) Handle JWT properly
-- Tools: `@nestjs/passport`, `@nestjs/jwt`, passport strategies
-- Resources: [Authentication](https://docs.nestjs.com/security/authentication), [Authorization](https://docs.nestjs.com/security/authorization)
-
-### Configuration & Environment Management
-- Common issues: Environment variables, configuration validation, async configuration
-- Root causes: Missing config module, improper validation, incorrect async loading
-- Solution priority: 1) Setup ConfigModule, 2) Add validation, 3) Handle async config
-- Tools: `@nestjs/config`, Joi validation
-- Resources: [Configuration](https://docs.nestjs.com/techniques/configuration)
-
-### Error Handling & Logging
-- Common issues: Exception filters, logging configuration, error propagation
-- Root causes: Missing exception filters, improper logger setup, unhandled promises
-- Solution priority: 1) Implement exception filters, 2) Configure logger, 3) Handle all errors
-- Tools: Built-in Logger, custom exception filters
-- Resources: [Exception Filters](https://docs.nestjs.com/exception-filters), [Logger](https://docs.nestjs.com/techniques/logger)
-
-## Environmental Adaptation
-
-### Detection Phase
-I analyze the project to understand:
-- Nest.js version and configuration
-- Module structure and organization
-- Database setup (TypeORM/Mongoose/Prisma)
-- Testing framework configuration
-- Authentication implementation
-
-Detection commands:
-```bash
-# Check Nest.js setup
-test -f nest-cli.json && echo "Nest.js CLI project detected"
-grep -q "@nestjs/core" package.json && echo "Nest.js framework installed"
-test -f tsconfig.json && echo "TypeScript configuration found"
-
-# Detect Nest.js version
-grep "@nestjs/core" package.json | sed 's/.*"\([0-9\.]*\)".*/Nest.js version: \1/'
-
-# Check database setup
-grep -q "@nestjs/typeorm" package.json && echo "TypeORM integration detected"
-grep -q "@nestjs/mongoose" package.json && echo "Mongoose integration detected"
-grep -q "@prisma/client" package.json && echo "Prisma ORM detected"
-
-# Check authentication
-grep -q "@nestjs/passport" package.json && echo "Passport authentication detected"
-grep -q "@nestjs/jwt" package.json && echo "JWT authentication detected"
-
-# Analyze module structure
-find src -name "*.module.ts" -type f | head -5 | xargs -I {} basename {} .module.ts
-```
-
-**Safety note**: Avoid watch/serve processes; use one-shot diagnostics only.
-
-### Adaptation Strategies
-- Match existing module patterns and naming conventions
-- Follow established testing patterns
-- Respect database strategy (repository pattern vs active record)
-- Use existing authentication guards and strategies
-
-## Tool Integration
-
-### Diagnostic Tools
-```bash
-# Analyze module dependencies
-nest info
-
-# Check for circular dependencies
-npm run build -- --watch=false
-
-# Validate module structure
-npm run lint
-```
-
-### Fix Validation
-```bash
-# Verify fixes (validation order)
-npm run build          # 1. Typecheck first
-npm run test           # 2. Run unit tests
-npm run test:e2e       # 3. Run e2e tests if needed
-```
-
-**Validation order**: typecheck → unit tests → integration tests → e2e tests
-
-## Problem-Specific Approaches (Real Issues from GitHub & Stack Overflow)
-
-### 1. "Nest can't resolve dependencies of the [Service] (?)"
-**Frequency**: HIGHEST (500+ GitHub issues) | **Complexity**: LOW-MEDIUM
-**Real Examples**: GitHub #3186, #886, #2359 | SO 75483101
-When encountering this error:
-1. Check if provider is in module's providers array
-2. Verify module exports if crossing boundaries  
-3. Check for typos in provider names (GitHub #598 - misleading error)
-4. Review import order in barrel exports (GitHub #9095)
-
-### 2. "Circular dependency detected"
-**Frequency**: HIGH | **Complexity**: HIGH
-**Real Examples**: SO 65671318 (32 votes) | Multiple GitHub discussions
-Community-proven solutions:
-1. Use forwardRef() on BOTH sides of the dependency
-2. Extract shared logic to a third module (recommended)
-3. Consider if circular dependency indicates design flaw
-4. Note: Community warns forwardRef() can mask deeper issues
-
-### 3. "Cannot test e2e because Nestjs doesn't resolve dependencies"
-**Frequency**: HIGH | **Complexity**: MEDIUM
-**Real Examples**: SO 75483101, 62942112, 62822943
-Proven testing solutions:
-1. Use @golevelup/ts-jest for createMock() helper
-2. Mock JwtService in test module providers
-3. Import all required modules in Test.createTestingModule()
-4. For Bazel users: Special configuration needed (SO 62942112)
-
-### 4. "[TypeOrmModule] Unable to connect to the database"
-**Frequency**: MEDIUM | **Complexity**: HIGH  
-**Real Examples**: GitHub typeorm#1151, #520, #2692
-Key insight - this error is often misleading:
-1. Check entity configuration - @Column() not @Column('description')
-2. For multiple DBs: Use named connections (GitHub #2692)
-3. Implement connection error handling to prevent app crash (#520)
-4. SQLite: Verify database file path (typeorm#8745)
-
-### 5. "Unknown authentication strategy 'jwt'"
-**Frequency**: HIGH | **Complexity**: LOW
-**Real Examples**: SO 79201800, 74763077, 62799708
-Common JWT authentication fixes:
-1. Import Strategy from 'passport-jwt' NOT 'passport-local'
-2. Ensure JwtModule.secret matches JwtStrategy.secretOrKey
-3. Check Bearer token format in Authorization header
-4. Set JWT_SECRET environment variable
-
-### 6. "ActorModule exporting itself instead of ActorService"
-**Frequency**: MEDIUM | **Complexity**: LOW
-**Real Example**: GitHub #866
-Module export configuration fix:
-1. Export the SERVICE not the MODULE from exports array
-2. Common mistake: exports: [ActorModule] → exports: [ActorService]
-3. Check all module exports for this pattern
-4. Validate with nest info command
-
-### 7. "secretOrPrivateKey must have a value" (JWT)
-**Frequency**: HIGH | **Complexity**: LOW
-**Real Examples**: Multiple community reports
-JWT configuration fixes:
-1. Set JWT_SECRET in environment variables
-2. Check ConfigModule loads before JwtModule
-3. Verify .env file is in correct location
-4. Use ConfigService for dynamic configuration
-
-### 8. Version-Specific Regressions
-**Frequency**: LOW | **Complexity**: MEDIUM
-**Real Example**: GitHub #2359 (v6.3.1 regression)
-Handling version-specific bugs:
-1. Check GitHub issues for your specific version
-2. Try downgrading to previous stable version
-3. Update to latest patch version
-4. Report regressions with minimal reproduction
-
-### 9. "Nest can't resolve dependencies of the UserController (?, +)"
-**Frequency**: HIGH | **Complexity**: LOW
-**Real Example**: GitHub #886
-Controller dependency resolution:
-1. The "?" indicates missing provider at that position
-2. Count constructor parameters to identify which is missing
-3. Add missing service to module providers
-4. Check service is properly decorated with @Injectable()
-
-### 10. "Nest can't resolve dependencies of the Repository" (Testing)
-**Frequency**: MEDIUM | **Complexity**: MEDIUM
-**Real Examples**: Community reports
-TypeORM repository testing:
-1. Use getRepositoryToken(Entity) for provider token
-2. Mock DataSource in test module
-3. Provide test database connection
-4. Consider mocking repository completely
-
-### 11. "Unauthorized 401 (Missing credentials)" with Passport JWT
-**Frequency**: HIGH | **Complexity**: LOW
-**Real Example**: SO 74763077
-JWT authentication debugging:
-1. Verify Authorization header format: "Bearer [token]"
-2. Check token expiration (use longer exp for testing)
-3. Test without nginx/proxy to isolate issue
-4. Use jwt.io to decode and verify token structure
-
-### 12. Memory Leaks in Production
-**Frequency**: LOW | **Complexity**: HIGH
-**Real Examples**: Community reports
-Memory leak detection and fixes:
-1. Profile with node --inspect and Chrome DevTools
-2. Remove event listeners in onModuleDestroy()
-3. Close database connections properly
-4. Monitor heap snapshots over time
-
-### 13. "More informative error message when dependencies are improperly setup"
-**Frequency**: N/A | **Complexity**: N/A
-**Real Example**: GitHub #223 (Feature Request)
-Debugging dependency injection:
-1. NestJS errors are intentionally generic for security
-2. Use verbose logging during development
-3. Add custom error messages in your providers
-4. Consider using dependency injection debugging tools
-
-### 14. Multiple Database Connections
-**Frequency**: MEDIUM | **Complexity**: MEDIUM
-**Real Example**: GitHub #2692
-Configuring multiple databases:
-1. Use named connections in TypeOrmModule
-2. Specify connection name in @InjectRepository()
-3. Configure separate connection options
-4. Test each connection independently
-
-### 15. "Connection with sqlite database is not established"
-**Frequency**: LOW | **Complexity**: LOW
-**Real Example**: typeorm#8745
-SQLite-specific issues:
-1. Check database file path is absolute
-2. Ensure directory exists before connection
-3. Verify file permissions
-4. Use synchronize: true for development
-
-### 16. Misleading "Unable to connect" Errors
-**Frequency**: MEDIUM | **Complexity**: HIGH
-**Real Example**: typeorm#1151
-True causes of connection errors:
-1. Entity syntax errors show as connection errors
-2. Wrong decorator usage: @Column() not @Column('description')
-3. Missing decorators on entity properties
-4. Always check entity files when connection errors occur
-
-### 17. "Typeorm connection error breaks entire nestjs application"
-**Frequency**: MEDIUM | **Complexity**: MEDIUM
-**Real Example**: typeorm#520
-Preventing app crash on DB failure:
-1. Wrap connection in try-catch in useFactory
-2. Allow app to start without database
-3. Implement health checks for DB status
-4. Use retryAttempts and retryDelay options
-
-## Common Patterns & Solutions
-
-### Module Organization
-```typescript
-// Feature module pattern
-@Module({
-  imports: [CommonModule, DatabaseModule],
-  controllers: [FeatureController],
-  providers: [FeatureService, FeatureRepository],
-  exports: [FeatureService] // Export for other modules
-})
-export class FeatureModule {}
-```
-
-### Custom Decorator Pattern
-```typescript
-// Combine multiple decorators
-export const Auth = (...roles: Role[]) => 
-  applyDecorators(
-    UseGuards(JwtAuthGuard, RolesGuard),
-    Roles(...roles),
-  );
-```
-
-### Testing Pattern
-```typescript
-// Comprehensive test setup
-beforeEach(async () => {
-  const module = await Test.createTestingModule({
-    providers: [
-      ServiceUnderTest,
-      {
-        provide: DependencyService,
-        useValue: mockDependency,
-      },
-    ],
-  }).compile();
-  
-  service = module.get<ServiceUnderTest>(ServiceUnderTest);
-});
-```
-
-### Exception Filter Pattern
-```typescript
-@Catch(HttpException)
-export class HttpExceptionFilter implements ExceptionFilter {
-  catch(exception: HttpException, host: ArgumentsHost) {
-    // Custom error handling
-  }
-}
-```
-
-## Code Review Checklist
-
-When reviewing Nest.js applications, focus on:
-
-### Module Architecture & Dependency Injection
-- [ ] All services are properly decorated with @Injectable()
-- [ ] Providers are listed in module's providers array and exports when needed
-- [ ] No circular dependencies between modules (check for forwardRef usage)
-- [ ] Module boundaries follow domain/feature separation
-- [ ] Custom providers use proper injection tokens (avoid string tokens)
-
-### Testing & Mocking
-- [ ] Test modules use minimal, focused provider mocks
-- [ ] TypeORM repositories use getRepositoryToken(Entity) for mocking
-- [ ] No actual database dependencies in unit tests
-- [ ] All async operations are properly awaited in tests
-- [ ] JwtService and external dependencies are mocked appropriately
-
-### Database Integration (TypeORM Focus)
-- [ ] Entity decorators use correct syntax (@Column() not @Column('description'))
-- [ ] Connection errors don't crash the entire application
-- [ ] Multiple database connections use named connections
-- [ ] Database connections have proper error handling and retry logic
-- [ ] Entities are properly registered in TypeOrmModule.forFeature()
-
-### Authentication & Security (JWT + Passport)
-- [ ] JWT Strategy imports from 'passport-jwt' not 'passport-local'
-- [ ] JwtModule secret matches JwtStrategy secretOrKey exactly
-- [ ] Authorization headers follow 'Bearer [token]' format
-- [ ] Token expiration times are appropriate for use case
-- [ ] JWT_SECRET environment variable is properly configured
-
-### Request Lifecycle & Middleware
-- [ ] Middleware execution order follows: Middleware → Guards → Interceptors → Pipes
-- [ ] Guards properly protect routes and return boolean/throw exceptions
-- [ ] Interceptors handle async operations correctly
-- [ ] Exception filters catch and transform errors appropriately
-- [ ] Pipes validate DTOs with class-validator decorators
-
-### Performance & Optimization
-- [ ] Caching is implemented for expensive operations
-- [ ] Database queries avoid N+1 problems (use DataLoader pattern)
-- [ ] Connection pooling is configured for database connections
-- [ ] Memory leaks are prevented (clean up event listeners)
-- [ ] Compression middleware is enabled for production
-
-## Decision Trees for Architecture
-
-### Choosing Database ORM
-```
-Project Requirements:
-├─ Need migrations? → TypeORM or Prisma
-├─ NoSQL database? → Mongoose
-├─ Type safety priority? → Prisma
-├─ Complex relations? → TypeORM
-└─ Existing database? → TypeORM (better legacy support)
-```
-
-### Module Organization Strategy
-```
-Feature Complexity:
-├─ Simple CRUD → Single module with controller + service
-├─ Domain logic → Separate domain module + infrastructure
-├─ Shared logic → Create shared module with exports
-├─ Microservice → Separate app with message patterns
-└─ External API → Create client module with HttpModule
-```
-
-### Testing Strategy Selection
-```
-Test Type Required:
-├─ Business logic → Unit tests with mocks
-├─ API contracts → Integration tests with test database
-├─ User flows → E2E tests with Supertest
-├─ Performance → Load tests with k6 or Artillery
-└─ Security → OWASP ZAP or security middleware tests
-```
-
-### Authentication Method
-```
-Security Requirements:
-├─ Stateless API → JWT with refresh tokens
-├─ Session-based → Express sessions with Redis
-├─ OAuth/Social → Passport with provider strategies
-├─ Multi-tenant → JWT with tenant claims
-└─ Microservices → Service-to-service auth with mTLS
-```
-
-### Caching Strategy
-```
-Data Characteristics:
-├─ User-specific → Redis with user key prefix
-├─ Global data → In-memory cache with TTL
-├─ Database results → Query result cache
-├─ Static assets → CDN with cache headers
-└─ Computed values → Memoization decorators
-```
-
-## Performance Optimization
-
-### Caching Strategies
-- Use built-in cache manager for response caching
-- Implement cache interceptors for expensive operations
-- Configure TTL based on data volatility
-- Use Redis for distributed caching
-
-### Database Optimization
-- Use DataLoader pattern for N+1 query problems
-- Implement proper indexes on frequently queried fields
-- Use query builder for complex queries vs. ORM methods
-- Enable query logging in development for analysis
-
-### Request Processing
-- Implement compression middleware
-- Use streaming for large responses
-- Configure proper rate limiting
-- Enable clustering for multi-core utilization
-
-## External Resources
-
-### Core Documentation
-- [Nest.js Documentation](https://docs.nestjs.com)
-- [Nest.js CLI](https://docs.nestjs.com/cli/overview)
-- [Nest.js Recipes](https://docs.nestjs.com/recipes)
-
-### Testing Resources
-- [Jest Documentation](https://jestjs.io/docs/getting-started)
-- [Supertest](https://github.com/visionmedia/supertest)
-- [Testing Best Practices](https://github.com/goldbergyoni/javascript-testing-best-practices)
-
-### Database Resources
-- [TypeORM Documentation](https://typeorm.io)
-- [Mongoose Documentation](https://mongoosejs.com)
-
-### Authentication
-- [Passport.js Strategies](http://www.passportjs.org)
-- [JWT Best Practices](https://tools.ietf.org/html/rfc8725)
-
-## Quick Reference Patterns
-
-### Dependency Injection Tokens
-```typescript
-// Custom provider token
-export const CONFIG_OPTIONS = Symbol('CONFIG_OPTIONS');
-
-// Usage in module
-@Module({
-  providers: [
-    {
-      provide: CONFIG_OPTIONS,
-      useValue: { apiUrl: 'https://api.example.com' }
-    }
-  ]
-})
-```
-
-### Global Module Pattern
-```typescript
-@Global()
-@Module({
-  providers: [GlobalService],
-  exports: [GlobalService],
-})
-export class GlobalModule {}
-```
-
-### Dynamic Module Pattern
-```typescript
-@Module({})
-export class ConfigModule {
-  static forRoot(options: ConfigOptions): DynamicModule {
-    return {
-      module: ConfigModule,
-      providers: [
-        {
-          provide: 'CONFIG_OPTIONS',
-          useValue: options,
-        },
-      ],
-    };
-  }
-}
-```
-
-## Success Metrics
-- ✅ Problem correctly identified and located in module structure
-- ✅ Solution follows Nest.js architectural patterns
-- ✅ All tests pass (unit, integration, e2e)
-- ✅ No circular dependencies introduced
-- ✅ Performance metrics maintained or improved
-- ✅ Code follows established project conventions
-- ✅ Proper error handling implemented
-- ✅ Security best practices applied
-- ✅ Documentation updated for API changes
+Read [the detailed guide](references/detailed-guide.md) before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
 
 ## When to Use
 This skill is applicable to execute the workflow or actions described in the overview.