@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/nestjs-dependency-injection/skill.yaml

@@ -0,0 +1,41 @@
+name: nestjs-dependency-injection
+version: "1.0.0"
+description: Master NestJS DI container with tokens, useClass/useValue/useFactory providers
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.module.ts"
+  - "**/*.service.ts"
+related_skills:
+  - nestjs-module-pattern
+  - nestjs-service-pattern
+  - nestjs-config-module
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - dependency-injection
+  - injection-token
+  - useClass
+  - useValue
+  - useFactory
+  - provider
+  - IoC
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/fundamentals/custom-providers"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/nestjs-dto-validation/SKILL.md

@@ -0,0 +1,133 @@
+# NestJS DTO Validation
+
+> Validate request payloads with class-validator, class-transformer, and DTO patterns
+
+## When to Use
+
+- You need to validate the shape and content of request bodies, query parameters, or path parameters
+- You want automatic stripping of unexpected properties from incoming requests
+- You need to document the API payload shape for Swagger/OpenAPI
+- You need nested object validation (e.g., an order with nested line items)
+
+## Instructions
+
+1. **Install dependencies:**
+
+```bash
+npm install class-validator class-transformer
+```
+
+2. **Create a DTO class** with validation decorators:
+
+```typescript
+import {
+  IsEmail,
+  IsString,
+  MinLength,
+  IsOptional,
+  IsEnum,
+  ValidateNested,
+  Type,
+} from 'class-validator';
+
+export enum UserRole {
+  ADMIN = 'admin',
+  USER = 'user',
+}
+
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8, { message: 'Password must be at least 8 characters' })
+  password: string;
+
+  @IsOptional()
+  @IsString()
+  displayName?: string;
+
+  @IsEnum(UserRole)
+  role: UserRole = UserRole.USER;
+}
+```
+
+3. **Nested DTO validation** — requires `@ValidateNested()` + `@Type()`:
+
+```typescript
+export class AddressDto {
+  @IsString() street: string;
+  @IsString() city: string;
+  @IsPostalCode('US') zip: string;
+}
+
+export class CreateOrderDto {
+  @ValidateNested()
+  @Type(() => AddressDto)
+  shippingAddress: AddressDto;
+
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => LineItemDto)
+  items: LineItemDto[];
+}
+```
+
+4. **Update DTOs** — use `PartialType` from `@nestjs/mapped-types`:
+
+```typescript
+import { PartialType } from '@nestjs/mapped-types';
+export class UpdateUserDto extends PartialType(CreateUserDto) {}
+```
+
+5. **Swagger + validation together** — use `@ApiProperty` alongside validators:
+
+```typescript
+@ApiProperty({ example: 'user@example.com' })
+@IsEmail()
+email: string;
+```
+
+Or use `@nestjs/swagger`'s `@ApiProperty` auto-generation via `PickType`, `OmitType`, `IntersectionType`.
+
+6. Enable `ValidationPipe` globally with `whitelist: true` and `transform: true` (see nestjs-pipes-pattern).
+
+## Details
+
+DTOs (Data Transfer Objects) define the shape of data flowing into your API. They serve three purposes simultaneously: validation, transformation, and documentation.
+
+**Common class-validator decorators:**
+
+- `@IsString()`, `@IsNumber()`, `@IsBoolean()`, `@IsDate()`
+- `@IsEmail()`, `@IsUrl()`, `@IsUUID()`, `@IsPostalCode()`
+- `@IsEnum(MyEnum)`, `@IsIn(['a', 'b', 'c'])`
+- `@Min(n)`, `@Max(n)`, `@MinLength(n)`, `@MaxLength(n)`
+- `@IsArray()`, `@ArrayMinSize(n)`, `@ArrayMaxSize(n)`
+- `@IsOptional()` — skips validation if the field is absent or undefined
+- `@IsDefined()` — fails if the field is undefined (stricter than `@IsNotEmpty()`)
+
+**`whitelist: true` and `forbidNonWhitelisted: true`:** With whitelist enabled, any property without a decorator is silently removed. With `forbidNonWhitelisted`, a 400 is thrown instead. Both protect against mass-assignment vulnerabilities.
+
+**`@Expose()` and `@Exclude()` (class-transformer):** When using `ClassSerializerInterceptor`, decorate response entity fields with `@Exclude()` to hide sensitive data (passwords, internal IDs). The `@Expose()` decorator marks which fields to include when `excludeExtraneousValues: true` is set.
+
+**Validation groups:** `class-validator` supports groups for conditional validation. Rarely needed — prefer creating separate DTOs (`CreateUserDto` vs `UpdateUserDto`) over validation groups.
+
+## Source
+
+https://docs.nestjs.com/techniques/validation
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/nestjs-dto-validation/skill.yaml

