@breadstone/archipel-mcp 0.0.21 → 0.0.22

package/{src/knowledge/dtoPattern.js → data/patterns/dto-pattern.md}

@@ -1,24 +1,23 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel DTO & validation pattern.
- * Returned by the get-dto-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DTO_PATTERN_KNOWLEDGE = void 0;
-exports.DTO_PATTERN_KNOWLEDGE = `# Archipel DTO & Validation Pattern
+---
+title: DTO & Validation Pattern
+description: Request/Response DTOs, class-validator decorators, cross-field validation, query parameter DTOs, OpenAPI integration, and naming conventions.
+order: 2
+---
+
+# Archipel DTO & Validation Pattern
 
 ## Overview
 
 Archipel uses **class-based DTOs** with **class-validator** decorators for input validation
-and **class-transformer** decorators for serialization control. A global \`ValidationPipe\`
+and **class-transformer** decorators for serialization control. A global `ValidationPipe`
 enforces validation on all incoming requests automatically.
 
 Request DTOs validate input; Response classes define the output shape with
-\`@ApiProperty\` decorators for OpenAPI documentation.
+`@ApiProperty` decorators for OpenAPI documentation.
 
 ## Global Validation Pipe
 
-\`\`\`typescript
+```typescript
 // In main.ts bootstrap:
 app.useGlobalPipes(
   new ValidationPipe({
@@ -27,11 +26,11 @@ app.useGlobalPipes(
     transform: true,             // Auto-transform payloads to DTO instances
   }),
 );
-\`\`\`
+```
 
 ## Request DTO (Input Validation)
 
-\`\`\`typescript
+```typescript
 // dtos/CreateUserRequest.ts
 import { Expose } from 'class-transformer';
 import { IsEmail, IsString, MinLength, MaxLength } from 'class-validator';
@@ -58,11 +57,11 @@ export class CreateUserRequest {
   public password!: string;
 
 }
-\`\`\`
+```
 
 ## Response DTO (Output Shape)
 
-\`\`\`typescript
+```typescript
 // dtos/UserResponse.ts
 import { Expose } from 'class-transformer';
 import { ApiProperty } from '@nestjs/swagger';
@@ -88,7 +87,7 @@ export class UserResponse {
   // Note: password is intentionally NOT exposed
 
 }
-\`\`\`
+```
 
 ## Common Validators
 
@@ -96,48 +95,48 @@ export class UserResponse {
 
 | Decorator | Purpose |
 |-----------|---------|
-| \`@IsString()\` | Must be a string |
-| \`@IsNumber()\` | Must be a number |
-| \`@IsBoolean()\` | Must be a boolean |
-| \`@IsEmail()\` | Must be a valid email |
-| \`@IsUUID()\` | Must be a valid UUID |
-| \`@IsDate()\` | Must be a Date instance |
-| \`@IsEnum(MyEnum)\` | Must be a value from the enum |
-| \`@IsOptional()\` | Field is optional (skip validation if undefined) |
+| `@IsString()` | Must be a string |
+| `@IsNumber()` | Must be a number |
+| `@IsBoolean()` | Must be a boolean |
+| `@IsEmail()` | Must be a valid email |
+| `@IsUUID()` | Must be a valid UUID |
+| `@IsDate()` | Must be a Date instance |
+| `@IsEnum(MyEnum)` | Must be a value from the enum |
+| `@IsOptional()` | Field is optional (skip validation if undefined) |
 
 ### String Constraints
 
 | Decorator | Purpose |
 |-----------|---------|
-| \`@MinLength(n)\` | Minimum string length |
-| \`@MaxLength(n)\` | Maximum string length |
-| \`@Matches(regex)\` | Must match a regex pattern |
-| \`@IsNotEmpty()\` | Must not be empty string |
+| `@MinLength(n)` | Minimum string length |
+| `@MaxLength(n)` | Maximum string length |
+| `@Matches(regex)` | Must match a regex pattern |
+| `@IsNotEmpty()` | Must not be empty string |
 
 ### Number Constraints
 
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Min(n)\` | Minimum value |
-| \`@Max(n)\` | Maximum value |
-| \`@IsPositive()\` | Must be > 0 |
-| \`@IsInt()\` | Must be integer |
+| `@Min(n)` | Minimum value |
+| `@Max(n)` | Maximum value |
+| `@IsPositive()` | Must be > 0 |
+| `@IsInt()` | Must be integer |
 
 ### Nested & Array
 
 | Decorator | Purpose |
 |-----------|---------|
-| \`@ValidateNested()\` | Validate nested objects |
-| \`@Type(() => Cls)\` | Transform to class instance (class-transformer) |
-| \`@IsArray()\` | Must be an array |
-| \`@ArrayMinSize(n)\` | Minimum array length |
-| \`@ArrayMaxSize(n)\` | Maximum array length |
+| `@ValidateNested()` | Validate nested objects |
+| `@Type(() => Cls)` | Transform to class instance (class-transformer) |
+| `@IsArray()` | Must be an array |
+| `@ArrayMinSize(n)` | Minimum array length |
+| `@ArrayMaxSize(n)` | Maximum array length |
 
 ## Cross-Field Validation
 
 For fields that depend on each other, use custom class-level validators:
 
-\`\`\`typescript
+```typescript
 import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments, Validate } from 'class-validator';
 
 @ValidatorConstraint({ name: 'Match', async: false })
@@ -153,7 +152,7 @@ export class MatchConstraint implements ValidatorConstraintInterface {
   public defaultMessage(args: ValidationArguments): string {
     const [relatedPropertyName] = args.constraints;
 
-    return \\\`\\\${args.property} must match \\\${relatedPropertyName}\\\`;
+    return `${args.property} must match ${relatedPropertyName}`;
   }
 
 }
@@ -172,13 +171,13 @@ export class ResetPasswordRequest {
   public confirmPassword!: string;
 
 }
-\`\`\`
+```
 
 ## Query Parameter DTOs
 
-For GET request query parameters, use \`@Transform()\` and \`@Type()\` for type coercion:
+For GET request query parameters, use `@Transform()` and `@Type()` for type coercion:
 
-\`\`\`typescript
+```typescript
 import { Type } from 'class-transformer';
 import { IsOptional, IsInt, Min, Max, IsString } from 'class-validator';
 import { ApiPropertyOptional } from '@nestjs/swagger';
@@ -206,13 +205,13 @@ export class PaginationQuery {
   public search?: string;
 
 }
-\`\`\`
+```
 
 ## OpenAPI / Swagger Integration
 
 ### @ApiProperty Decorators
 
-\`\`\`typescript
+```typescript
 @ApiProperty({
   description: 'User email address',
   example: 'user@example.com',
@@ -225,11 +224,11 @@ public email!: string;
   maxLength: 500,
 })
 public bio?: string;
-\`\`\`
+```
 
 ### Controller Response Decorators
 
-\`\`\`typescript
+```typescript
 @Controller('/users')
 @ApiTags('Users')
 export class UsersController {
@@ -244,23 +243,23 @@ export class UsersController {
   }
 
 }
-\`\`\`
+```
 
 ## Naming Conventions
 
 | Type | Naming Pattern | Example |
 |------|---------------|---------|
-| Create input | \`Create{Entity}Request\` | \`CreateUserRequest\` |
-| Update input | \`Update{Entity}Request\` | \`UpdateUserRequest\` |
-| Query params | \`{Entity}Query\` or \`Pagination{Entity}Query\` | \`UserQuery\` |
-| Response | \`{Entity}Response\` | \`UserResponse\` |
-| List response | \`{Entity}ListResponse\` | \`UserListResponse\` |
+| Create input | `Create{Entity}Request` | `CreateUserRequest` |
+| Update input | `Update{Entity}Request` | `UpdateUserRequest` |
+| Query params | `{Entity}Query` or `Pagination{Entity}Query` | `UserQuery` |
+| Response | `{Entity}Response` | `UserResponse` |
+| List response | `{Entity}ListResponse` | `UserListResponse` |
 
 ## Constants for Bounds
 
 Define and reuse constants for upper limits:
 
-\`\`\`typescript
+```typescript
 // constants/ValidationConstants.ts
 export const MAX_PAGE_SIZE = 100;
 export const MAX_SEARCH_LIMIT = 50;
@@ -270,17 +269,15 @@ export const MAX_BIO_LENGTH = 500;
 // In DTO:
 @Max(MAX_PAGE_SIZE)
 public perPage?: number;
-\`\`\`
+```
 
 ## Rules
 
-1. **Every field has \`@Expose()\`** for serialization control.
-2. **Every field has \`@ApiProperty()\`** for OpenAPI documentation.
+1. **Every field has `@Expose()`** for serialization control.
+2. **Every field has `@ApiProperty()`** for OpenAPI documentation.
 3. **Request DTOs use class-validator decorators** — validation is automatic via global pipe.
 4. **Response DTOs have no validation decorators** — they're output-only shapes.
 5. **Cross-field validation uses custom class-level validators** — never imperative checks in services.
-6. **Query parameters use \`@Type(() => Number)\`** for type coercion from strings.
-7. **Upper bounds (\`@Max\`, \`@MaxLength\`) defined as exported constants** — never inline magic numbers.
-8. **\`whitelist: true\` + \`forbidNonWhitelisted: true\`** strips and rejects unknown properties.
-`;
-//# sourceMappingURL=dtoPattern.js.map
+6. **Query parameters use `@Type(() => Number)`** for type coercion from strings.
+7. **Upper bounds (`@Max`, `@MaxLength`) defined as exported constants** — never inline magic numbers.
+8. **`whitelist: true` + `forbidNonWhitelisted: true`** strips and rejects unknown properties.

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.