@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/api-versioning.md

@@ -0,0 +1,191 @@
+---
+title: Use API Versioning for Breaking Changes
+impact: MEDIUM
+impactDescription: Versioning allows you to evolve APIs without breaking existing clients
+tags: api, versioning, breaking-changes, compatibility
+---
+
+## Use API Versioning for Breaking Changes
+
+Use NestJS built-in versioning when making breaking changes to your API. Choose a versioning strategy (URI, header, or media type) and apply it consistently. This allows old clients to continue working while new clients use updated endpoints.
+
+**Incorrect (breaking changes without versioning):**
+
+```typescript
+// Breaking changes without versioning
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async findOne(@Param('id') id: string): Promise<User> {
+    // Original response: { id, name, email }
+    // Later changed to: { id, firstName, lastName, emailAddress }
+    // Old clients break!
+    return this.usersService.findOne(id);
+  }
+}
+
+// Manual versioning in routes
+@Controller('v1/users')
+export class UsersV1Controller {}
+
+@Controller('v2/users')
+export class UsersV2Controller {}
+// Inconsistent, error-prone, hard to maintain
+```
+
+**Correct (use NestJS built-in versioning):**
+
+```typescript
+// Enable versioning in main.ts
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  // URI versioning: /v1/users, /v2/users
+  app.enableVersioning({
+    type: VersioningType.URI,
+    defaultVersion: '1',
+  });
+
+  // Or header versioning: X-API-Version: 1
+  app.enableVersioning({
+    type: VersioningType.HEADER,
+    header: 'X-API-Version',
+    defaultVersion: '1',
+  });
+
+  // Or media type: Accept: application/json;v=1
+  app.enableVersioning({
+    type: VersioningType.MEDIA_TYPE,
+    key: 'v=',
+    defaultVersion: '1',
+  });
+
+  await app.listen(3000);
+}
+
+// Version-specific controllers
+@Controller('users')
+@Version('1')
+export class UsersV1Controller {
+  @Get(':id')
+  async findOne(@Param('id') id: string): Promise<UserV1Response> {
+    const user = await this.usersService.findOne(id);
+    // V1 response format
+    return {
+      id: user.id,
+      name: user.name,
+      email: user.email,
+    };
+  }
+}
+
+@Controller('users')
+@Version('2')
+export class UsersV2Controller {
+  @Get(':id')
+  async findOne(@Param('id') id: string): Promise<UserV2Response> {
+    const user = await this.usersService.findOne(id);
+    // V2 response format with breaking changes
+    return {
+      id: user.id,
+      firstName: user.firstName,
+      lastName: user.lastName,
+      emailAddress: user.email,
+      createdAt: user.createdAt,
+    };
+  }
+}
+
+// Per-route versioning - different versions for different routes
+@Controller('users')
+export class UsersController {
+  @Get()
+  @Version('1')
+  findAllV1(): Promise<UserV1Response[]> {
+    return this.usersService.findAllV1();
+  }
+
+  @Get()
+  @Version('2')
+  findAllV2(): Promise<UserV2Response[]> {
+    return this.usersService.findAllV2();
+  }
+
+  @Get(':id')
+  @Version(['1', '2']) // Same handler for multiple versions
+  findOne(@Param('id') id: string): Promise<User> {
+    return this.usersService.findOne(id);
+  }
+
+  @Post()
+  @Version(VERSION_NEUTRAL) // Available in all versions
+  create(@Body() dto: CreateUserDto): Promise<User> {
+    return this.usersService.create(dto);
+  }
+}
+
+// Shared service with version-specific logic
+@Injectable()
+export class UsersService {
+  async findOne(id: string, version: string): Promise<any> {
+    const user = await this.repo.findOne({ where: { id } });
+
+    if (version === '1') {
+      return this.toV1Response(user);
+    }
+    return this.toV2Response(user);
+  }
+
+  private toV1Response(user: User): UserV1Response {
+    return {
+      id: user.id,
+      name: `${user.firstName} ${user.lastName}`,
+      email: user.email,
+    };
+  }
+
+  private toV2Response(user: User): UserV2Response {
+    return {
+      id: user.id,
+      firstName: user.firstName,
+      lastName: user.lastName,
+      emailAddress: user.email,
+      createdAt: user.createdAt,
+    };
+  }
+}
+
+// Controller extracts version
+@Controller('users')
+export class UsersController {
+  @Get(':id')
+  async findOne(
+    @Param('id') id: string,
+    @Headers('X-API-Version') version: string = '1',
+  ): Promise<any> {
+    return this.usersService.findOne(id, version);
+  }
+}
+
+// Deprecation strategy - mark old versions as deprecated
+@Controller('users')
+@Version('1')
+@UseInterceptors(DeprecationInterceptor)
+export class UsersV1Controller {
+  // All V1 routes will include deprecation warning
+}
+
+@Injectable()
+export class DeprecationInterceptor implements NestInterceptor {
+  intercept(context: ExecutionContext, next: CallHandler): Observable<any> {
+    const response = context.switchToHttp().getResponse();
+    response.setHeader('Deprecation', 'true');
+    response.setHeader('Sunset', 'Sat, 1 Jan 2025 00:00:00 GMT');
+    response.setHeader('Link', '</v2/users>; rel="successor-version"');
+
+    return next.handle();
+  }
+}
+```
+
+Reference: [NestJS Versioning](https://docs.nestjs.com/techniques/versioning)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/arch-avoid-circular-deps.md

@@ -0,0 +1,80 @@
+---
+title: Avoid Circular Dependencies
+impact: CRITICAL
+impactDescription: "#1 cause of runtime crashes"
+tags: architecture, modules, dependencies
+---
+
+## Avoid Circular Dependencies
+
+Circular dependencies occur when Module A imports Module B, and Module B imports Module A (directly or transitively). NestJS can sometimes resolve these through forward references, but they indicate architectural problems and should be avoided. This is the #1 cause of runtime crashes in NestJS applications.
+
+**Incorrect (circular module imports):**
+
+```typescript
+// users.module.ts
+@Module({
+  imports: [OrdersModule], // Orders needs Users, Users needs Orders = circular
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}
+
+// orders.module.ts
+@Module({
+  imports: [UsersModule], // Circular dependency!
+  providers: [OrdersService],
+  exports: [OrdersService],
+})
+export class OrdersModule {}
+```
+
+**Correct (extract shared logic or use events):**
+
+```typescript
+// Option 1: Extract shared logic to a third module
+// shared.module.ts
+@Module({
+  providers: [SharedService],
+  exports: [SharedService],
+})
+export class SharedModule {}
+
+// users.module.ts
+@Module({
+  imports: [SharedModule],
+  providers: [UsersService],
+})
+export class UsersModule {}
+
+// orders.module.ts
+@Module({
+  imports: [SharedModule],
+  providers: [OrdersService],
+})
+export class OrdersModule {}
+
+// Option 2: Use events for decoupled communication
+// users.service.ts
+@Injectable()
+export class UsersService {
+  constructor(private eventEmitter: EventEmitter2) {}
+
+  async createUser(data: CreateUserDto) {
+    const user = await this.userRepo.save(data);
+    this.eventEmitter.emit('user.created', user);
+    return user;
+  }
+}
+
+// orders.service.ts
+@Injectable()
+export class OrdersService {
+  @OnEvent('user.created')
+  handleUserCreated(user: User) {
+    // React to user creation without direct dependency
+  }
+}
+```
+
+Reference: [NestJS Circular Dependency](https://docs.nestjs.com/fundamentals/circular-dependency)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/arch-feature-modules.md

@@ -0,0 +1,82 @@
+---
+title: Organize by Feature Modules
+impact: CRITICAL
+impactDescription: "3-5x faster onboarding and development"
+tags: architecture, modules, organization
+---
+
+## Organize by Feature Modules
+
+Organize your application into feature modules that encapsulate related functionality. Each feature module should be self-contained with its own controllers, services, entities, and DTOs. Avoid organizing by technical layer (all controllers together, all services together). This enables 3-5x faster onboarding and feature development.
+
+**Incorrect (technical layer organization):**
+
+```typescript
+// Technical layer organization (anti-pattern)
+src/
+├── controllers/
+│   ├── users.controller.ts
+│   ├── orders.controller.ts
+│   └── products.controller.ts
+├── services/
+│   ├── users.service.ts
+│   ├── orders.service.ts
+│   └── products.service.ts
+├── entities/
+│   ├── user.entity.ts
+│   ├── order.entity.ts
+│   └── product.entity.ts
+└── app.module.ts  // Imports everything directly
+```
+
+**Correct (feature module organization):**
+
+```typescript
+// Feature module organization
+src/
+├── users/
+│   ├── dto/
+│   │   ├── create-user.dto.ts
+│   │   └── update-user.dto.ts
+│   ├── entities/
+│   │   └── user.entity.ts
+│   ├── users.controller.ts
+│   ├── users.service.ts
+│   ├── users.repository.ts
+│   └── users.module.ts
+├── orders/
+│   ├── dto/
+│   ├── entities/
+│   ├── orders.controller.ts
+│   ├── orders.service.ts
+│   └── orders.module.ts
+├── shared/
+│   ├── guards/
+│   ├── interceptors/
+│   ├── filters/
+│   └── shared.module.ts
+└── app.module.ts
+
+// users.module.ts
+@Module({
+  imports: [TypeOrmModule.forFeature([User])],
+  controllers: [UsersController],
+  providers: [UsersService, UsersRepository],
+  exports: [UsersService], // Only export what others need
+})
+export class UsersModule {}
+
+// app.module.ts
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    TypeOrmModule.forRoot(),
+    UsersModule,
+    OrdersModule,
+    SharedModule,
+  ],
+})
+export class AppModule {}
+```
+
+Reference: [NestJS Modules](https://docs.nestjs.com/modules)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/arch-module-sharing.md

@@ -0,0 +1,141 @@
+---
+title: Use Proper Module Sharing Patterns
+impact: CRITICAL
+impactDescription: Prevents duplicate instances, memory leaks, and state inconsistency
+tags: architecture, modules, sharing, exports
+---
+
+## Use Proper Module Sharing Patterns
+
+NestJS modules are singletons by default. When a service is properly exported from a module and that module is imported elsewhere, the same instance is shared. However, providing a service in multiple modules creates separate instances, leading to memory waste, state inconsistency, and confusing behavior. Always encapsulate services in dedicated modules, export them explicitly, and import the module where needed.
+
+**Incorrect (service provided in multiple modules):**
+
+```typescript
+// StorageService provided directly in multiple modules - WRONG
+// storage.service.ts
+@Injectable()
+export class StorageService {
+  private cache = new Map(); // Each instance has separate state!
+
+  store(key: string, value: any) {
+    this.cache.set(key, value);
+  }
+}
+
+// app.module.ts
+@Module({
+  providers: [StorageService], // Instance #1
+  controllers: [AppController],
+})
+export class AppModule {}
+
+// videos.module.ts
+@Module({
+  providers: [StorageService], // Instance #2 - different from AppModule!
+  controllers: [VideosController],
+})
+export class VideosModule {}
+
+// Problems:
+// 1. Two separate StorageService instances exist
+// 2. cache.set() in VideosModule doesn't affect AppModule's cache
+// 3. Memory wasted on duplicate instances
+// 4. Debugging nightmares when state doesn't sync
+```
+
+**Correct (dedicated module with exports):**
+
+```typescript
+// storage/storage.module.ts
+@Module({
+  providers: [StorageService],
+  exports: [StorageService], // Make available to importers
+})
+export class StorageModule {}
+
+// videos/videos.module.ts
+@Module({
+  imports: [StorageModule], // Import the module, not the service
+  controllers: [VideosController],
+  providers: [VideosService],
+})
+export class VideosModule {}
+
+// channels/channels.module.ts
+@Module({
+  imports: [StorageModule], // Same instance shared
+  controllers: [ChannelsController],
+  providers: [ChannelsService],
+})
+export class ChannelsModule {}
+
+// app.module.ts
+@Module({
+  imports: [
+    StorageModule, // Only if AppModule itself needs StorageService
+    VideosModule,
+    ChannelsModule,
+  ],
+})
+export class AppModule {}
+
+// Now all modules share the SAME StorageService instance
+```
+
+**When to use @Global() (sparingly):**
+
+```typescript
+// ONLY for truly cross-cutting concerns
+@Global()
+@Module({
+  providers: [ConfigService, LoggerService],
+  exports: [ConfigService, LoggerService],
+})
+export class CoreModule {}
+
+// Import once in AppModule
+@Module({
+  imports: [CoreModule], // Registered globally, available everywhere
+})
+export class AppModule {}
+
+// Other modules don't need to import CoreModule
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService], // Can inject ConfigService without importing
+})
+export class UsersModule {}
+
+// WARNING: Don't make everything global!
+// - Hides dependencies (can't see what a module needs from imports)
+// - Makes testing harder
+// - Reserve for: config, logging, database connections
+```
+
+**Module re-exporting pattern:**
+
+```typescript
+// common.module.ts - shared utilities
+@Module({
+  providers: [DateService, ValidationService],
+  exports: [DateService, ValidationService],
+})
+export class CommonModule {}
+
+// core.module.ts - re-exports common for convenience
+@Module({
+  imports: [CommonModule, DatabaseModule],
+  exports: [CommonModule, DatabaseModule], // Re-export for consumers
+})
+export class CoreModule {}
+
+// feature.module.ts - imports CoreModule, gets both
+@Module({
+  imports: [CoreModule], // Gets CommonModule + DatabaseModule
+  controllers: [FeatureController],
+})
+export class FeatureModule {}
+```
+
+Reference: [NestJS Modules](https://docs.nestjs.com/modules#shared-modules)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/arch-single-responsibility.md

@@ -0,0 +1,106 @@
+---
+title: Single Responsibility for Services
+impact: CRITICAL
+impactDescription: "40%+ improvement in testability"
+tags: architecture, services, single-responsibility
+---
+
+## Single Responsibility for Services
+
+Each service should have a single, well-defined responsibility. Avoid "god services" that handle multiple unrelated concerns. If a service name includes "And" or handles more than one domain concept, it likely violates single responsibility. This reduces complexity and improves testability by 40%+.
+
+**Incorrect (god service anti-pattern):**
+
+```typescript
+// God service anti-pattern
+@Injectable()
+export class UserAndOrderService {
+  constructor(
+    private userRepo: UserRepository,
+    private orderRepo: OrderRepository,
+    private mailer: MailService,
+    private payment: PaymentService,
+  ) {}
+
+  async createUser(dto: CreateUserDto) {
+    const user = await this.userRepo.save(dto);
+    await this.mailer.sendWelcome(user);
+    return user;
+  }
+
+  async createOrder(userId: string, dto: CreateOrderDto) {
+    const order = await this.orderRepo.save({ userId, ...dto });
+    await this.payment.charge(order);
+    await this.mailer.sendOrderConfirmation(order);
+    return order;
+  }
+
+  async calculateOrderStats(userId: string) {
+    // Stats logic mixed in
+  }
+
+  async validatePayment(orderId: string) {
+    // Payment logic mixed in
+  }
+}
+```
+
+**Correct (focused services with single responsibility):**
+
+```typescript
+// Focused services with single responsibility
+@Injectable()
+export class UsersService {
+  constructor(private userRepo: UserRepository) {}
+
+  async create(dto: CreateUserDto): Promise<User> {
+    return this.userRepo.save(dto);
+  }
+
+  async findById(id: string): Promise<User> {
+    return this.userRepo.findOneOrFail({ where: { id } });
+  }
+}
+
+@Injectable()
+export class OrdersService {
+  constructor(private orderRepo: OrderRepository) {}
+
+  async create(userId: string, dto: CreateOrderDto): Promise<Order> {
+    return this.orderRepo.save({ userId, ...dto });
+  }
+
+  async findByUser(userId: string): Promise<Order[]> {
+    return this.orderRepo.find({ where: { userId } });
+  }
+}
+
+@Injectable()
+export class OrderStatsService {
+  constructor(private orderRepo: OrderRepository) {}
+
+  async calculateForUser(userId: string): Promise<OrderStats> {
+    // Focused stats calculation
+  }
+}
+
+// Orchestration in controller or dedicated orchestrator
+@Controller('orders')
+export class OrdersController {
+  constructor(
+    private orders: OrdersService,
+    private payment: PaymentService,
+    private notifications: NotificationService,
+  ) {}
+
+  @Post()
+  async create(@CurrentUser() user: User, @Body() dto: CreateOrderDto) {
+    const order = await this.orders.create(user.id, dto);
+    await this.payment.charge(order);
+    await this.notifications.sendOrderConfirmation(order);
+    return order;
+  }
+}
+```
+
+Reference: [NestJS Providers](https://docs.nestjs.com/providers)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/arch-use-events.md

@@ -0,0 +1,108 @@
+---
+title: Use Event-Driven Architecture for Decoupling
+impact: MEDIUM-HIGH
+impactDescription: Enables async processing and modularity
+tags: architecture, events, decoupling
+---
+
+## Use Event-Driven Architecture for Decoupling
+
+Use `@nestjs/event-emitter` for intra-service events and message brokers for inter-service communication. Events allow modules to react to changes without direct dependencies, improving modularity and enabling async processing.
+
+**Incorrect (direct service coupling):**
+
+```typescript
+// Direct service coupling
+@Injectable()
+export class OrdersService {
+  constructor(
+    private inventoryService: InventoryService,
+    private emailService: EmailService,
+    private analyticsService: AnalyticsService,
+    private notificationService: NotificationService,
+    private loyaltyService: LoyaltyService,
+  ) {}
+
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    const order = await this.repo.save(dto);
+
+    // Tight coupling - OrdersService knows about all consumers
+    await this.inventoryService.reserve(order.items);
+    await this.emailService.sendConfirmation(order);
+    await this.analyticsService.track('order_created', order);
+    await this.notificationService.push(order.userId, 'Order placed');
+    await this.loyaltyService.addPoints(order.userId, order.total);
+
+    // Adding new behavior requires modifying this service
+    return order;
+  }
+}
+```
+
+**Correct (event-driven decoupling):**
+
+```typescript
+// Use EventEmitter for decoupling
+import { EventEmitter2 } from '@nestjs/event-emitter';
+
+// Define event
+export class OrderCreatedEvent {
+  constructor(
+    public readonly orderId: string,
+    public readonly userId: string,
+    public readonly items: OrderItem[],
+    public readonly total: number,
+  ) {}
+}
+
+// Service emits events
+@Injectable()
+export class OrdersService {
+  constructor(
+    private eventEmitter: EventEmitter2,
+    private repo: Repository<Order>,
+  ) {}
+
+  async createOrder(dto: CreateOrderDto): Promise<Order> {
+    const order = await this.repo.save(dto);
+
+    // Emit event - no knowledge of consumers
+    this.eventEmitter.emit(
+      'order.created',
+      new OrderCreatedEvent(order.id, order.userId, order.items, order.total),
+    );
+
+    return order;
+  }
+}
+
+// Listeners in separate modules
+@Injectable()
+export class InventoryListener {
+  @OnEvent('order.created')
+  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
+    await this.inventoryService.reserve(event.items);
+  }
+}
+
+@Injectable()
+export class EmailListener {
+  @OnEvent('order.created')
+  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
+    await this.emailService.sendConfirmation(event.orderId);
+  }
+}
+
+@Injectable()
+export class AnalyticsListener {
+  @OnEvent('order.created')
+  async handleOrderCreated(event: OrderCreatedEvent): Promise<void> {
+    await this.analyticsService.track('order_created', {
+      orderId: event.orderId,
+      total: event.total,
+    });
+  }
+}
+```
+
+Reference: [NestJS Events](https://docs.nestjs.com/techniques/events)