@breadstone/archipel-mcp 0.0.13 → 0.0.14

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

@@ -1,190 +0,0 @@
----
-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

@@ -1,319 +0,0 @@
----
-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

@@ -1,45 +0,0 @@
----
-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

@@ -1,52 +0,0 @@
----
-title: Packages
-description: All Archipel platform packages with their primary capabilities.
----
-
-# Packages
-
-Archipel is organized into 17 independent NestJS modules. Each package can be installed and used on its own — you only pull in what you need.
-
-Every package follows the same structure: a dynamic NestJS module with `register()` configuration, abstract ports for contracts you implement, and concrete services you consume.
-
-## Foundation
-
-| Package                                             | Description                                                                                                  |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [`platform-core`](./platform-core/)                 | Configuration, mapping, templates, event pub/sub, and shared utilities. Every other package depends on this. |
-| [`platform-cryptography`](./platform-cryptography/) | Bcrypt password hashing, prefixed UUID generation, and TOTP multi-factor authentication.                     |
-| [`platform-database`](./platform-database/)         | Prisma + PostgreSQL integration with the repository/query pattern and transactional support.                 |
-
-## Identity & Access
-
-| Package                                                 | Description                                                                                                    |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| [`platform-authentication`](./platform-authentication/) | JWT, OAuth (GitHub, Google, Microsoft, Apple), MFA, sessions, anonymous auth, and email verification.          |
-| [`platform-payments`](./platform-payments/)             | Multi-provider payment client (Stripe, LemonSqueezy, Paddle, Creem) with feature gating and quota enforcement. |
-
-## Infrastructure
-
-| Package                                             | Description                                                                                                                 |
-| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| [`platform-blob-storage`](./platform-blob-storage/) | Provider-agnostic blob storage (Vercel, Azure, AWS S3) with metadata tracking and image variant support.                    |
-| [`platform-caching`](./platform-caching/)           | Layered caching with in-memory LRU and Redis-backed implementations, TTL, stale-while-revalidate, and metrics.              |
-| [`platform-esigning`](./platform-esigning/)         | Provider-agnostic e-signing with support for DocuSign, Adobe Sign, Dropbox Sign, signNow, and a built-in internal provider. |
-| [`platform-mailing`](./platform-mailing/)           | Multi-strategy email delivery (SMTP, Postmark, Resend, Plunk, Log) with template rendering and verification flows.          |
-| [`platform-documents`](./platform-documents/)       | Document generation with pluggable renderers for DOCX, PDF, and image processing.                                           |
-
-## Operations
-
-| Package                                       | Description                                                                                                  |
-| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| [`platform-openapi`](./platform-openapi/)     | Feature-scoped Swagger/OpenAPI documentation with multi-document registry and discovery.                     |
-| [`platform-logging`](./platform-logging/)     | Sentry integration for structured error tracking and analytics.                                              |
-| [`platform-telemetry`](./platform-telemetry/) | OpenTelemetry tracing, metrics, a rule engine for conditional recording, and graceful noop fallback.         |
-| [`platform-analytics`](./platform-analytics/) | Provider-agnostic analytics and error tracking (Sentry, Application Insights, Datadog) with no-op fallback.  |
-| [`platform-reporting`](./platform-reporting/) | Contributor-based reporting engine with dataset registration and query execution.                            |
-| [`platform-mcp`](./platform-mcp/)             | Decorator-driven MCP (Model Context Protocol) server module with auto-discovery and multi-transport support. |
-
-## AI & Extensibility
-
-| Package                                             | Description                                                                                                            |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| [`platform-intelligence`](./platform-intelligence/) | Multi-provider AI text generation (OpenAI, Anthropic, Google, Grok) with capability registry and intent orchestration. |