@breadstone/archipel-mcp 0.0.1

package/src/knowledge/configPattern.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel configuration pattern.
+ * Returned by the get-config-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_PATTERN_KNOWLEDGE = void 0;
+exports.CONFIG_PATTERN_KNOWLEDGE = `# Archipel Configuration Pattern
+
+## Overview
+
+Archipel uses a **typed configuration key** system with a **central registry**.
+Each platform library declares its required and optional config keys in an \`env.ts\`
+file, which are registered into the global \`ConfigRegistry\`. At runtime, the
+\`ConfigService\` resolves values through a pluggable strategy (environment variables,
+Azure App Configuration, etc.).
+
+**Rule:** No direct \`process.env\` access outside of config strategy implementations.
+
+## Core Types
+
+### IConfigKey<TType>
+
+\`\`\`typescript
+export interface IConfigKey<TType = unknown> {
+  readonly _type?: TType;  // Phantom type for compile-time safety
+  readonly key: string;     // The actual config key string
+}
+\`\`\`
+
+### createConfigKey<TType>
+
+\`\`\`typescript
+import { createConfigKey } from '@breadstone/archipel-platform-core';
+
+export const APP_URL = createConfigKey<string>('APP_URL');
+export const APP_PORT = createConfigKey<number>('APP_PORT');
+export const FEATURE_ENABLED = createConfigKey<boolean>('FEATURE_ENABLED');
+\`\`\`
+
+## ConfigService API
+
+\`\`\`typescript
+@Injectable()
+export class ConfigService {
+
+  // Throws if key not found
+  public get<T>(key: string): T;
+
+  // Returns fallback if key not found
+  public tryGet<T>(key: string, fallback: T): T;
+
+  // Compares a key's value to an expected value
+  public compare<T>(key: string, value: T): boolean;
+
+}
+\`\`\`
+
+**Auto-parsing:** String values are automatically converted:
+- \`'true'\` / \`'false'\` → \`boolean\`
+- Numeric strings → \`number\`
+- Empty strings → \`null\`
+
+## ConfigRegistry
+
+A static global registry that collects all declared config keys at module initialization.
+
+\`\`\`typescript
+export class ConfigRegistry {
+
+  // Register keys for a module
+  public static register(module: string, entries: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>>): void;
+
+  // Query all registered entries
+  public static getAll(): ReadonlyArray<IConfigRegistryEntry>;
+  public static getByModule(): ReadonlyMap<string, ReadonlyArray<IConfigRegistryEntry>>;
+  public static getRequired(): ReadonlyArray<IConfigRegistryEntry>;
+  public static getModules(): ReadonlyArray<string>;
+
+}
+\`\`\`
+
+### IConfigRegistryEntry
+
+\`\`\`typescript
+export interface IConfigRegistryEntry<TType = unknown> {
+  readonly key: IConfigKey<TType>;
+  readonly module: string;
+  readonly required: boolean;
+  readonly defaultValue?: TType;
+  readonly description?: string;
+}
+\`\`\`
+
+## How to Add Configuration to a Library
+
+### Step 1: Define typed config keys in env.ts
+
+\`\`\`typescript
+// src/env.ts
+import { createConfigKey } from '@breadstone/archipel-platform-core';
+import { ConfigRegistry, IConfigRegistryEntry } from '@breadstone/archipel-platform-core';
+
+// ──────────────────────────────────────────────────────────────
+// Keys
+// ──────────────────────────────────────────────────────────────
+
+export const STRIPE_SECRET_KEY = createConfigKey<string>('STRIPE_SECRET_KEY');
+export const STRIPE_WEBHOOK_SECRET = createConfigKey<string>('STRIPE_WEBHOOK_SECRET');
+export const PAYMENT_CURRENCY = createConfigKey<string>('PAYMENT_CURRENCY');
+
+// ──────────────────────────────────────────────────────────────
+// Registry entries
+// ──────────────────────────────────────────────────────────────
+
+export const PLATFORM_PAYMENTS_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistryEntry, 'module'>> = [
+  { key: STRIPE_SECRET_KEY, required: true, description: 'Stripe API secret key.' },
+  { key: STRIPE_WEBHOOK_SECRET, required: true, description: 'Stripe webhook signing secret.' },
+  { key: PAYMENT_CURRENCY, required: false, defaultValue: 'EUR', description: 'Default payment currency.' },
+];
+\`\`\`
+
+### Step 2: Register in ConfigModule
+
+\`\`\`typescript
+// In the module's register() method:
+imports: [ConfigModule.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES)]
+\`\`\`
+
+Or for libraries without a dedicated module (self-registration):
+
+\`\`\`typescript
+// At the bottom of env.ts:
+ConfigRegistry.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES);
+\`\`\`
+
+### Step 3: Use in services
+
+\`\`\`typescript
+@Injectable()
+export class StripeClient {
+
+  private readonly _configService: ConfigService;
+
+  public constructor(configService: ConfigService) {
+    this._configService = configService;
+  }
+
+  private getApiKey(): string {
+    return this._configService.get<string>('STRIPE_SECRET_KEY');
+  }
+
+}
+\`\`\`
+
+## ConfigModule
+
+### register() — Per-library config registration
+
+Declares which config keys a library needs. Used in \`imports\` of feature modules.
+
+\`\`\`typescript
+ConfigModule.register('platform-authentication', PLATFORM_AUTHENTICATION_CONFIG_ENTRIES)
+\`\`\`
+
+### forRoot() — Application bootstrap
+
+Configures the global strategy and static overrides. Used once in the root module.
+
+\`\`\`typescript
+ConfigModule.forRoot({
+  strategyFactory: () => new EnvironmentConfigStrategy(),
+  statics: { APP_VERSION: '1.0.0' },
+})
+\`\`\`
+
+## ConfigStrategyBase
+
+Pluggable strategy for resolving config values:
+
+\`\`\`typescript
+export abstract class ConfigStrategyBase {
+  public abstract initialize(): void;
+  public abstract resolve<T>(key: string): T;
+  public abstract tryResolve<T>(key: string, fallback: T): T;
+  public abstract has(key: string): boolean;
+}
+\`\`\`
+
+Implementations can read from environment variables, Azure App Configuration, Consul, etc.
+
+## Existing Config Modules
+
+| Module | Prefix | Example Keys |
+|--------|--------|-------------|
+| platform-core | APP_, NODE_ENV, INTELLIGENCE_ | APP_URL, APP_PORT, APP_VERSION, INTELLIGENCE_MODEL |
+| platform-authentication | AUTH_ | AUTH_JWT_SECRET, AUTH_JWT_EXPIRES_IN |
+| platform-payments | STRIPE_ | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET |
+| platform-openapi | SWAGGER_ | SWAGGER_CONTACT_NAME, SWAGGER_CONTACT_URL |
+
+## Rules
+
+1. **All config keys defined via \`createConfigKey<T>()\`** — never raw \`process.env\` access.
+2. **Each library declares entries in \`env.ts\`** with required flag, default value, and description.
+3. **Registration via \`ConfigModule.register()\`** in the module, or self-registration for libraries without modules.
+4. **\`ConfigService.get()\` throws on missing required keys** — fail-fast at startup.
+5. **Use \`tryGet()\` with fallback** for optional keys.
+6. **Config key names use UPPER_SNAKE_CASE** matching environment variable conventions.
+7. **Group related keys** with comment separators in env.ts.
+`;
+//# sourceMappingURL=configPattern.js.map

