@harness-engineering/cli 1.23.2 → 1.24.1

package/dist/agents/skills/codex/nestjs-module-pattern/SKILL.md

@@ -0,0 +1,89 @@
+# NestJS Module Pattern
+
+> Organize NestJS applications with cohesive feature modules, controlled exports, and composable dynamic configurations
+
+## When to Use
+
+- Starting a new NestJS feature and deciding where to place providers, controllers, and services
+- Sharing providers between modules without creating circular dependencies
+- Building reusable library modules that accept configuration (e.g., a database module, auth module)
+- Registering global utilities (guards, interceptors, pipes) that should apply application-wide
+
+## Instructions
+
+1. Create one module per feature domain (e.g., `UsersModule`, `OrdersModule`, `AuthModule`). Group the controller, service, and repository for that domain inside it.
+2. Declare every provider in the `providers` array of the module that owns it. Only add it to `exports` when another module needs to inject it.
+3. Import a module to gain access to its exported providers — never directly import a provider from another module's file.
+4. Use `@Global()` sparingly: only for truly cross-cutting utilities (logging, config, event bus). Overuse destroys encapsulation.
+5. Implement `forRoot()` / `forFeature()` static methods for modules that need external configuration:
+
+```typescript
+@Module({})
+export class DatabaseModule {
+  static forRoot(options: DatabaseOptions): DynamicModule {
+    return {
+      module: DatabaseModule,
+      providers: [{ provide: DATABASE_OPTIONS, useValue: options }, DatabaseService],
+      exports: [DatabaseService],
+      global: true,
+    };
+  }
+}
+```
+
+6. Use `forFeature()` for per-feature registration (e.g., registering Prisma models or TypeORM repositories for a specific module).
+7. Keep `AppModule` thin — it should only import feature modules and global infrastructure modules, not declare providers directly.
+8. Avoid circular module dependencies. If two modules need each other's providers, extract the shared logic into a third `SharedModule`.
+
+## Details
+
+NestJS modules are the primary unit of application organization. They enforce explicit dependency declaration: a module cannot use a provider unless it either declares it internally or imports a module that exports it. This makes dependency graphs auditable and prevents accidental coupling.
+
+**Module anatomy:**
+
+```typescript
+@Module({
+  imports: [TypeOrmModule.forFeature([User])], // modules whose exports you need
+  controllers: [UsersController], // route handlers scoped to this module
+  providers: [UsersService, UsersRepository], // services, repos, guards, etc.
+  exports: [UsersService], // what other modules may inject
+})
+export class UsersModule {}
+```
+
+**Dynamic modules** solve the configuration problem. A static module cannot accept runtime configuration; `forRoot()` returns a `DynamicModule` object that NestJS treats identically to a static module but allows passing options:
+
+```typescript
+// In AppModule:
+DatabaseModule.forRoot({ url: process.env.DATABASE_URL });
+```
+
+**Global modules** (`@Global()`) register their exports into every module without requiring an explicit `imports` declaration. Use this for config, logging, and event buses — not for business-logic services where explicit imports communicate intent.
+
+**Shared modules** are a common pattern for breaking circular dependencies. Extract the shared provider into its own module, export it, and import `SharedModule` from both dependents.
+
+**Trade-offs:**
+
+- Explicit imports are verbose but make coupling visible at a glance
+- Global modules reduce boilerplate but hide dependencies — use them only for infrastructure
+- Dynamic modules enable reusability but add complexity; prefer static modules until reuse is needed
+
+## Source
+
+https://docs.nestjs.com/modules
+
+## 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/codex/nestjs-module-pattern/skill.yaml

@@ -0,0 +1,43 @@
+name: nestjs-module-pattern
+version: "1.0.0"
+description: Organize NestJS applications with @Module, imports/exports, global and dynamic modules
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.module.ts"
+  - "**/*.controller.ts"
+  - "**/*.service.ts"
+related_skills:
+  - nestjs-dependency-injection
+  - nestjs-service-pattern
+  - nestjs-config-module
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - module
+  - imports
+  - exports
+  - providers
+  - controllers
+  - global
+  - dynamic-module
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/modules"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/nestjs-pipes-pattern/SKILL.md

