@breadstone/archipel-mcp 0.0.21 → 0.0.22

package/data/packages/platform-core/api/Interface.IResourceStrategy.md

@@ -1,134 +0,0 @@
----
-title: 'Interface: IResourceStrategy'
-generated: true
-editUrl: false
----
-# Interface: IResourceStrategy
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:8](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L8)
-
-Strategy for loading resources from a specific source.
-
-## Properties
-
-### name
-
-```ts
-readonly name: string;
-```
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L13)
-
-The unique name of this strategy.
-
-## Methods
-
-### exists()
-
-```ts
-exists(key): boolean;
-```
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:37](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L37)
-
-Checks if a resource exists without loading it.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `string` | The resource key/identifier |
-
-#### Returns
-
-`boolean`
-
-True if the resource exists
-
-***
-
-### existsAsync()
-
-```ts
-existsAsync(key): Promise<boolean>;
-```
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:45](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L45)
-
-Checks if a resource exists without loading it (asynchronous).
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `string` | The resource key/identifier |
-
-#### Returns
-
-`Promise`\<`boolean`\>
-
-Promise resolving to true if the resource exists
-
-***
-
-### load()
-
-```ts
-load(key): IResourceResult | undefined;
-```
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:21](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L21)
-
-Loads a resource by its key.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `string` | The resource key/identifier |
-
-#### Returns
-
-[`IResourceResult`](Interface.IResourceResult) \| `undefined`
-
-The resource result or undefined if not found
-
-***
-
-### loadAsync()
-
-```ts
-loadAsync(key): Promise<IResourceResult | undefined>;
-```
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L29)
-
-Loads a resource by its key (asynchronous).
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `key` | `string` | The resource key/identifier |
-
-#### Returns
-
-`Promise`\<[`IResourceResult`](Interface.IResourceResult) \| `undefined`\>
-
-Promise resolving to the resource result or undefined if not found
-
-***
-
-### whatDoIHave()
-
-```ts
-whatDoIHave(): void;
-```
-
-Defined in: [resources/strategies/abstracts/IResourceStrategy.ts:50](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/resources/strategies/abstracts/IResourceStrategy.ts#L50)
-
-List all files and folders in the base paths for debugging purposes.
-
-#### Returns
-
-`void`

package/data/packages/platform-core/api/Variable.HEALTH_INDICATORS_TOKEN.md

@@ -1,14 +0,0 @@
----
-title: 'Variable: HEALTH\_INDICATORS\_TOKEN'
-generated: true
-editUrl: false
----
-# Variable: HEALTH\_INDICATORS\_TOKEN
-
-```ts
-const HEALTH_INDICATORS_TOKEN: typeof HEALTH_INDICATORS_TOKEN;
-```
-
-Defined in: [health/HealthTokens.ts:2](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-core/src/health/HealthTokens.ts#L2)
-
-Injection token for registered health indicators

package/data/packages/platform-mailing/api/Class.BlobTemplateFetchStrategy.md

@@ -1,60 +0,0 @@
----
-title: 'Class: BlobTemplateFetchStrategy'
-generated: true
-editUrl: false
----
-# Class: BlobTemplateFetchStrategy
-
-Defined in: [platform-mailing/src/templating/strategies/BlobTemplateFetchStrategy.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/templating/strategies/BlobTemplateFetchStrategy.ts#L16)
-
-The `BlobTemplateFetchStrategy` class.
-
-## Extends
-
-- [`TemplateFetchStrategyBase`](Class.TemplateFetchStrategyBase)
-
-## Constructors
-
-### Constructor
-
-```ts
-new BlobTemplateFetchStrategy(blobService): BlobTemplateFetchStrategy;
-```
-
-Defined in: [platform-mailing/src/templating/strategies/BlobTemplateFetchStrategy.ts:31](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/templating/strategies/BlobTemplateFetchStrategy.ts#L31)
-
-Constructs a new instance of the `BlobTemplateFetchStrategy` class.
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `blobService` | `BlobService` |
-
-#### Returns
-
-`BlobTemplateFetchStrategy`
-
-#### Overrides
-
-[`TemplateFetchStrategyBase`](Class.TemplateFetchStrategyBase).[`constructor`](Class.TemplateFetchStrategyBase#constructor)
-
-## Methods
-
-### load()
-
-```ts
-abstract load(): Promise<Record<string, IMailTemplateVariants>>;
-```
-
-Defined in: [platform-mailing/src/templating/strategies/BlobTemplateFetchStrategy.ts:41](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/templating/strategies/BlobTemplateFetchStrategy.ts#L41)
-
-Loads the templates.
-
-#### Returns
-
-`Promise`\<`Record`\<`string`, [`IMailTemplateVariants`](Interface.IMailTemplateVariants)\>\>
-
-#### Overrides
-
-[`TemplateFetchStrategyBase`](Class.TemplateFetchStrategyBase).[`load`](Class.TemplateFetchStrategyBase#load)

package/data/packages/platform-mailing/api/Class.FileTemplateFetchStrategy.md

@@ -1,58 +0,0 @@
----
-title: 'Class: FileTemplateFetchStrategy'
-generated: true
-editUrl: false
----
-# Class: FileTemplateFetchStrategy
-
-Defined in: [platform-mailing/src/templating/strategies/FileTemplateFetchStrategy.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/templating/strategies/FileTemplateFetchStrategy.ts#L16)
-
-The `FileTemplateFetchStrategy` class.
-
-## Extends
-
-- [`TemplateFetchStrategyBase`](Class.TemplateFetchStrategyBase)
-
-## Constructors
-
-### Constructor
-
-```ts
-new FileTemplateFetchStrategy(resourceManager): FileTemplateFetchStrategy;
-```
-
-Defined in: [platform-mailing/src/templating/strategies/FileTemplateFetchStrategy.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/templating/strategies/FileTemplateFetchStrategy.ts#L26)
-
-#### Parameters
-
-| Parameter | Type |
-| ------ | ------ |
-| `resourceManager` | `ResourceManager` |
-
-#### Returns
-
-`FileTemplateFetchStrategy`
-
-#### Overrides
-
-[`TemplateFetchStrategyBase`](Class.TemplateFetchStrategyBase).[`constructor`](Class.TemplateFetchStrategyBase#constructor)
-
-## Methods
-
-### load()
-
-```ts
-load(): Promise<Record<string, IMailTemplateVariants>>;
-```
-
-Defined in: [platform-mailing/src/templating/strategies/FileTemplateFetchStrategy.ts:40](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/templating/strategies/FileTemplateFetchStrategy.ts#L40)
-
-Loads mail templates from the file system.
-
-#### Returns
-
-`Promise`\<`Record`\<`string`, [`IMailTemplateVariants`](Interface.IMailTemplateVariants)\>\>
-
-#### Overrides
-
-[`TemplateFetchStrategyBase`](Class.TemplateFetchStrategyBase).[`load`](Class.TemplateFetchStrategyBase#load)

package/data/packages/platform-mailing/api/Class.LogDeliveryStrategy.md

@@ -1,71 +0,0 @@
----
-title: 'Class: LogDeliveryStrategy'
-generated: true
-editUrl: false
----
-# Class: LogDeliveryStrategy
-
-Defined in: [platform-mailing/src/services/strategies/LogDeliveryStrategy.ts:13](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/strategies/LogDeliveryStrategy.ts#L13)
-
-The `LogDeliveryStrategy` class.
-
-## Extends
-
-- [`DeliveryStrategyBase`](Class.DeliveryStrategyBase)
-
-## Constructors
-
-### Constructor
-
-```ts
-new LogDeliveryStrategy(): LogDeliveryStrategy;
-```
-
-Defined in: [platform-mailing/src/services/strategies/LogDeliveryStrategy.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/strategies/LogDeliveryStrategy.ts#L27)
-
-Constructs a new instance of the `LogDelivery` class.
-
-#### Returns
-
-`LogDeliveryStrategy`
-
-#### Overrides
-
-[`DeliveryStrategyBase`](Class.DeliveryStrategyBase).[`constructor`](Class.DeliveryStrategyBase#constructor)
-
-## Methods
-
-### send()
-
-```ts
-abstract send(
-   from, 
-   to, 
-   subject, 
-   content, 
-   isHtml, 
-_attachments?): Promise<void>;
-```
-
-Defined in: [platform-mailing/src/services/strategies/LogDeliveryStrategy.ts:35](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-mailing/src/services/strategies/LogDeliveryStrategy.ts#L35)
-
-Sends an email with either plain text or HTML content.
-
-#### Parameters
-
-| Parameter | Type | Description |
-| ------ | ------ | ------ |
-| `from` | `string` | Sender's email address (optional, defaults to config) |
-| `to` | `string` | Recipient's email address |
-| `subject` | `string` | Subject of the email |
-| `content` | `string` | Email body content (plain text or HTML) |
-| `isHtml` | `boolean` | Flag to indicate whether the email is HTML (true) or plain text (false) |
-| `_attachments?` | [`IMailAttachment`](Interface.IMailAttachment)[] | - |
-
-#### Returns
-
-`Promise`\<`void`\>
-
-#### Overrides
-
-[`DeliveryStrategyBase`](Class.DeliveryStrategyBase).[`send`](Class.DeliveryStrategyBase#send)

package/src/knowledge/configPattern.d.ts

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

package/src/knowledge/dtoPattern.d.ts

@@ -1,5 +0,0 @@
-/**
- * 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/errorHandlingPattern.d.ts

@@ -1,5 +0,0 @@
-/**
- * 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";

package/src/knowledge/guardPattern.d.ts

@@ -1,5 +0,0 @@
-/**
- * Static knowledge content for the Archipel guard & interceptor pattern.
- * Returned by the get-guard-pattern tool.
- */
-export declare const GUARD_PATTERN_KNOWLEDGE = "# Archipel Guard & Interceptor Pattern\n\n## Overview\n\nArchipel uses a **metadata-driven** guard and interceptor pattern. A custom decorator\nattaches metadata (e.g., a feature key or role) to the handler. The guard reads this\nmetadata to decide access. An optional interceptor runs after the handler to record\nusage or perform side effects.\n\nThis creates a reusable trio: **Decorator \u2192 Guard \u2192 Interceptor**.\n\n## Guard Architecture\n\n```\n@RequiresFeature('create-posts')       \u2190 Decorator sets metadata\n@UseGuards(JwtAuthGuard, FeatureGuard) \u2190 Guard reads metadata, checks access\n@UseInterceptors(FeatureUsageInterceptor) \u2190 Interceptor records usage after success\n```\n\n## Available Guards\n\n| Guard | Strategy | Purpose |\n|-------|----------|---------|\n| `JwtAuthGuard` | jwt | Validates JWT bearer token |\n| `LocalAuthGuard` | local | Validates username + password |\n| `AnonymousAuthGuard` | anonymous | Allows unauthenticated access with a seed user |\n| `GithubAuthGuard` | github | OAuth via GitHub |\n| `RolesGuard` | metadata | Checks user roles against required roles |\n| `FeatureGuard` | metadata + port | Checks feature access via FeatureAccessPort |\n\n## The Feature Guard Pattern (Full Example)\n\n### Step 1: Metadata Decorator\n\n```typescript\nimport { SetMetadata } from '@nestjs/common';\n\nexport const FEATURE_KEY_METADATA = 'feature_key';\n\nexport const RequiresFeature = (featureKey: string) =>\n  SetMetadata(FEATURE_KEY_METADATA, featureKey);\n```\n\n### Step 2: Guard\n\n```typescript\nimport { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';\nimport { Reflector } from '@nestjs/core';\nimport { FeatureAccessPort } from '../contracts/FeatureAccessPort';\n\n@Injectable()\nexport class FeatureGuard implements CanActivate {\n\n  // #region Fields\n\n  private readonly _featureAccessPort: FeatureAccessPort;\n  private readonly _reflector: Reflector;\n\n  // #endregion\n\n  // #region Ctor\n\n  public constructor(featureAccessPort: FeatureAccessPort, reflector: Reflector) {\n    this._featureAccessPort = featureAccessPort;\n    this._reflector = reflector;\n  }\n\n  // #endregion\n\n  // #region Methods\n\n  public async canActivate(context: ExecutionContext): Promise<boolean> {\n    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());\n\n    if (!featureKey) {\n      return true; // No feature requirement on this endpoint\n    }\n\n    const request = context.switchToHttp().getRequest();\n    const user = request.user;\n\n    if (!user || !user.id) {\n      return false;\n    }\n\n    const access = await this._featureAccessPort.checkAccess(user.id, featureKey);\n    request.featureAccess = access; // Attach for downstream use\n\n    return access.allowed;\n  }\n\n  // #endregion\n\n}\n```\n\n### Step 3: Interceptor (records usage after success)\n\n```typescript\nimport { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';\nimport { Reflector } from '@nestjs/core';\nimport { Observable } from 'rxjs';\nimport { tap } from 'rxjs/operators';\n\n@Injectable()\nexport class FeatureUsageInterceptor implements NestInterceptor {\n\n  // #region Fields\n\n  private readonly _featureAccessPort: FeatureAccessPort;\n  private readonly _reflector: Reflector;\n\n  // #endregion\n\n  // #region Ctor\n\n  public constructor(featureAccessPort: FeatureAccessPort, reflector: Reflector) {\n    this._featureAccessPort = featureAccessPort;\n    this._reflector = reflector;\n  }\n\n  // #endregion\n\n  // #region Methods\n\n  public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {\n    const featureKey = this._reflector.get<string>(FEATURE_KEY_METADATA, context.getHandler());\n\n    if (!featureKey) {\n      return next.handle();\n    }\n\n    const request = context.switchToHttp().getRequest();\n    const user = request.user;\n\n    return next.handle().pipe(\n      tap(async () => {\n        if (user && user.id) {\n          await this._featureAccessPort.recordUsage(user.id, featureKey);\n        }\n      }),\n    );\n  }\n\n  // #endregion\n\n}\n```\n\n### Step 4: Controller Usage\n\n```typescript\n@Controller('/posts')\nexport class PostsController {\n\n  @Post()\n  @RequiresFeature('create-posts')\n  @UseGuards(JwtAuthGuard, FeatureGuard)\n  @UseInterceptors(FeatureUsageInterceptor)\n  public async createPost(@Body() body: CreatePostRequest): Promise<PostResponse> {\n    const entity = await this._postService.create(body);\n\n    return this._mappingService.map(POST_MAPPING_KEY, entity);\n  }\n\n}\n```\n\n## Roles Guard Pattern\n\n```typescript\n// Decorator\nexport const Roles = (...roles: string[]) => SetMetadata('roles', roles);\n\n// Guard\n@Injectable()\nexport class RolesGuard implements CanActivate {\n\n  public constructor(private readonly _reflector: Reflector) {}\n\n  public canActivate(context: ExecutionContext): boolean {\n    const requiredRoles = this._reflector.get<string[]>('roles', context.getHandler());\n    if (!requiredRoles) return true;\n\n    const request = context.switchToHttp().getRequest();\n    const user = request.user;\n\n    return requiredRoles.some((role) => user.roles?.includes(role));\n  }\n\n}\n\n// Usage\n@Get('/admin')\n@Roles('admin', 'superadmin')\n@UseGuards(JwtAuthGuard, RolesGuard)\npublic async getAdminPanel(): Promise<AdminResponse> { ... }\n```\n\n## Telemetry Interceptor\n\n```typescript\n@Injectable()\nexport class OperationTelemetryInterceptor implements NestInterceptor {\n\n  private readonly _facade: ITelemetryFacade;\n\n  public intercept(context: ExecutionContext, next: CallHandler): Observable<unknown> {\n    const handler = context.getHandler().name;\n    const cls = context.getClass().name;\n    // ... start span, capture duration, record outcome\n    return next.handle();\n  }\n\n}\n```\n\n## How to Create a Custom Guard + Interceptor Pair\n\n### Step 1: Define the metadata key and decorator\n\n```typescript\nexport const RATE_LIMIT_METADATA = 'rate_limit';\nexport const RateLimit = (maxRequests: number) => SetMetadata(RATE_LIMIT_METADATA, maxRequests);\n```\n\n### Step 2: Create the guard\n\nRead metadata via `Reflector`, check the condition, return boolean.\n\n### Step 3: Create the interceptor (optional)\n\nUse `tap()` in the RxJS pipeline to perform post-handler side effects.\n\n### Step 4: Register in the module\n\nExport guard and interceptor from the library module so consumers can apply them.\n\n## Rules\n\n1. **Guards decide access** \u2014 return `true` or `false`, never throw directly.\n2. **Interceptors handle side effects** \u2014 recording, logging, transforming responses.\n3. **Metadata decorators are the glue** \u2014 they attach config to handlers, read by guards/interceptors.\n4. **Auth guards extend Passport's AuthGuard** \u2014 e.g. `AuthGuard('jwt')`.\n5. **Feature guards delegate to ports** \u2014 the guard itself holds no business logic.\n6. **Guard order matters** \u2014 `@UseGuards(AuthGuard, FeatureGuard)`: auth runs first.\n7. **Interceptors use `tap()`** for post-handler logic, `map()` for response transformation.\n";

package/src/knowledge/mappingPattern.d.ts

@@ -1,6 +0,0 @@
-/**
- * Static knowledge content for the Archipel mapping pattern.
- * Returned by the get-mapping-pattern tool.
- */
-export declare const MAPPING_PATTERN_KNOWLEDGE = "# Archipel Mapping Pattern\n\n## Overview\n\nIn Archipel, all object-to-object mapping goes through a central **MappingService** with\n**branded, type-safe mapping keys**. This guarantees compile-time type safety: the key\nencodes both the input and output type, so calling `mappingService.map(KEY, input)` is\nstatically checked \u2014 the compiler verifies that `input` matches the key's input type and\ninfers the return type automatically.\n\n**Rule:** Services MUST NOT inline-create response objects. They return entities.\nControllers use the MappingService to convert entities to response DTOs.\n\n## Core Types\n\n### IMappingKey<TInput, TOutput>\n\n```typescript\nexport interface IMappingKey<TInput, TOutput> {\n  readonly _brand: 'MappingKey';\n  readonly _input: TInput;\n  readonly _output: TOutput;\n  readonly key: string;\n}\n```\n\nThe `_input` and `_output` fields are phantom types \u2014 they exist only for compile-time\ntype encoding and are never accessed at runtime.\n\n### createMappingKey<TInput, TOutput>\n\n```typescript\nimport { createMappingKey } from '@breadstone/archipel-platform-core';\n\nexport const PRODUCT_MAPPING_KEY = createMappingKey<IProductMappingInput, ProductResponse>('food.product');\n```\n\nThe string argument `'food.product'` is the unique registry key. Convention:\n`<domain>.<entity>` in lowercase dot-notation.\n\n## MappingService API\n\n```typescript\n// Key-based mapping (preferred)\nconst response = mappingService.map(PRODUCT_MAPPING_KEY, input);\n// \u2192 TOutput is inferred from the key, TInput is validated\n\n// Safe variant (returns undefined if not registered)\nconst maybeResponse = mappingService.tryMap(PRODUCT_MAPPING_KEY, input);\n\n// Type-based mapping (alternative)\nconst response = mappingService.mapTypes(sourceInstance, DestinationClass);\nconst responses = mappingService.mapTypesArray(sourceArray, DestinationClass);\n```\n\n## How to Create a Mapping\n\n### Step 1: Define the input interface\n\nThe input interface represents the shape of data coming from the repository query.\nProperty names MUST match the Prisma select shape exactly.\n\n```typescript\n// models/mapping-inputs/IProductMappingInput.ts\nexport interface IProductMappingInput {\n  readonly id: string;\n  readonly barcode: string;\n  readonly name: string;\n  readonly categoryId: string;\n  readonly createdAt: Date;\n}\n```\n\n### Step 2: Create a branded mapping key\n\nEach key is an **exported constant** \u2014 never inline magic strings.\n\n```typescript\n// constants/MappingKeys.ts\nimport { createMappingKey } from '@breadstone/archipel-platform-core';\nimport { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';\nimport { ProductResponse } from '../dtos/ProductResponse';\n\nexport const PRODUCT_MAPPING_KEY = createMappingKey<IProductMappingInput, ProductResponse>('food.product');\n```\n\n### Step 3: Create a mapping profile\n\nA profile extends `MappingProfileBase` and registers one or more mappings via the builder.\n\n```typescript\n// mappers/ProductMappingProfile.ts\nimport { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-core';\nimport { PRODUCT_MAPPING_KEY } from '../constants/MappingKeys';\nimport { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';\nimport { ProductResponse } from '../dtos/ProductResponse';\n\nexport class ProductMappingProfile extends MappingProfileBase {\n\n  // #region Methods\n\n  public configure(builder: IMappingBuilder): void {\n    builder.createKeyedMap(PRODUCT_MAPPING_KEY, (input: IProductMappingInput) => {\n      const response = new ProductResponse();\n      response.id = input.id;\n      response.barcode = input.barcode;\n      response.name = input.name;\n      response.categoryId = input.categoryId;\n      response.createdAt = input.createdAt;\n\n      return response;\n    });\n  }\n\n  // #endregion\n\n}\n```\n\n### Step 4: Register the profile in the module\n\n```typescript\nimport { MappingModule } from '@breadstone/archipel-platform-core';\nimport { ProductMappingProfile } from './mappers/ProductMappingProfile';\n\n@Module({\n  imports: [\n    MappingModule.withProfiles([ProductMappingProfile]),\n  ],\n})\nexport class ProductModule {}\n```\n\n### Step 5: Use in controller (NOT in service)\n\n```typescript\n@Controller('/products')\nexport class ProductController {\n\n  // #region Fields\n\n  private readonly _productService: ProductService;\n  private readonly _mappingService: MappingService;\n\n  // #endregion\n\n  // #region Ctor\n\n  public constructor(productService: ProductService, mappingService: MappingService) {\n    this._productService = productService;\n    this._mappingService = mappingService;\n  }\n\n  // #endregion\n\n  // #region Methods\n\n  @Get(':id')\n  public async getProduct(@Param('id') id: string): Promise<ProductResponse> {\n    const entity = await this._productService.findById(id);\n\n    return this._mappingService.map(PRODUCT_MAPPING_KEY, entity);\n  }\n\n  @Get()\n  public async listProducts(): Promise<ProductResponse[]> {\n    const entities = await this._productService.findAll();\n\n    return entities.map((e) => this._mappingService.map(PRODUCT_MAPPING_KEY, e));\n  }\n\n  // #endregion\n\n}\n```\n\n## MappingBuilder Methods\n\nThe builder supports two registration flavors:\n\n### createKeyedMap (preferred)\n\n```typescript\nbuilder.createKeyedMap(SOME_MAPPING_KEY, (input: TInput) => {\n  const output = new TOutput();\n  // ... map fields\n  return output;\n});\n```\n\n### createMap (type-based)\n\n```typescript\nbuilder.createMap(SourceClass, DestinationClass, (source: SourceClass) => {\n  const dest = new DestinationClass();\n  // ... map fields\n  return dest;\n});\n```\n\n## Error Handling\n\n- `MappingNotRegisteredError` \u2014 thrown when a keyed mapping is not found\n- `TypeMappingNotRegisteredError` \u2014 thrown when a type-based mapping is not found\n- Both extend `MappingError` with a machine-readable `code` field\n\n## Rules\n\n1. **Mapping keys MUST be exported constants** \u2014 never inline magic strings in services or controllers.\n2. **Services return entities, controllers map to responses** \u2014 services MUST NOT create response objects.\n3. **One mapping key per entity\u2192response pair** \u2014 use descriptive dot notation for the key string.\n4. **Input interfaces match Prisma select shape** \u2014 property names must align exactly.\n5. **Profiles extend MappingProfileBase** and are registered via `MappingModule.withProfiles()`.\n6. **Use `createKeyedMap` over `createMap`** \u2014 branded keys provide better type safety.\n7. **Mapping functions instantiate response classes** \u2014 use `new ResponseClass()` and assign fields.\n";
-export declare const MAPPING_PATTERN_WITH_CONTEXT: (entityName: string, fields: string[], responseName: string) => string;

package/src/knowledge/modulePattern.d.ts

@@ -1,6 +0,0 @@
-/**
- * Static knowledge content for the Archipel dynamic module pattern.
- * Returned by the get-module-pattern tool.
- */
-export declare const MODULE_PATTERN_KNOWLEDGE = "# Archipel Dynamic Module Pattern\n\n## Overview\n\nArchipel platform libraries use **NestJS dynamic modules** with a `register()` factory\nmethod and **port/adapter dependency inversion**. Each library defines abstract port\nclasses. The consuming application provides concrete implementations at registration time.\n\nThis pattern keeps platform libraries free of product-specific logic while allowing\nfull customization through dependency injection.\n\n## Pattern Structure\n\n### 1. Abstract Port (Contract)\n\n```typescript\n// contracts/FeatureAccessPort.ts\n\nexport abstract class FeatureAccessPort {\n\n  public abstract checkAccess(userId: string, featureKey: string): Promise<IFeatureAccessResult>;\n\n  public abstract recordUsage(userId: string, featureKey: string): Promise<void>;\n\n}\n```\n\nPorts are **abstract classes** (not interfaces) so they can serve as NestJS injection tokens.\n\n### 2. Options Interface\n\n```typescript\n// interfaces/IPaymentModuleOptions.ts\n\nexport interface IPaymentModuleOptions {\n  /**\n   * Concrete implementation of the FeatureAccessPort.\n   */\n  featureAccess?: Type<FeatureAccessPort>;\n\n  /**\n   * When true the module is registered globally.\n   */\n  isGlobal?: boolean;\n}\n```\n\n### 3. Dynamic Module with register()\n\n```typescript\n// PaymentModule.ts\nimport { ConfigModule } from '@breadstone/archipel-platform-core';\nimport { type DynamicModule, Module, type Type } from '@nestjs/common';\n\n@Module({})\nexport class PaymentModule {\n\n  public static register(options?: IPaymentModuleOptions): DynamicModule {\n    const providers = [StripeClient, FeatureGuard, FeatureUsageInterceptor];\n\n    if (options?.featureAccess) {\n      providers.push({\n        provide: FeatureAccessPort,\n        useClass: options.featureAccess,\n      } as never);\n    }\n\n    return {\n      global: options?.isGlobal ?? false,\n      module: PaymentModule,\n      imports: [ConfigModule.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES)],\n      providers: providers,\n      exports: [StripeClient, FeatureGuard, FeatureUsageInterceptor],\n    };\n  }\n\n}\n```\n\n### 4. Consumer Registration\n\n```typescript\n// In the consuming application:\n@Module({\n  imports: [\n    PaymentModule.register({\n      featureAccess: MyFeatureAccessAdapter,\n      isGlobal: true,\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n## Variants in the Codebase\n\n### Simple: PaymentModule\n\n- 1 optional port (`featureAccess`)\n- Optional `isGlobal` flag\n- Config via `ConfigModule.register()`\n\n### Complex: AuthModule\n\n- 4 required ports (`authSubject`, `mfaSubject`, `sessionPersistence`, `verificationSubject`)\n- 2 optional ports (`socialAuth`, `tokenEnricher`)\n- Conditional strategy registration (social OAuth only when `socialAuth` provided)\n- Imports: PassportModule, JwtModule, MappingModule, EventModule, IdentifierModule\n- Middleware configuration via `configure(consumer)`\n\n### Provider-based: BlobModule\n\n- Uses `forRoot()` instead of `register()` (global by default)\n- Discriminated union for provider selection: `{ kind: 'Vercel' }` or `{ kind: 'Custom', useClass: ... }`\n- Optional persistence ports (`objectPersistence`, `variantPersistence`)\n\n### Infrastructure: DatabaseModule\n\n- Both `forRoot()` (global) and `register()` (scoped) variants\n- Factory provider for PrismaService with extensions\n- Health indicator bootstrapping\n\n### Async: McpModule\n\n- `register(options)` for synchronous configuration\n- `registerAsync({ useFactory, inject })` for async (e.g., reading config at runtime)\n- `registerAsync({ useClass })` for factory class pattern\n- `registerAsync({ useExisting })` for reusing an existing factory\n\n## ConfigModule Integration\n\nEvery library module imports `ConfigModule.register()` to declare its configuration\ndependencies:\n\n```typescript\nimports: [ConfigModule.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES)]\n```\n\nThis registers typed config keys into the global `ConfigRegistry` for validation\nand discovery.\n\n## MappingModule Integration\n\nModules that need object mapping import `MappingModule.withProfiles()`:\n\n```typescript\nimports: [MappingModule.withProfiles([SessionMappingProfile])]\n```\n\n## Health Indicator Pattern\n\nInfrastructure modules (Database, Blob) register health indicators:\n\n```typescript\nproviders: [\n  BlobHealthIndicator,\n  {\n    provide: 'BLOB_HEALTH_INDICATOR_BOOTSTRAP',\n    useFactory: (orchestrator: HealthOrchestrator, indicator: BlobHealthIndicator) => {\n      orchestrator.registerIndicator(indicator);\n      return true;\n    },\n    inject: [HealthOrchestrator, BlobHealthIndicator],\n  },\n]\n```\n\n## Rules\n\n1. **Ports are abstract classes** \u2014 not interfaces \u2014 so they work as DI tokens.\n2. **`register()` for stateless config**, `registerAsync()` when config depends on runtime values.\n3. **`forRoot()` for global singletons** (database, blob storage), `register()` for scoped modules.\n4. **Always import ConfigModule.register()** to declare environment dependencies.\n5. **Optional ports use conditional provider registration** (`if (options?.port)`).\n6. **Required ports are listed in the options interface** without optional markers.\n7. **Exports should list concrete services, guards, interceptors** \u2014 not internal implementation details.\n";
-export declare const MODULE_PATTERN_WITH_CONTEXT: (moduleName: string, ports: string[]) => string;