@ngxtm/devkit 3.3.0 → 3.4.1

package/rules/nestjs/documentation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: NestJS OpenAPI
+description: Swagger automation and Generic response documentation.
+metadata:
+  labels: [nestjs, swagger, openapi, docs]
+  triggers:
+    files: ['main.ts', '**/*.dto.ts']
+    keywords: [DocumentBuilder, SwaggerModule, ApiProperty, ApiResponse]
+---
+
+# OpenAPI & Documentation
+
+## Swagger (OpenAPI)
+
+- **Automation**: **ALWAYS** use the Nest CLI Plugin (`@nestjs/swagger/plugin`).
+  - **Benefit**: Auto-generates `@ApiProperty` for DTOs and response types. Reduces boilerplate by 50%.
+  - **Config**: `nest-cli.json` -> `"plugins": ["@nestjs/swagger"]`.
+- **Versioning**: Maintain separate Swagger docs for `v1`, `v2` if breaking changes occur.
+
+## Response Documentation
+
+- **Strictness**: Every controller method must have `@ApiResponse({ status: 200, type: UserDto })`.
+- **Generic Wrappers**: Define `ApiPaginatedResponse<T>` decorators to document generic `PageDto<T>` returns properly (Swagger doesn't handle generics well by default).
+  - **Technique**: Use `ApiExtraModels` + `getSchemaPath()` in the custom decorator to handle the generic `T` ref.
+
+## Advanced Patterns
+
+- **Polymorphism**: Use `@ApiExtraModels` and `getSchemaPath` for `oneOf`/`anyOf` union types.
+- **File Uploads**: Document `multipart/form-data` explicitly.
+  - **Decorator**: `@ApiConsumes('multipart/form-data')`.
+  - **Body**: `@ApiBody({ schema: { type: 'object', properties: { file: { type: 'string', format: 'binary' } } } })`.
+- **Authentication**: Specify granular security schemes per route/controller.
+  - **Types**: `@ApiBearerAuth()` or `@ApiSecurity('api-key')` (Must match `DocumentBuilder().addBearerAuth()`).
+- **Enums**: Force named enums for reusable schema references.
+  - **Code**: `@ApiProperty({ enum: MyEnum, enumName: 'MyEnum' })`.
+
+## Operation Grouping
+
+- **Tags**: Mandatory `@ApiTags('domains')` on every Controller to group endpoints logically.
+- **Multiple Docs**: generate separate docs for different audiences (e.g. Public vs Internal).
+
+  ```typescript
+  SwaggerModule.createDocument(app, config, { include: [PublicModule] }); // /api/docs
+  SwaggerModule.createDocument(app, adminConfig, { include: [AdminModule] }); // /admin/docs
+  ```
+
+## Self-Documentation
+
+- **Compodoc**: Use `@compodoc/compodoc` to generate static documentation of the module graph, services, and dependencies.
+  - **Use Case**: New developer onboarding and architectural review.
+
+## Advanced OpenAPI
+
+- **Polymorphism**: Use `@ApiExtraModels` and `getSchemaPath` for `oneOf`/`anyOf` union types.
+  - **Pattern**: Register generic/sub-types in controller, refer via schema `$ref`.
+- **File Uploads**: Document `multipart/form-data` explicitly.
+  - **Decorator**: `@ApiConsumes('multipart/form-data')`.
+  - **Body**: `@ApiBody({ schema: { type: 'object', properties: { file: { type: 'string', format: 'binary' } } } })`.
+- **Authentication**: Specify granular security schemes per route/controller.
+  - **Types**: `@ApiBearerAuth()` or `@ApiSecurity('api-key')`. Match setup in `DocumentBuilder`.
+- **Enums**: Force named enums for reusable schema references.
+  - **Code**: `@ApiProperty({ enum: MyEnum, enumName: 'MyEnum' })`.
+- **Grouping**: Segregate public vs. internal docs.
+  - **Setup**: `SwaggerModule.createDocument(app, config, { include: [AdminModule] })`.

package/rules/nestjs/documentation/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Documentation References
+
+## References
+
+- [**Swagger Patterns**](swagger-patterns.md) - OpenAPI, decorators, schemas
+
+## Quick Checks
+
+- [ ] Use @ApiTags for controller grouping
+- [ ] Document all DTOs with @ApiProperty
+- [ ] Add @ApiResponse for all status codes
+- [ ] Include authentication in swagger config
+- [ ] Generate OpenAPI spec for clients

package/rules/nestjs/documentation/references/swagger-patterns.md

@@ -0,0 +1,139 @@
+# NestJS Swagger/OpenAPI Patterns
+
+## Setup
+
+```typescript
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const config = new DocumentBuilder()
+    .setTitle('API Documentation')
+    .setDescription('REST API endpoints')
+    .setVersion('1.0')
+    .addBearerAuth()
+    .addTag('users')
+    .addTag('orders')
+    .build();
+
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api/docs', app, document);
+
+  await app.listen(3000);
+}
+```
+
+## DTO Documentation
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateUserDto {
+  @ApiProperty({
+    description: 'User email address',
+    example: 'user@example.com',
+  })
+  email: string;
+
+  @ApiProperty({
+    description: 'User password',
+    minLength: 8,
+  })
+  password: string;
+
+  @ApiPropertyOptional({
+    description: 'User display name',
+    example: 'John Doe',
+  })
+  name?: string;
+
+  @ApiProperty({
+    enum: ['admin', 'user', 'guest'],
+    default: 'user',
+  })
+  role: string;
+}
+```
+
+## Controller Documentation
+
+```typescript
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiBearerAuth,
+  ApiParam,
+  ApiQuery,
+} from '@nestjs/swagger';
+
+@ApiTags('users')
+@Controller('users')
+export class UsersController {
+  @Get()
+  @ApiOperation({ summary: 'Get all users' })
+  @ApiQuery({ name: 'page', required: false, type: Number })
+  @ApiQuery({ name: 'limit', required: false, type: Number })
+  @ApiResponse({ status: 200, description: 'List of users', type: [User] })
+  findAll(@Query() query: PaginationDto) {
+    return this.usersService.findAll(query);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiParam({ name: 'id', description: 'User ID' })
+  @ApiResponse({ status: 200, description: 'User found', type: User })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(id);
+  }
+
+  @Post()
+  @ApiBearerAuth()
+  @ApiOperation({ summary: 'Create new user' })
+  @ApiResponse({ status: 201, description: 'User created', type: User })
+  @ApiResponse({ status: 400, description: 'Validation error' })
+  create(@Body() dto: CreateUserDto) {
+    return this.usersService.create(dto);
+  }
+}
+```
+
+## Response Schema
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class PaginatedResponse<T> {
+  @ApiProperty()
+  data: T[];
+
+  @ApiProperty({ example: 100 })
+  total: number;
+
+  @ApiProperty({ example: 1 })
+  page: number;
+
+  @ApiProperty({ example: 10 })
+  limit: number;
+}
+
+// Usage in controller
+@ApiResponse({
+  status: 200,
+  schema: {
+    allOf: [
+      { $ref: getSchemaPath(PaginatedResponse) },
+      {
+        properties: {
+          data: {
+            type: 'array',
+            items: { $ref: getSchemaPath(User) },
+          },
+        },
+      },
+    ],
+  },
+})
+```

