@breadstone/archipel-mcp 0.0.20 → 0.0.22

package/{src/knowledge/guardPattern.js → data/patterns/guard-pattern.md}

@@ -1,11 +1,10 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel guard & interceptor pattern.
- * Returned by the get-guard-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.GUARD_PATTERN_KNOWLEDGE = void 0;
-exports.GUARD_PATTERN_KNOWLEDGE = `# Archipel Guard & Interceptor Pattern
+---
+title: Guard & Interceptor Pattern
+description: Metadata decorators, FeatureGuard, RolesGuard, FeatureUsageInterceptor, and the full decorator-guard-interceptor trio.
+order: 4
+---
+
+# Archipel Guard & Interceptor Pattern
 
 ## Overview
 
@@ -18,39 +17,39 @@ This creates a reusable trio: **Decorator → Guard → Interceptor**.
 
 ## Guard Architecture
 
-\`\`\`
+```
 @RequiresFeature('create-posts')       ← Decorator sets metadata
 @UseGuards(JwtAuthGuard, FeatureGuard) ← Guard reads metadata, checks access
 @UseInterceptors(FeatureUsageInterceptor) ← Interceptor records usage after success
-\`\`\`
+```
 
 ## Available Guards
 
 | Guard | Strategy | Purpose |
 |-------|----------|---------|
-| \`JwtAuthGuard\` | jwt | Validates JWT bearer token |
-| \`LocalAuthGuard\` | local | Validates username + password |
-| \`AnonymousAuthGuard\` | anonymous | Allows unauthenticated access with a seed user |
-| \`GithubAuthGuard\` | github | OAuth via GitHub |
-| \`RolesGuard\` | metadata | Checks user roles against required roles |
-| \`FeatureGuard\` | metadata + port | Checks feature access via FeatureAccessPort |
+| `JwtAuthGuard` | jwt | Validates JWT bearer token |
+| `LocalAuthGuard` | local | Validates username + password |
+| `AnonymousAuthGuard` | anonymous | Allows unauthenticated access with a seed user |
+| `GithubAuthGuard` | github | OAuth via GitHub |
+| `RolesGuard` | metadata | Checks user roles against required roles |
+| `FeatureGuard` | metadata + port | Checks feature access via FeatureAccessPort |
 
 ## The Feature Guard Pattern (Full Example)
 
 ### Step 1: Metadata Decorator
 
-\`\`\`typescript
+```typescript
 import { SetMetadata } from '@nestjs/common';
 
 export const FEATURE_KEY_METADATA = 'feature_key';
 
 export const RequiresFeature = (featureKey: string) =>
   SetMetadata(FEATURE_KEY_METADATA, featureKey);
-\`\`\`
+```
 
 ### Step 2: Guard
 
-\`\`\`typescript
+```typescript
 import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { FeatureAccessPort } from '../contracts/FeatureAccessPort';
@@ -99,11 +98,11 @@ export class FeatureGuard implements CanActivate {
   // #endregion
 
 }
-\`\`\`
+```
 
 ### Step 3: Interceptor (records usage after success)
 
-\`\`\`typescript
+```typescript
 import { CallHandler, ExecutionContext, Injectable, NestInterceptor } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { Observable } from 'rxjs';
@@ -152,11 +151,11 @@ export class FeatureUsageInterceptor implements NestInterceptor {
   // #endregion
 
 }
-\`\`\`
+```
 
 ### Step 4: Controller Usage
 
-\`\`\`typescript
+```typescript
 @Controller('/posts')
 export class PostsController {
 
@@ -171,11 +170,11 @@ export class PostsController {
   }
 
 }
-\`\`\`
+```
 
 ## Roles Guard Pattern
 
-\`\`\`typescript
+```typescript
 // Decorator
 export const Roles = (...roles: string[]) => SetMetadata('roles', roles);
 
