@breadstone/archipel-mcp 0.0.9 → 0.0.11

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-analytics/api/Class.AnalyticsClientPort.md

@@ -3,7 +3,6 @@ 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)
@@ -45,15 +44,15 @@ Add a breadcrumb entry to the analytics trail.
 
 #### Parameters
 
-| Parameter    | Type                                                     | Description            |
-| ------------ | -------------------------------------------------------- | ---------------------- |
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
 | `breadcrumb` | [`IAnalyticsBreadcrumb`](Interface.IAnalyticsBreadcrumb) | The breadcrumb to add. |
 
 #### Returns
 
 `void`
 
----
+***
 
 ### captureException()
 
@@ -67,23 +66,23 @@ Capture an exception with optional context.
 
 #### Parameters
 
-| Parameter  | Type                            | Description                           |
-| ---------- | ------------------------------- | ------------------------------------- |
-| `error`    | `Error`                         | The error to capture.                 |
+| 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,
+   message, 
+   level, 
    context?): void;
 ```
 
@@ -93,17 +92,17 @@ 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. |
+| 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()
 
@@ -119,7 +118,7 @@ Clear the current user context.
 
 `void`
 
----
+***
 
 ### setUser()
 
@@ -133,9 +132,9 @@ Set the current user context for subsequent events.
 
 #### Parameters
 
-| Parameter | Type                                         | Description              |
-| --------- | -------------------------------------------- | ------------------------ |
-| `user`    | [`IAnalyticsUser`](Interface.IAnalyticsUser) | The user context to set. |
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `user` | [`IAnalyticsUser`](Interface.IAnalyticsUser) | The user context to set. |
 
 #### Returns
 

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

@@ -3,7 +3,6 @@ title: 'Class: AnalyticsModule'
 generated: true
 editUrl: false
 ---
-
 # Class: AnalyticsModule
 
 Defined in: [AnalyticsModule.ts:43](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/AnalyticsModule.ts#L43)
@@ -37,8 +36,8 @@ Configures the module with the specified options.
 
 #### Parameters
 
-| Parameter | Type                                                           | Description                       |
-| --------- | -------------------------------------------------------------- | --------------------------------- |
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
 | `options` | [`IAnalyticsModuleOptions`](Interface.IAnalyticsModuleOptions) | The module configuration options. |
 
 #### Returns

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

@@ -3,7 +3,6 @@ title: 'Class: AppInsightsAnalyticsClient'
 generated: true
 editUrl: false
 ---
-
 # Class: AppInsightsAnalyticsClient
 
 Defined in: [application-insights/AppInsightsAnalyticsClient.ts:22](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-analytics/src/application-insights/AppInsightsAnalyticsClient.ts#L22)
@@ -27,8 +26,8 @@ Defined in: [application-insights/AppInsightsAnalyticsClient.ts:32](https://gith
 
 #### Parameters
 
-| Parameter       | Type            |
-| --------------- | --------------- |
+| Parameter | Type |
+| ------ | ------ |
 | `configService` | `ConfigService` |
 
 #### Returns
@@ -53,8 +52,8 @@ Add a breadcrumb entry to the analytics trail.
 
 #### Parameters
 
-| Parameter    | Type                                                     | Description            |
-| ------------ | -------------------------------------------------------- | ---------------------- |
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
 | `breadcrumb` | [`IAnalyticsBreadcrumb`](Interface.IAnalyticsBreadcrumb) | The breadcrumb to add. |
 
 #### Returns
@@ -65,7 +64,7 @@ Add a breadcrumb entry to the analytics trail.
 
 [`AnalyticsClientPort`](Class.AnalyticsClientPort).[`addBreadcrumb`](Class.AnalyticsClientPort#addbreadcrumb)
 
----
+***
 
 ### captureException()
 
@@ -79,9 +78,9 @@ Capture an exception with optional context.
 
 #### Parameters
 
-| Parameter  | Type                            | Description                           |
-| ---------- | ------------------------------- | ------------------------------------- |
-| `error`    | `Error`                         | The error to capture.                 |
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `error` | `Error` | The error to capture. |
 | `context?` | `Record`\<`string`, `unknown`\> | Optional additional context metadata. |
 
 #### Returns
@@ -92,14 +91,14 @@ Capture an exception with optional context.
 
 [`AnalyticsClientPort`](Class.AnalyticsClientPort).[`captureException`](Class.AnalyticsClientPort#captureexception)
 
----
+***
 
 ### captureMessage()
 
 ```ts
 captureMessage(
-   message,
-   level,
+   message, 
+   level, 
    context?): void;
 ```
 
@@ -109,11 +108,11 @@ 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. |
+| 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
 
@@ -123,7 +122,7 @@ Capture a message with a specific severity level.
 
 [`AnalyticsClientPort`](Class.AnalyticsClientPort).[`captureMessage`](Class.AnalyticsClientPort#capturemessage)
 
----
+***
 
 ### clearUser()
 
@@ -143,7 +142,7 @@ Clear the current user context.
 
 [`AnalyticsClientPort`](Class.AnalyticsClientPort).[`clearUser`](Class.AnalyticsClientPort#clearuser)
 
----
+***
 
 ### setUser()
 
@@ -157,9 +156,9 @@ Set the current user context for subsequent events.
 
 #### Parameters
 
-| Parameter | Type                                         | Description              |
-| --------- | -------------------------------------------- | ------------------------ |
-| `user`    | [`IAnalyticsUser`](Interface.IAnalyticsUser) | The user context to set. |
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `user` | [`IAnalyticsUser`](Interface.IAnalyticsUser) | The user context to set. |
 
 #### Returns