@biggora/claude-plugins 1.2.0 → 1.3.0

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
+-->

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

@@ -0,0 +1,176 @@
+---
+name: cqrs
+description: Command Query Responsibility Segregation pattern for complex applications
+---
+
+# CQRS
+
+Separate read and write operations for scalability and flexibility.
+
+## Installation
+
+```bash
+npm install @nestjs/cqrs
+```
+
+```typescript
+@Module({
+  imports: [CqrsModule.forRoot()],
+})
+export class AppModule {}
+```
+
+## Commands
+
+Commands change application state. Use `CommandBus` to dispatch.
+
+```typescript
+// kill-dragon.command.ts
+export class KillDragonCommand extends Command<{ actionId: string }> {
+  constructor(
+    public readonly heroId: string,
+    public readonly dragonId: string,
+  ) {
+    super();
+  }
+}
+
+// kill-dragon.handler.ts
+@CommandHandler(KillDragonCommand)
+export class KillDragonHandler implements ICommandHandler<KillDragonCommand> {
+  constructor(private repository: HeroesRepository) {}
+
+  async execute(command: KillDragonCommand) {
+    const { heroId, dragonId } = command;
+    const hero = await this.repository.findOneById(+heroId);
+    hero.killEnemy(dragonId);
+    await this.repository.persist(hero);
+    return { actionId: crypto.randomUUID() };
+  }
+}
+```
+
+```typescript
+// Usage
+await this.commandBus.execute(
+  new KillDragonCommand(heroId, killDragonDto.dragonId)
+);
+```
+
+## Queries
+
+```typescript
+export class GetHeroQuery extends Query<Hero> {
+  constructor(public readonly heroId: string) {
+    super();
+  }
+}
+
+@QueryHandler(GetHeroQuery)
+export class GetHeroHandler implements IQueryHandler<GetHeroQuery> {
+  constructor(private repository: HeroesRepository) {}
+
+  async execute(query: GetHeroQuery) {
+    return this.repository.findOneById(query.heroId);
+  }
+}
+```
+
+```typescript
+const hero = await this.queryBus.execute(new GetHeroQuery(heroId));
+```
+
+## Events
+
+```typescript
+export class HeroKilledDragonEvent {
+  constructor(
+    public readonly heroId: string,
+    public readonly dragonId: string,
+  ) {}
+}
+
+@EventsHandler(HeroKilledDragonEvent)
+export class HeroKilledDragonHandler implements IEventHandler<HeroKilledDragonEvent> {
+  handle(event: HeroKilledDragonEvent) {
+    // Update read model, send notifications, etc.
+  }
+}
+```
+
+Publish from model with `AggregateRoot`:
+
+```typescript
+export class Hero extends AggregateRoot {
+  killEnemy(enemyId: string) {
+    this.apply(new HeroKilledDragonEvent(this.id, enemyId));
+  }
+}
+```
+
+Requires `EventPublisher.mergeObjectContext()` and `hero.commit()`.
+
+Or publish manually:
+
+```typescript
+this.eventBus.publish(new HeroKilledDragonEvent(heroId, dragonId));
+```
+
+## Sagas
+
+Long-running processes that listen to events and dispatch commands.
+
+```typescript
+@Injectable()
+export class HeroesGameSagas {
+  @Saga()
+  dragonKilled = (events$: Observable<any>): Observable<ICommand> => {
+    return events$.pipe(
+      ofType(HeroKilledDragonEvent),
+      map((event) => new DropAncientItemCommand(event.heroId, fakeItemID)),
+    );
+  };
+}
+```
+
+Register saga as provider. `ofType` filters events; return command to dispatch.
+
+## Request-Scoped Handlers
+
+```typescript
+@CommandHandler(KillDragonCommand, { scope: Scope.REQUEST })
+export class KillDragonHandler {
+  constructor(@Inject(REQUEST) private request: MyRequest) {}
+}
+```
+
+Pass `AsyncContext` when executing:
+
+```typescript
+const myRequest = new MyRequest(user);
+await this.commandBus.execute(command, myRequest);
+```
+
+## Unhandled Exceptions
+
+Event handler errors don't reach Exception filters. Subscribe to `UnhandledExceptionBus`:
+
+```typescript
+this.unhandledExceptionsBus
+  .pipe(takeUntil(this.destroy$))
+  .subscribe((exceptionInfo) => {
+    // Handle exception
+  });
+```
+
+## Key Points
+
+- Commands: task-based, change state; Queries: data-centric, read state
+- Register all handlers/sagas as providers
+- Event handlers run asynchronously—no HTTP response
+- Use Redis-backed event store for production sagas
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/cqrs
+-->

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

@@ -0,0 +1,87 @@
+---
+name: recipes-crud-generator
+description: Using Nest CLI to generate CRUD resources
+---
+
+# CRUD Generator
+
+Nest CLI provides a resource generator that automatically creates all boilerplate code for CRUD operations.
+
+## Generate Resource
+
+```bash
+nest g resource
+```
+
+The generator will prompt for:
+- Resource name
+- Transport layer (REST API, GraphQL, Microservice, WebSocket)
+- Whether to generate CRUD entry points
+
+## Generated Files
+
+For REST API, generates:
+- Module file (`users.module.ts`)
+- Controller file (`users.controller.ts`)
+- Service file (`users.service.ts`)
+- DTO files (`create-user.dto.ts`, `update-user.dto.ts`)
+- Entity file (`user.entity.ts`)
+- Test files (`.spec.ts`)
+
+## Generated Controller
+
+```typescript
+@Controller('users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Post()
+  create(@Body() createUserDto: CreateUserDto) {
+    return this.usersService.create(createUserDto);
+  }
+
+  @Get()
+  findAll() {
+    return this.usersService.findAll();
+  }
+
+  @Get(':id')
+  findOne(@Param('id') id: string) {
+    return this.usersService.findOne(+id);
+  }
+
+  @Patch(':id')
+  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
+    return this.usersService.update(+id, updateUserDto);
+  }
+
+  @Delete(':id')
+  remove(@Param('id') id: string) {
+    return this.usersService.remove(+id);
+  }
+}
+```
+
+## GraphQL Support
+
+For GraphQL applications, generates resolvers instead of controllers:
+
+```bash
+nest g resource users
+# Select: GraphQL (code first)
+# Select: Yes for CRUD entry points
+```
+
+## Key Points
+
+- Generates all CRUD boilerplate automatically
+- Supports REST, GraphQL, Microservices, and WebSockets
+- Service methods contain placeholders for implementation
+- Not tied to any specific ORM
+- Includes test files
+- Saves significant development time
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/crud-generator
+-->