@@ -0,0 +1,111 @@
+# NestJS Pipes Pattern
+
+> Validate and transform request data with PipeTransform, ValidationPipe, and custom pipes
+
+## When to Use
+
+- You need to validate incoming request bodies against a DTO class
+- You need to transform a string route parameter to a number, UUID, boolean, or enum
+- You want validation to run automatically on all routes without per-handler boilerplate
+- You are building a custom transformation (e.g., trim strings, normalize phone numbers)
+
+## Instructions
+
+1. **Enable ValidationPipe globally** in `main.ts` (recommended for most applications):
+
+```typescript
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true, // strip properties not in DTO
+    forbidNonWhitelisted: true, // throw on extra properties
+    transform: true, // auto-transform payload to DTO class instance
+    transformOptions: { enableImplicitConversion: true },
+  })
+);
+```
+
+2. **Use built-in transformation pipes** as inline pipe arguments:
+
+```typescript
+@Get(':id')
+findOne(@Param('id', ParseUUIDPipe) id: string) { ... }
+
+@Get(':page')
+list(@Query('page', ParseIntPipe) page: number) { ... }
+
+@Param('status', new ParseEnumPipe(UserStatus)) status: UserStatus
+```
+
+3. **Define DTO classes with class-validator decorators:**
+
+```typescript
+import { IsEmail, IsString, MinLength, IsOptional } from 'class-validator';
+
+export class CreateUserDto {
+  @IsEmail()
+  email: string;
+
+  @IsString()
+  @MinLength(8)
+  password: string;
+
+  @IsOptional()
+  @IsString()
+  displayName?: string;
+}
+```
+
+4. **Custom pipe** — implement `PipeTransform<T, R>`:
+
+```typescript
+@Injectable()
+export class TrimPipe implements PipeTransform<string, string> {
+  transform(value: string): string {
+    if (typeof value !== 'string') return value;
+    return value.trim();
+  }
+}
+```
+
+5. Apply custom pipes at the parameter level: `@Body('name', TrimPipe) name: string`.
+
+6. For pipes that may fail (e.g., parsing), throw `BadRequestException` rather than returning null.
+
+## Details
+
+Pipes serve two roles: **validation** (throw if invalid) and **transformation** (convert to the expected type). Both happen before the handler executes.
+
+**`whitelist: true` behavior:** `ValidationPipe` strips any property on the incoming JSON that has no corresponding decorator in the DTO. This prevents mass-assignment attacks where clients send unexpected fields (e.g., `isAdmin: true`). `forbidNonWhitelisted: true` goes further and throws a 400 if any extra property is present.
+
+**`transform: true`:** Without this, `@Body() dto: CreateUserDto` gives you a plain object, not a `CreateUserDto` instance. With it, NestJS runs `class-transformer`'s `plainToInstance` automatically so you get a proper class instance and `@Type()` decorators work correctly.
+
+**Class-validator integration:** All `class-validator` decorators (`@IsEmail()`, `@IsUUID()`, `@IsEnum()`, `@Min()`, `@Max()`, etc.) work with `ValidationPipe`. Nested DTOs require `@ValidateNested()` combined with `@Type(() => NestedDto)`.
+
+**Scope:** Pipes can be applied at four levels (most specific wins):
+
+1. Global — `app.useGlobalPipes()`
+2. Controller — `@UsePipes()`
+3. Method — `@UsePipes()`
+4. Parameter — inline in `@Param('id', ParseUUIDPipe)`
+
+**Async pipes:** `transform()` can return `Promise<R>`. This enables async validation (e.g., checking a database for uniqueness), though this is better done at the service layer.
+
+## Source
+
+https://docs.nestjs.com/pipes
+
+## 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/codex/nestjs-pipes-pattern/skill.yaml

@@ -0,0 +1,41 @@
+name: nestjs-pipes-pattern
+version: "1.0.0"
+description: Validate and transform request data with PipeTransform, ValidationPipe, and custom pipes
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.pipe.ts"
+  - "**/*.controller.ts"
+related_skills:
+  - nestjs-controller-pattern
+  - nestjs-dto-validation
+  - nestjs-exception-filters
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - pipe
+  - validation
+  - transform
+  - PipeTransform
+  - ValidationPipe
+  - ParseIntPipe
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/pipes"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/nestjs-service-pattern/SKILL.md