package/rules/nestjs/error-handling/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: NestJS Error Handling
+description: Global Exception Filters and standard error formats.
+metadata:
+  labels: [nestjs, errors, filters]
+  triggers:
+    files: ['**/*.filter.ts', 'main.ts']
+    keywords: [ExceptionFilter, Catch, HttpException]
+---
+
+# NestJS Error Handling Standards
+
+## Global Exception Filter
+
+- **Requirement**: Centralize error formatting.
+- **Platform Agnostic**: Do **not** import `Request`/`Response` from Express/Fastify types directly.
+  - **Use**: `HttpAdapterHost` to access the underlying platform response methods.
+  - `const { httpAdapter } = this.httpAdapterHost;`
+- **Structure**:
+  - Implement strictly typed error responses.
+  - Refer to **[API Standards](../api-standards/SKILL.md)** for `ApiErrorResponse`.
+
+  ```json
+  {
+    "statusCode": 400,
+    "message": "Validation failed",
+    "error": "Bad Request",
+    "timestamp": "ISO...",
+    "path": "/users"
+  }
+  ```
+
+## Error Flow
+
+1. **Service**: Throws specific or generic errors (e.g., `EntityNotFoundError`).
+2. **Interceptor**: Maps low-level errors to HTTP Exceptions (e.g., `catchError(err => throw new NotFoundException())`).
+   - _Why_: Keeps Exception Filters focused on formatting, not business logic interpretation.
+3. **Global Filter**: Formats the final JSON response.
+
+## Built-in Exceptions
+
+- **Use**: Throw `NotFoundException`, `ForbiddenException`, `BadRequestException`.
+- **Custom**: Extend `HttpException` only for domain-specific failures that need specific status codes.
+
+## Logging
+
+- **Context**: Always pass `MyClass.name` to the `Logger` constructor.
+- **Levels**:
+  - `error`: 500s (Stack trace required).
+  - `warn`: 400s (Client errors).
+
+## Security (Information Leakage)
+
+- **Production**: **NEVER** expose stack traces in HTTP responses (`process.env.NODE_ENV === 'production'`).
+- **Sanitization**: Ensure `ApiException` payloads do not leak internal file paths or raw variable dumps.