package/src/knowledge/dtoPattern.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Static knowledge content for the Archipel DTO & validation pattern.
+ * Returned by the get-dto-pattern tool.
+ */
+export declare const DTO_PATTERN_KNOWLEDGE = "# Archipel DTO & Validation Pattern\n\n## Overview\n\nArchipel uses **class-based DTOs** with **class-validator** decorators for input validation\nand **class-transformer** decorators for serialization control. A global `ValidationPipe`\nenforces validation on all incoming requests automatically.\n\nRequest DTOs validate input; Response classes define the output shape with\n`@ApiProperty` decorators for OpenAPI documentation.\n\n## Global Validation Pipe\n\n```typescript\n// In main.ts bootstrap:\napp.useGlobalPipes(\n  new ValidationPipe({\n    whitelist: true,             // Strip unknown properties\n    forbidNonWhitelisted: true,  // Throw on unknown properties\n    transform: true,             // Auto-transform payloads to DTO instances\n  }),\n);\n```\n\n## Request DTO (Input Validation)\n\n```typescript\n// dtos/CreateUserRequest.ts\nimport { Expose } from 'class-transformer';\nimport { IsEmail, IsString, MinLength, MaxLength } from 'class-validator';\nimport { ApiProperty } from '@nestjs/swagger';\n\nexport class CreateUserRequest {\n\n  @Expose()\n  @IsEmail()\n  @ApiProperty({ example: 'user@example.com', description: 'User email address' })\n  public email!: string;\n\n  @Expose()\n  @IsString()\n  @MinLength(3)\n  @MaxLength(50)\n  @ApiProperty({ description: 'Display name' })\n  public name!: string;\n\n  @Expose()\n  @IsString()\n  @MinLength(8)\n  @ApiProperty({ description: 'Password (min 8 characters)' })\n  public password!: string;\n\n}\n```\n\n## Response DTO (Output Shape)\n\n```typescript\n// dtos/UserResponse.ts\nimport { Expose } from 'class-transformer';\nimport { ApiProperty } from '@nestjs/swagger';\n\nexport class UserResponse {\n\n  @Expose()\n  @ApiProperty({ description: 'Unique identifier' })\n  public id!: string;\n\n  @Expose()\n  @ApiProperty({ description: 'User email address' })\n  public email!: string;\n\n  @Expose()\n  @ApiProperty({ description: 'Display name' })\n  public name!: string;\n\n  @Expose()\n  @ApiProperty({ description: 'Account creation date' })\n  public createdAt!: Date;\n\n  // Note: password is intentionally NOT exposed\n\n}\n```\n\n## Common Validators\n\n### Basic Types\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@IsString()` | Must be a string |\n| `@IsNumber()` | Must be a number |\n| `@IsBoolean()` | Must be a boolean |\n| `@IsEmail()` | Must be a valid email |\n| `@IsUUID()` | Must be a valid UUID |\n| `@IsDate()` | Must be a Date instance |\n| `@IsEnum(MyEnum)` | Must be a value from the enum |\n| `@IsOptional()` | Field is optional (skip validation if undefined) |\n\n### String Constraints\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@MinLength(n)` | Minimum string length |\n| `@MaxLength(n)` | Maximum string length |\n| `@Matches(regex)` | Must match a regex pattern |\n| `@IsNotEmpty()` | Must not be empty string |\n\n### Number Constraints\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@Min(n)` | Minimum value |\n| `@Max(n)` | Maximum value |\n| `@IsPositive()` | Must be > 0 |\n| `@IsInt()` | Must be integer |\n\n### Nested & Array\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@ValidateNested()` | Validate nested objects |\n| `@Type(() => Cls)` | Transform to class instance (class-transformer) |\n| `@IsArray()` | Must be an array |\n| `@ArrayMinSize(n)` | Minimum array length |\n| `@ArrayMaxSize(n)` | Maximum array length |\n\n## Cross-Field Validation\n\nFor fields that depend on each other, use custom class-level validators:\n\n```typescript\nimport { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments, Validate } from 'class-validator';\n\n@ValidatorConstraint({ name: 'Match', async: false })\nexport class MatchConstraint implements ValidatorConstraintInterface {\n\n  public validate(value: unknown, args: ValidationArguments): boolean {\n    const [relatedPropertyName] = args.constraints;\n    const relatedValue = (args.object as Record<string, unknown>)[relatedPropertyName];\n\n    return value === relatedValue;\n  }\n\n  public defaultMessage(args: ValidationArguments): string {\n    const [relatedPropertyName] = args.constraints;\n\n    return \\`\\${args.property} must match \\${relatedPropertyName}\\`;\n  }\n\n}\n\n// Usage in DTO:\nexport class ResetPasswordRequest {\n\n  @Expose()\n  @IsString()\n  @MinLength(8)\n  public password!: string;\n\n  @Expose()\n  @IsString()\n  @Validate(MatchConstraint, ['password'])\n  public confirmPassword!: string;\n\n}\n```\n\n## Query Parameter DTOs\n\nFor GET request query parameters, use `@Transform()` and `@Type()` for type coercion:\n\n```typescript\nimport { Type } from 'class-transformer';\nimport { IsOptional, IsInt, Min, Max, IsString } from 'class-validator';\nimport { ApiPropertyOptional } from '@nestjs/swagger';\n\nexport class PaginationQuery {\n\n  @IsOptional()\n  @Type(() => Number)\n  @IsInt()\n  @Min(1)\n  @ApiPropertyOptional({ default: 1 })\n  public page?: number = 1;\n\n  @IsOptional()\n  @Type(() => Number)\n  @IsInt()\n  @Min(1)\n  @Max(100)\n  @ApiPropertyOptional({ default: 20 })\n  public perPage?: number = 20;\n\n  @IsOptional()\n  @IsString()\n  @ApiPropertyOptional()\n  public search?: string;\n\n}\n```\n\n## OpenAPI / Swagger Integration\n\n### @ApiProperty Decorators\n\n```typescript\n@ApiProperty({\n  description: 'User email address',\n  example: 'user@example.com',\n  required: true,\n})\npublic email!: string;\n\n@ApiPropertyOptional({\n  description: 'Profile bio',\n  maxLength: 500,\n})\npublic bio?: string;\n```\n\n### Controller Response Decorators\n\n```typescript\n@Controller('/users')\n@ApiTags('Users')\nexport class UsersController {\n\n  @Post()\n  @HttpCode(HttpStatus.CREATED)\n  @ApiOperation({ summary: 'Create a new user' })\n  @ApiResponse({ status: 201, description: 'User created', type: UserResponse })\n  @ApiResponse({ status: 400, description: 'Validation error' })\n  public async createUser(@Body() body: CreateUserRequest): Promise<UserResponse> {\n    // ...\n  }\n\n}\n```\n\n## Naming Conventions\n\n| Type | Naming Pattern | Example |\n|------|---------------|---------|\n| Create input | `Create{Entity}Request` | `CreateUserRequest` |\n| Update input | `Update{Entity}Request` | `UpdateUserRequest` |\n| Query params | `{Entity}Query` or `Pagination{Entity}Query` | `UserQuery` |\n| Response | `{Entity}Response` | `UserResponse` |\n| List response | `{Entity}ListResponse` | `UserListResponse` |\n\n## Constants for Bounds\n\nDefine and reuse constants for upper limits:\n\n```typescript\n// constants/ValidationConstants.ts\nexport const MAX_PAGE_SIZE = 100;\nexport const MAX_SEARCH_LIMIT = 50;\nexport const MAX_NAME_LENGTH = 100;\nexport const MAX_BIO_LENGTH = 500;\n\n// In DTO:\n@Max(MAX_PAGE_SIZE)\npublic perPage?: number;\n```\n\n## Rules\n\n1. **Every field has `@Expose()`** for serialization control.\n2. **Every field has `@ApiProperty()`** for OpenAPI documentation.\n3. **Request DTOs use class-validator decorators** \u2014 validation is automatic via global pipe.\n4. **Response DTOs have no validation decorators** \u2014 they're output-only shapes.\n5. **Cross-field validation uses custom class-level validators** \u2014 never imperative checks in services.\n6. **Query parameters use `@Type(() => Number)`** for type coercion from strings.\n7. **Upper bounds (`@Max`, `@MaxLength`) defined as exported constants** \u2014 never inline magic numbers.\n8. **`whitelist: true` + `forbidNonWhitelisted: true`** strips and rejects unknown properties.\n";

