@ngxtm/devkit 3.4.0 → 3.4.1

package/rules/nestjs/scheduling/references/scheduling-patterns.md

@@ -0,0 +1,137 @@
+# NestJS Scheduling Patterns
+
+## Cron Jobs
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { Cron, CronExpression, SchedulerRegistry } from '@nestjs/schedule';
+
+@Injectable()
+export class TasksService {
+  constructor(private schedulerRegistry: SchedulerRegistry) {}
+
+  // Every day at midnight
+  @Cron('0 0 * * *')
+  handleDailyCleanup() {
+    console.log('Running daily cleanup');
+  }
+
+  // Every 5 minutes
+  @Cron(CronExpression.EVERY_5_MINUTES)
+  handleFrequentTask() {
+    console.log('Running every 5 minutes');
+  }
+
+  // Dynamic cron job
+  addCronJob(name: string, cronTime: string, callback: () => void) {
+    const job = new CronJob(cronTime, callback);
+    this.schedulerRegistry.addCronJob(name, job);
+    job.start();
+  }
+
+  deleteCronJob(name: string) {
+    this.schedulerRegistry.deleteCronJob(name);
+  }
+}
+```
+
+## Intervals and Timeouts
+
+```typescript
+import { Interval, Timeout } from '@nestjs/schedule';
+
+@Injectable()
+export class PollingService {
+  @Interval(10000) // Every 10 seconds
+  checkHealth() {
+    console.log('Health check');
+  }
+
+  @Timeout(5000) // Run once after 5 seconds
+  onApplicationReady() {
+    console.log('Application warm-up complete');
+  }
+}
+```
+
+## Bull Queues
+
+```typescript
+// queue.module.ts
+import { BullModule } from '@nestjs/bull';
+
+@Module({
+  imports: [
+    BullModule.forRoot({
+      redis: { host: 'localhost', port: 6379 },
+    }),
+    BullModule.registerQueue({ name: 'email' }),
+  ],
+})
+export class QueueModule {}
+
+// email.processor.ts
+import { Processor, Process, OnQueueFailed } from '@nestjs/bull';
+import { Job } from 'bull';
+
+@Processor('email')
+export class EmailProcessor {
+  @Process()
+  async sendEmail(job: Job<{ to: string; subject: string }>) {
+    const { to, subject } = job.data;
+    await this.mailer.send(to, subject);
+  }
+
+  @Process('welcome')
+  async sendWelcome(job: Job) {
+    // Named job processor
+  }
+
+  @OnQueueFailed()
+  onFailed(job: Job, error: Error) {
+    console.error(`Job ${job.id} failed:`, error.message);
+  }
+}
+
+// Usage in service
+@Injectable()
+export class EmailService {
+  constructor(@InjectQueue('email') private emailQueue: Queue) {}
+
+  async queueEmail(to: string, subject: string) {
+    await this.emailQueue.add({ to, subject }, {
+      attempts: 3,
+      backoff: { type: 'exponential', delay: 1000 },
+    });
+  }
+}
+```
+
+## Distributed Locking
+
+```typescript
+import Redlock from 'redlock';
+
+@Injectable()
+export class DistributedTaskService {
+  private redlock: Redlock;
+
+  constructor(private redis: Redis) {
+    this.redlock = new Redlock([redis]);
+  }
+
+  @Cron('0 * * * *')
+  async runExclusiveTask() {
+    try {
+      const lock = await this.redlock.acquire(['task:hourly'], 30000);
+      try {
+        await this.doWork();
+      } finally {
+        await lock.release();
+      }
+    } catch (err) {
+      // Another instance is running the task
+    }
+  }
+}
+```

package/rules/nestjs/search/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: NestJS Search & CQRS
+description: Elasticsearch integration and Sync patterns.
+metadata:
+  labels: [nestjs, search, elasticsearch, cqrs]
+  triggers:
+    files: ['**/*.service.ts', '**/search/**']
+    keywords: [Elasticsearch, CQRS, Synchronization]
+---
+
+# Search Engine & Full-Text
+
+## Strategy
+
+- **Pattern**: **CQRS (Command Query Responsibility Segregation)**.
+  - **Write**: To Primary Database (Postgres/MySQL). Source of Truth.
+  - **Read (Complex)**: To Search Engine (Elasticsearch, OpenSearch, MeiliSearch). Optimized for filtering, fuzzy search, and aggregation.
+
+## Synchronization (The Hard Part)
+
+- **Dual Write (Anti-Pattern)**: `await db.save(); await es.index();`.
+  - _Why_: Partial failures leave data inconsistent. Slows down HTTP response.
+- **Event-Driven (Recommended)**:
+  1. Service writes to DB.
+  2. Service emits `EntityUpdated`.
+  3. Event Handler (Async) pushes to Queue (BullMQ).
+  4. Worker indexes document to Search Engine with retries.
+- **CDC (Golden Standard)**: Change Data Capture (Debezium). Connects directly to DB transaction log. No app conceptual overhead, but higher ops complexity.
+
+## Organization
+
+- **Module**: Encapsulate the client in a `SearchModule`.
+- **Abstraction**: Create generic `SearchService<T>` helpers.
+  - `indexDocument(id, body)`
+  - `search(query, filters)`
+- **Mapping**: Use `class-transformer` to map Entities to "Search Documents". Search docs should be flatter than Relational entities constraints.
+
+## Testing
+
+- **E2E**: Do not mock the search engine in critical E2E flows.
+- **Docker**: Spin up `elasticsearch:8` container in the test harness to verify indexing works.

package/rules/nestjs/search/references/REFERENCE.md

@@ -0,0 +1,13 @@
+# NestJS Search References
+
+## References
+
+- [**Search Patterns**](search-patterns.md) - Elasticsearch, full-text search, indexing
+
+## Quick Checks
+
+- [ ] Use dedicated search service
+- [ ] Index relevant fields
+- [ ] Implement pagination for results
+- [ ] Handle search query sanitization
+- [ ] Consider fuzzy matching for UX

package/rules/nestjs/search/references/search-patterns.md

@@ -0,0 +1,137 @@
+# NestJS Search Patterns
+
+## Elasticsearch Integration
+
+```typescript
+import { ElasticsearchModule, ElasticsearchService } from '@nestjs/elasticsearch';
+
+@Module({
+  imports: [
+    ElasticsearchModule.register({
+      node: 'http://localhost:9200',
+    }),
+  ],
+})
+export class SearchModule {}
+
+@Injectable()
+export class ProductSearchService {
+  constructor(private readonly esService: ElasticsearchService) {}
+
+  async indexProduct(product: Product) {
+    await this.esService.index({
+      index: 'products',
+      id: product.id,
+      document: {
+        name: product.name,
+        description: product.description,
+        category: product.category,
+        price: product.price,
+      },
+    });
+  }
+
+  async search(query: string, options?: { page?: number; limit?: number }) {
+    const { page = 1, limit = 10 } = options || {};
+
+    const result = await this.esService.search({
+      index: 'products',
+      from: (page - 1) * limit,
+      size: limit,
+      query: {
+        multi_match: {
+          query,
+          fields: ['name^3', 'description', 'category'],
+          fuzziness: 'AUTO',
+        },
+      },
+    });
+
+    return {
+      hits: result.hits.hits.map(hit => hit._source),
+      total: result.hits.total,
+    };
+  }
+
+  async deleteIndex(id: string) {
+    await this.esService.delete({ index: 'products', id });
+  }
+}
+```
+
+## PostgreSQL Full-Text Search
+
+```typescript
+import { Repository } from 'typeorm';
+
+@Injectable()
+export class ArticleSearchService {
+  constructor(
+    @InjectRepository(Article)
+    private articleRepo: Repository<Article>,
+  ) {}
+
+  async search(query: string) {
+    return this.articleRepo
+      .createQueryBuilder('article')
+      .where(
+        `to_tsvector('english', article.title || ' ' || article.content) @@ plainto_tsquery('english', :query)`,
+        { query },
+      )
+      .orderBy(
+        `ts_rank(to_tsvector('english', article.title || ' ' || article.content), plainto_tsquery('english', :query))`,
+        'DESC',
+      )
+      .getMany();
+  }
+}
+
+// Migration for GIN index
+export class AddSearchIndex implements MigrationInterface {
+  async up(queryRunner: QueryRunner) {
+    await queryRunner.query(`
+      CREATE INDEX idx_article_search
+      ON article
+      USING GIN (to_tsvector('english', title || ' ' || content))
+    `);
+  }
+}
+```
+
+## Search with Filters
+
+```typescript
+async advancedSearch(params: SearchParams) {
+  const { query, category, minPrice, maxPrice, sort } = params;
+
+  const must = [];
+  const filter = [];
+
+  if (query) {
+    must.push({
+      multi_match: { query, fields: ['name', 'description'] },
+    });
+  }
+
+  if (category) {
+    filter.push({ term: { category } });
+  }
+
+  if (minPrice || maxPrice) {
+    filter.push({
+      range: {
+        price: {
+          ...(minPrice && { gte: minPrice }),
+          ...(maxPrice && { lte: maxPrice }),
+        },
+      },
+    });
+  }
+
+  return this.esService.search({
+    index: 'products',
+    query: { bool: { must, filter } },
+    sort: sort ? [{ [sort.field]: sort.order }] : undefined,
+  });
+}
+```

package/rules/nestjs/security/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: NestJS Security
+description: Authentication, RBAC, and Hardening standards.
+metadata:
+  labels: [nestjs, security, auth, jwt]
+  triggers:
+    files: ['**/*.guard.ts', '**/*.strategy.ts', '**/auth/**']
+    keywords: [Passport, JWT, AuthGuard, CSRF, Helmet]
+---
+
+# NestJS Security Standards
+
+## Authentication
+
+- **Strategies**: Use `@nestjs/passport` with `passport-jwt`.
+- **JWT Hardening**:
+  - **Algorithm**: Enforce `algorithms: ['RS256']` (preferred) or `['HS256']`. **Reject `none`**.
+  - **Claims**: Validate `iss` (Issuer) and `aud` (Audience).
+  - **Secrets**: High entropy (> 256-bit) for HS256.
+- **State**: Stateless. Short access tokens (15m), Long httponly refresh tokens (7d).
+- **MFA**: Require 2FA for sensitive access (admin panels).
+
+## Authorization (RBAC)
+
+- **Strategy**: **Deny by default**.
+  - **Implementation**: Bind `AuthGuard` globally (APP_GUARD).
+  - **Bypass**: Create a `@Public()` decorator and allow access if present in the Guard.
+- **Metadata**: Use `Reflector.createDecorator<string[]>()`.
+- **Guards**: Use `Reflector` to merge Method/Class roles (`getAllAndOverride`).
+
+## Cryptography & Hashing
+
+- **Hashing**:
+  - **Algorithm**: Use **Argon2id** (`argon2`) instead of Bcrypt (vulnerable to GPU/FPGA cracking).
+  - **Implementation**: `await argon2.hash(password)`.
+- **Encryption** (At Rest):
+  - **Algorithm**: Use **AES-256-GCM** (Authenticated Encryption).
+  - **Keys**: Never hardcode. Rotate keys using a KMS (Key Management Service).
+  - **Native**: Use Node.js `crypto.createCipheriv`.
+
+## CSRF (Cross-Site Request Forgery)
+
+- **Context**: Mandatory if using **Cookie-based sessions** or **Cookie-based JWTs**.
+- **Mitigation**:
+  - **Synchronizer Token**: Use `csurf` via `@nest-middlewares/csurf` or similar wrapper.
+  - **State**: Token must be cryptographically strong and verified on every state-changing request (POST/PUT/DELETE).
+- **Note**: If using strictly `Authorization: Bearer` headers (localStorage), CSRF is less critical but `SameSite: Strict` cookies are still recommended for defense-in-depth.
+
+## Hardening
+
+1. **Helmet**: Mandatory. `app.use(helmet())`.
+   - **HSTS**: Enable `Strict-Transport-Security` with `preload`.
+   - **CSP**: Configure Content Security Policy specifically if serving any UI.
+2. **Permissions-Policy**: Restrict browser permissions via `helmet.permissionsPolicy()`.
+3. **CORS**: Explicit origins only. No `*`.
+4. **Throttling**:
+   - **Distributed**: Do not use in-memory rate limiting in production. Use `@nestjs/throttler` with **Redis storage** (`throttler-storage-redis`) to sync limits across instances.
+
+## Audit Logging
+
+- **Requirement**: Track critical mutations (Who, What, When).
+- **Pattern**: Implement an `AuditInterceptor` that logs `POST/PUT/DELETE` actions to a secure, immutable log store (separate from app logs).
+
+## Secrets & Config
+
+- **CI/CD**: Run `npm audit` or `pnpm audit --prod` in pipelines.
+- **Runtime**: Avoid `.env` files in production runtime. Inject secrets via environment variables from a vault (AWS Secret Manager / HashiCorp Vault) into the container environment.
+
+## Data Sanitization
+
+- **Transform**: Use `ClassSerializerInterceptor` + `@Exclude()` globally or per-controller to strip sensitive fields (passwords) from responses.
+- **Validation**: `ValidationPipe({ whitelist: true })` prevents mass assignment attacks by stripping unknown properties from payloads.
+
+## Improper Assets Management
+
+- **Shadow APIs**: Audit routes regularly.
+- **Deprecation**: Disable Swagger/OpenAPI endpoints (`/api`, `/docs`) in **production**.
+
+## Server-Side Request Forgery (SSRF)
+
+- **Validation**: Validate/Allowlist domains for **all** outgoing HTTP requests (`HttpService`).
+- **Network**: Restrict egress traffic (e.g., block AWS metadata `169.254.169.254`) via infrastructure/firewall.
+
+## Injection Prevention
+
+- **SQLi**: Prefer ORM/ODM methods. **Avoid raw queries** (`query()`) with string concatenation. Use parameterized queries if raw SQL is strictly necessary.
+- **XSS**: Input validation is not enough. Sanitize HTML input (e.g., `dompurify`) before storage or output.

package/rules/nestjs/security/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# NestJS Security References
+
+## References
+
+- [**Authentication**](authentication.md) - JWT, Passport, sessions
+- [**Authorization**](authorization.md) - Guards, RBAC, policies
+
+## Quick Checks
+
+- [ ] Use Passport strategies for auth
+- [ ] JWT with proper expiration
+- [ ] Guards for route protection
+- [ ] RBAC or ABAC for permissions
+- [ ] Rate limiting for API protection

package/rules/nestjs/security/references/authentication.md

@@ -0,0 +1,151 @@
+# NestJS Authentication
+
+## JWT Strategy
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { PassportStrategy } from '@nestjs/passport';
+import { ExtractJwt, Strategy } from 'passport-jwt';
+
+@Injectable()
+export class JwtStrategy extends PassportStrategy(Strategy) {
+  constructor(private configService: ConfigService) {
+    super({
+      jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
+      ignoreExpiration: false,
+      secretOrKey: configService.get('JWT_SECRET'),
+    });
+  }
+
+  async validate(payload: JwtPayload) {
+    return { userId: payload.sub, email: payload.email, roles: payload.roles };
+  }
+}
+```
+
+## Auth Service
+
+```typescript
+import { JwtService } from '@nestjs/jwt';
+import * as bcrypt from 'bcrypt';
+
+@Injectable()
+export class AuthService {
+  constructor(
+    private usersService: UsersService,
+    private jwtService: JwtService,
+  ) {}
+
+  async validateUser(email: string, password: string): Promise<User | null> {
+    const user = await this.usersService.findByEmail(email);
+    if (user && await bcrypt.compare(password, user.password)) {
+      return user;
+    }
+    return null;
+  }
+
+  async login(user: User) {
+    const payload = { email: user.email, sub: user.id, roles: user.roles };
+    return {
+      access_token: this.jwtService.sign(payload),
+      refresh_token: this.jwtService.sign(payload, { expiresIn: '7d' }),
+    };
+  }
+
+  async refreshToken(token: string) {
+    const payload = this.jwtService.verify(token);
+    const user = await this.usersService.findById(payload.sub);
+    return this.login(user);
+  }
+}
+```
+
+## Auth Guard
+
+```typescript
+import { Injectable, ExecutionContext } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+import { Reflector } from '@nestjs/core';
+
+@Injectable()
+export class JwtAuthGuard extends AuthGuard('jwt') {
+  constructor(private reflector: Reflector) {
+    super();
+  }
+
+  canActivate(context: ExecutionContext) {
+    const isPublic = this.reflector.getAllAndOverride<boolean>('isPublic', [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+    if (isPublic) return true;
+    return super.canActivate(context);
+  }
+}
+
+// Public decorator
+export const Public = () => SetMetadata('isPublic', true);
+
+// Usage
+@Controller('users')
+@UseGuards(JwtAuthGuard)
+export class UsersController {
+  @Public()
+  @Get('public')
+  publicRoute() {}
+
+  @Get('protected')
+  protectedRoute(@CurrentUser() user: User) {}
+}
+```
+
+## Roles Guard
+
+```typescript
+import { SetMetadata } from '@nestjs/common';
+
+export const ROLES_KEY = 'roles';
+export const Roles = (...roles: Role[]) => SetMetadata(ROLES_KEY, roles);
+
+@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));
+  }
+}
+
+// Usage
+@Post()
+@Roles(Role.Admin)
+@UseGuards(JwtAuthGuard, RolesGuard)
+create() {}
+```
+
+## Module Setup
+
+```typescript
+@Module({
+  imports: [
+    PassportModule,
+    JwtModule.registerAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        secret: config.get('JWT_SECRET'),
+        signOptions: { expiresIn: '1h' },
+      }),
+    }),
+  ],
+  providers: [AuthService, JwtStrategy, JwtAuthGuard, RolesGuard],
+  exports: [AuthService],
+})
+export class AuthModule {}
+```