package/rules/nestjs/error-handling/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Error Handling References
+
+## References
+
+- [**Exception Filters**](exception-filters.md) - Custom filters, error responses
+
+## Quick Checks
+
+- [ ] Use built-in HTTP exceptions
+- [ ] Custom exception filters for consistent responses
+- [ ] Log errors appropriately
+- [ ] Don't expose internal errors to clients
+- [ ] Handle validation errors gracefully

package/rules/nestjs/error-handling/references/exception-filters.md

@@ -0,0 +1,152 @@
+# NestJS Exception Filters
+
+## Built-in Exceptions
+
+```typescript
+import {
+  BadRequestException,
+  UnauthorizedException,
+  ForbiddenException,
+  NotFoundException,
+  ConflictException,
+  InternalServerErrorException,
+} from '@nestjs/common';
+
+// Usage
+throw new NotFoundException('User not found');
+throw new BadRequestException('Invalid input');
+throw new UnauthorizedException('Invalid credentials');
+throw new ConflictException('Email already exists');
+```
+
+## Custom Exception
+
+```typescript
+export class BusinessException extends HttpException {
+  constructor(
+    public readonly code: string,
+    message: string,
+    status: HttpStatus = HttpStatus.BAD_REQUEST,
+  ) {
+    super({ code, message }, status);
+  }
+}
+
+// Usage
+throw new BusinessException('INSUFFICIENT_FUNDS', 'Not enough balance');
+```
+
+## Global Exception Filter
+
+```typescript
+import { ExceptionFilter, Catch, ArgumentsHost, HttpException, HttpStatus } from '@nestjs/common';
+import { Response } from 'express';
+
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  constructor(private readonly logger: Logger) {}
+
+  catch(exception: unknown, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest();
+
+    const status = exception instanceof HttpException
+      ? exception.getStatus()
+      : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message = exception instanceof HttpException
+      ? exception.getResponse()
+      : 'Internal server error';
+
+    const errorResponse = {
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      message: typeof message === 'string' ? message : (message as any).message,
+    };
+
+    this.logger.error(
+      `${request.method} ${request.url}`,
+      exception instanceof Error ? exception.stack : 'Unknown error',
+    );
+
+    response.status(status).json(errorResponse);
+  }
+}
+
+// main.ts
+app.useGlobalFilters(new AllExceptionsFilter(new Logger()));
+```
+
+## Validation Exception Filter
+
+```typescript
+@Catch(ValidationError)
+export class ValidationExceptionFilter implements ExceptionFilter {
+  catch(exception: ValidationError[], host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+
+    const errors = exception.map(err => ({
+      field: err.property,
+      constraints: Object.values(err.constraints || {}),
+    }));
+
+    response.status(HttpStatus.BAD_REQUEST).json({
+      statusCode: HttpStatus.BAD_REQUEST,
+      message: 'Validation failed',
+      errors,
+    });
+  }
+}
+```
+
+## HTTP Exception Filter
+
+```typescript
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const status = exception.getStatus();
+    const exceptionResponse = exception.getResponse();
+
+    response.status(status).json({
+      success: false,
+      statusCode: status,
+      ...(typeof exceptionResponse === 'object' ? exceptionResponse : { message: exceptionResponse }),
+      timestamp: new Date().toISOString(),
+    });
+  }
+}
+```
+
+## Using Filters
+
+```typescript
+// Controller level
+@Controller('users')
+@UseFilters(HttpExceptionFilter)
+export class UsersController {}
+
+// Method level
+@Post()
+@UseFilters(ValidationExceptionFilter)
+create(@Body() dto: CreateUserDto) {}
+
+// Global (main.ts)
+app.useGlobalFilters(new AllExceptionsFilter());
+
+// Global with DI
+@Module({
+  providers: [
+    {
+      provide: APP_FILTER,
+      useClass: AllExceptionsFilter,
+    },
+  ],
+})
+export class AppModule {}
+```