@@ -0,0 +1,83 @@
+# NestJS Service Pattern
+
+> Encapsulate business logic in @Injectable services with repository pattern separation
+
+## When to Use
+
+- You are implementing business logic that should be reusable across multiple controllers
+- You need to interact with a database, external API, or message queue from your application layer
+- You want to separate data access concerns (repository) from business rules (service)
+- You are writing unit tests and need to mock data access without touching the database
+
+## Instructions
+
+1. Decorate the class with `@Injectable()`. This registers it as a provider that the DI container can instantiate and inject.
+2. Declare the service in the `providers` array of its module. Export it if other modules need to inject it.
+3. Inject dependencies through the constructor using TypeScript types — NestJS uses reflection metadata to resolve them.
+4. Keep one service per domain aggregate (e.g., `UsersService`, `OrdersService`). Avoid `AppService` catch-alls.
+5. Apply the repository pattern: have the service call a repository (or Prisma/TypeORM directly) rather than embedding query logic inline.
+6. Throw `HttpException` subclasses (`NotFoundException`, `ConflictException`, etc.) for domain errors so exception filters can serialize them correctly.
+
+```typescript
+@Injectable()
+export class UsersService {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async findOne(id: string): Promise<User> {
+    const user = await this.prisma.user.findUnique({ where: { id } });
+    if (!user) throw new NotFoundException(`User ${id} not found`);
+    return user;
+  }
+
+  async create(dto: CreateUserDto): Promise<User> {
+    const existing = await this.prisma.user.findUnique({ where: { email: dto.email } });
+    if (existing) throw new ConflictException('Email already registered');
+    return this.prisma.user.create({ data: dto });
+  }
+
+  async update(id: string, dto: UpdateUserDto): Promise<User> {
+    await this.findOne(id); // reuse findOne for existence check
+    return this.prisma.user.update({ where: { id }, data: dto });
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.findOne(id);
+    await this.prisma.user.delete({ where: { id } });
+  }
+}
+```
+
+7. Use `async/await` for all async operations. Do not mix callbacks and promises.
+8. Keep methods focused — a method does one thing. Extract helpers for repeated logic.
+
+## Details
+
+Services are the workhorses of NestJS applications. They are singleton-scoped by default (one instance shared across the entire app lifetime), which means you should not store per-request state in service instance variables.
+
+**Scope options:** `@Injectable({ scope: Scope.REQUEST })` creates a new instance per request — useful for request-scoped data (e.g., tenant ID) but has a performance cost since the entire dependency chain must be request-scoped. Use the default `DEFAULT` (singleton) scope unless you have a concrete reason not to.
+
+**Repository pattern with Prisma:** Rather than calling `prisma.user` everywhere in a service, some teams create a `UsersRepository` class that wraps Prisma calls and exposes domain-level methods (`findByEmail`, `findActiveUsers`). This makes the service easier to test and the data access logic easier to swap.
+
+**Error boundaries:** Only throw HTTP exceptions in the service if it is HTTP-facing. For domain services shared between HTTP and microservice transports, throw domain-specific exceptions and convert them to `RpcException` or `HttpException` at the transport layer.
+
+**Circular dependency between services:** When `ServiceA` depends on `ServiceB` and vice versa, inject with `forwardRef()`: `@Inject(forwardRef(() => ServiceB)) private serviceB: ServiceB`. Prefer refactoring to a shared third service instead.
+
+## Source
+
+https://docs.nestjs.com/providers
+
+## 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/codex/nestjs-service-pattern/skill.yaml

@@ -0,0 +1,40 @@
+name: nestjs-service-pattern
+version: "1.0.0"
+description: Encapsulate business logic in @Injectable services with repository pattern separation
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.service.ts"
+  - "**/*.module.ts"
+related_skills:
+  - nestjs-module-pattern
+  - nestjs-dependency-injection
+  - prisma-client-queries
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - service
+  - injectable
+  - business-logic
+  - repository
+  - provider
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/providers"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/nestjs-swagger-integration/SKILL.md

