@breadstone/archipel-mcp 0.0.1

package/src/knowledge/mappingPattern.js

@@ -0,0 +1,322 @@
+"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
+
+## 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
+infers the return type automatically.
+
+**Rule:** Services MUST NOT inline-create response objects. They return entities.
+Controllers use the MappingService to convert entities to response DTOs.
+
+## Core Types
+
+### IMappingKey<TInput, TOutput>
+
+\`\`\`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
+type encoding and are never accessed at runtime.
+
+### createMappingKey<TInput, TOutput>
+
+\`\`\`typescript
+import { createMappingKey } from '@breadstone/archipel-platform-core';
+
+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.
+
+## MappingService API
+
+\`\`\`typescript
+// Key-based mapping (preferred)
+const response = mappingService.map(PRODUCT_MAPPING_KEY, input);
+// → TOutput is inferred from the key, TInput is validated
+
+// Safe variant (returns undefined if not registered)
+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
+
+### Step 1: Define the input interface
+
+The input interface represents the shape of data coming from the repository query.
+Property names MUST match the Prisma select shape exactly.
+
+\`\`\`typescript
+// models/mapping-inputs/IProductMappingInput.ts
+export interface IProductMappingInput {
+  readonly id: string;
+  readonly barcode: string;
+  readonly name: string;
+  readonly categoryId: string;
+  readonly createdAt: Date;
+}
+\`\`\`
+
+### Step 2: Create a branded mapping key
+
+Each key is an **exported constant** — never inline magic strings.
+
+\`\`\`typescript
+// constants/MappingKeys.ts
+import { createMappingKey } from '@breadstone/archipel-platform-core';
+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.
+
+\`\`\`typescript
+// mappers/ProductMappingProfile.ts
+import { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-core';
+import { PRODUCT_MAPPING_KEY } from '../constants/MappingKeys';
+import { IProductMappingInput } from '../models/mapping-inputs/IProductMappingInput';
+import { ProductResponse } from '../dtos/ProductResponse';
+
+export class ProductMappingProfile extends MappingProfileBase {
+
+  // #region Methods
+
+  public configure(builder: IMappingBuilder): void {
+    builder.createKeyedMap(PRODUCT_MAPPING_KEY, (input: IProductMappingInput) => {
+      const response = new ProductResponse();
+      response.id = input.id;
+      response.barcode = input.barcode;
+      response.name = input.name;
+      response.categoryId = input.categoryId;
+      response.createdAt = input.createdAt;
+
+      return response;
+    });
+  }
+
+  // #endregion
+
+}
+\`\`\`
+
+### Step 4: Register the profile in the module
+
+\`\`\`typescript
+import { MappingModule } from '@breadstone/archipel-platform-core';
+import { ProductMappingProfile } from './mappers/ProductMappingProfile';
+
+@Module({
+  imports: [
+    MappingModule.withProfiles([ProductMappingProfile]),
+  ],
+})
+export class ProductModule {}
+\`\`\`
+
+### Step 5: Use in controller (NOT in service)
+
+\`\`\`typescript
+@Controller('/products')
+export class ProductController {
+
+  // #region Fields
+
+  private readonly _productService: ProductService;
+  private readonly _mappingService: MappingService;
+
+  // #endregion
+
+  // #region Ctor
+
+  public constructor(productService: ProductService, mappingService: MappingService) {
+    this._productService = productService;
+    this._mappingService = mappingService;
+  }
+
+  // #endregion
+
+  // #region Methods
+
+  @Get(':id')
+  public async getProduct(@Param('id') id: string): Promise<ProductResponse> {
+    const entity = await this._productService.findById(id);
+
+    return this._mappingService.map(PRODUCT_MAPPING_KEY, entity);
+  }
+
+  @Get()
+  public async listProducts(): Promise<ProductResponse[]> {
+    const entities = await this._productService.findAll();
+
+    return entities.map((e) => this._mappingService.map(PRODUCT_MAPPING_KEY, e));
+  }
+
+  // #endregion
+
+}
+\`\`\`
+
+## MappingBuilder Methods
+
+The builder supports two registration flavors:
+
+### createKeyedMap (preferred)
+
+\`\`\`typescript
+builder.createKeyedMap(SOME_MAPPING_KEY, (input: TInput) => {
+  const output = new TOutput();
+  // ... map fields
+  return output;
+});
+\`\`\`
+
+### createMap (type-based)
+
+\`\`\`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
+
+## Rules
+
+1. **Mapping keys MUST be exported constants** — never inline magic strings in services or controllers.
+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

package/src/knowledge/modulePattern.d.ts

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

package/src/knowledge/modulePattern.js

@@ -0,0 +1,283 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel dynamic module pattern.
+ * Returned by the get-module-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_PATTERN_WITH_CONTEXT = exports.MODULE_PATTERN_KNOWLEDGE = void 0;
+exports.MODULE_PATTERN_KNOWLEDGE = `# 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.
+`;
+const MODULE_PATTERN_WITH_CONTEXT = (moduleName, ports) => `
+## Example: Dynamic Module "${moduleName}"
+
+With ports: ${ports.map((p) => `\`${p}\``).join(', ')}
+
+### Port Definitions
+
+${ports
+    .map((port) => `\`\`\`typescript
+// contracts/${port}.ts
+
+export abstract class ${port} {
+
+  // Define abstract methods for the port contract
+  public abstract execute(/* args */): Promise<void>;
+
+}
+\`\`\``)
+    .join('\n\n')}
+
+### Options Interface
+
+\`\`\`typescript
+// interfaces/I${moduleName}Options.ts
+import { Type } from '@nestjs/common';
+${ports.map((port) => `import { ${port} } from '../contracts/${port}';`).join('\n')}
+
+export interface I${moduleName}Options {
+${ports.map((port) => `  ${lowerFirstChar(port)}: Type<${port}>;`).join('\n')}
+  isGlobal?: boolean;
+}
+\`\`\`
+
+### Module Class
+
+\`\`\`typescript
+// ${moduleName}.ts
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { type DynamicModule, Module, type Type } from '@nestjs/common';
+import { I${moduleName}Options } from './interfaces/I${moduleName}Options';
+${ports.map((port) => `import { ${port} } from './contracts/${port}';`).join('\n')}
+
+@Module({})
+export class ${moduleName} {
+
+  public static register(options: I${moduleName}Options): DynamicModule {
+    const portProviders = [
+${ports.map((port) => `      { provide: ${port}, useClass: options.${lowerFirstChar(port)} },`).join('\n')}
+    ];
+
+    return {
+      global: options.isGlobal ?? false,
+      module: ${moduleName},
+      imports: [
+        ConfigModule.register('${toKebabCase(moduleName)}', PLATFORM_${toUpperSnakeCase(moduleName)}_CONFIG_ENTRIES),
+      ],
+      providers: [
+        ...portProviders,
+        // Add services, guards, interceptors here
+      ],
+      exports: [
+        // Export public services, guards, interceptors
+      ],
+    };
+  }
+
+}
+\`\`\`
+
+### Consumer Usage
+
+\`\`\`typescript
+@Module({
+  imports: [
+    ${moduleName}.register({
+${ports.map((port) => `      ${lowerFirstChar(port)}: My${port}Adapter,`).join('\n')}
+    }),
+  ],
+})
+export class AppModule {}
+\`\`\`
+`;
+exports.MODULE_PATTERN_WITH_CONTEXT = MODULE_PATTERN_WITH_CONTEXT;
+function lowerFirstChar(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+function toKebabCase(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/module$/, '');
+}
+function toUpperSnakeCase(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, '$1_$2')
+        .toUpperCase()
+        .replace(/MODULE$/, '');
+}
+//# sourceMappingURL=modulePattern.js.map

package/src/knowledge/queryPattern.d.ts

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