@biggora/claude-plugins 1.2.2 → 1.3.1

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

@@ -0,0 +1,148 @@
+---
+name: terminus
+description: Health checks and readiness/liveness probes with @nestjs/terminus
+---
+
+# Health Checks (Terminus)
+
+Readiness/liveness probes for Kubernetes and orchestration.
+
+## Installation
+
+```bash
+npm install @nestjs/terminus
+```
+
+## Basic Setup
+
+```typescript
+@Module({
+  imports: [TerminusModule],
+})
+export class HealthModule {}
+
+@Controller('health')
+export class HealthController {
+  constructor(
+    private health: HealthCheckService,
+    private http: HttpHealthIndicator,
+  ) {}
+
+  @Get()
+  @HealthCheck()
+  check() {
+    return this.health.check([
+      () => this.http.pingCheck('nestjs-docs', 'https://docs.nestjs.com'),
+    ]);
+  }
+}
+```
+
+## Health Indicators
+
+| Indicator | Purpose |
+|-----------|---------|
+| `HttpHealthIndicator` | HTTP ping |
+| `TypeOrmHealthIndicator` | Database (SELECT 1) |
+| `MongooseHealthIndicator` | MongoDB |
+| `PrismaHealthIndicator` | Prisma |
+| `MemoryHealthIndicator` | Heap/RSS limits |
+| `DiskHealthIndicator` | Disk space |
+| `MicroserviceHealthIndicator` | Microservice |
+| `GRPCHealthIndicator` | gRPC |
+
+## TypeORM
+
+```typescript
+constructor(
+  private health: HealthCheckService,
+  private db: TypeOrmHealthIndicator,
+) {}
+
+@Get()
+@HealthCheck()
+check() {
+  return this.health.check([
+    () => this.db.pingCheck('database'),
+  ]);
+}
+```
+
+Multiple databases: inject connections and pass to `pingCheck('name', { connection })`.
+
+## Memory
+
+```typescript
+return this.health.check([
+  () => this.memory.checkHeap('memory_heap', 150 * 1024 * 1024),  // 150MB
+  () => this.memory.checkRSS('memory_rss', 150 * 1024 * 1024),
+]);
+```
+
+## Disk
+
+```typescript
+return this.health.check([
+  () => this.disk.checkStorage('storage', { path: '/', thresholdPercent: 0.5 }),
+  () => this.disk.checkStorage('storage', { path: '/', threshold: 250 * 1024 * 1024 * 1024 }),
+]);
+```
+
+## HTTP Response Check
+
+```typescript
+() => this.http.responseCheck(
+  'my-service',
+  'https://my-service.com',
+  (res) => res.status === 204,
+),
+```
+
+## Custom Indicator
+
+```typescript
+@Injectable()
+export class DogHealthIndicator {
+  constructor(private health: HealthIndicatorService) {}
+
+  async isHealthy(key: string) {
+    const indicator = this.health.check(key);
+    const isHealthy = /* custom logic */;
+    if (!isHealthy) return indicator.down({ reason: '...' });
+    return indicator.up();
+  }
+}
+```
+
+## Response Format
+
+```json
+{
+  "status": "ok",
+  "info": { "database": { "status": "up" } },
+  "error": {},
+  "details": { "database": { "status": "up" } }
+}
+```
+
+Status: `'ok' | 'error' | 'shutting_down'`
+
+## Graceful Shutdown
+
+```typescript
+TerminusModule.forRoot({
+  gracefulShutdownTimeoutMs: 1000,
+}),
+```
+
+## Key Points
+
+- Enable shutdown hooks for Terminus lifecycle
+- Use `@HealthCheck()` decorator on endpoints
+- `HttpHealthIndicator` requires `@nestjs/axios`
+- Custom indicators extend `HealthIndicatorService`
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/terminus
+-->

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

