@biggora/claude-plugins 1.2.0 → 1.3.0

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

@@ -0,0 +1,93 @@
+---
+name: recipes-documentation
+description: OpenAPI/Swagger documentation setup in NestJS
+---
+
+# API Documentation
+
+NestJS provides integration with Swagger/OpenAPI for automatic API documentation generation.
+
+## Installation
+
+```bash
+npm install --save @nestjs/swagger
+```
+
+## Basic Setup
+
+```typescript
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  const config = new DocumentBuilder()
+    .setTitle('Cats example')
+    .setDescription('The cats API description')
+    .setVersion('1.0')
+    .addTag('cats')
+    .build();
+  const document = SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, document);
+
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+## DTO Decorators
+
+```typescript
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateCatDto {
+  @ApiProperty()
+  name: string;
+
+  @ApiProperty()
+  age: number;
+
+  @ApiProperty()
+  breed: string;
+}
+```
+
+## Controller Decorators
+
+```typescript
+import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
+
+@ApiTags('cats')
+@Controller('cats')
+export class CatsController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new cat' })
+  @ApiResponse({ status: 201, description: 'The cat has been successfully created.' })
+  @ApiResponse({ status: 403, description: 'Forbidden.' })
+  create(@Body() createCatDto: CreateCatDto) {
+    return this.catsService.create(createCatDto);
+  }
+}
+```
+
+## Security
+
+```typescript
+const config = new DocumentBuilder()
+  .addBearerAuth()
+  .build();
+```
+
+## Key Points
+
+- Use `@nestjs/swagger` for OpenAPI integration
+- Decorate DTOs with `@ApiProperty()`
+- Use `@ApiTags()` to group endpoints
+- Add `@ApiOperation()` and `@ApiResponse()` for documentation
+- Configure security schemes for authentication
+- Access docs at `/api` endpoint
+
+<!--
+Source references:
+- https://docs.nestjs.com/openapi/introduction
+-->

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

@@ -0,0 +1,153 @@
+---
+name: mongoose
+description: MongoDB integration with Mongoose ODM
+---
+
+# Mongoose (MongoDB)
+
+Mongoose is the most popular MongoDB object modeling tool for Node.js.
+
+## Installation
+
+```bash
+npm i @nestjs/mongoose mongoose
+```
+
+## Setup
+
+```typescript
+@Module({
+  imports: [
+    MongooseModule.forRoot('mongodb://localhost/nest'),
+    // Or with options
+    MongooseModule.forRoot('mongodb://localhost/nest', {
+      connectionName: 'cats',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+## Schema Definition
+
+```typescript
+import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
+import { HydratedDocument } from 'mongoose';
+
+export type CatDocument = HydratedDocument<Cat>;
+
+@Schema()
+export class Cat {
+  @Prop()
+  name: string;
+
+  @Prop({ required: true })
+  age: number;
+
+  @Prop([String])
+  tags: string[];
+
+  @Prop({ default: Date.now })
+  createdAt: Date;
+
+  @Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' })
+  owner: Owner;
+}
+
+export const CatSchema = SchemaFactory.createForClass(Cat);
+```
+
+## Register Model
+
+```typescript
+@Module({
+  imports: [
+    MongooseModule.forFeature([
+      { name: Cat.name, schema: CatSchema },
+    ]),
+  ],
+})
+export class CatsModule {}
+```
+
+## Inject and Use
+
+```typescript
+@Injectable()
+export class CatsService {
+  constructor(
+    @InjectModel(Cat.name) private catModel: Model<CatDocument>,
+  ) {}
+
+  async create(createCatDto: CreateCatDto) {
+    const created = new this.catModel(createCatDto);
+    return created.save();
+  }
+
+  async findAll(): Promise<Cat[]> {
+    return this.catModel.find().exec();
+  }
+
+  async findOne(id: string) {
+    return this.catModel.findById(id).populate('owner').exec();
+  }
+}
+```
+
+## @Prop Options
+
+| Option | Description |
+|--------|-------------|
+| `required` | Required field |
+| `default` | Default value |
+| `unique` | Unique index |
+| `index` | Create index |
+| `type` | Explicit type (e.g., `mongoose.Schema.Types.ObjectId`) |
+| `ref` | Reference to another model |
+
+## Relations (Population)
+
+```typescript
+@Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' })
+owner: Owner;
+
+// Multiple
+@Prop({ type: [{ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' }] })
+owners: Owner[];
+```
+
+```typescript
+return this.catModel.find().populate('owner').exec();
+return this.catModel.find().populate({ path: 'owner', select: 'name' }).exec();
+```
+
+## Plugins
+
+```typescript
+CatSchema.plugin(require('mongoose-autopopulate'));
+```
+
+## Async Configuration
+
+```typescript
+MongooseModule.forRootAsync({
+  imports: [ConfigModule],
+  useFactory: (config: ConfigService) => ({
+    uri: config.get('MONGODB_URI'),
+  }),
+  inject: [ConfigService],
+}),
+```
+
+## Key Points
+
+- Use `@Schema()` and `@Prop()` decorators
+- `SchemaFactory.createForClass()` generates schema
+- `@InjectModel()` injects Model
+- Use `populate()` for relations
+- `HydratedDocument<Cat>` for typed documents
+
+<!--
+Source references:
+- https://docs.nestjs.com/techniques/mongodb
+-->

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

@@ -0,0 +1,98 @@
+---
+name: recipes-prisma
+description: Prisma ORM integration in NestJS
+---
+
+# Prisma Integration
+
+Prisma is a next-generation ORM that provides type-safe database access.
+
+## Installation
+
+```bash
+npm install --save @prisma/client
+npm install --save-dev prisma
+npx prisma init
+```
+
+## Prisma Service
+
+```typescript
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { PrismaClient } from '@prisma/client';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit {
+  async onModuleInit() {
+    await this.$connect();
+  }
+}
+```
+
+## Module Setup
+
+```typescript
+import { Module } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+@Module({
+  providers: [PrismaService],
+  exports: [PrismaService],
+})
+export class PrismaModule {}
+```
+
+## Using Prisma Service
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PrismaService } from './prisma.service';
+
+@Injectable()
+export class UsersService {
+  constructor(private prisma: PrismaService) {}
+
+  async findAll() {
+    return this.prisma.user.findMany();
+  }
+
+  async findOne(id: number) {
+    return this.prisma.user.findUnique({
+      where: { id },
+    });
+  }
+
+  async create(data: CreateUserDto) {
+    return this.prisma.user.create({
+      data,
+    });
+  }
+
+  async update(id: number, data: UpdateUserDto) {
+    return this.prisma.user.update({
+      where: { id },
+      data,
+    });
+  }
+
+  async remove(id: number) {
+    return this.prisma.user.delete({
+      where: { id },
+    });
+  }
+}
+```
+
+## Key Points
+
+- Prisma provides type-safe database access
+- Extend `PrismaClient` for service
+- Use `$connect()` in `onModuleInit()`
+- Prisma generates types from schema
+- Use Prisma Studio for database management
+- Supports migrations and seeding
+
+<!--
+Source references:
+- https://docs.nestjs.com/recipes/prisma
+-->

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