@breadstone/archipel-mcp 0.0.21 → 0.0.23

package/{src/knowledge/errorHandlingPattern.js → data/patterns/error-handling-pattern.md}

@@ -1,11 +1,10 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel error handling pattern.
- * Returned by the get-error-handling-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ERROR_HANDLING_PATTERN_KNOWLEDGE = void 0;
-exports.ERROR_HANDLING_PATTERN_KNOWLEDGE = `# Archipel Error Handling Pattern
+---
+title: Error Handling Pattern
+description: Domain errors, RepositoryError, exception filters, and structured error response envelopes.
+order: 3
+---
+
+# Archipel Error Handling Pattern
 
 ## Overview
 
@@ -15,17 +14,17 @@ the HTTP translation. This keeps business logic clean and error responses consis
 
 ## Layer Architecture
 
-\`\`\`
+```
 Service → throws DomainError → ExceptionFilter → HTTP Response Envelope
-\`\`\`
+```
 
 ## Base Error Classes
 
 ### RepositoryError
 
-Thrown when any Prisma operation fails. Automatically wrapped by \`RepositoryBase.tryCatch()\`.
+Thrown when any Prisma operation fails. Automatically wrapped by `RepositoryBase.tryCatch()`.
 
-\`\`\`typescript
+```typescript
 // models/errors/RepositoryError.ts
 export class RepositoryError extends Error {
 
@@ -46,13 +45,13 @@ export class RepositoryError extends Error {
   }
 
 }
-\`\`\`
+```
 
 ### MappingError (abstract)
 
 Base for mapping-related errors.
 
-\`\`\`typescript
+```typescript
 export abstract class MappingError extends Error {
   public readonly code: string;
 
@@ -61,17 +60,17 @@ export abstract class MappingError extends Error {
     this.code = code;
   }
 }
-\`\`\`
+```
 
 Concrete variants:
-- \`MappingNotRegisteredError\` — code: \`'MAPPING_NOT_REGISTERED'\`
-- \`TypeMappingNotRegisteredError\` — code: \`'TYPE_MAPPING_NOT_REGISTERED'\`
+- `MappingNotRegisteredError` — code: `'MAPPING_NOT_REGISTERED'`
+- `TypeMappingNotRegisteredError` — code: `'TYPE_MAPPING_NOT_REGISTERED'`
 
 ## Exception Filters
 
 ### RepositoryExceptionFilter
 
-\`\`\`typescript
+```typescript
 import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
 import { Request, Response } from 'express';
 import { RepositoryError } from '../models/errors/RepositoryError';
@@ -93,19 +92,19 @@ export class RepositoryExceptionFilter implements ExceptionFilter<RepositoryErro
   }
 
 }
-\`\`\`
+```
 
 ### Registration (in main.ts or AppModule)
 
-\`\`\`typescript
+```typescript
 app.useGlobalFilters(new RepositoryExceptionFilter());
-\`\`\`
+```
 
 ## How to Create a Domain Error
 
 ### Step 1: Define the error class
 
-\`\`\`typescript
+```typescript
 // models/errors/UserNotFoundError.ts
 export class UserNotFoundError extends Error {
 
@@ -113,7 +112,7 @@ export class UserNotFoundError extends Error {
   public readonly userId: string;
 
   public constructor(userId: string) {
-    super(\\\`User not found: \\\${userId}\\\`);
+    super(`User not found: ${userId}`);
     Object.setPrototypeOf(this, UserNotFoundError.prototype);
     this.name = 'UserNotFoundError';
     this.userId = userId;
@@ -124,11 +123,11 @@ export class UserNotFoundError extends Error {
   }
 
 }
-\`\`\`
+```
 
 ### Step 2: Create an exception filter
 
-\`\`\`typescript
+```typescript
 // filters/UserNotFoundExceptionFilter.ts
 import { ArgumentsHost, Catch, ExceptionFilter, HttpStatus } from '@nestjs/common';
 import { Request, Response } from 'express';
@@ -152,20 +151,20 @@ export class UserNotFoundExceptionFilter implements ExceptionFilter<UserNotFound
   }
 
 }
-\`\`\`
+```
 
 ### Step 3: Register the filter globally
 
-\`\`\`typescript
+```typescript
 app.useGlobalFilters(
   new RepositoryExceptionFilter(),
   new UserNotFoundExceptionFilter(),
 );
-\`\`\`
+```
 
 ### Step 4: Throw from a service
 
-\`\`\`typescript
+```typescript
 @Injectable()
 export class UserService {
 
@@ -180,13 +179,13 @@ export class UserService {
   }
 
 }
-\`\`\`
+```
 
 ## Response Envelope Convention
 
 All error responses follow the same shape:
 
-\`\`\`json
+```json
 {
   "statusCode": 404,
   "timestamp": "2026-04-05T12:00:00.000Z",
@@ -194,11 +193,11 @@ All error responses follow the same shape:
   "message": "User not found: abc-123",
   "path": "/api/v1/users/abc-123"
 }
-\`\`\`
+```
 
 ## Prisma Error Code Reference
 
-Common Prisma error codes wrapped by \`RepositoryError\`:
+Common Prisma error codes wrapped by `RepositoryError`:
 
 | Code | Meaning |
 |------|---------|
@@ -211,9 +210,7 @@ Common Prisma error codes wrapped by \`RepositoryError\`:
 
 1. **Services throw domain errors** — never raw NestJS HttpException in service layer.
 2. **Exception filters map to HTTP** — one filter per domain error type.
-3. **Error classes include a machine-readable \`code\`** — used for client-side error handling.
-4. **Use \`Object.setPrototypeOf\`** and \`Error.captureStackTrace\` in custom Error subclasses.
+3. **Error classes include a machine-readable `code`** — used for client-side error handling.
+4. **Use `Object.setPrototypeOf`** and `Error.captureStackTrace` in custom Error subclasses.
 5. **Don't leak internal details** — the filter should not expose Prisma error codes or stack traces.
-6. **Register filters globally** in the bootstrap function or via \`APP_FILTER\` provider.
-`;
-//# sourceMappingURL=errorHandlingPattern.js.map
+6. **Register filters globally** in the bootstrap function or via `APP_FILTER` provider.

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.