@breadstone/archipel-mcp 0.0.15 → 0.0.16

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 via the `OperationTelemetryInterceptor`. The interceptor wraps the handler in a telemetry operation and returns an `Observable<unknown>`, making it fully compatible with NestJS interceptor pipelines. It records:
+
+- Operation name (`ControllerName.methodName`)
+- 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/index.md

@@ -0,0 +1,8 @@
+---
+title: Packages
+description: All Archipel platform packages with their primary capabilities.
+---
+
+# Packages
+
+<PackagesOverview />

package/data/packages/platform-analytics/api/Class.AnalyticsClientPort.md

@@ -0,0 +1,141 @@
+---
+title: 'Abstract Class: AnalyticsClientPort'
+generated: true
+editUrl: false
+---
+# Abstract Class: AnalyticsClientPort
+
+Defined in: [contracts/AnalyticsClientPort.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L16)
+
+Abstract port for analytics and error tracking clients.
+Each provider (Sentry, Application Insights, Datadog) must implement this contract
+so that the consuming application can switch providers without changing business logic.
+
+## Extended by
+
+- [`NoopAnalyticsClient`](Class.NoopAnalyticsClient)
+- [`SentryAnalyticsClient`](Class.SentryAnalyticsClient)
+- [`AppInsightsAnalyticsClient`](Class.AppInsightsAnalyticsClient)
+- [`DatadogAnalyticsClient`](Class.DatadogAnalyticsClient)
+
+## Constructors
+
+### Constructor
+
+```ts
+new AnalyticsClientPort(): AnalyticsClientPort;
+```
+
+#### Returns
+
+`AnalyticsClientPort`
+
+## Methods
+
+### addBreadcrumb()
+
+```ts
+abstract addBreadcrumb(breadcrumb): void;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:59](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L59)
+
+Add a breadcrumb entry to the analytics trail.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `breadcrumb` | [`IAnalyticsBreadcrumb`](Interface.IAnalyticsBreadcrumb) | The breadcrumb to add. |
+
+#### Returns
+
+`void`
+
+***
+
+### captureException()
+
+```ts
+abstract captureException(error, context?): void;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:26](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L26)
+
+Capture an exception with optional context.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `error` | `Error` | The error to capture. |
+| `context?` | `Record`\<`string`, `unknown`\> | Optional additional context metadata. |
+
+#### Returns
+
+`void`
+
+***
+
+### captureMessage()
+
+```ts
+abstract captureMessage(
+   message, 
+   level, 
+   context?): void;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:36](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L36)
+
+Capture a message with a specific severity level.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `message` | `string` | The message to capture. |
+| `level` | [`AnalyticsLevel`](TypeAlias.AnalyticsLevel) | Severity level of the message. |
+| `context?` | `Record`\<`string`, `unknown`\> | Optional additional context metadata. |
+
+#### Returns
+
+`void`
+
+***
+
+### clearUser()
+
+```ts
+abstract clearUser(): void;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:51](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L51)
+
+Clear the current user context.
+
+#### Returns
+
+`void`
+
+***
+
+### setUser()
+
+```ts
+abstract setUser(user): void;
+```
+
+Defined in: [contracts/AnalyticsClientPort.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/contracts/AnalyticsClientPort.ts#L44)
+
+Set the current user context for subsequent events.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `user` | [`IAnalyticsUser`](Interface.IAnalyticsUser) | The user context to set. |
+
+#### Returns
+
+`void`