@breadstone/archipel-mcp 0.0.21 → 0.0.22

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.

package/data/patterns/query-pattern.md

@@ -0,0 +1,137 @@
+---
+title: Query Pattern
+description: Repository + Query pattern with IRepositoryQuery, factory functions, transactional queries, and rules.
+order: 7
+---
+
+# Archipel Query Pattern (v1)
+
+## Overview
+
+In Archipel, data access follows the **Repository + Query** pattern. Repositories never expose
+raw Prisma delegate methods to services. Instead, every data operation is wrapped in a
+**query factory function** that returns an `IRepositoryQuery` object. Services call
+`repository.execute(someQuery(...))` — never `repository.findFirst(...)` directly.
+
+## Core Interface
+
+```typescript
+export interface IRepositoryQuery<TDelegate, TResult> {
+  readonly name: string;
+  run(model: TDelegate): Promise<TResult>;
+}
+```
+
+- `TDelegate` — the Prisma delegate type (e.g. `Prisma.UserDelegate`)
+- `TResult` — the query's return type
+- `name` — identifier used for logging and debugging
+
+## Factory Function
+
+```typescript
+import { IRepositoryQuery } from '@breadstone/archipel-platform-database';
+
+export function query<TDelegate, TResult>(
+  name: string,
+  run: (model: TDelegate) => Promise<TResult>,
+): IRepositoryQuery<TDelegate, TResult> {
+  return { name, run };
+}
+```
+
+## Type Extraction
+
+```typescript
+export type QueryResultType<T> = T extends IRepositoryQuery<unknown, infer R> ? R : never;
+```
+
+Use this to derive the result type from a query factory without duplicating types:
+```typescript
+type UserProfileResult = QueryResultType<ReturnType<typeof findUserProfileQuery>>;
+```
+
+## How to Write a Query
+
+### Step 1: Define the query factory function
+
+Each query is a **named function** that returns an `IRepositoryQuery`. The function may accept
+parameters — these become the query's runtime arguments.
+
+```typescript
+import { Prisma } from '@prisma/client';
+import { query } from '@breadstone/archipel-platform-database';
+
+export function findUserByEmailQuery(email: string) {
+  return query<Prisma.UserDelegate, { id: string; email: string; name: string } | null>(
+    'findUserByEmail',
+    (model) =>
+      model.findFirst({
+        where: { email },
+        select: { id: true, email: true, name: true },
+      }),
+  );
+}
+```
+
+### Step 2: Call from a service via repository.execute()
+
+```typescript
+// In the service:
+const user = await this._userRepository.execute(findUserByEmailQuery(email));
+```
+
+### Step 3: Extract result type if needed for mapping
+
+```typescript
+type FindUserByEmailResult = QueryResultType<ReturnType<typeof findUserByEmailQuery>>;
+```
+
+## Transactional Queries
+
+For operations that span multiple models, use `transactionalQuery`:
+
+```typescript
+import { Prisma } from '@prisma/client';
+import { transactionalQuery } from '@breadstone/archipel-platform-database';
+
+export function createOrderWithItemsQuery(data: { userId: string; items: Array<{ productId: string; quantity: number }> }) {
+  return transactionalQuery<{ orderId: string }>(
+    'createOrderWithItems',
+    async (tx: Prisma.TransactionClient) => {
+      const order = await tx.order.create({
+        data: { userId: data.userId },
+        select: { id: true },
+      });
+
+      await tx.orderItem.createMany({
+        data: data.items.map((item) => ({
+          orderId: order.id,
+          productId: item.productId,
+          quantity: item.quantity,
+        })),
+      });
+
+      return { orderId: order.id };
+    },
+  );
+}
+```
+
+Called via:
+```typescript
+const result = await this._orderRepository.executeTransactional(
+  createOrderWithItemsQuery({ userId, items }),
+);
+```
+
+## Rules
+
+1. **Never call Prisma delegate methods directly from services.** Always go through `execute(query)`.
+2. **Always select only the fields you need.** Use `select` — never return full records.
+3. **Query names must be descriptive.** Use the pattern: `verbModelByConditionQuery`
+   (e.g. `findUserByEmailQuery`, `countOrdersByStatusQuery`, `updateUserNameQuery`).
+4. **One query per file** for non-trivial queries. Small related queries may share a file.
+5. **Type the result explicitly.** The second generic parameter of `query()` should be an inline
+   object type or a dedicated interface matching the `select` shape.
+6. **Each query factory is a standalone function** (not a class method). Import `query` from
+   `@breadstone/archipel-platform-database`.