@@ -202,11 +201,11 @@ export class RolesGuard implements CanActivate {
 @Roles('admin', 'superadmin')
 @UseGuards(JwtAuthGuard, RolesGuard)
 public async getAdminPanel(): Promise<AdminResponse> { ... }
-\`\`\`
+```
 
 ## Telemetry Interceptor
 
-\`\`\`typescript
+```typescript
 @Injectable()
 export class OperationTelemetryInterceptor implements NestInterceptor {
 
@@ -220,24 +219,24 @@ export class OperationTelemetryInterceptor implements NestInterceptor {
   }
 
 }
-\`\`\`
+```
 
 ## How to Create a Custom Guard + Interceptor Pair
 
 ### Step 1: Define the metadata key and decorator
 
-\`\`\`typescript
+```typescript
 export const RATE_LIMIT_METADATA = 'rate_limit';
 export const RateLimit = (maxRequests: number) => SetMetadata(RATE_LIMIT_METADATA, maxRequests);
-\`\`\`
+```
 
 ### Step 2: Create the guard
 
-Read metadata via \`Reflector\`, check the condition, return boolean.
+Read metadata via `Reflector`, check the condition, return boolean.
 
 ### Step 3: Create the interceptor (optional)
 
-Use \`tap()\` in the RxJS pipeline to perform post-handler side effects.
+Use `tap()` in the RxJS pipeline to perform post-handler side effects.
 
 ### Step 4: Register in the module
 
@@ -245,12 +244,10 @@ Export guard and interceptor from the library module so consumers can apply them
 
 ## Rules
 
-1. **Guards decide access** — return \`true\` or \`false\`, never throw directly.
+1. **Guards decide access** — return `true` or `false`, never throw directly.
 2. **Interceptors handle side effects** — recording, logging, transforming responses.
 3. **Metadata decorators are the glue** — they attach config to handlers, read by guards/interceptors.
-4. **Auth guards extend Passport's AuthGuard** — e.g. \`AuthGuard('jwt')\`.
+4. **Auth guards extend Passport's AuthGuard** — e.g. `AuthGuard('jwt')`.
 5. **Feature guards delegate to ports** — the guard itself holds no business logic.
-6. **Guard order matters** — \`@UseGuards(AuthGuard, FeatureGuard)\`: auth runs first.
-7. **Interceptors use \`tap()\`** for post-handler logic, \`map()\` for response transformation.
-`;
-//# sourceMappingURL=guardPattern.js.map
+6. **Guard order matters** — `@UseGuards(AuthGuard, FeatureGuard)`: auth runs first.
+7. **Interceptors use `tap()`** for post-handler logic, `map()` for response transformation.

package/{src/knowledge/mappingPattern.js → data/patterns/mapping-pattern.md}

@@ -1,18 +1,17 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel mapping pattern.
- * Returned by the get-mapping-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAPPING_PATTERN_WITH_CONTEXT = exports.MAPPING_PATTERN_KNOWLEDGE = void 0;
-exports.MAPPING_PATTERN_KNOWLEDGE = `# Archipel Mapping Pattern
+---
+title: Mapping Pattern
+description: Branded type-safe mapping keys, MappingProfileBase, MappingService, and MappingModule registration.
+order: 5
+---
+
+# Archipel Mapping Pattern
 
 ## Overview
 
 In Archipel, all object-to-object mapping goes through a central **MappingService** with
 **branded, type-safe mapping keys**. This guarantees compile-time type safety: the key
-encodes both the input and output type, so calling \`mappingService.map(KEY, input)\` is
-statically checked — the compiler verifies that \`input\` matches the key's input type and
+encodes both the input and output type, so calling `mappingService.map(KEY, input)` is
+statically checked — the compiler verifies that `input` matches the key's input type and
 infers the return type automatically.
 
 **Rule:** Services MUST NOT inline-create response objects. They return entities.
@@ -22,32 +21,32 @@ Controllers use the MappingService to convert entities to response DTOs.
 
 ### IMappingKey<TInput, TOutput>
 
-\`\`\`typescript
+```typescript
 export interface IMappingKey<TInput, TOutput> {
   readonly _brand: 'MappingKey';
   readonly _input: TInput;
   readonly _output: TOutput;
   readonly key: string;
 }
-\`\`\`
+```
 
-The \`_input\` and \`_output\` fields are phantom types — they exist only for compile-time
+The `_input` and `_output` fields are phantom types — they exist only for compile-time
 type encoding and are never accessed at runtime.
 
 ### createMappingKey<TInput, TOutput>
 
-\`\`\`typescript
-import { createMappingKey } from '@breadstone/archipel-platform-core';
+```typescript
+import { createMappingKey } from '@breadstone/archipel-platform-mapping';
 
 export const PRODUCT_MAPPING_KEY = createMappingKey<IProductMappingInput, ProductResponse>('food.product');
-\`\`\`
+```
 
-The string argument \`'food.product'\` is the unique registry key. Convention:
-\`<domain>.<entity>\` in lowercase dot-notation.
+The string argument `'food.product'` is the unique registry key. Convention:
+`<domain>.<entity>` in lowercase dot-notation.
 
 ## MappingService API
 
-\`\`\`typescript
+```typescript
 // Key-based mapping (preferred)
 const response = mappingService.map(PRODUCT_MAPPING_KEY, input);
 // → TOutput is inferred from the key, TInput is validated
@@ -58,7 +57,7 @@ const maybeResponse = mappingService.tryMap(PRODUCT_MAPPING_KEY, input);
 // Type-based mapping (alternative)
 const response = mappingService.mapTypes(sourceInstance, DestinationClass);
 const responses = mappingService.mapTypesArray(sourceArray, DestinationClass);
-\`\`\`
+```
 
 ## How to Create a Mapping
 
@@ -67,7 +66,7 @@ const responses = mappingService.mapTypesArray(sourceArray, DestinationClass);
 The input interface represents the shape of data coming from the repository query.
 Property names MUST match the Prisma select shape exactly.
 
-\`\`\`typescript
+```typescript
 // models/mapping-inputs/IProductMappingInput.ts
 export interface IProductMappingInput {
   readonly id: string;
@@ -76,28 +75,28 @@ export interface IProductMappingInput {
   readonly categoryId: string;
   readonly createdAt: Date;
 }
-\`\`\`
+```
 
 ### Step 2: Create a branded mapping key
 
 Each key is an **exported constant** — never inline magic strings.
 
-\`\`\`typescript
+```typescript
 // constants/MappingKeys.ts
-import { createMappingKey } from '@breadstone/archipel-platform-core';
+import { createMappingKey } from '@breadstone/archipel-platform-mapping';
 import { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';
 import { ProductResponse } from '../dtos/ProductResponse';
 
 export const PRODUCT_MAPPING_KEY = createMappingKey<IProductMappingInput, ProductResponse>('food.product');
-\`\`\`
+```
 
 ### Step 3: Create a mapping profile
 
-A profile extends \`MappingProfileBase\` and registers one or more mappings via the builder.
+A profile extends `MappingProfileBase` and registers one or more mappings via the builder.
 
-\`\`\`typescript
+```typescript
 // mappers/ProductMappingProfile.ts
-import { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-core';
+import { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-mapping';
 import { PRODUCT_MAPPING_KEY } from '../constants/MappingKeys';
 import { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';
 import { ProductResponse } from '../dtos/ProductResponse';
@@ -122,12 +121,12 @@ export class ProductMappingProfile extends MappingProfileBase {
   // #endregion
 
 }
-\`\`\`
+```
 
 ### Step 4: Register the profile in the module
 
-\`\`\`typescript
-import { MappingModule } from '@breadstone/archipel-platform-core';
+```typescript
+import { MappingModule } from '@breadstone/archipel-platform-mapping';
 import { ProductMappingProfile } from './mappers/ProductMappingProfile';
 
 @Module({
@@ -136,11 +135,11 @@ import { ProductMappingProfile } from './mappers/ProductMappingProfile';
   ],
 })
 export class ProductModule {}
-\`\`\`
+```
 
 ### Step 5: Use in controller (NOT in service)
 
-\`\`\`typescript
+```typescript
 @Controller('/products')
 export class ProductController {
 
@@ -179,7 +178,7 @@ export class ProductController {
   // #endregion
 
 }
-\`\`\`
+```
 
 ## MappingBuilder Methods
 
@@ -187,29 +186,29 @@ The builder supports two registration flavors:
 
 ### createKeyedMap (preferred)
 
-\`\`\`typescript
+```typescript
 builder.createKeyedMap(SOME_MAPPING_KEY, (input: TInput) => {
   const output = new TOutput();
   // ... map fields
   return output;
 });
-\`\`\`
+```
 
 ### createMap (type-based)
 
-\`\`\`typescript
+```typescript
 builder.createMap(SourceClass, DestinationClass, (source: SourceClass) => {
   const dest = new DestinationClass();
   // ... map fields
   return dest;
 });
-\`\`\`
+```
 
 ## Error Handling
 
-- \`MappingNotRegisteredError\` — thrown when a keyed mapping is not found
-- \`TypeMappingNotRegisteredError\` — thrown when a type-based mapping is not found
-- Both extend \`MappingError\` with a machine-readable \`code\` field
+- `MappingNotRegisteredError` — thrown when a keyed mapping is not found
+- `TypeMappingNotRegisteredError` — thrown when a type-based mapping is not found
+- Both extend `MappingError` with a machine-readable `code` field
 
 ## Rules
 
@@ -217,106 +216,6 @@ builder.createMap(SourceClass, DestinationClass, (source: SourceClass) => {
 2. **Services return entities, controllers map to responses** — services MUST NOT create response objects.
 3. **One mapping key per entity→response pair** — use descriptive dot notation for the key string.
 4. **Input interfaces match Prisma select shape** — property names must align exactly.
-5. **Profiles extend MappingProfileBase** and are registered via \`MappingModule.withProfiles()\`.
-6. **Use \`createKeyedMap\` over \`createMap\`** — branded keys provide better type safety.
-7. **Mapping functions instantiate response classes** — use \`new ResponseClass()\` and assign fields.
-`;
-const MAPPING_PATTERN_WITH_CONTEXT = (entityName, fields, responseName) => `
-## Example: Mapping for "${entityName}" → "${responseName}"
-
-Given an entity \`${entityName}\` with fields: ${fields.map((f) => `\`${f}\``).join(', ')}
-
-### 1. Input Interface
-
-\`\`\`typescript
-// models/mapping-inputs/I${entityName}MappingInput.ts
-
-export interface I${entityName}MappingInput {
-${fields.map((f) => `  readonly ${f}: ${inferMappingFieldType(f)};`).join('\n')}
-}
-\`\`\`
-
-### 2. Mapping Key
-
-\`\`\`typescript
-// constants/MappingKeys.ts
-import { createMappingKey } from '@breadstone/archipel-platform-core';
-import { I${entityName}MappingInput } from '../models/mapping-inputs/I${entityName}MappingInput';
-import { ${responseName} } from '../dtos/${responseName}';
-
-export const ${toConstantCase(entityName)}_MAPPING_KEY = createMappingKey<I${entityName}MappingInput, ${responseName}>('${toDotNotation(entityName)}');
-\`\`\`
-
-### 3. Mapping Profile
-
-\`\`\`typescript
-// mappers/${entityName}MappingProfile.ts
-import { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-core';
-import { ${toConstantCase(entityName)}_MAPPING_KEY } from '../constants/MappingKeys';
-import { I${entityName}MappingInput } from '../models/mapping-inputs/I${entityName}MappingInput';
-import { ${responseName} } from '../dtos/${responseName}';
-
-export class ${entityName}MappingProfile extends MappingProfileBase {
-
-  // #region Methods
-
-  public configure(builder: IMappingBuilder): void {
-    builder.createKeyedMap(${toConstantCase(entityName)}_MAPPING_KEY, (input: I${entityName}MappingInput) => {
-      const response = new ${responseName}();
-${fields.map((f) => `      response.${f} = input.${f};`).join('\n')}
-
-      return response;
-    });
-  }
-
-  // #endregion
-
-}
-\`\`\`
-
-### 4. Module Registration
-
-\`\`\`typescript
-import { MappingModule } from '@breadstone/archipel-platform-core';
-import { ${entityName}MappingProfile } from './mappers/${entityName}MappingProfile';
-
-@Module({
-  imports: [
-    MappingModule.withProfiles([${entityName}MappingProfile]),
-  ],
-})
-export class ${entityName}Module {}
-\`\`\`
-
-### 5. Controller Usage
-
-\`\`\`typescript
-// In a controller method:
-const entity = await this._${lowerFirst(entityName)}Service.findById(id);
-const response = this._mappingService.map(${toConstantCase(entityName)}_MAPPING_KEY, entity);
-\`\`\`
-`;
-exports.MAPPING_PATTERN_WITH_CONTEXT = MAPPING_PATTERN_WITH_CONTEXT;
-function inferMappingFieldType(fieldName) {
-    if (fieldName === 'id')
-        return 'string';
-    if (fieldName.endsWith('Id'))
-        return 'string';
-    if (fieldName.endsWith('At') || fieldName === 'createdAt' || fieldName === 'updatedAt')
-        return 'Date';
-    if (fieldName.startsWith('is') || fieldName.startsWith('has'))
-        return 'boolean';
-    if (fieldName === 'count' || fieldName === 'quantity' || fieldName === 'amount' || fieldName === 'price')
-        return 'number';
-    return 'string';
-}
-function toConstantCase(name) {
-    return name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase();
-}
-function toDotNotation(name) {
-    return name.replace(/([a-z])([A-Z])/g, '$1.$2').toLowerCase();
-}
-function lowerFirst(str) {
-    return str.charAt(0).toLowerCase() + str.slice(1);
-}
-//# sourceMappingURL=mappingPattern.js.map
+5. **Profiles extend MappingProfileBase** and are registered via `MappingModule.withProfiles()`.
+6. **Use `createKeyedMap` over `createMap`** — branded keys provide better type safety.
+7. **Mapping functions instantiate response classes** — use `new ResponseClass()` and assign fields.

package/data/patterns/module-pattern.md

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