package/rules/nestjs/file-uploads/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: NestJS File Uploads
+description: Secure file handling, Validation, and S3 streaming.
+metadata:
+  labels: [nestjs, upload, multer, s3]
+  triggers:
+    files: ['**/*.controller.ts']
+    keywords: [FileInterceptor, Multer, S3, UploadedFile]
+---
+
+# File Upload Patterns
+
+## Security (Input Validation)
+
+- **Magic Bytes**: NEVER trust `content-type` header or file extension.
+  - **Tool**: Use `file-type` or `mmmagic` to verify the actual buffer signature.
+- **Limits**: Set strict `limits: { fileSize: 5000000 }` (5MB) in Multer config to prevent DoS.
+
+## Streaming (Scalability)
+
+- **Memory Warning**: Default Multer `MemoryStorage` crashes servers with large files.
+- **Pattern**: Use **Streaming** for any file > 10MB.
+  - **Library**: `multer-s3` (direct upload to bucket) or `busboy` (raw stream processing).
+  - **Architecture**:
+    1. Client requests Signed URL from API.
+    2. Client uploads directly to S3/GCS (Bypassing API server completely).
+    3. **Pro Tip**: This is the only way to scale file uploads infinitely.
+
+## Processing
+
+- **Async**: Don't process images/videos in the HTTP Request.
+- **Flow**:
+  1. Upload file.
+  2. Push `FileUploadedEvent` to Queue (BullMQ).
+  3. Worker downloads, resizes/converts, and re-uploads.

package/rules/nestjs/file-uploads/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS File Uploads References
+
+## References
+
+- [**Upload Patterns**](upload-patterns.md) - Multer, streaming, S3 integration
+
+## Quick Checks
+
+- [ ] Validate file types and sizes
+- [ ] Use streaming for large files
+- [ ] Configure proper storage destination
+- [ ] Handle multiple file uploads
+- [ ] Implement virus scanning for production

package/rules/nestjs/file-uploads/references/upload-patterns.md

