@punks/cli 0.1.16 → 1.0.1

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/micro-use-patterns.md

@@ -0,0 +1,167 @@
+---
+title: Use Message and Event Patterns Correctly
+impact: MEDIUM
+impactDescription: Proper patterns ensure reliable microservice communication
+tags: microservices, message-pattern, event-pattern, communication
+---
+
+## Use Message and Event Patterns Correctly
+
+NestJS microservices support two communication patterns: request-response (MessagePattern) and event-based (EventPattern). Use MessagePattern when you need a response, and EventPattern for fire-and-forget notifications. Understanding the difference prevents communication bugs.
+
+**Incorrect (using wrong pattern for use case):**
+
+```typescript
+// Use @MessagePattern for fire-and-forget
+@Controller()
+export class NotificationsController {
+  @MessagePattern('user.created')
+  async handleUserCreated(data: UserCreatedEvent) {
+    // This WAITS for response, blocking the sender
+    await this.emailService.sendWelcome(data.email);
+    // If email fails, sender gets an error (coupling!)
+  }
+}
+
+// Use @EventPattern expecting a response
+@Controller()
+export class OrdersController {
+  @EventPattern('inventory.check')
+  async checkInventory(data: CheckInventoryDto) {
+    const available = await this.inventory.check(data);
+    return available; // This return value is IGNORED with @EventPattern!
+  }
+}
+
+// Tight coupling in client
+@Injectable()
+export class UsersService {
+  async createUser(dto: CreateUserDto): Promise<User> {
+    const user = await this.repo.save(dto);
+
+    // Blocks until notification service responds
+    await this.client.send('user.created', user).toPromise();
+    // If notification service is down, user creation fails!
+
+    return user;
+  }
+}
+```
+
+**Correct (use MessagePattern for request-response, EventPattern for fire-and-forget):**
+
+```typescript
+// MessagePattern: Request-Response (when you NEED a response)
+@Controller()
+export class InventoryController {
+  @MessagePattern({ cmd: 'check_inventory' })
+  async checkInventory(data: CheckInventoryDto): Promise<InventoryResult> {
+    const result = await this.inventoryService.check(data.productId, data.quantity);
+    return result; // Response sent back to caller
+  }
+}
+
+// Client expects response
+@Injectable()
+export class OrdersService {
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    // Check inventory - we NEED this response to proceed
+    const inventory = await firstValueFrom(
+      this.inventoryClient.send<InventoryResult>(
+        { cmd: 'check_inventory' },
+        { productId: dto.productId, quantity: dto.quantity },
+      ),
+    );
+
+    if (!inventory.available) {
+      throw new BadRequestException('Insufficient inventory');
+    }
+
+    return this.repo.save(dto);
+  }
+}
+
+// EventPattern: Fire-and-Forget (for notifications, side effects)
+@Controller()
+export class NotificationsController {
+  @EventPattern('user.created')
+  async handleUserCreated(data: UserCreatedEvent): Promise<void> {
+    // No return value needed - just process the event
+    await this.emailService.sendWelcome(data.email);
+    await this.analyticsService.track('user_signup', data);
+    // If this fails, it doesn't affect the sender
+  }
+}
+
+// Client emits event without waiting
+@Injectable()
+export class UsersService {
+  async createUser(dto: CreateUserDto): Promise<User> {
+    const user = await this.repo.save(dto);
+
+    // Fire and forget - doesn't block, doesn't wait
+    this.eventClient.emit('user.created', {
+      userId: user.id,
+      email: user.email,
+      timestamp: new Date(),
+    });
+
+    return user; // User creation succeeds regardless of event handling
+  }
+}
+
+// Hybrid pattern for critical events
+@Injectable()
+export class OrdersService {
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    const order = await this.repo.save(dto);
+
+    // Critical: inventory reservation (use MessagePattern)
+    const reserved = await firstValueFrom(
+      this.inventoryClient.send({ cmd: 'reserve_inventory' }, {
+        orderId: order.id,
+        items: dto.items,
+      }),
+    );
+
+    if (!reserved.success) {
+      await this.repo.delete(order.id);
+      throw new BadRequestException('Could not reserve inventory');
+    }
+
+    // Non-critical: notifications (use EventPattern)
+    this.eventClient.emit('order.created', {
+      orderId: order.id,
+      userId: dto.userId,
+      total: dto.total,
+    });
+
+    return order;
+  }
+}
+
+// Error handling patterns
+// MessagePattern errors propagate to caller
+@MessagePattern({ cmd: 'get_user' })
+async getUser(userId: string): Promise<User> {
+  const user = await this.repo.findOne({ where: { id: userId } });
+  if (!user) {
+    throw new RpcException('User not found'); // Received by caller
+  }
+  return user;
+}
+
+// EventPattern errors should be handled locally
+@EventPattern('order.created')
+async handleOrderCreated(data: OrderCreatedEvent): Promise<void> {
+  try {
+    await this.processOrder(data);
+  } catch (error) {
+    // Log and potentially retry - don't throw
+    this.logger.error('Failed to process order event', error);
+    await this.deadLetterQueue.add(data);
+  }
+}
+```
+
+Reference: [NestJS Microservices](https://docs.nestjs.com/microservices/basics)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/micro-use-queues.md

@@ -0,0 +1,252 @@
+---
+title: Use Message Queues for Background Jobs
+impact: MEDIUM-HIGH
+impactDescription: Queues enable reliable background processing
+tags: microservices, queues, bullmq, background-jobs
+---
+
+## Use Message Queues for Background Jobs
+
+Use `@nestjs/bullmq` for background job processing. Queues decouple long-running tasks from HTTP requests, enable retry logic, and distribute workload across workers. Use them for emails, file processing, notifications, and any task that shouldn't block user requests.
+
+**Incorrect (long-running tasks in HTTP handlers):**
+
+```typescript
+// Long-running tasks in HTTP handlers
+@Controller('reports')
+export class ReportsController {
+  @Post()
+  async generate(@Body() dto: GenerateReportDto): Promise<Report> {
+    // This blocks the request for potentially minutes
+    const data = await this.fetchLargeDataset(dto);
+    const report = await this.processData(data); // Slow!
+    await this.sendEmail(dto.email, report); // Can fail!
+    return report; // Client times out
+  }
+}
+
+// Fire-and-forget without retry
+@Injectable()
+export class EmailService {
+  async sendWelcome(email: string): Promise<void> {
+    // If this fails, email is never sent
+    await this.mailer.send({ to: email, template: 'welcome' });
+    // No retry, no tracking, no visibility
+  }
+}
+
+// Use setInterval for scheduled tasks
+setInterval(async () => {
+  await cleanupOldRecords();
+}, 60000); // No error handling, memory leaks
+```
+
+**Correct (use BullMQ for background processing):**
+
+```typescript
+// Configure BullMQ
+import { BullModule } from '@nestjs/bullmq';
+
+@Module({
+  imports: [
+    BullModule.forRoot({
+      connection: {
+        host: 'localhost',
+        port: 6379,
+      },
+      defaultJobOptions: {
+        removeOnComplete: 1000,
+        removeOnFail: 5000,
+        attempts: 3,
+        backoff: {
+          type: 'exponential',
+          delay: 1000,
+        },
+      },
+    }),
+    BullModule.registerQueue(
+      { name: 'email' },
+      { name: 'reports' },
+      { name: 'notifications' },
+    ),
+  ],
+})
+export class QueueModule {}
+
+// Producer: Add jobs to queue
+@Injectable()
+export class ReportsService {
+  constructor(
+    @InjectQueue('reports') private reportsQueue: Queue,
+  ) {}
+
+  async requestReport(dto: GenerateReportDto): Promise<{ jobId: string }> {
+    // Return immediately, process in background
+    const job = await this.reportsQueue.add('generate', dto, {
+      priority: dto.urgent ? 1 : 10,
+      delay: dto.scheduledFor ? Date.parse(dto.scheduledFor) - Date.now() : 0,
+    });
+
+    return { jobId: job.id };
+  }
+
+  async getJobStatus(jobId: string): Promise<JobStatus> {
+    const job = await this.reportsQueue.getJob(jobId);
+    return {
+      status: await job.getState(),
+      progress: job.progress,
+      result: job.returnvalue,
+    };
+  }
+}
+
+// Consumer: Process jobs
+@Processor('reports')
+export class ReportsProcessor {
+  private readonly logger = new Logger(ReportsProcessor.name);
+
+  @Process('generate')
+  async generateReport(job: Job<GenerateReportDto>): Promise<Report> {
+    this.logger.log(`Processing report job ${job.id}`);
+
+    // Update progress
+    await job.updateProgress(10);
+
+    const data = await this.fetchData(job.data);
+    await job.updateProgress(50);
+
+    const report = await this.processData(data);
+    await job.updateProgress(90);
+
+    await this.saveReport(report);
+    await job.updateProgress(100);
+
+    return report;
+  }
+
+  @OnQueueActive()
+  onActive(job: Job) {
+    this.logger.log(`Processing job ${job.id}`);
+  }
+
+  @OnQueueCompleted()
+  onCompleted(job: Job, result: any) {
+    this.logger.log(`Job ${job.id} completed`);
+  }
+
+  @OnQueueFailed()
+  onFailed(job: Job, error: Error) {
+    this.logger.error(`Job ${job.id} failed: ${error.message}`);
+  }
+}
+
+// Email queue with retry
+@Processor('email')
+export class EmailProcessor {
+  @Process('send')
+  async sendEmail(job: Job<SendEmailDto>): Promise<void> {
+    const { to, template, data } = job.data;
+
+    try {
+      await this.mailer.send({
+        to,
+        template,
+        context: data,
+      });
+    } catch (error) {
+      // BullMQ will retry based on job options
+      throw error;
+    }
+  }
+}
+
+// Usage
+@Injectable()
+export class NotificationService {
+  constructor(@InjectQueue('email') private emailQueue: Queue) {}
+
+  async sendWelcome(user: User): Promise<void> {
+    await this.emailQueue.add(
+      'send',
+      {
+        to: user.email,
+        template: 'welcome',
+        data: { name: user.name },
+      },
+      {
+        attempts: 5,
+        backoff: { type: 'exponential', delay: 5000 },
+      },
+    );
+  }
+}
+
+// Scheduled jobs
+@Injectable()
+export class ScheduledJobsService implements OnModuleInit {
+  constructor(@InjectQueue('maintenance') private queue: Queue) {}
+
+  async onModuleInit(): Promise<void> {
+    // Clean up old reports daily at midnight
+    await this.queue.add(
+      'cleanup',
+      {},
+      {
+        repeat: { cron: '0 0 * * *' },
+        jobId: 'daily-cleanup', // Prevent duplicates
+      },
+    );
+
+    // Send digest every hour
+    await this.queue.add(
+      'digest',
+      {},
+      {
+        repeat: { every: 60 * 60 * 1000 },
+        jobId: 'hourly-digest',
+      },
+    );
+  }
+}
+
+@Processor('maintenance')
+export class MaintenanceProcessor {
+  @Process('cleanup')
+  async cleanup(): Promise<void> {
+    await this.cleanupOldReports();
+    await this.cleanupExpiredSessions();
+  }
+
+  @Process('digest')
+  async sendDigest(): Promise<void> {
+    const users = await this.getUsersForDigest();
+    for (const user of users) {
+      await this.emailQueue.add('send', { to: user.email, template: 'digest' });
+    }
+  }
+}
+
+// Queue monitoring with Bull Board
+import { BullBoardModule } from '@bull-board/nestjs';
+import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
+
+@Module({
+  imports: [
+    BullBoardModule.forRoot({
+      route: '/admin/queues',
+      adapter: ExpressAdapter,
+    }),
+    BullBoardModule.forFeature({
+      name: 'email',
+      adapter: BullMQAdapter,
+    }),
+    BullBoardModule.forFeature({
+      name: 'reports',
+      adapter: BullMQAdapter,
+    }),
+  ],
+})
+export class AdminModule {}
+```
+
+Reference: [NestJS Queues](https://docs.nestjs.com/techniques/queues)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/perf-async-hooks.md

@@ -0,0 +1,109 @@
+---
+title: Use Async Lifecycle Hooks Correctly
+impact: HIGH
+impactDescription: Improper async handling blocks application startup
+tags: performance, lifecycle, async, hooks
+---
+
+## Use Async Lifecycle Hooks Correctly
+
+NestJS lifecycle hooks (`onModuleInit`, `onApplicationBootstrap`, etc.) support async operations. However, misusing them can block application startup or cause race conditions. Understand the lifecycle order and use hooks appropriately.
+
+**Incorrect (fire-and-forget async without await):**
+
+```typescript
+// Fire-and-forget async without await
+@Injectable()
+export class DatabaseService implements OnModuleInit {
+  onModuleInit() {
+    // This runs but doesn't block - app starts before DB is ready!
+    this.connect();
+  }
+
+  private async connect() {
+    await this.pool.connect();
+    console.log('Database connected');
+  }
+}
+
+// Heavy blocking operations in constructor
+@Injectable()
+export class ConfigService {
+  private config: Config;
+
+  constructor() {
+    // BLOCKS entire module instantiation synchronously
+    this.config = fs.readFileSync('config.json');
+  }
+}
+```
+
+**Correct (return promises from async hooks):**
+
+```typescript
+// Return promise from async hooks
+@Injectable()
+export class DatabaseService implements OnModuleInit {
+  private pool: Pool;
+
+  async onModuleInit(): Promise<void> {
+    // NestJS waits for this to complete before continuing
+    await this.pool.connect();
+    console.log('Database connected');
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    // Clean up resources on shutdown
+    await this.pool.end();
+    console.log('Database disconnected');
+  }
+}
+
+// Use onApplicationBootstrap for cross-module dependencies
+@Injectable()
+export class CacheWarmerService implements OnApplicationBootstrap {
+  constructor(
+    private cache: CacheService,
+    private products: ProductsService,
+  ) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    // All modules are initialized, safe to warm cache
+    const products = await this.products.findPopular();
+    await this.cache.warmup(products);
+  }
+}
+
+// Heavy init in async hooks, not constructor
+@Injectable()
+export class ConfigService implements OnModuleInit {
+  private config: Config;
+
+  constructor() {
+    // Keep constructor synchronous and fast
+  }
+
+  async onModuleInit(): Promise<void> {
+    // Async loading in lifecycle hook
+    this.config = await this.loadConfig();
+  }
+
+  private async loadConfig(): Promise<Config> {
+    const file = await fs.promises.readFile('config.json');
+    return JSON.parse(file.toString());
+  }
+
+  get<T>(key: string): T {
+    return this.config[key];
+  }
+}
+
+// Enable shutdown hooks in main.ts
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  app.enableShutdownHooks(); // Enable SIGTERM/SIGINT handling
+  await app.listen(3000);
+}
+```
+
+Reference: [NestJS Lifecycle Events](https://docs.nestjs.com/fundamentals/lifecycle-events)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/perf-lazy-loading.md

@@ -0,0 +1,121 @@
+---
+title: Use Lazy Loading for Large Modules
+impact: MEDIUM
+impactDescription: Improves startup time for large applications
+tags: performance, lazy-loading, modules, optimization
+---
+
+## Use Lazy Loading for Large Modules
+
+NestJS supports lazy-loading modules, which defers initialization until first use. This is valuable for large applications where some features are rarely used, serverless deployments where cold start time matters, or when certain modules have heavy initialization costs.
+
+**Incorrect (loading everything eagerly):**
+
+```typescript
+// Load everything eagerly in a large app
+@Module({
+  imports: [
+    UsersModule,
+    OrdersModule,
+    PaymentsModule,
+    ReportsModule, // Heavy, rarely used
+    AnalyticsModule, // Heavy, rarely used
+    AdminModule, // Only admins use this
+    LegacyModule, // Migration module, rarely used
+    BulkImportModule, // Used once a month
+  ],
+})
+export class AppModule {}
+
+// All modules initialize at startup, even if never used
+// Slow cold starts in serverless
+// Memory wasted on unused modules
+```
+
+**Correct (lazy load rarely-used modules):**
+
+```typescript
+// Use LazyModuleLoader for optional modules
+import { LazyModuleLoader } from '@nestjs/core';
+
+@Injectable()
+export class ReportsService {
+  constructor(private lazyModuleLoader: LazyModuleLoader) {}
+
+  async generateReport(type: string): Promise<Report> {
+    // Load module only when needed
+    const { ReportsModule } = await import('./reports/reports.module');
+    const moduleRef = await this.lazyModuleLoader.load(() => ReportsModule);
+
+    const reportsService = moduleRef.get(ReportsGeneratorService);
+    return reportsService.generate(type);
+  }
+}
+
+// Lazy load admin features with caching
+@Injectable()
+export class AdminService {
+  private adminModule: ModuleRef | null = null;
+
+  constructor(private lazyModuleLoader: LazyModuleLoader) {}
+
+  private async getAdminModule(): Promise<ModuleRef> {
+    if (!this.adminModule) {
+      const { AdminModule } = await import('./admin/admin.module');
+      this.adminModule = await this.lazyModuleLoader.load(() => AdminModule);
+    }
+    return this.adminModule;
+  }
+
+  async runAdminTask(task: string): Promise<void> {
+    const moduleRef = await this.getAdminModule();
+    const taskRunner = moduleRef.get(AdminTaskRunner);
+    await taskRunner.run(task);
+  }
+}
+
+// Reusable lazy loader service
+@Injectable()
+export class ModuleLoaderService {
+  private loadedModules = new Map<string, ModuleRef>();
+
+  constructor(private lazyModuleLoader: LazyModuleLoader) {}
+
+  async load<T>(
+    key: string,
+    importFn: () => Promise<{ default: Type<T> } | Type<T>>,
+  ): Promise<ModuleRef> {
+    if (!this.loadedModules.has(key)) {
+      const module = await importFn();
+      const moduleType = 'default' in module ? module.default : module;
+      const moduleRef = await this.lazyModuleLoader.load(() => moduleType);
+      this.loadedModules.set(key, moduleRef);
+    }
+    return this.loadedModules.get(key)!;
+  }
+}
+
+// Preload modules in background after startup
+@Injectable()
+export class ModulePreloader implements OnApplicationBootstrap {
+  constructor(private lazyModuleLoader: LazyModuleLoader) {}
+
+  async onApplicationBootstrap(): Promise<void> {
+    setTimeout(async () => {
+      await this.preloadModule(() => import('./reports/reports.module'));
+    }, 5000); // 5 seconds after startup
+  }
+
+  private async preloadModule(importFn: () => Promise<any>): Promise<void> {
+    try {
+      const module = await importFn();
+      const moduleType = module.default || Object.values(module)[0];
+      await this.lazyModuleLoader.load(() => moduleType);
+    } catch (error) {
+      console.warn('Failed to preload module', error);
+    }
+  }
+}
+```
+
+Reference: [NestJS Lazy Loading Modules](https://docs.nestjs.com/fundamentals/lazy-loading-modules)