@punks/cli 0.1.15 → 1.0.0

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/perf-optimize-database.md

@@ -0,0 +1,131 @@
+---
+title: Optimize Database Queries
+impact: HIGH
+impactDescription: Database queries are typically the largest source of latency
+tags: performance, database, queries, optimization
+---
+
+## Optimize Database Queries
+
+Select only needed columns, use proper indexes, avoid over-fetching relations, and consider query performance when designing your data access. Most API slowness traces back to inefficient database queries.
+
+**Incorrect (over-fetching data and missing indexes):**
+
+```typescript
+// Select everything when you need few fields
+@Injectable()
+export class UsersService {
+  async findAllEmails(): Promise<string[]> {
+    const users = await this.repo.find();
+    // Fetches ALL columns for ALL users
+    return users.map((u) => u.email);
+  }
+
+  async getUserSummary(id: string): Promise<UserSummary> {
+    const user = await this.repo.findOne({
+      where: { id },
+      relations: ['posts', 'posts.comments', 'posts.comments.author', 'followers'],
+    });
+    // Over-fetches massive relation tree
+    return { name: user.name, postCount: user.posts.length };
+  }
+}
+
+// No indexes on frequently queried columns
+@Entity()
+export class Order {
+  @Column()
+  userId: string; // No index - full table scan on every lookup
+
+  @Column()
+  status: string; // No index - slow status filtering
+}
+```
+
+**Correct (select only needed data with proper indexes):**
+
+```typescript
+// Select only needed columns
+@Injectable()
+export class UsersService {
+  async findAllEmails(): Promise<string[]> {
+    const users = await this.repo.find({
+      select: ['email'], // Only fetch email column
+    });
+    return users.map((u) => u.email);
+  }
+
+  // Use QueryBuilder for complex selections
+  async getUserSummary(id: string): Promise<UserSummary> {
+    return this.repo
+      .createQueryBuilder('user')
+      .select('user.name', 'name')
+      .addSelect('COUNT(post.id)', 'postCount')
+      .leftJoin('user.posts', 'post')
+      .where('user.id = :id', { id })
+      .groupBy('user.id')
+      .getRawOne();
+  }
+
+  // Fetch relations only when needed
+  async getFullProfile(id: string): Promise<User> {
+    return this.repo.findOne({
+      where: { id },
+      relations: ['posts'], // Only immediate relation
+      select: {
+        id: true,
+        name: true,
+        email: true,
+        posts: {
+          id: true,
+          title: true,
+        },
+      },
+    });
+  }
+}
+
+// Add indexes on frequently queried columns
+@Entity()
+@Index(['userId'])
+@Index(['status'])
+@Index(['createdAt'])
+@Index(['userId', 'status']) // Composite index for common query pattern
+export class Order {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  userId: string;
+
+  @Column()
+  status: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+}
+
+// Always paginate large datasets
+@Injectable()
+export class OrdersService {
+  async findAll(page = 1, limit = 20): Promise<PaginatedResult<Order>> {
+    const [items, total] = await this.repo.findAndCount({
+      skip: (page - 1) * limit,
+      take: limit,
+      order: { createdAt: 'DESC' },
+    });
+
+    return {
+      items,
+      meta: {
+        page,
+        limit,
+        total,
+        totalPages: Math.ceil(total / limit),
+      },
+    };
+  }
+}
+```
+
+Reference: [TypeORM Query Builder](https://typeorm.io/select-query-builder)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/perf-use-caching.md

@@ -0,0 +1,128 @@
+---
+title: Use Caching Strategically
+impact: HIGH
+impactDescription: Dramatically reduces database load and response times
+tags: performance, caching, redis, optimization
+---
+
+## Use Caching Strategically
+
+Implement caching for expensive operations, frequently accessed data, and external API calls. Use NestJS CacheModule with appropriate TTLs and cache invalidation strategies. Don't cache everything - focus on high-impact areas.
+
+**Incorrect (no caching or caching everything):**
+
+```typescript
+// No caching for expensive, repeated queries
+@Injectable()
+export class ProductsService {
+  async getPopular(): Promise<Product[]> {
+    // Runs complex aggregation query EVERY request
+    return this.productsRepo
+      .createQueryBuilder('p')
+      .leftJoin('p.orders', 'o')
+      .select('p.*, COUNT(o.id) as orderCount')
+      .groupBy('p.id')
+      .orderBy('orderCount', 'DESC')
+      .limit(20)
+      .getMany();
+  }
+}
+
+// Cache everything without thought
+@Injectable()
+export class UsersService {
+  @CacheKey('users')
+  @CacheTTL(3600)
+  @UseInterceptors(CacheInterceptor)
+  async findAll(): Promise<User[]> {
+    // Caching user list for 1 hour is wrong if data changes frequently
+    return this.usersRepo.find();
+  }
+}
+```
+
+**Correct (strategic caching with proper invalidation):**
+
+```typescript
+// Setup caching module
+@Module({
+  imports: [
+    CacheModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        stores: [
+          new KeyvRedis(config.get('REDIS_URL')),
+        ],
+        ttl: 60 * 1000, // Default 60s
+      }),
+    }),
+  ],
+})
+export class AppModule {}
+
+// Manual caching for granular control
+@Injectable()
+export class ProductsService {
+  constructor(
+    @Inject(CACHE_MANAGER) private cache: Cache,
+    private productsRepo: ProductRepository,
+  ) {}
+
+  async getPopular(): Promise<Product[]> {
+    const cacheKey = 'products:popular';
+
+    // Try cache first
+    const cached = await this.cache.get<Product[]>(cacheKey);
+    if (cached) return cached;
+
+    // Cache miss - fetch and cache
+    const products = await this.fetchPopularProducts();
+    await this.cache.set(cacheKey, products, 5 * 60 * 1000); // 5 min TTL
+    return products;
+  }
+
+  // Invalidate cache on changes
+  async updateProduct(id: string, dto: UpdateProductDto): Promise<Product> {
+    const product = await this.productsRepo.save({ id, ...dto });
+    await this.cache.del('products:popular'); // Invalidate
+    return product;
+  }
+}
+
+// Decorator-based caching with auto-interceptor
+@Controller('categories')
+@UseInterceptors(CacheInterceptor)
+export class CategoriesController {
+  @Get()
+  @CacheTTL(30 * 60 * 1000) // 30 minutes - categories rarely change
+  findAll(): Promise<Category[]> {
+    return this.categoriesService.findAll();
+  }
+
+  @Get(':id')
+  @CacheTTL(60 * 1000) // 1 minute
+  @CacheKey('category')
+  findOne(@Param('id') id: string): Promise<Category> {
+    return this.categoriesService.findOne(id);
+  }
+}
+
+// Event-based cache invalidation
+@Injectable()
+export class CacheInvalidationService {
+  constructor(@Inject(CACHE_MANAGER) private cache: Cache) {}
+
+  @OnEvent('product.created')
+  @OnEvent('product.updated')
+  @OnEvent('product.deleted')
+  async invalidateProductCaches(event: ProductEvent) {
+    await Promise.all([
+      this.cache.del('products:popular'),
+      this.cache.del(`product:${event.productId}`),
+    ]);
+  }
+}
+```
+
+Reference: [NestJS Caching](https://docs.nestjs.com/techniques/caching)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/security-auth-jwt.md

@@ -0,0 +1,146 @@
+---
+title: Implement Secure JWT Authentication
+impact: CRITICAL
+impactDescription: Essential for secure APIs
+tags: security, jwt, authentication, tokens
+---
+
+## Implement Secure JWT Authentication
+
+Use `@nestjs/jwt` with `@nestjs/passport` for authentication. Store secrets securely, use appropriate token lifetimes, implement refresh tokens, and validate tokens properly. Never expose sensitive data in JWT payloads.
+
+**Incorrect (insecure JWT implementation):**
+
+```typescript
+// Hardcode secrets
+@Module({
+  imports: [
+    JwtModule.register({
+      secret: 'my-secret-key', // Exposed in code
+      signOptions: { expiresIn: '7d' }, // Too long
+    }),
+  ],
+})
+export class AuthModule {}
+
+// Store sensitive data in JWT
+async login(user: User): Promise<{ accessToken: string }> {
+  const payload = {
+    sub: user.id,
+    email: user.email,
+    password: user.password, // NEVER include password!
+    ssn: user.ssn, // NEVER include sensitive data!
+    isAdmin: user.isAdmin, // Can be tampered if not verified
+  };
+  return { accessToken: this.jwtService.sign(payload) };
+}
+
+// Skip token validation
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor() {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: 'my-secret',
+    });
+  }
+
+  async validate(payload: any): Promise<any> {
+    return payload; // No validation of user existence
+  }
+}
+```
+
+**Correct (secure JWT with refresh tokens):**
+
+```typescript
+// Secure JWT configuration
+@Module({
+  imports: [
+    JwtModule.registerAsync({
+      imports: [ConfigModule],
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.get<string>('JWT_SECRET'),
+        signOptions: {
+          expiresIn: '15m', // Short-lived access tokens
+          issuer: config.get<string>('JWT_ISSUER'),
+          audience: config.get<string>('JWT_AUDIENCE'),
+        },
+      }),
+    }),
+    PassportModule.register({ defaultStrategy: 'jwt' }),
+  ],
+})
+export class AuthModule {}
+
+// Minimal JWT payload
+@Injectable()
+export class AuthService {
+  async login(user: User): Promise<TokenResponse> {
+    // Only include necessary, non-sensitive data
+    const payload: JwtPayload = {
+      sub: user.id,
+      email: user.email,
+      roles: user.roles,
+      iat: Math.floor(Date.now() / 1000),
+    };
+
+    const accessToken = this.jwtService.sign(payload);
+    const refreshToken = await this.createRefreshToken(user.id);
+
+    return { accessToken, refreshToken, expiresIn: 900 };
+  }
+
+  private async createRefreshToken(userId: string): Promise<string> {
+    const token = randomBytes(32).toString('hex');
+    const hashedToken = await bcrypt.hash(token, 10);
+
+    await this.refreshTokenRepo.save({
+      userId,
+      token: hashedToken,
+      expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000), // 7 days
+    });
+
+    return token;
+  }
+}
+
+// Proper JWT strategy with validation
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(
+    private config: ConfigService,
+    private usersService: UsersService,
+  ) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      secretOrKey: config.get<string>('JWT_SECRET'),
+      ignoreExpiration: false,
+      issuer: config.get<string>('JWT_ISSUER'),
+      audience: config.get<string>('JWT_AUDIENCE'),
+    });
+  }
+
+  async validate(payload: JwtPayload): Promise<User> {
+    // Verify user still exists and is active
+    const user = await this.usersService.findById(payload.sub);
+
+    if (!user || !user.isActive) {
+      throw new UnauthorizedException('User not found or inactive');
+    }
+
+    // Verify token wasn't issued before password change
+    if (user.passwordChangedAt) {
+      const tokenIssuedAt = new Date(payload.iat * 1000);
+      if (tokenIssuedAt < user.passwordChangedAt) {
+        throw new UnauthorizedException('Token invalidated by password change');
+      }
+    }
+
+    return user;
+  }
+}
+```
+
+Reference: [NestJS Authentication](https://docs.nestjs.com/security/authentication)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/security-rate-limiting.md

@@ -0,0 +1,125 @@
+---
+title: Implement Rate Limiting
+impact: HIGH
+impactDescription: Protects against abuse and ensures fair resource usage
+tags: security, rate-limiting, throttler, protection
+---
+
+## Implement Rate Limiting
+
+Use `@nestjs/throttler` to limit request rates per client. Apply different limits for different endpoints - stricter for auth endpoints, more relaxed for read operations. Consider using Redis for distributed rate limiting in clustered deployments.
+
+**Incorrect (no rate limiting on sensitive endpoints):**
+
+```typescript
+// No rate limiting on sensitive endpoints
+@Controller('auth')
+export class AuthController {
+  @Post('login')
+  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
+    // Attackers can brute-force credentials
+    return this.authService.login(dto);
+  }
+
+  @Post('forgot-password')
+  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
+    // Can be abused to spam users with emails
+    return this.authService.sendResetEmail(dto.email);
+  }
+}
+
+// Same limits for all endpoints
+@UseGuards(ThrottlerGuard)
+@Controller('api')
+export class ApiController {
+  @Get('public-data')
+  async getPublic() {} // Should allow more requests
+
+  @Post('process-payment')
+  async payment() {} // Should be more restrictive
+}
+```
+
+**Correct (configured throttler with endpoint-specific limits):**
+
+```typescript
+// Configure throttler globally with multiple limits
+import { ThrottlerModule, ThrottlerGuard } from '@nestjs/throttler';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot([
+      {
+        name: 'short',
+        ttl: 1000, // 1 second
+        limit: 3, // 3 requests per second
+      },
+      {
+        name: 'medium',
+        ttl: 10000, // 10 seconds
+        limit: 20, // 20 requests per 10 seconds
+      },
+      {
+        name: 'long',
+        ttl: 60000, // 1 minute
+        limit: 100, // 100 requests per minute
+      },
+    ]),
+  ],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+  ],
+})
+export class AppModule {}
+
+// Override limits per endpoint
+@Controller('auth')
+export class AuthController {
+  @Post('login')
+  @Throttle({ short: { limit: 5, ttl: 60000 } }) // 5 attempts per minute
+  async login(@Body() dto: LoginDto): Promise<TokenResponse> {
+    return this.authService.login(dto);
+  }
+
+  @Post('forgot-password')
+  @Throttle({ short: { limit: 3, ttl: 3600000 } }) // 3 per hour
+  async forgotPassword(@Body() dto: ForgotPasswordDto): Promise<void> {
+    return this.authService.sendResetEmail(dto.email);
+  }
+}
+
+// Skip throttling for certain routes
+@Controller('health')
+export class HealthController {
+  @Get()
+  @SkipThrottle()
+  check(): string {
+    return 'OK';
+  }
+}
+
+// Custom throttle per user type
+@Injectable()
+export class CustomThrottlerGuard extends ThrottlerGuard {
+  protected async getTracker(req: Request): Promise<string> {
+    // Use user ID if authenticated, IP otherwise
+    return req.user?.id || req.ip;
+  }
+
+  protected async getLimit(context: ExecutionContext): Promise<number> {
+    const request = context.switchToHttp().getRequest();
+
+    // Higher limits for authenticated users
+    if (request.user) {
+      return request.user.isPremium ? 1000 : 200;
+    }
+
+    return 50; // Anonymous users
+  }
+}
+```
+
+Reference: [NestJS Throttler](https://docs.nestjs.com/security/rate-limiting)

package/dist/skills/frameworks/nestjs/nestjs-best-practices/rules/security-sanitize-output.md

@@ -0,0 +1,139 @@
+---
+title: Sanitize Output to Prevent XSS
+impact: HIGH
+impactDescription: XSS vulnerabilities can compromise user sessions and data
+tags: security, xss, sanitization, html
+---
+
+## Sanitize Output to Prevent XSS
+
+While NestJS APIs typically return JSON (which browsers don't execute), XSS risks exist when rendering HTML, storing user content, or when frontend frameworks improperly handle API responses. Sanitize user-generated content before storage and use proper Content-Type headers.
+
+**Incorrect (storing raw HTML without sanitization):**
+
+```typescript
+// Store raw HTML from users
+@Injectable()
+export class CommentsService {
+  async create(dto: CreateCommentDto): Promise<Comment> {
+    // User can inject: <script>steal(document.cookie)</script>
+    return this.repo.save({
+      content: dto.content, // Raw, unsanitized
+      authorId: dto.authorId,
+    });
+  }
+}
+
+// Return HTML without sanitization
+@Controller('pages')
+export class PagesController {
+  @Get(':slug')
+  @Header('Content-Type', 'text/html')
+  async getPage(@Param('slug') slug: string): Promise<string> {
+    const page = await this.pagesService.findBySlug(slug);
+    // If page.content contains user input, XSS is possible
+    return `<html><body>${page.content}</body></html>`;
+  }
+}
+
+// Reflect user input in errors
+@Get(':id')
+async findOne(@Param('id') id: string): Promise<User> {
+  const user = await this.repo.findOne({ where: { id } });
+  if (!user) {
+    // XSS if id contains malicious content and error is rendered
+    throw new NotFoundException(`User ${id} not found`);
+  }
+  return user;
+}
+```
+
+**Correct (sanitize content and use proper headers):**
+
+```typescript
+// Sanitize HTML content before storage
+import * as sanitizeHtml from 'sanitize-html';
+
+@Injectable()
+export class CommentsService {
+  private readonly sanitizeOptions: sanitizeHtml.IOptions = {
+    allowedTags: ['b', 'i', 'em', 'strong', 'a', 'p', 'br'],
+    allowedAttributes: {
+      a: ['href', 'title'],
+    },
+    allowedSchemes: ['http', 'https', 'mailto'],
+  };
+
+  async create(dto: CreateCommentDto): Promise<Comment> {
+    return this.repo.save({
+      content: sanitizeHtml(dto.content, this.sanitizeOptions),
+      authorId: dto.authorId,
+    });
+  }
+}
+
+// Use validation pipe to strip HTML
+import { Transform } from 'class-transformer';
+
+export class CreatePostDto {
+  @IsString()
+  @MaxLength(1000)
+  @Transform(({ value }) => sanitizeHtml(value, { allowedTags: [] }))
+  title: string;
+
+  @IsString()
+  @Transform(({ value }) =>
+    sanitizeHtml(value, {
+      allowedTags: ['p', 'br', 'b', 'i', 'a'],
+      allowedAttributes: { a: ['href'] },
+    }),
+  )
+  content: string;
+}
+
+// Set proper Content-Type headers
+@Controller('api')
+export class ApiController {
+  @Get('data')
+  @Header('Content-Type', 'application/json')
+  async getData(): Promise<DataResponse> {
+    // JSON response - browser won't execute scripts
+    return this.service.getData();
+  }
+}
+
+// Sanitize error messages
+@Get(':id')
+async findOne(@Param('id', ParseUUIDPipe) id: string): Promise<User> {
+  const user = await this.repo.findOne({ where: { id } });
+  if (!user) {
+    // UUID validation ensures safe format
+    throw new NotFoundException('User not found');
+  }
+  return user;
+}
+
+// Use Helmet for CSP headers
+import helmet from 'helmet';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+
+  app.use(
+    helmet({
+      contentSecurityPolicy: {
+        directives: {
+          defaultSrc: ["'self'"],
+          scriptSrc: ["'self'"],
+          styleSrc: ["'self'", "'unsafe-inline'"],
+          imgSrc: ["'self'", 'data:', 'https:'],
+        },
+      },
+    }),
+  );
+
+  await app.listen(3000);
+}
+```
+
+Reference: [OWASP XSS Prevention](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)