@@ -0,0 +1,125 @@
+# NestJS File Upload Patterns
+
+## Basic Upload
+
+```typescript
+import {
+  Controller,
+  Post,
+  UseInterceptors,
+  UploadedFile,
+  ParseFilePipe,
+  MaxFileSizeValidator,
+  FileTypeValidator,
+} from '@nestjs/common';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { diskStorage } from 'multer';
+
+@Controller('files')
+export class FilesController {
+  @Post('upload')
+  @UseInterceptors(FileInterceptor('file', {
+    storage: diskStorage({
+      destination: './uploads',
+      filename: (req, file, cb) => {
+        const uniqueSuffix = Date.now() + '-' + Math.round(Math.random() * 1e9);
+        cb(null, `${uniqueSuffix}-${file.originalname}`);
+      },
+    }),
+  }))
+  uploadFile(
+    @UploadedFile(
+      new ParseFilePipe({
+        validators: [
+          new MaxFileSizeValidator({ maxSize: 5 * 1024 * 1024 }), // 5MB
+          new FileTypeValidator({ fileType: /image\/(jpeg|png|gif)/ }),
+        ],
+      }),
+    )
+    file: Express.Multer.File,
+  ) {
+    return { filename: file.filename, size: file.size };
+  }
+}
+```
+
+## Multiple Files
+
+```typescript
+import { FilesInterceptor, FileFieldsInterceptor } from '@nestjs/platform-express';
+
+@Post('multiple')
+@UseInterceptors(FilesInterceptor('files', 10))
+uploadMultiple(@UploadedFiles() files: Express.Multer.File[]) {
+  return files.map(f => ({ name: f.filename, size: f.size }));
+}
+
+@Post('fields')
+@UseInterceptors(FileFieldsInterceptor([
+  { name: 'avatar', maxCount: 1 },
+  { name: 'documents', maxCount: 5 },
+]))
+uploadFields(@UploadedFiles() files: {
+  avatar?: Express.Multer.File[],
+  documents?: Express.Multer.File[],
+}) {
+  return { avatar: files.avatar?.[0], documents: files.documents };
+}
+```
+
+## S3 Upload
+
+```typescript
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+@Injectable()
+export class S3Service {
+  private s3: S3Client;
+
+  constructor(private config: ConfigService) {
+    this.s3 = new S3Client({
+      region: config.get('AWS_REGION'),
+      credentials: {
+        accessKeyId: config.get('AWS_ACCESS_KEY'),
+        secretAccessKey: config.get('AWS_SECRET_KEY'),
+      },
+    });
+  }
+
+  async upload(file: Express.Multer.File, key: string): Promise<string> {
+    await this.s3.send(new PutObjectCommand({
+      Bucket: this.config.get('S3_BUCKET'),
+      Key: key,
+      Body: file.buffer,
+      ContentType: file.mimetype,
+    }));
+
+    return `https://${this.config.get('S3_BUCKET')}.s3.amazonaws.com/${key}`;
+  }
+
+  async getPresignedUrl(key: string): Promise<string> {
+    const command = new PutObjectCommand({
+      Bucket: this.config.get('S3_BUCKET'),
+      Key: key,
+    });
+    return getSignedUrl(this.s3, command, { expiresIn: 3600 });
+  }
+}
+```
+
+## Streaming Large Files
+
+```typescript
+import { StreamableFile } from '@nestjs/common';
+import { createReadStream } from 'fs';
+
+@Get('download/:filename')
+downloadFile(@Param('filename') filename: string): StreamableFile {
+  const file = createReadStream(`./uploads/${filename}`);
+  return new StreamableFile(file, {
+    type: 'application/octet-stream',
+    disposition: `attachment; filename="${filename}"`,
+  });
+}
+```

package/rules/nestjs/observability/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: NestJS Observability
+description: Structured logging (Pino) and Prometheus metrics.
+metadata:
+  labels: [nestjs, logging, monitoring, pino]
+  triggers:
+    files: ['main.ts', '**/*.module.ts']
+    keywords: [nestjs-pino, Prometheus, Logger, reqId]
+---
+
+# Observability Standards
+
+## Structured Logging
+
+- **Standard**: Use `nestjs-pino` for high-performance JSON logging.
+  - **Why**: Node's built-in `console.log` is blocking and unstructured.
+- **Configuration**:
+  - **Redaction**: Mandatory masking of sensitive fields (`password`, `token`, `email`).
+  - **Context**: Always inject `Logger` and set the context (`LoginService`).
+
+## Tracing (Correlation)
+
+- **Request ID**: Every log line **must** include a `reqId` (Request ID).
+  - `nestjs-pino` handles this automatically using `AsyncLocalStorage`.
+  - **Propagation**: Pass `x-request-id` to downstream microservices/database queries key to trace flows.
+
+## Metrics
+
+- **Exposure**: Use `@willsoto/nestjs-prometheus` to expose `/metrics` for Prometheus scraping.
+- **Key Metrics**:
+  1. `http_request_duration_seconds` (Histogram)
+  2. `db_query_duration_seconds` (Histogram)
+  3. `memory_usage_bytes` (Gauge)
+
+## Health Checks
+
+- **Terminus**: Implement explicit logic for "Liveness" (I'm alive) vs "Readiness" (I can take traffic).
+  - **DB Check**: `TypeOrmHealthIndicator` / `PrismaHealthIndicator`.
+  - **Memory Check**: Fail if Heap > 300MB (prevent crash loops).

package/rules/nestjs/observability/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Observability References
+
+## References
+
+- [**Logging & Metrics**](logging-metrics.md) - Logger, Prometheus, tracing
+
+## Quick Checks
+
+- [ ] Structured logging with context
+- [ ] Request correlation IDs
+- [ ] Prometheus metrics for monitoring
+- [ ] Health checks for readiness
+- [ ] Distributed tracing for microservices