@@ -0,0 +1,42 @@
+name: nestjs-dto-validation
+version: "1.0.0"
+description: Validate request payloads with class-validator, class-transformer, and DTO patterns
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.dto.ts"
+  - "**/*.controller.ts"
+related_skills:
+  - nestjs-pipes-pattern
+  - nestjs-controller-pattern
+  - nestjs-swagger-integration
+  - ts-utility-types
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - dto
+  - validation
+  - class-validator
+  - class-transformer
+  - whitelist
+  - IsString
+  - IsEmail
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/techniques/validation"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/nestjs-event-driven/SKILL.md

@@ -0,0 +1,123 @@
+# NestJS Event-Driven Pattern
+
+> Build event-driven systems with EventEmitter2, CQRS module, CommandBus, and QueryBus
+
+## When to Use
+
+- You need to decouple side effects (send email, update audit log) from the primary operation
+- You are implementing CQRS to separate read and write models for a bounded context
+- You need event sourcing where domain events are the source of truth
+- You want to publish domain events that multiple services can independently handle
+
+## Instructions
+
+### EventEmitter2 (simple pub/sub within the same process)
+
+1. **Setup:**
+
+```bash
+npm install @nestjs/event-emitter
+```
+
+```typescript
+@Module({ imports: [EventEmitterModule.forRoot()] })
+export class AppModule {}
+```
+
+2. **Emit events from a service:**
+
+```typescript
+@Injectable()
+export class UsersService {
+  constructor(private eventEmitter: EventEmitter2) {}
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const user = await this.prisma.user.create({ data: dto });
+    this.eventEmitter.emit('user.created', new UserCreatedEvent(user));
+    return user;
+  }
+}
+```
+
+3. **Handle events:**
+
+```typescript
+@Injectable()
+export class EmailNotificationListener {
+  @OnEvent('user.created')
+  async handleUserCreated(event: UserCreatedEvent): Promise<void> {
+    await this.mailService.sendWelcomeEmail(event.user.email);
+  }
+
+  @OnEvent('user.*') // wildcard
+  async handleAnyUserEvent(event: unknown): Promise<void> { ... }
+}
+```
+
+### CQRS Module (commands and queries)
+
+```typescript
+npm install @nestjs/cqrs
+```
+
+```typescript
+// command
+export class CreateUserCommand { constructor(public dto: CreateUserDto) {} }
+
+// handler
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler implements ICommandHandler<CreateUserCommand> {
+  constructor(private usersRepo: UsersRepository) {}
+  async execute(command: CreateUserCommand): Promise<User> {
+    return this.usersRepo.create(command.dto);
+  }
+}
+
+// dispatch from controller
+@Post()
+create(@Body() dto: CreateUserDto) {
+  return this.commandBus.execute(new CreateUserCommand(dto));
+}
+
+// query
+@QueryHandler(GetUserQuery)
+export class GetUserHandler implements IQueryHandler<GetUserQuery> {
+  async execute(query: GetUserQuery): Promise<User> {
+    return this.usersReadRepo.findById(query.id);
+  }
+}
+```
+
+Register all handlers in `providers`.
+
+## Details
+
+**EventEmitter2 vs CQRS:** EventEmitter2 is in-process pub/sub — simple, zero setup overhead, good for side effects. CQRS is a structural pattern that separates commands (writes) from queries (reads) — use it when you need independent scaling of read/write paths or when the read model differs significantly from the write model.
+
+**EventEmitter2 async handlers:** `@OnEvent('user.created', { async: true })` ensures async handlers do not block the event loop. Set `promisify: true` on `EventEmitterModule.forRoot()` to await async handlers before continuing.
+
+**EventBus (CQRS):** In addition to `CommandBus` and `QueryBus`, the CQRS module provides `EventBus` for domain events. `IEventHandler` implementations react to events published via `eventBus.publish(new UserCreatedEvent(user))`.
+
+**Saga pattern:** `@nestjs/cqrs` supports long-running processes via `@Saga()` decorator — these are RxJS streams that react to events and dispatch commands.
+
+**Cross-service events:** EventEmitter2 is in-process only. For cross-service messaging (microservices), use the NestJS microservices transport layer (`@EventPattern`, Redis/RabbitMQ) or integrate with Kafka/NATS for durable event streams.
+
+## Source
+
+https://docs.nestjs.com/recipes/cqrs
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/nestjs-event-driven/skill.yaml