package/src/knowledge/dtoPattern.js

@@ -0,0 +1,286 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel DTO & validation pattern.
+ * Returned by the get-dto-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DTO_PATTERN_KNOWLEDGE = void 0;
+exports.DTO_PATTERN_KNOWLEDGE = `# Archipel DTO & Validation Pattern
+
+## Overview
+
+Archipel uses **class-based DTOs** with **class-validator** decorators for input validation
+and **class-transformer** decorators for serialization control. A global \`ValidationPipe\`
+enforces validation on all incoming requests automatically.
+
+Request DTOs validate input; Response classes define the output shape with
+\`@ApiProperty\` decorators for OpenAPI documentation.
+
+## Global Validation Pipe
+
+\`\`\`typescript
+// In main.ts bootstrap:
+app.useGlobalPipes(
+  new ValidationPipe({
+    whitelist: true,             // Strip unknown properties
+    forbidNonWhitelisted: true,  // Throw on unknown properties
+    transform: true,             // Auto-transform payloads to DTO instances
+  }),
+);
+\`\`\`
+
+## Request DTO (Input Validation)
+
+\`\`\`typescript
+// dtos/CreateUserRequest.ts
+import { Expose } from 'class-transformer';
+import { IsEmail, IsString, MinLength, MaxLength } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class CreateUserRequest {
+
+  @Expose()
+  @IsEmail()
+  @ApiProperty({ example: 'user@example.com', description: 'User email address' })
+  public email!: string;
+
+  @Expose()
+  @IsString()
+  @MinLength(3)
+  @MaxLength(50)
+  @ApiProperty({ description: 'Display name' })
+  public name!: string;
+
+  @Expose()
+  @IsString()
+  @MinLength(8)
+  @ApiProperty({ description: 'Password (min 8 characters)' })
+  public password!: string;
+
+}
+\`\`\`
+
+## Response DTO (Output Shape)
+
+\`\`\`typescript
+// dtos/UserResponse.ts
+import { Expose } from 'class-transformer';
+import { ApiProperty } from '@nestjs/swagger';
+
+export class UserResponse {
+
+  @Expose()
+  @ApiProperty({ description: 'Unique identifier' })
+  public id!: string;
+
+  @Expose()
+  @ApiProperty({ description: 'User email address' })
+  public email!: string;
+
+  @Expose()
+  @ApiProperty({ description: 'Display name' })
+  public name!: string;
+
+  @Expose()
+  @ApiProperty({ description: 'Account creation date' })
+  public createdAt!: Date;
+
+  // Note: password is intentionally NOT exposed
+
+}
+\`\`\`
+
+## Common Validators
+
+### Basic Types
+
+| Decorator | Purpose |
+|-----------|---------|
+| \`@IsString()\` | Must be a string |
+| \`@IsNumber()\` | Must be a number |
+| \`@IsBoolean()\` | Must be a boolean |
+| \`@IsEmail()\` | Must be a valid email |
+| \`@IsUUID()\` | Must be a valid UUID |
+| \`@IsDate()\` | Must be a Date instance |
+| \`@IsEnum(MyEnum)\` | Must be a value from the enum |
+| \`@IsOptional()\` | Field is optional (skip validation if undefined) |
+
+### String Constraints
+
+| Decorator | Purpose |
+|-----------|---------|
+| \`@MinLength(n)\` | Minimum string length |
+| \`@MaxLength(n)\` | Maximum string length |
+| \`@Matches(regex)\` | Must match a regex pattern |
+| \`@IsNotEmpty()\` | Must not be empty string |
+
+### Number Constraints
+
+| Decorator | Purpose |
+|-----------|---------|
+| \`@Min(n)\` | Minimum value |
+| \`@Max(n)\` | Maximum value |
+| \`@IsPositive()\` | Must be > 0 |
+| \`@IsInt()\` | Must be integer |
+
+### Nested & Array
+
+| Decorator | Purpose |
+|-----------|---------|
+| \`@ValidateNested()\` | Validate nested objects |
+| \`@Type(() => Cls)\` | Transform to class instance (class-transformer) |
+| \`@IsArray()\` | Must be an array |
+| \`@ArrayMinSize(n)\` | Minimum array length |
+| \`@ArrayMaxSize(n)\` | Maximum array length |
+
+## Cross-Field Validation
+
+For fields that depend on each other, use custom class-level validators:
+
+\`\`\`typescript
+import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments, Validate } from 'class-validator';
+
+@ValidatorConstraint({ name: 'Match', async: false })
+export class MatchConstraint implements ValidatorConstraintInterface {
+
+  public validate(value: unknown, args: ValidationArguments): boolean {
+    const [relatedPropertyName] = args.constraints;
+    const relatedValue = (args.object as Record<string, unknown>)[relatedPropertyName];
+
+    return value === relatedValue;
+  }
+
+  public defaultMessage(args: ValidationArguments): string {
+    const [relatedPropertyName] = args.constraints;
+
+    return \\\`\\\${args.property} must match \\\${relatedPropertyName}\\\`;
+  }
+
+}
+
+// Usage in DTO:
+export class ResetPasswordRequest {
+
+  @Expose()
+  @IsString()
+  @MinLength(8)
+  public password!: string;
+
+  @Expose()
+  @IsString()
+  @Validate(MatchConstraint, ['password'])
+  public confirmPassword!: string;
+
+}
+\`\`\`
+
+## Query Parameter DTOs
+
+For GET request query parameters, use \`@Transform()\` and \`@Type()\` for type coercion:
+
+\`\`\`typescript
+import { Type } from 'class-transformer';
+import { IsOptional, IsInt, Min, Max, IsString } from 'class-validator';
+import { ApiPropertyOptional } from '@nestjs/swagger';
+
+export class PaginationQuery {
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @ApiPropertyOptional({ default: 1 })
+  public page?: number = 1;
+
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  @ApiPropertyOptional({ default: 20 })
+  public perPage?: number = 20;
+
+  @IsOptional()
+  @IsString()
+  @ApiPropertyOptional()
+  public search?: string;
+
+}
+\`\`\`
+
+## OpenAPI / Swagger Integration
+
+### @ApiProperty Decorators
+
+\`\`\`typescript
+@ApiProperty({
+  description: 'User email address',
+  example: 'user@example.com',
+  required: true,
+})
+public email!: string;
+
+@ApiPropertyOptional({
+  description: 'Profile bio',
+  maxLength: 500,
+})
+public bio?: string;
+\`\`\`
+
+### Controller Response Decorators
+
+\`\`\`typescript
+@Controller('/users')
+@ApiTags('Users')
+export class UsersController {
+
+  @Post()
+  @HttpCode(HttpStatus.CREATED)
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({ status: 201, description: 'User created', type: UserResponse })
+  @ApiResponse({ status: 400, description: 'Validation error' })
+  public async createUser(@Body() body: CreateUserRequest): Promise<UserResponse> {
+    // ...
+  }
+
+}
+\`\`\`
+
+## Naming Conventions
+
+| Type | Naming Pattern | Example |
+|------|---------------|---------|
+| Create input | \`Create{Entity}Request\` | \`CreateUserRequest\` |
+| Update input | \`Update{Entity}Request\` | \`UpdateUserRequest\` |
+| Query params | \`{Entity}Query\` or \`Pagination{Entity}Query\` | \`UserQuery\` |
+| Response | \`{Entity}Response\` | \`UserResponse\` |
+| List response | \`{Entity}ListResponse\` | \`UserListResponse\` |
+
+## Constants for Bounds
+
+Define and reuse constants for upper limits:
+
+\`\`\`typescript
+// constants/ValidationConstants.ts
+export const MAX_PAGE_SIZE = 100;
+export const MAX_SEARCH_LIMIT = 50;
+export const MAX_NAME_LENGTH = 100;
+export const MAX_BIO_LENGTH = 500;
+
+// In DTO:
+@Max(MAX_PAGE_SIZE)
+public perPage?: number;
+\`\`\`
+
+## Rules
+
+1. **Every field has \`@Expose()\`** for serialization control.
+2. **Every field has \`@ApiProperty()\`** for OpenAPI documentation.
+3. **Request DTOs use class-validator decorators** — validation is automatic via global pipe.
+4. **Response DTOs have no validation decorators** — they're output-only shapes.
+5. **Cross-field validation uses custom class-level validators** — never imperative checks in services.
+6. **Query parameters use \`@Type(() => Number)\`** for type coercion from strings.
+7. **Upper bounds (\`@Max\`, \`@MaxLength\`) defined as exported constants** — never inline magic numbers.
+8. **\`whitelist: true\` + \`forbidNonWhitelisted: true\`** strips and rejects unknown properties.
+`;
+//# sourceMappingURL=dtoPattern.js.map