@@ -0,0 +1,137 @@
+# NestJS Swagger Integration
+
+> Document APIs with @ApiProperty, @ApiOperation, @ApiTags, and DocumentBuilder
+
+## When to Use
+
+- You need interactive API documentation served at `/api` (or a custom path)
+- You need to document request/response schemas for frontend developers or API consumers
+- You want to generate an OpenAPI spec that can be imported into Postman, Insomnia, or API gateways
+- You are documenting authentication requirements (Bearer token, API key) on your endpoints
+
+## Instructions
+
+1. **Install and bootstrap:**
+
+```bash
+npm install @nestjs/swagger swagger-ui-express
+```
+
+```typescript
+// main.ts
+const config = new DocumentBuilder()
+  .setTitle('My API')
+  .setDescription('REST API documentation')
+  .setVersion('1.0')
+  .addBearerAuth()
+  .build();
+
+const document = SwaggerModule.createDocument(app, config);
+SwaggerModule.setup('api', app, document, {
+  swaggerOptions: { persistAuthorization: true },
+});
+```
+
+2. **Annotate controllers:**
+
+```typescript
+@ApiTags('users')
+@Controller('users')
+export class UsersController {
+  @ApiOperation({ summary: 'Get a user by ID' })
+  @ApiParam({ name: 'id', type: 'string', format: 'uuid' })
+  @ApiResponse({ status: 200, type: UserDto })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  @Get(':id')
+  findOne(@Param('id') id: string) { ... }
+
+  @ApiOperation({ summary: 'Create a user' })
+  @ApiBody({ type: CreateUserDto })
+  @ApiResponse({ status: 201, type: UserDto })
+  @ApiBearerAuth()
+  @Post()
+  create(@Body() dto: CreateUserDto) { ... }
+}
+```
+
+3. **Annotate DTOs:**
+
+```typescript
+export class CreateUserDto {
+  @ApiProperty({ example: 'user@example.com', description: 'User email address' })
+  @IsEmail()
+  email: string;
+
+  @ApiProperty({ example: 'myP@ssw0rd', minLength: 8 })
+  @IsString()
+  @MinLength(8)
+  password: string;
+
+  @ApiPropertyOptional({ example: 'John Doe' })
+  @IsOptional()
+  @IsString()
+  displayName?: string;
+}
+```
+
+4. **Use mapped types from `@nestjs/swagger`** (not `@nestjs/mapped-types`) for full Swagger compatibility:
+
+```typescript
+import { PartialType, OmitType, PickType } from '@nestjs/swagger';
+export class UpdateUserDto extends PartialType(CreateUserDto) {}
+export class UserProfileDto extends OmitType(CreateUserDto, ['password']) {}
+```
+
+5. **Document pagination responses:**
+
+```typescript
+@ApiResponse({ status: 200, schema: {
+  properties: {
+    data: { type: 'array', items: { $ref: getSchemaPath(UserDto) } },
+    total: { type: 'number' },
+    page: { type: 'number' },
+  }
+}})
+```
+
+## Details
+
+`@nestjs/swagger` uses TypeScript reflection metadata to auto-detect types in DTOs and controllers. When `emitDecoratorMetadata` is enabled in `tsconfig.json` (it must be for NestJS to work), most types are inferred automatically.
+
+**Enum documentation:** Pass `enum: MyEnum` in `@ApiProperty` for Swagger to show all valid values: `@ApiProperty({ enum: UserRole, enumName: 'UserRole' })`.
+
+**`@ApiHideProperty()`:** Exclude a property from the Swagger spec (e.g., internal tracking fields) without removing it from the DTO class.
+
+**CLI plugin (recommended):** Add to `nest-cli.json` to auto-add `@ApiProperty` based on class-validator decorators — eliminates duplication:
+
+```json
+{
+  "compilerOptions": {
+    "plugins": ["@nestjs/swagger"]
+  }
+}
+```
+
+**Exclude from production:** The Swagger UI and spec endpoint should be conditionally registered. Wrap the `SwaggerModule.setup()` call: `if (process.env.NODE_ENV !== 'production') { ... }`.
+
+**Export the spec:** `SwaggerModule.createDocument()` returns a plain OpenAPI 3.0 object. Write it to disk with `fs.writeFileSync('swagger.json', JSON.stringify(document))` to integrate with API gateway import workflows.
+
+## Source
+
+https://docs.nestjs.com/openapi/introduction
+
+## 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/codex/nestjs-swagger-integration/skill.yaml

@@ -0,0 +1,41 @@
+name: nestjs-swagger-integration
+version: "1.0.0"
+description: Document APIs with @ApiProperty, @ApiOperation, @ApiTags, and DocumentBuilder
+stability: static
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "nest-cli.json"
+  - "**/*.controller.ts"
+  - "**/*.dto.ts"
+related_skills:
+  - nestjs-controller-pattern
+  - nestjs-dto-validation
+stack_signals:
+  - nestjs
+  - typescript
+  - nodejs
+keywords:
+  - swagger
+  - openapi
+  - ApiProperty
+  - ApiOperation
+  - ApiTags
+  - DocumentBuilder
+  - api-docs
+metadata:
+  author: community
+  upstream: "docs.nestjs.com/openapi/introduction"
+state:
+  persistent: false
+  files: []
+depends_on: []