@@ -0,0 +1,43 @@
+name: nestjs-event-driven
+version: "1.0.0"
+description: Build event-driven systems with EventEmitter2, CQRS module, CommandBus, and QueryBus
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.module.ts"
+  - "**/*.handler.ts"
+  - "**/*.command.ts"
+  - "**/*.event.ts"
+related_skills:
+  - nestjs-module-pattern
+  - nestjs-service-pattern
+  - node-event-emitter
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - event-driven
+  - EventEmitter2
+  - CQRS
+  - CommandBus
+  - QueryBus
+  - EventBus
+  - OnEvent
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/recipes/cqrs"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/nestjs-exception-filters/SKILL.md

@@ -0,0 +1,119 @@
+# NestJS Exception Filters
+
+> Handle errors globally with @Catch, ExceptionFilter, and custom exception hierarchies
+
+## When to Use
+
+- You need a consistent error response format across all routes (e.g., `{ error, message, statusCode, timestamp }`)
+- You need to handle third-party library errors (Prisma errors, TypeORM errors) and map them to HTTP exceptions
+- You want to log errors with context (request URL, user ID) before sending the response
+- You are building a custom exception class hierarchy for domain errors
+
+## Instructions
+
+1. **Custom exception class:**
+
+```typescript
+export class ResourceNotFoundException extends HttpException {
+  constructor(resource: string, id: string) {
+    super({ error: 'NOT_FOUND', message: `${resource} ${id} not found` }, HttpStatus.NOT_FOUND);
+  }
+}
+```
+
+2. **Global exception filter:**
+
+```typescript
+@Catch()
+export class AllExceptionsFilter implements ExceptionFilter {
+  constructor(private readonly logger: Logger) {}
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const ctx = host.switchToHttp();
+    const response = ctx.getResponse<Response>();
+    const request = ctx.getRequest<Request>();
+
+    const status =
+      exception instanceof HttpException ? exception.getStatus() : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const message =
+      exception instanceof HttpException ? exception.getResponse() : 'Internal server error';
+
+    this.logger.error(exception, { url: request.url, method: request.method });
+
+    response.status(status).json({
+      statusCode: status,
+      message,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+    });
+  }
+}
+```
+
+3. **Catch specific exceptions only:**
+
+```typescript
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter { ... }
+
+@Catch(PrismaClientKnownRequestError)
+export class PrismaExceptionFilter implements ExceptionFilter {
+  catch(exception: PrismaClientKnownRequestError, host: ArgumentsHost) {
+    if (exception.code === 'P2002') {
+      // unique constraint violation
+    }
+    if (exception.code === 'P2025') {
+      // record not found
+    }
+  }
+}
+```
+
+4. **Register globally** (DI-aware):
+
+```typescript
+providers: [{ provide: APP_FILTER, useClass: AllExceptionsFilter }];
+```
+
+Or without DI: `app.useGlobalFilters(new AllExceptionsFilter())`.
+
+5. Multiple filters execute in reverse registration order — the last registered filter catches first.
+
+## Details
+
+Exception filters are the final layer of the NestJS request pipeline. They catch exceptions that were not caught by interceptors or handlers and convert them to HTTP responses.
+
+**`@Catch()` with no arguments** catches ALL exceptions including non-HTTP ones (uncaught database errors, third-party SDK failures). This is useful as a safety net but should log the error and return a generic 500.
+
+**`@Catch(HttpException)` specifically** only intercepts NestJS HTTP exceptions, leaving non-HTTP exceptions to bubble up to the next filter (or the runtime).
+
+**Prisma error codes:**
+
+- `P2002` — Unique constraint violation → `ConflictException`
+- `P2025` — Record not found → `NotFoundException`
+- `P2003` — Foreign key constraint failure → `BadRequestException`
+
+**Exception hierarchy design:** Build a `DomainException extends HttpException` base, then specific exceptions like `InsufficientInventoryException extends DomainException`. The filter only needs to handle `DomainException` and extract the structured payload.
+
+**WebSocket and microservice contexts:** `ArgumentsHost` is transport-agnostic. Use `host.getType()` to check whether the request is HTTP, WS, or RPC before calling `switchToHttp()`.
+
+## Source
+
+https://docs.nestjs.com/exception-filters
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/nestjs-exception-filters/skill.yaml