package/src/knowledge/errorHandlingPattern.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Static knowledge content for the Archipel error handling pattern.
+ * Returned by the get-error-handling-pattern tool.
+ */
+export declare const ERROR_HANDLING_PATTERN_KNOWLEDGE = "# Archipel Error Handling Pattern\n\n## Overview\n\nArchipel uses **domain-specific error classes** that are caught by **global exception filters**\nand mapped to structured HTTP responses. Services throw domain errors; the framework handles\nthe HTTP translation. This keeps business logic clean and error responses consistent.\n\n## Layer Architecture\n\n```\nService \u2192 throws DomainError \u2192 ExceptionFilter \u2192 HTTP Response Envelope\n```\n\n## Base Error Classes\n\n### RepositoryError\n\nThrown when any Prisma operation fails. Automatically wrapped by `RepositoryBase.tryCatch()`.\n\n```typescript\n// models/errors/RepositoryError.ts\nexport class RepositoryError extends Error {\n\n  public readonly code = 'REPOSITORY_ERROR';\n  public readonly originalCode?: string;\n  public readonly meta?: Record<string, unknown>;\n\n  public constructor(message: string, originalCode?: string, meta?: Record<string, unknown>) {\n    super(message);\n    Object.setPrototypeOf(this, RepositoryError.prototype);\n    this.name = 'RepositoryError';\n    this.originalCode = originalCode;\n    this.meta = meta;\n\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, RepositoryError);\n    }\n  }\n\n}\n```\n\n### MappingError (abstract)\n\nBase for mapping-related errors.\n\n```typescript\nexport abstract class MappingError extends Error {\n  public readonly code: string;\n\n  protected constructor(message: string, code: string) {\n    super(message);\n    this.code = code;\n  }\n}\n```\n\nConcrete variants:\n- `MappingNotRegisteredError` \u2014 code: `'MAPPING_NOT_REGISTERED'`\n- `TypeMappingNotRegisteredError` \u2014 code: `'TYPE_MAPPING_NOT_REGISTERED'`\n\n## Exception Filters\n\n### RepositoryExceptionFilter\n\n```typescript\nimport { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';\nimport { Request, Response } from 'express';\nimport { RepositoryError } from '../models/errors/RepositoryError';\n\n@Catch(RepositoryError)\nexport class RepositoryExceptionFilter implements ExceptionFilter<RepositoryError> {\n\n  public catch(_exception: RepositoryError, host: ArgumentsHost): void {\n    const ctx = host.switchToHttp();\n    const response = ctx.getResponse<Response>();\n    const request = ctx.getRequest<Request>();\n\n    response.status(HttpStatus.INTERNAL_SERVER_ERROR).json({\n      statusCode: HttpStatus.INTERNAL_SERVER_ERROR,\n      timestamp: new Date().toISOString(),\n      error: 'Repository Error',\n      path: request.url,\n    });\n  }\n\n}\n```\n\n### Registration (in main.ts or AppModule)\n\n```typescript\napp.useGlobalFilters(new RepositoryExceptionFilter());\n```\n\n## How to Create a Domain Error\n\n### Step 1: Define the error class\n\n```typescript\n// models/errors/UserNotFoundError.ts\nexport class UserNotFoundError extends Error {\n\n  public readonly code = 'USER_NOT_FOUND';\n  public readonly userId: string;\n\n  public constructor(userId: string) {\n    super(\\`User not found: \\${userId}\\`);\n    Object.setPrototypeOf(this, UserNotFoundError.prototype);\n    this.name = 'UserNotFoundError';\n    this.userId = userId;\n\n    if (Error.captureStackTrace) {\n      Error.captureStackTrace(this, UserNotFoundError);\n    }\n  }\n\n}\n```\n\n### Step 2: Create an exception filter\n\n```typescript\n// filters/UserNotFoundExceptionFilter.ts\nimport { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';\nimport { Request, Response } from 'express';\nimport { UserNotFoundError } from '../models/errors/UserNotFoundError';\n\n@Catch(UserNotFoundError)\nexport class UserNotFoundExceptionFilter implements ExceptionFilter<UserNotFoundError> {\n\n  public catch(exception: UserNotFoundError, host: ArgumentsHost): void {\n    const ctx = host.switchToHttp();\n    const response = ctx.getResponse<Response>();\n    const request = ctx.getRequest<Request>();\n\n    response.status(HttpStatus.NOT_FOUND).json({\n      statusCode: HttpStatus.NOT_FOUND,\n      timestamp: new Date().toISOString(),\n      error: exception.code,\n      message: exception.message,\n      path: request.url,\n    });\n  }\n\n}\n```\n\n### Step 3: Register the filter globally\n\n```typescript\napp.useGlobalFilters(\n  new RepositoryExceptionFilter(),\n  new UserNotFoundExceptionFilter(),\n);\n```\n\n### Step 4: Throw from a service\n\n```typescript\n@Injectable()\nexport class UserService {\n\n  public async findById(id: string): Promise<IUserEntity> {\n    const user = await this._userRepository.execute(findUserByIdQuery(id));\n\n    if (!user) {\n      throw new UserNotFoundError(id);\n    }\n\n    return user;\n  }\n\n}\n```\n\n## Response Envelope Convention\n\nAll error responses follow the same shape:\n\n```json\n{\n  \"statusCode\": 404,\n  \"timestamp\": \"2026-04-05T12:00:00.000Z\",\n  \"error\": \"USER_NOT_FOUND\",\n  \"message\": \"User not found: abc-123\",\n  \"path\": \"/api/v1/users/abc-123\"\n}\n```\n\n## Prisma Error Code Reference\n\nCommon Prisma error codes wrapped by `RepositoryError`:\n\n| Code | Meaning |\n|------|---------|\n| P2000 | Value too long |\n| P2002 | Unique constraint violation |\n| P2003 | Foreign key constraint violation |\n| P2025 | Record not found |\n\n## Rules\n\n1. **Services throw domain errors** \u2014 never raw NestJS HttpException in service layer.\n2. **Exception filters map to HTTP** \u2014 one filter per domain error type.\n3. **Error classes include a machine-readable `code`** \u2014 used for client-side error handling.\n4. **Use `Object.setPrototypeOf`** and `Error.captureStackTrace` in custom Error subclasses.\n5. **Don't leak internal details** \u2014 the filter should not expose Prisma error codes or stack traces.\n6. **Register filters globally** in the bootstrap function or via `APP_FILTER` provider.\n";