package/rules/nestjs/testing/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: NestJS Testing
+description: Unit and E2E testing strategies with Docker.
+metadata:
+  labels: [nestjs, testing, jest, e2e]
+  triggers:
+    files: ['**/*.spec.ts', 'test/**']
+    keywords: [Test.createTestingModule, supertest, jest]
+---
+
+# NestJS Testing Standards
+
+## Strategy
+
+1. **Unit Tests**: Isolated logic (Services). Mock **all** dependencies (`jest.fn()`).
+2. **E2E Tests**: Full lifecycle (`test/app.e2e-spec.ts`).
+   - **Rule**: Use a **real** Test Database (Docker). Never mock the database in E2E.
+   - **Idempotency**: **Mandatory** cleanup. Use a transaction rollback strategy or explicit `TRUNCATE` in `afterEach` to ensure tests don't leak state.
+
+## E2E Best Practices (Pro)
+
+- **Overriding**: Use `.overrideProvider(AuthGuard).useValue({ canActivate: () => true })` to bypass security in functional flow tests.
+- **Factories**: Use Factory patterns (e.g. `mockUserFactory()`) to generate DTOs/Entities. Avoid hardcoded JSON literals.
+
+## Tools
+
+- **Runner**: Jest (swc/ts-jest).
+- **Mocks**: `jest.fn()`, `jest.spyOn()`.
+
+## Setup Pattern
+
+```typescript
+// Standard Setup
+const module: TestingModule = await Test.createTestingModule({
+  providers: [
+    UsersService,
+    { provide: getRepositoryToken(User), useValue: mockRepo },
+  ],
+}).compile();
+```

package/rules/nestjs/testing/references/REFERENCE.md

@@ -0,0 +1,14 @@
+# NestJS Testing References
+
+## References
+
+- [**Unit Testing**](unit-testing.md) - Services, mocking, Jest patterns
+- [**E2E Testing**](e2e-testing.md) - Supertest, test modules
+
+## Quick Checks
+
+- [ ] Use Test.createTestingModule for unit tests
+- [ ] Mock dependencies with jest.mock or providers
+- [ ] E2E tests with supertest
+- [ ] Test database with in-memory or test containers
+- [ ] Coverage thresholds in jest config