@@ -0,0 +1,40 @@
+name: nestjs-exception-filters
+version: "1.0.0"
+description: Handle errors globally with @Catch, ExceptionFilter, and custom exception hierarchies
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.filter.ts"
+  - "**/*.exception.ts"
+related_skills:
+  - nestjs-controller-pattern
+  - nestjs-interceptors-pattern
+  - nestjs-pipes-pattern
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - exception-filter
+  - error-handling
+  - HttpException
+  - Catch
+  - custom-exception
+  - global-filter
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/exception-filters"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/nestjs-graphql-integration/SKILL.md

@@ -0,0 +1,132 @@
+# NestJS GraphQL Integration
+
+> Build GraphQL APIs with GraphQLModule, @Resolver, @Query/@Mutation, @ObjectType, and DataLoader
+
+## When to Use
+
+- You are building an API that needs flexible field selection to avoid over/under-fetching
+- You have a complex domain with many interrelated entities and nested queries
+- Your frontend needs real-time subscriptions alongside standard queries
+- You want a strongly-typed schema generated from TypeScript classes (code-first approach)
+
+## Instructions
+
+1. **Install and configure:**
+
+```bash
+npm install @nestjs/graphql @nestjs/apollo @apollo/server graphql
+```
+
+```typescript
+@Module({
+  imports: [
+    GraphQLModule.forRoot<ApolloDriverConfig>({
+      driver: ApolloDriver,
+      autoSchemaFile: join(process.cwd(), 'src/schema.gql'),
+      sortSchema: true,
+      playground: true,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+2. **Define object types:**
+
+```typescript
+@ObjectType()
+export class User {
+  @Field(() => ID) id: string;
+  @Field() email: string;
+  @Field({ nullable: true }) displayName?: string;
+  @Field(() => [Post]) posts: Post[];
+}
+```
+
+3. **Create a resolver:**
+
+```typescript
+@Resolver(() => User)
+export class UsersResolver {
+  constructor(
+    private usersService: UsersService,
+    private postsService: PostsService
+  ) {}
+
+  @Query(() => User, { nullable: true })
+  user(@Args('id', { type: () => ID }) id: string): Promise<User | null> {
+    return this.usersService.findOne(id);
+  }
+
+  @Query(() => [User])
+  users(): Promise<User[]> {
+    return this.usersService.findAll();
+  }
+
+  @Mutation(() => User)
+  createUser(@Args('input') input: CreateUserInput): Promise<User> {
+    return this.usersService.create(input);
+  }
+
+  @ResolveField(() => [Post])
+  posts(@Parent() user: User): Promise<Post[]> {
+    return this.postsService.findByUser(user.id);
+  }
+}
+```
+
+4. **Input types for mutations:**
+
+```typescript
+@InputType()
+export class CreateUserInput {
+  @Field() @IsEmail() email: string;
+  @Field() @MinLength(8) password: string;
+}
+```
+
+5. **DataLoader for N+1 prevention:**
+
+```typescript
+@Injectable({ scope: Scope.REQUEST })
+export class PostsLoader {
+  constructor(private postsService: PostsService) {}
+
+  readonly loader = new DataLoader<string, Post[]>(async (userIds) => {
+    const posts = await this.postsService.findByUserIds([...userIds]);
+    return userIds.map((id) => posts.filter((p) => p.userId === id));
+  });
+}
+```
+
+## Details
+
+**Code-first vs schema-first:** Code-first (above) generates the SDL from TypeScript decorators. Schema-first starts from a `.graphql` file and maps resolvers to it. Code-first is preferred for TypeScript teams because types are unified.
+
+**`@Field(() => Type)` explicit types:** When TypeScript reflection cannot determine the type (arrays, enums, circular references), the explicit arrow function syntax is required. For nullable fields: `@Field({ nullable: true })`.
+
+**Auth on resolvers:** Apply guards with `@UseGuards(JwtAuthGuard)` on the class or individual query/mutation. Access the current user via `@Context() ctx: GqlContext` where `ctx.req.user` is populated by the guard.
+
+**Subscriptions:** Add `installSubscriptionHandlers: true` and use `@Subscription(() => Post)` with `pubSub.asyncIterator('postCreated')` for real-time updates via WebSocket.
+
+**Complexity and depth limiting:** In production, configure `validationRules: [depthLimit(5), createComplexityRule(...)]` to prevent expensive queries from exhausting server resources.
+
+## Source
+
+https://docs.nestjs.com/graphql/quick-start
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.