@@ -0,0 +1,122 @@
+---
+name: recipes-typeorm
+description: TypeORM integration and usage in NestJS
+---
+
+# TypeORM Integration
+
+TypeORM is a popular ORM for TypeScript and JavaScript that works with NestJS.
+
+## Installation
+
+```bash
+npm install --save @nestjs/typeorm typeorm mysql2
+```
+
+## Configuration
+
+```typescript
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+@Module({
+  imports: [
+    TypeOrmModule.forRoot({
+      type: 'mysql',
+      host: 'localhost',
+      port: 3306,
+      username: 'root',
+      password: 'root',
+      database: 'test',
+      entities: [User],
+      synchronize: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Entity Definition
+
+```typescript
+import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
+
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn()
+  id: number;
+
+  @Column()
+  firstName: string;
+
+  @Column()
+  lastName: string;
+
+  @Column({ default: true })
+  isActive: boolean;
+}
+```
+
+## Feature Module
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { User } from './user.entity';
+import { UsersService } from './users.service';
+import { UsersController } from './users.controller';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  providers: [UsersService],
+  controllers: [UsersController],
+})
+export class UsersModule {}
+```
+
+## Repository Injection
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { User } from './user.entity';
+
+@Injectable()
+export class UsersService {
+  constructor(
+    @InjectRepository(User)
+    private usersRepository: Repository<User>,
+  ) {}
+
+  findAll(): Promise<User[]> {
+    return this.usersRepository.find();
+  }
+
+  findOne(id: number): Promise<User> {
+    return this.usersRepository.findOneBy({ id });
+  }
+
+  async create(user: User): Promise<User> {
+    return this.usersRepository.save(user);
+  }
+
+  async remove(id: number): Promise<void> {
+    await this.usersRepository.delete(id);
+  }
+}
+```
+
+## Key Points
+
+- Use `TypeOrmModule.forRoot()` for configuration
+- Use `TypeOrmModule.forFeature()` in feature modules
+- Inject repositories with `@InjectRepository()`
+- Define entities with decorators
+- Use repository methods for database operations
+- Configure connection in root module
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/database
+- https://docs.nestjs.com/recipes/sql-typeorm
+-->

package/src/skills/nest-best-practices/references/security-authorization.md

@@ -0,0 +1,196 @@
+---
+name: authorization
+description: Role-based access control (RBAC) and CASL integration
+---
+
+# Authorization
+
+Authorization determines what authenticated users can do. NestJS supports RBAC, claims-based, and policy-based authorization.
+
+## Basic RBAC Implementation
+
+### 1. Define Roles
+
+```typescript
+// role.enum.ts
+export enum Role {
+  User = 'user',
+  Admin = 'admin',
+}
+```
+
+### 2. Create Roles Decorator
+
+```typescript
+// roles.decorator.ts
+import { SetMetadata } from '@nestjs/common';
+import { Role } from './role.enum';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);
+```
+
+### 3. Create Roles Guard
+
+```typescript
+// roles.guard.ts
+import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { Role } from './role.enum';
+import { ROLES_KEY } from './roles.decorator';
+
+@Injectable()
+export class RolesGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredRoles = this.reflector.getAllAndOverride<Role[]>(ROLES_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    
+    if (!requiredRoles) return true;
+
+    const { user } = context.switchToHttp().getRequest();
+    return requiredRoles.some((role) => user.roles?.includes(role));
+  }
+}
+```
+
+### 4. Apply to Routes
+
+```typescript
+@Post()
+@Roles(Role.Admin)
+@UseGuards(AuthGuard, RolesGuard)
+create(@Body() dto: CreateDto) {
+  return this.service.create(dto);
+}
+```
+
+### 5. Register Globally
+
+```typescript
+@Module({
+  providers: [
+    { provide: APP_GUARD, useClass: RolesGuard },
+  ],
+})
+export class AppModule {}
+```
+
+## Claims-Based Authorization
+
+Check specific permissions instead of roles:
+
+```typescript
+// permissions.decorator.ts
+export const PERMISSIONS_KEY = 'permissions';
+export const RequirePermissions = (...permissions: Permission[]) =>
+  SetMetadata(PERMISSIONS_KEY, permissions);
+
+// Usage
+@Post()
+@RequirePermissions(Permission.CREATE_POST)
+create() {}
+```
+
+## CASL Integration
+
+For complex authorization rules:
+
+```bash
+npm install @casl/ability
+```
+
+### Define Abilities
+
+```typescript
+// casl-ability.factory.ts
+import { AbilityBuilder, createMongoAbility, MongoAbility } from '@casl/ability';
+
+export type AppAbility = MongoAbility<[Action, Subjects]>;
+
+@Injectable()
+export class CaslAbilityFactory {
+  createForUser(user: User) {
+    const { can, cannot, build } = new AbilityBuilder(createMongoAbility);
+
+    if (user.isAdmin) {
+      can(Action.Manage, 'all');
+    } else {
+      can(Action.Read, 'all');
+      can(Action.Update, Article, { authorId: user.id });
+      cannot(Action.Delete, Article, { isPublished: true });
+    }
+
+    return build();
+  }
+}
+```
+
+### Use in Services
+
+```typescript
+@Injectable()
+export class ArticlesService {
+  constructor(private caslAbilityFactory: CaslAbilityFactory) {}
+
+  async update(user: User, articleId: string, dto: UpdateDto) {
+    const article = await this.findOne(articleId);
+    const ability = this.caslAbilityFactory.createForUser(user);
+
+    if (!ability.can(Action.Update, article)) {
+      throw new ForbiddenException('Cannot update this article');
+    }
+
+    return this.articlesRepository.update(articleId, dto);
+  }
+}
+```
+
+### Policies Guard
+
+```typescript
+@Injectable()
+export class PoliciesGuard implements CanActivate {
+  constructor(
+    private reflector: Reflector,
+    private caslAbilityFactory: CaslAbilityFactory,
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const policyHandlers = this.reflector.get<PolicyHandler[]>(
+      CHECK_POLICIES_KEY,
+      context.getHandler(),
+    ) || [];
+
+    const { user } = context.switchToHttp().getRequest();
+    const ability = this.caslAbilityFactory.createForUser(user);
+
+    return policyHandlers.every((handler) =>
+      typeof handler === 'function'
+        ? handler(ability)
+        : handler.handle(ability),
+    );
+  }
+}
+
+// Usage
+@Get()
+@UseGuards(PoliciesGuard)
+@CheckPolicies((ability: AppAbility) => ability.can(Action.Read, Article))
+findAll() {}
+```
+
+## Key Points
+
+- Authorization is independent from authentication
+- Use `Reflector` to access route metadata
+- CASL provides fine-grained, attribute-based control
+- `user.roles` should be attached by authentication guard
+
+<!--
+Source references:
+- https://docs.nestjs.com/security/authorization
+-->

package/src/skills/nest-best-practices/references/security-cors-helmet-rate-limiting.md

@@ -0,0 +1,204 @@
+---
+name: cors-helmet-rate-limiting
+description: CORS, security headers, and rate limiting protection
+---
+
+# Security Middleware
+
+Essential security measures for NestJS applications.
+
+## CORS (Cross-Origin Resource Sharing)
+
+Enable CORS to allow cross-origin requests:
+
+```typescript
+// Simple enable
+const app = await NestFactory.create(AppModule, { cors: true });
+
+// Or with configuration
+const app = await NestFactory.create(AppModule);
+app.enableCors({
+  origin: ['https://example.com', 'https://app.example.com'],
+  methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  credentials: true,
+});
+```
+
+Dynamic origin:
+
+```typescript
+app.enableCors({
+  origin: (origin, callback) => {
+    const whitelist = ['https://example.com'];
+    if (!origin || whitelist.includes(origin)) {
+      callback(null, true);
+    } else {
+      callback(new Error('Not allowed by CORS'));
+    }
+  },
+});
+```
+
+## Helmet (Security Headers)
+
+```bash
+npm install helmet
+```
+
+```typescript
+import helmet from 'helmet';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.use(helmet());
+  await app.listen(3000);
+}
+```
+
+## Rate Limiting
+
+Protect against brute-force attacks:
+
+```bash
+npm install @nestjs/throttler
+```
+
+### Basic Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+import { APP_GUARD } from '@nestjs/core';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      throttlers: [
+        { ttl: 60000, limit: 10 }, // 10 requests per minute
+      ],
+    }),
+  ],
+  providers: [
+    { provide: APP_GUARD, useClass: ThrottlerGuard },
+  ],
+})
+export class AppModule {}
+```
+
+### Multiple Limits
+
+```typescript
+ThrottlerModule.forRoot({
+  throttlers: [
+    { name: 'short', ttl: 1000, limit: 3 },    // 3 per second
+    { name: 'medium', ttl: 10000, limit: 20 }, // 20 per 10 seconds
+    { name: 'long', ttl: 60000, limit: 100 },  // 100 per minute
+  ],
+});
+```
+
+### Skip Routes
+
+```typescript
+import { SkipThrottle } from '@nestjs/throttler';
+
+@SkipThrottle()
+@Controller('health')
+export class HealthController {}
+
+// Or skip specific throttlers
+@SkipThrottle({ short: true })
+@Get()
+findAll() {}
+```
+
+### Override Limits
+
+```typescript
+import { Throttle } from '@nestjs/throttler';
+
+@Throttle({ default: { limit: 3, ttl: 60000 } })
+@Get()
+findAll() {}
+```
+
+### Behind Proxy
+
+```typescript
+// main.ts
+const app = await NestFactory.create<NestExpressApplication>(AppModule);
+app.set('trust proxy', 'loopback');
+
+// Custom tracker for proxy
+@Injectable()
+export class ThrottlerBehindProxyGuard extends ThrottlerGuard {
+  protected async getTracker(req: Record<string, any>): Promise<string> {
+    return req.ips.length ? req.ips[0] : req.ip;
+  }
+}
+```
+
+### Redis Storage
+
+For distributed systems:
+
+```bash
+npm install @nest-lab/throttler-storage-redis
+```
+
+```typescript
+import { ThrottlerStorageRedisService } from '@nest-lab/throttler-storage-redis';
+
+ThrottlerModule.forRoot({
+  throttlers: [{ ttl: 60000, limit: 10 }],
+  storage: new ThrottlerStorageRedisService('redis://localhost:6379'),
+});
+```
+
+### WebSocket Rate Limiting
+
+```typescript
+@Injectable()
+export class WsThrottlerGuard extends ThrottlerGuard {
+  async handleRequest(requestProps: ThrottlerRequest): Promise<boolean> {
+    const { context, limit, ttl } = requestProps;
+    const client = context.switchToWs().getClient();
+    const tracker = client._socket.remoteAddress;
+    // Custom logic
+    return true;
+  }
+}
+```
+
+### GraphQL Rate Limiting
+
+```typescript
+@Injectable()
+export class GqlThrottlerGuard extends ThrottlerGuard {
+  getRequestResponse(context: ExecutionContext) {
+    const gqlCtx = GqlExecutionContext.create(context);
+    const ctx = gqlCtx.getContext();
+    return { req: ctx.req, res: ctx.res };
+  }
+}
+```
+
+## Time Helpers
+
+```typescript
+import { seconds, minutes, hours } from '@nestjs/throttler';
+
+ThrottlerModule.forRoot({
+  throttlers: [
+    { ttl: seconds(30), limit: 10 },
+    { ttl: minutes(5), limit: 100 },
+  ],
+});
+```
+
+<!--
+Source references:
+- https://docs.nestjs.com/security/cors
+- https://docs.nestjs.com/security/helmet
+- https://docs.nestjs.com/security/rate-limiting
+-->