@breadstone/archipel-mcp 0.0.10 → 0.0.13

package/data/guides/telemetry-and-observability.md

@@ -0,0 +1,190 @@
+---
+title: Telemetry & Observability
+description: Add OpenTelemetry-based metrics, tracing, and structured logging to your NestJS application.
+order: 10
+---
+
+# Telemetry & Observability
+
+This guide covers adding observability to your application with `platform-telemetry`: setup, metrics recording, distributed tracing, structured logging, and graceful shutdown.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-telemetry
+```
+
+---
+
+## Module Registration
+
+```typescript
+import { Module } from '@nestjs/common';
+import { TelemetryModule } from '@breadstone/archipel-platform-telemetry';
+
+@Module({
+  imports: [
+    TelemetryModule.register({
+      enabled: true,
+      interceptor: {
+        operation: true, // auto-instrument controller operations
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+When `enabled` is `false`, the module provides a no-op facade (`NoopTelemetryFacade`) that silently discards all telemetry calls. This means you can instrument your code once and toggle telemetry via configuration.
+
+---
+
+## Configuration
+
+```env
+TELEMETRY_ENABLED=true
+TELEMETRY_SERVICE_NAME=my-api
+TELEMETRY_EXPORTER_ENDPOINT=https://otel-collector.example.com:4318
+```
+
+---
+
+## Recording Metrics
+
+Use `TelemetryFacade` to record application metrics:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { TelemetryFacade } from '@breadstone/archipel-platform-telemetry';
+
+@Injectable()
+export class OrderService {
+  private readonly _telemetry: TelemetryFacade;
+
+  constructor(telemetry: TelemetryFacade) {
+    this._telemetry = telemetry;
+  }
+
+  public async createOrder(userId: string): Promise<void> {
+    const start = Date.now();
+
+    try {
+      // ... business logic
+
+      this._telemetry.recordCounter('domain_command_total', 1, {
+        command: 'create_order',
+        status: 'success',
+      });
+    } catch (error) {
+      this._telemetry.recordCounter('domain_command_total', 1, {
+        command: 'create_order',
+        status: 'failure',
+      });
+      throw error;
+    } finally {
+      this._telemetry.recordHistogram('order_processing_duration_ms', Date.now() - start, {
+        command: 'create_order',
+      });
+    }
+  }
+}
+```
+
+### Recommended Baseline Metrics
+
+| Metric                                    | Type      | Labels                        |
+| ----------------------------------------- | --------- | ----------------------------- |
+| `db_query_duration_ms`                    | Histogram | `model`, `operation`          |
+| `cache_hits_total` / `cache_misses_total` | Counter   | `cache`                       |
+| `domain_command_total`                    | Counter   | `command`, `status`           |
+| `external_http_request_duration_ms`       | Histogram | `service`, `action`, `status` |
+
+---
+
+## Structured Logging
+
+`TelemetryLoggerService` provides structured logging with automatic correlation:
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { TelemetryLoggerService } from '@breadstone/archipel-platform-telemetry';
+
+@Injectable()
+export class PaymentService {
+  private readonly _logger: TelemetryLoggerService;
+
+  constructor(logger: TelemetryLoggerService) {
+    this._logger = logger;
+  }
+
+  public async processPayment(orderId: string): Promise<void> {
+    this._logger.log('Processing payment', { orderId });
+
+    try {
+      // ... payment logic
+      this._logger.log('Payment processed successfully', { orderId });
+    } catch (error) {
+      this._logger.error('Payment processing failed', { orderId, error });
+      throw error;
+    }
+  }
+}
+```
+
+All log entries automatically include `requestId` for request-level correlation.
+
+---
+
+## Automatic Operation Instrumentation
+
+When you set `interceptor.operation: true`, every controller method is automatically traced. The interceptor records:
+
+- Operation name (controller + method)
+- Duration
+- HTTP status code
+- Error details on failure
+
+This gives you endpoint-level performance visibility without manual instrumentation.
+
+---
+
+## Rule Engine
+
+`TelemetryRuleEngine` lets you configure sampling and filtering rules:
+
+```typescript
+TelemetryModule.register({
+  enabled: true,
+  interceptor: { operation: true },
+  rules: [
+    { pattern: '/health', action: 'drop' },       // Don't trace health checks
+    { pattern: '/api/v1/**', action: 'sample', rate: 0.1 }, // Sample 10% of API traffic
+  ],
+}),
+```
+
+This prevents noisy endpoints (health checks, readiness probes) from overwhelming your telemetry backend.
+
+---
+
+## Graceful Shutdown
+
+The module registers a shutdown hook that flushes all pending telemetry data before the process exits. This ensures you don't lose metrics or traces during deployments or scaling events.
+
+---
+
+## Development Tips
+
+- Set `TELEMETRY_ENABLED=false` in local development to avoid telemetry overhead.
+- Use the `log` exporter during development to see traces in the console.
+- Add metrics incrementally — start with the baseline metrics and expand as you identify bottlenecks.
+- Include `requestId` in all log entries. The telemetry module handles this automatically for HTTP requests.
+
+---
+
+## Next Steps
+
+- Browse the [platform-telemetry API reference](/packages/platform-telemetry/api/) for complete method signatures
+- See the [Testing](/guides/testing) guide for verifying telemetry calls in unit tests

package/data/guides/testing.md

@@ -0,0 +1,319 @@
+---
+title: Testing
+description: Testing strategies and patterns for Archipel-powered NestJS applications.
+order: 3
+---
+
+# Testing
+
+This guide covers testing patterns for applications that use Archipel packages. It walks through unit testing services, testing port adapters, building in-memory adapters for integration tests, and verifying that modules compose correctly.
+
+Archipel uses [Vitest](https://vitest.dev/) as the test runner. All examples follow the Arrange-Act-Assert pattern.
+
+---
+
+## Unit Testing Services
+
+When testing services that depend on Archipel ports or other services, mock the dependencies and test business logic in isolation. Don't try to instantiate real modules — that's for integration tests.
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { UserService } from './UserService';
+import { type AuthSubjectPort } from '@breadstone/archipel-platform-authentication';
+
+describe('UserService', () => {
+  let service: UserService;
+  let mockAuthSubject: { findById: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    mockAuthSubject = {
+      findById: vi.fn(),
+    };
+    service = new UserService(mockAuthSubject as unknown as AuthSubjectPort);
+  });
+
+  it('should return user when found', async () => {
+    const user = { id: 'user-1', userName: 'alice', email: 'alice@test.com' };
+    mockAuthSubject.findById.mockResolvedValue(user);
+
+    const result = await service.getUser('user-1');
+
+    expect(result).toEqual(user);
+    expect(mockAuthSubject.findById).toHaveBeenCalledWith('user-1');
+  });
+
+  it('should throw when user not found', async () => {
+    mockAuthSubject.findById.mockResolvedValue(null);
+
+    await expect(service.getUser('missing')).rejects.toThrow();
+  });
+});
+```
+
+The key principle: mock at the boundary (the port), not inside the implementation. Your test shouldn't know that `AuthSubjectPort` calls Prisma under the hood — it only knows the port interface.
+
+### Mocking the MappingService
+
+The `MappingService` from `platform-core` is commonly injected in controllers to convert entities to response DTOs. Mock it in unit tests to avoid requiring mapping profile registration:
+
+```typescript
+import { MappingService } from '@breadstone/archipel-platform-core';
+
+const mockMappingService = {
+  map: vi.fn((key, source) => source), // pass-through by default
+} as unknown as MappingService;
+```
+
+When the mapping output matters for a specific test, configure the mock:
+
+```typescript
+it('should return mapped user response', async () => {
+  mockMappingService.map = vi.fn().mockReturnValue({
+    id: 'user-1',
+    displayName: 'Alice',
+  });
+
+  const result = await controller.getUser('user-1');
+
+  expect(result).toEqual({ id: 'user-1', displayName: 'Alice' });
+  expect(mockMappingService.map).toHaveBeenCalledWith(USER_TO_RESPONSE, expect.any(Object));
+});
+```
+
+### Mocking Repositories
+
+Repositories extend `RepositoryBase` and use the `execute(query)` pattern internally. In tests, mock the repository's public methods directly — don't try to mock `execute()` or `PrismaService` internals:
+
+```typescript
+const mockUserRepository = {
+  findById: vi.fn(),
+  findByEmail: vi.fn(),
+  create: vi.fn(),
+};
+```
+
+This keeps your tests decoupled from the data access implementation. If you later switch from Prisma to another ORM or change query structure, service tests stay unchanged.
+
+---
+
+## Testing Port Adapters
+
+Port adapters translate between your application's data model and the interface the platform library expects. They deserve their own tests because mapping errors are a common source of bugs.
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { PrismaAuthSubjectAdapter } from './PrismaAuthSubjectAdapter';
+
+describe('PrismaAuthSubjectAdapter', () => {
+  let adapter: PrismaAuthSubjectAdapter;
+  let mockPrisma: {
+    user: {
+      findUnique: ReturnType<typeof vi.fn>;
+      findFirst: ReturnType<typeof vi.fn>;
+    };
+  };
+
+  beforeEach(() => {
+    mockPrisma = {
+      user: {
+        findUnique: vi.fn(),
+        findFirst: vi.fn(),
+      },
+    };
+    adapter = new PrismaAuthSubjectAdapter(mockPrisma as never);
+  });
+
+  describe('findById', () => {
+    it('should return null when user does not exist', async () => {
+      mockPrisma.user.findUnique.mockResolvedValue(null);
+
+      const result = await adapter.findById('non-existent');
+
+      expect(result).toBeNull();
+    });
+
+    it('should map database record to IAuthSubject', async () => {
+      const dbUser = {
+        id: 'user-1',
+        userName: 'alice',
+        email: 'alice@example.com',
+        password: '$argon2id$hash',
+        isVerified: true,
+        isAnonymous: false,
+        roles: ['user', 'admin'],
+        mfaEnabled: false,
+      };
+      mockPrisma.user.findUnique.mockResolvedValue(dbUser);
+
+      const result = await adapter.findById('user-1');
+
+      expect(result).toEqual({
+        id: 'user-1',
+        userName: 'alice',
+        email: 'alice@example.com',
+        password: '$argon2id$hash',
+        isVerified: true,
+        isAnonymous: false,
+        roles: ['user', 'admin'],
+        mfaEnabled: false,
+      });
+    });
+  });
+
+  describe('findByLogin', () => {
+    it('should search by both userName and email', async () => {
+      mockPrisma.user.findFirst.mockResolvedValue(null);
+
+      await adapter.findByLogin('alice@example.com');
+
+      expect(mockPrisma.user.findFirst).toHaveBeenCalledWith({
+        where: {
+          OR: [{ userName: 'alice@example.com' }, { email: 'alice@example.com' }],
+        },
+        select: expect.any(Object),
+      });
+    });
+  });
+});
+```
+
+### Testing Schema Mapping
+
+When your database schema doesn't match the port interface directly, your adapter performs a mapping. Test that mapping explicitly — it's where subtle bugs hide:
+
+```typescript
+it('should derive isAnonymous from user type field', async () => {
+  const dbUser = {
+    id: 'u1',
+    username: 'guest_42',
+    emailAddress: null,
+    passwordHash: null,
+    emailVerified: false,
+    type: 'anonymous',
+    userRoles: [{ role: { name: 'guest' } }],
+    twoFactorEnabled: false,
+  };
+  mockPrisma.user.findUnique.mockResolvedValue(dbUser);
+
+  const result = await adapter.findById('u1');
+
+  expect(result?.isAnonymous).toBe(true);
+  expect(result?.roles).toEqual(['guest']);
+});
+```
+
+---
+
+## In-Memory Adapters
+
+For integration tests where you need working ports without a real database, create in-memory implementations. They're fast, deterministic, and let you seed exactly the state you need for each test.
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { AuthSubjectPort, type IAuthSubject } from '@breadstone/archipel-platform-authentication';
+
+@Injectable()
+export class InMemoryAuthSubjectAdapter extends AuthSubjectPort {
+  private readonly _subjects = new Map<string, IAuthSubject>();
+
+  public seed(subjects: IAuthSubject[]): void {
+    this._subjects.clear();
+    subjects.forEach((s) => this._subjects.set(s.id, s));
+  }
+
+  public async findById(id: string): Promise<IAuthSubject | null> {
+    return this._subjects.get(id) ?? null;
+  }
+
+  public async findByLogin(login: string): Promise<IAuthSubject | null> {
+    return [...this._subjects.values()].find((s) => s.userName === login || s.email === login) ?? null;
+  }
+
+  public async findAnonymous(userName: string): Promise<IAuthSubject | null> {
+    return [...this._subjects.values()].find((s) => s.userName === userName && s.isAnonymous) ?? null;
+  }
+}
+```
+
+This pattern works for any port. Store state in a `Map`, expose a `seed()` method for setup, and implement the port interface. Your tests run in milliseconds without touching a database.
+
+---
+
+## Integration Testing with Module Composition
+
+To verify that modules wire together correctly — that all providers resolve, ports are bound to the right adapters, and services function end-to-end — bootstrap a minimal NestJS test module:
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { AuthModule, AuthTokenService, AuthSubjectPort } from '@breadstone/archipel-platform-authentication';
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { InMemoryAuthSubjectAdapter } from './InMemoryAuthSubjectAdapter';
+import { InMemoryMfaSubjectAdapter } from './InMemoryMfaSubjectAdapter';
+import { InMemorySessionAdapter } from './InMemorySessionAdapter';
+import { InMemoryVerificationAdapter } from './InMemoryVerificationAdapter';
+
+describe('Auth module integration', () => {
+  let authTokenService: AuthTokenService;
+  let authSubjectAdapter: InMemoryAuthSubjectAdapter;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      imports: [
+        ConfigModule.register('test', TEST_CONFIG_ENTRIES),
+        AuthModule.register({
+          authSubject: InMemoryAuthSubjectAdapter,
+          mfaSubject: InMemoryMfaSubjectAdapter,
+          sessionPersistence: InMemorySessionAdapter,
+          verificationSubject: InMemoryVerificationAdapter,
+        }),
+      ],
+    }).compile();
+
+    authTokenService = module.get(AuthTokenService);
+    authSubjectAdapter = module.get(AuthSubjectPort) as InMemoryAuthSubjectAdapter;
+  });
+
+  it('should resolve AuthTokenService with all dependencies', () => {
+    expect(authTokenService).toBeDefined();
+  });
+
+  it('should generate a valid JWT for a seeded user', async () => {
+    authSubjectAdapter.seed([
+      {
+        id: 'user-1',
+        userName: 'alice',
+        email: 'alice@test.com',
+        password: '$argon2id$hash',
+        isVerified: true,
+        isAnonymous: false,
+        roles: ['user'],
+        mfaEnabled: false,
+      },
+    ]);
+
+    const token = await authTokenService.signToken({
+      id: 'user-1',
+      email: 'alice@test.com',
+      roles: ['user'],
+    });
+
+    expect(token).toBeDefined();
+    expect(typeof token).toBe('string');
+  });
+});
+```
+
+This catches wiring errors early. If you forget to register a required port, mistype an adapter class, or have a circular dependency, `Test.createTestingModule(...).compile()` throws immediately with a clear error message.
+
+---
+
+## Pre-Release Checklist
+
+Before shipping a new Archipel integration, verify:
+
+- [ ] All required port adapters have unit tests covering happy path and null/error cases
+- [ ] Schema mapping is tested explicitly when database fields differ from port interfaces
+- [ ] Module composition boots without missing provider errors (integration test)
+- [ ] Health indicators report correct status for connected infrastructure
+- [ ] Error responses use documented error shapes, not raw NestJS exceptions
+- [ ] Required environment variables fail fast at startup when missing

package/data/guides/tsdoc-guidelines.md

@@ -0,0 +1,45 @@
+---
+title: API Documentation Standards
+description: Documentation standards for stable Archipel public APIs and generated reference pages.
+order: 5
+tags: [guides, docs, api, standards]
+---
+
+# API Documentation Standards
+
+Use these standards for package APIs that are consumed by application teams.
+
+## What must be documented
+
+For every exported public symbol:
+
+- purpose and intended usage,
+- input/output contract,
+- failure behavior,
+- minimal usage example when non-obvious.
+
+## Consumer-first writing rules
+
+- Explain **what integrators need to do**, not repository internals.
+- Mark required vs optional integration points explicitly.
+- Keep examples small and runnable.
+- Avoid architecture jargon without practical effect.
+
+## Recommended structure for package overview pages
+
+1. Capability summary
+2. Installation/import information
+3. Required ports/adapters
+4. Optional extension points
+5. Minimal registration example
+6. Link to generated API reference
+
+## Stability signaling
+
+Document stability expectations clearly:
+
+- `Stable`: safe for long-lived integrations
+- `Evolving`: may receive additive changes
+- `Experimental`: breaking changes possible
+
+If a symbol is internal, do not expose it from the package barrel.

package/data/packages/platform-database/api/Class.DatabaseModule.md

@@ -5,9 +5,7 @@ editUrl: false
 ---
 # Class: DatabaseModule
 
-Defined in: [DatabaseModule.ts:48](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L48)
-
-Represents the database module.
+Defined in: [DatabaseModule.ts:62](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L62)
 
 ## Constructors
 
@@ -29,7 +27,7 @@ new DatabaseModule(): DatabaseModule;
 static forRoot(config?): DynamicModule;
 ```
 
-Defined in: [DatabaseModule.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L57)
+Defined in: [DatabaseModule.ts:71](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L71)
 
 Registers the `DatabaseModule` with global middlewares.
 
@@ -53,7 +51,7 @@ A `DynamicModule` that can be imported globally
 static register(config?): DynamicModule;
 ```
 
-Defined in: [DatabaseModule.ts:77](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L77)
+Defined in: [DatabaseModule.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/DatabaseModule.ts#L91)
 
 Registers the `DatabaseModule` with dynamic middlewares.
 

package/data/packages/platform-database/api/Class.DatabaseService.md

@@ -24,7 +24,7 @@ Represents the database service.
 ### Constructor
 
 ```ts
-new DatabaseService(configService): DatabaseService;
+new DatabaseService(configService, options?): DatabaseService;
 ```
 
 Defined in: [services/DatabaseService.ts:24](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/DatabaseService.ts#L24)
@@ -36,6 +36,7 @@ Constructs a new instance of the `DatabaseService` class.
 | Parameter | Type |
 | ------ | ------ |
 | `configService` | `ConfigService` |
+| `options?` | [`IPrismaServiceOptions`](Interface.IPrismaServiceOptions) |
 
 #### Returns
 
@@ -53,7 +54,7 @@ Constructs a new instance of the `DatabaseService` class.
 onModuleDestroy(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L80)
+Defined in: [services/PrismaService.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L91)
 
 #### Returns
 
@@ -71,7 +72,7 @@ Defined in: [services/PrismaService.ts:80](https://github.com/RueDeRennes/archip
 onModuleInit(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L68)
+Defined in: [services/PrismaService.ts:79](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L79)
 
 #### Returns
 
@@ -149,7 +150,7 @@ Executes a transactional callback (extended overload missing in base typing wrap
 withExtensions(): PrismaService;
 ```
 
-Defined in: [services/PrismaService.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L44)
+Defined in: [services/PrismaService.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L55)
 
 #### Returns
 

package/data/packages/platform-database/api/Class.PrismaService.md

@@ -5,7 +5,7 @@ editUrl: false
 ---
 # Class: PrismaService
 
-Defined in: [services/PrismaService.ts:20](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L20)
+Defined in: [services/PrismaService.ts:27](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L27)
 
 Represents the prisma service.
 
@@ -33,18 +33,19 @@ Represents the prisma service.
 ### Constructor
 
 ```ts
-new PrismaService(configService): PrismaService;
+new PrismaService(configService, options?): PrismaService;
 ```
 
-Defined in: [services/PrismaService.ts:34](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L34)
+Defined in: [services/PrismaService.ts:41](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L41)
 
-Constructs a new instance of the `DatabaseService` class.
+Constructs a new instance of the `PrismaService` class.
 
 #### Parameters
 
 | Parameter | Type |
 | ------ | ------ |
 | `configService` | `ConfigService` |
+| `options?` | [`IPrismaServiceOptions`](Interface.IPrismaServiceOptions) |
 
 #### Returns
 
@@ -64,7 +65,7 @@ PrismaClient.constructor
 onModuleDestroy(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L80)
+Defined in: [services/PrismaService.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L91)
 
 #### Returns
 
@@ -84,7 +85,7 @@ OnModuleDestroy.onModuleDestroy
 onModuleInit(): Promise<void>;
 ```
 
-Defined in: [services/PrismaService.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L68)
+Defined in: [services/PrismaService.ts:79](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L79)
 
 #### Returns
 
@@ -104,7 +105,7 @@ OnModuleInit.onModuleInit
 withExtensions(): PrismaService;
 ```
 
-Defined in: [services/PrismaService.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L44)
+Defined in: [services/PrismaService.ts:55](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-database/src/services/PrismaService.ts#L55)
 
 #### Returns