@biggora/claude-plugins 1.2.2 → 1.3.1

package/src/skills/nest-best-practices/references/microservices-overview.md

@@ -0,0 +1,221 @@
+---
+name: microservices
+description: Building microservices with various transport layers
+---
+
+# Microservices
+
+NestJS supports microservice architecture with multiple transport protocols.
+
+## Installation
+
+```bash
+npm install @nestjs/microservices
+```
+
+## Available Transporters
+
+| Transport | Package |
+|-----------|---------|
+| TCP | Built-in |
+| Redis | `redis` |
+| MQTT | `mqtt` |
+| NATS | `nats` |
+| RabbitMQ | `amqplib` |
+| Kafka | `kafkajs` |
+| gRPC | `@grpc/grpc-js` |
+
+## Creating a Microservice
+
+```typescript
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { Transport, MicroserviceOptions } from '@nestjs/microservices';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.createMicroservice<MicroserviceOptions>(
+    AppModule,
+    {
+      transport: Transport.TCP,
+      options: { host: 'localhost', port: 3001 },
+    },
+  );
+  await app.listen();
+}
+bootstrap();
+```
+
+## Hybrid Application
+
+Combine HTTP and microservice:
+
+```typescript
+const app = await NestFactory.create(AppModule);
+app.connectMicroservice<MicroserviceOptions>({
+  transport: Transport.TCP,
+  options: { port: 3001 },
+});
+await app.startAllMicroservices();
+await app.listen(3000);
+```
+
+## Request-Response Pattern
+
+### Handler (Microservice)
+
+```typescript
+import { Controller } from '@nestjs/common';
+import { MessagePattern, Payload } from '@nestjs/microservices';
+
+@Controller()
+export class MathController {
+  @MessagePattern({ cmd: 'sum' })
+  sum(@Payload() data: number[]): number {
+    return data.reduce((a, b) => a + b, 0);
+  }
+}
+```
+
+### Client (Producer)
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ClientsModule, Transport } from '@nestjs/microservices';
+
+@Module({
+  imports: [
+    ClientsModule.register([
+      {
+        name: 'MATH_SERVICE',
+        transport: Transport.TCP,
+        options: { host: 'localhost', port: 3001 },
+      },
+    ]),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+import { Injectable, Inject } from '@nestjs/common';
+import { ClientProxy } from '@nestjs/microservices';
+import { firstValueFrom } from 'rxjs';
+
+@Injectable()
+export class AppService {
+  constructor(@Inject('MATH_SERVICE') private client: ClientProxy) {}
+
+  async calculate(): Promise<number> {
+    const pattern = { cmd: 'sum' };
+    const payload = [1, 2, 3, 4, 5];
+    return firstValueFrom(this.client.send<number>(pattern, payload));
+  }
+}
+```
+
+## Event-Based Pattern
+
+### Handler
+
+```typescript
+@EventPattern('user_created')
+async handleUserCreated(@Payload() data: CreateUserEvent) {
+  await this.usersService.processNewUser(data);
+}
+```
+
+### Emitter
+
+```typescript
+async createUser(dto: CreateUserDto) {
+  const user = await this.usersRepository.create(dto);
+  this.client.emit('user_created', new CreateUserEvent(user));
+  return user;
+}
+```
+
+## Accessing Context
+
+```typescript
+import { Ctx, Payload, NatsContext } from '@nestjs/microservices';
+
+@MessagePattern('time.us.*')
+getDate(@Payload() data: any, @Ctx() context: NatsContext) {
+  console.log(`Subject: ${context.getSubject()}`);
+  return new Date().toISOString();
+}
+```
+
+## Async Configuration
+
+```typescript
+ClientsModule.registerAsync([
+  {
+    name: 'MATH_SERVICE',
+    imports: [ConfigModule],
+    useFactory: async (configService: ConfigService) => ({
+      transport: Transport.TCP,
+      options: {
+        host: configService.get('MATH_HOST'),
+        port: configService.get('MATH_PORT'),
+      },
+    }),
+    inject: [ConfigService],
+  },
+]);
+```
+
+## Timeout Handling
+
+```typescript
+import { timeout } from 'rxjs/operators';
+
+this.client
+  .send<number>({ cmd: 'sum' }, [1, 2, 3])
+  .pipe(timeout(5000));
+```
+
+## TLS Support
+
+```typescript
+// Server
+const app = await NestFactory.createMicroservice<MicroserviceOptions>(
+  AppModule,
+  {
+    transport: Transport.TCP,
+    options: {
+      tlsOptions: {
+        key: fs.readFileSync('key.pem'),
+        cert: fs.readFileSync('cert.pem'),
+      },
+    },
+  },
+);
+
+// Client
+ClientsModule.register([
+  {
+    name: 'SERVICE',
+    transport: Transport.TCP,
+    options: {
+      tlsOptions: {
+        ca: [fs.readFileSync('ca.pem')],
+      },
+    },
+  },
+]);
+```
+
+## Key Points
+
+- `@MessagePattern()` for request-response (requires reply)
+- `@EventPattern()` for fire-and-forget events
+- Client connection is lazy (connects on first call)
+- Use `firstValueFrom` to convert Observable to Promise
+- TCP is the default transport
+
+<!--
+Source references:
+- https://docs.nestjs.com/microservices/basics
+-->

package/src/skills/nest-best-practices/references/microservices-transports.md

@@ -0,0 +1,119 @@
+---
+name: microservices-transports
+description: Redis, Kafka, NATS, RabbitMQ transport configuration
+---
+
+# Microservice Transports
+
+## Redis
+
+```bash
+npm i ioredis
+```
+
+```typescript
+{
+  transport: Transport.REDIS,
+  options: {
+    host: 'localhost',
+    port: 6379,
+    password: 'secret',
+    retryAttempts: 3,
+    retryDelay: 1000,
+    wildcards: true,  // psubscribe for pattern matching
+  },
+}
+```
+
+Client: `ClientsModule.register([{ name: 'MATH_SERVICE', transport: Transport.REDIS, options: {...} }])`
+
+## Kafka
+
+```bash
+npm i kafkajs
+```
+
+```typescript
+{
+  transport: Transport.KAFKA,
+  options: {
+    client: {
+      clientId: 'my-app',
+      brokers: ['localhost:9092'],
+    },
+    consumer: {
+      groupId: 'my-consumer',
+    },
+    producer: {
+      allowAutoTopicCreation: true,
+    },
+  },
+}
+```
+
+Use `@MessagePattern('topic')` for Kafka topics. Event-based (fire-and-forget) by default.
+
+## NATS
+
+```bash
+npm i nats
+```
+
+```typescript
+{
+  transport: Transport.NATS,
+  options: {
+    servers: ['nats://localhost:4222'],
+    queue: 'my-queue',  // queue group
+  },
+}
+```
+
+Supports wildcards: `@MessagePattern('time.us.*')` — `*` and `>` (multi-level).
+
+## RabbitMQ
+
+```bash
+npm i amqplib
+```
+
+```typescript
+{
+  transport: Transport.RMQ,
+  options: {
+    urls: ['amqp://localhost:5672'],
+    queue: 'my_queue',
+    queueOptions: {
+      durable: true,
+    },
+    noAck: false,
+    prefetchCount: 1,
+  },
+}
+```
+
+## Transport Comparison
+
+| Transport | Pattern | Use Case |
+|-----------|---------|----------|
+| TCP | Request-Response | Internal RPC |
+| Redis | Pub/Sub, Request-Response | Caching, queues |
+| Kafka | Event-based | Event streaming |
+| NATS | Pub/Sub, Request-Response | Lightweight messaging |
+| RabbitMQ | Pub/Sub, Request-Response | Enterprise messaging |
+| gRPC | Request-Response, Streaming | Performance, typed APIs |
+
+## Key Points
+
+- Redis: fire-and-forget, no delivery guarantee
+- Kafka: persistent events, consumer groups
+- NATS: wildcards (`*`, `>`), queue groups
+- RabbitMQ: durable queues, ack required for reliability
+
+<!--
+Source references:
+- https://docs.nestjs.com/microservices/redis
+- https://docs.nestjs.com/microservices/kafka
+- https://docs.nestjs.com/microservices/nats
+- https://docs.nestjs.com/microservices/rabbitmq
+-->

package/src/skills/nest-best-practices/references/openapi-swagger.md

@@ -0,0 +1,207 @@
+---
+name: openapi-swagger
+description: OpenAPI/Swagger documentation generation
+---
+
+# OpenAPI (Swagger)
+
+Generate interactive API documentation using the OpenAPI specification.
+
+## Installation
+
+```bash
+npm install @nestjs/swagger
+```
+
+## Basic Setup
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+import { AppModule } from './app.module';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const config = new DocumentBuilder()
+    .setTitle('Cats API')
+    .setDescription('The cats API description')
+    .setVersion('1.0')
+    .addTag('cats')
+    .addBearerAuth()
+    .build();
+    
+  const documentFactory = () => SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, documentFactory);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+Access Swagger UI at `http://localhost:3000/api`
+
+## DTO Documentation
+
+Use `@ApiProperty()` to document DTO properties:
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty({ description: 'The name of the cat' })
+  name: string;
+
+  @ApiProperty({ minimum: 0, maximum: 30, default: 1 })
+  age: number;
+
+  @ApiPropertyOptional({ example: 'Persian' })
+  breed?: string;
+
+  @ApiProperty({ enum: ['male', 'female'] })
+  gender: string;
+
+  @ApiProperty({ type: [String] })
+  tags: string[];
+}
+```
+
+## Common Decorators
+
+| Decorator | Level | Purpose |
+|-----------|-------|---------|
+| `@ApiTags()` | Controller/Method | Group endpoints |
+| `@ApiOperation()` | Method | Describe operation |
+| `@ApiResponse()` | Method/Controller | Document responses |
+| `@ApiParam()` | Method | Document URL params |
+| `@ApiQuery()` | Method | Document query params |
+| `@ApiBody()` | Method | Document request body |
+| `@ApiBearerAuth()` | Method/Controller | Mark as authenticated |
+| `@ApiProperty()` | Model | Document property |
+| `@ApiHideProperty()` | Model | Hide property |
+| `@ApiExcludeEndpoint()` | Method | Exclude from docs |
+
+## Controller Documentation
+
+```typescript
+import { 
+  ApiTags, 
+  ApiOperation, 
+  ApiResponse,
+  ApiBearerAuth,
+} from '@nestjs/swagger';
+
+@ApiTags('cats')
+@ApiBearerAuth()
+@Controller('cats')
+export class CatsController {
+  @Post()
+  @ApiOperation({ summary: 'Create a cat' })
+  @ApiResponse({ status: 201, description: 'Cat created successfully' })
+  @ApiResponse({ status: 400, description: 'Invalid input' })
+  create(@Body() dto: CreateCatDto) {
+    return this.catsService.create(dto);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get a cat by ID' })
+  @ApiParam({ name: 'id', description: 'Cat ID' })
+  @ApiResponse({ status: 200, type: Cat })
+  @ApiResponse({ status: 404, description: 'Cat not found' })
+  findOne(@Param('id') id: string) {
+    return this.catsService.findOne(id);
+  }
+}
+```
+
+## Enums
+
+```typescript
+export enum CatStatus {
+  Available = 'available',
+  Pending = 'pending',
+  Sold = 'sold',
+}
+
+@ApiProperty({ 
+  enum: CatStatus, 
+  enumName: 'CatStatus' 
+})
+status: CatStatus;
+```
+
+## Authentication
+
+```typescript
+const config = new DocumentBuilder()
+  .addBearerAuth()
+  .addApiKey({ type: 'apiKey', name: 'X-API-Key', in: 'header' }, 'api-key')
+  .addOAuth2()
+  .build();
+
+// Apply to endpoints
+@ApiBearerAuth()
+@UseGuards(AuthGuard('jwt'))
+@Get('profile')
+getProfile() {}
+```
+
+## CLI Plugin
+
+Auto-document DTOs by adding to `nest-cli.json`:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": ["@nestjs/swagger"]
+  }
+}
+```
+
+With options:
+
+```json
+{
+  "plugins": [
+    {
+      "name": "@nestjs/swagger",
+      "options": {
+        "classValidatorShim": true,
+        "introspectComments": true
+      }
+    }
+  ]
+}
+```
+
+## Document Options
+
+```typescript
+const documentFactory = () => SwaggerModule.createDocument(app, config, {
+  include: [CatsModule],        // Only include specific modules
+  extraModels: [ExtraModel],    // Add extra models
+  ignoreGlobalPrefix: false,    // Include global prefix
+  deepScanRoutes: true,         // Scan imported modules
+});
+```
+
+## Setup Options
+
+```typescript
+SwaggerModule.setup('api', app, documentFactory, {
+  jsonDocumentUrl: '/api-json',
+  yamlDocumentUrl: '/api-yaml',
+  customSiteTitle: 'My API Docs',
+  customCss: '.swagger-ui .topbar { display: none }',
+  swaggerOptions: {
+    persistAuthorization: true,
+  },
+});
+```
+
+<!--
+Source references:
+- https://docs.nestjs.com/openapi/introduction
+- https://docs.nestjs.com/openapi/types-and-parameters
+- https://docs.nestjs.com/openapi/decorators
+-->

package/src/skills/nest-best-practices/references/recipes-authentication.md

@@ -0,0 +1,97 @@
+---
+name: recipes-authentication
+description: Authentication with Passport in NestJS
+---
+
+# Authentication
+
+NestJS integrates with Passport for authentication strategies.
+
+## Installation
+
+```bash
+npm install --save @nestjs/passport passport passport-local
+npm install --save-dev @types/passport-local
+```
+
+## Local Strategy
+
+```typescript
+import { Injectable, UnauthorizedException } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { Strategy } from 'passport-local';
+import { AuthService } from './auth.service';
+
+@Injectable()
+export class LocalStrategy extends PassportStrategy(Strategy) {
+  constructor(private authService: AuthService) {
+    super();
+  }
+
+  async validate(username: string, password: string): Promise<any> {
+    const user = await this.authService.validateUser(username, password);
+    if (!user) {
+      throw new UnauthorizedException();
+    }
+    return user;
+  }
+}
+```
+
+## JWT Strategy
+
+```bash
+npm install --save @nestjs/jwt passport-jwt
+npm install --save-dev @types/passport-jwt
+```
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor() {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: 'secret',
+    });
+  }
+
+  async validate(payload: any) {
+    return { userId: payload.sub, username: payload.username };
+  }
+}
+```
+
+## Using Guards
+
+```typescript
+@UseGuards(AuthGuard('local'))
+@Post('auth/login')
+async login(@Request() req) {
+  return req.user;
+}
+
+@UseGuards(AuthGuard('jwt'))
+@Get('profile')
+getProfile(@Request() req) {
+  return req.user;
+}
+```
+
+## Key Points
+
+- Use `@nestjs/passport` for Passport integration
+- Create strategies extending `PassportStrategy`
+- Use `AuthGuard` with strategy name
+- JWT tokens for stateless authentication
+- Local strategy for username/password
+- User object available in `request.user`
+
+<!--
+Source references:
+- https://docs.nestjs.com/security/authentication
+-->