@breadstone/archipel-mcp 0.0.38 → 0.0.39

package/data/guides/application-bootstrap.md

@@ -0,0 +1,181 @@
+---
+title: Application Bootstrap
+description: Compose NestJS startup concerns with platform-bootstrap, Express middleware, security, sessions, OpenAPI, and typed configuration.
+order: 3
+---
+
+# Application Bootstrap
+
+`platform-bootstrap` standardizes the small but important code that usually accumulates in `main.ts`: global API prefix, validation pipe, filters, Express middleware, CORS, Helmet, sessions, rate limiting, Swagger UI, app initialization, and HTTP listening.
+
+The consuming application still owns `NestFactory`, the HTTP adapter, and the concrete Nest application type. This keeps serverless and Vercel entrypoints explicit while moving reusable startup concerns into composable `PlatformBootstrapStep` functions.
+
+---
+
+## Installation
+
+```bash
+yarn add @breadstone/archipel-platform-bootstrap @nestjs/platform-express express compression helmet express-rate-limit express-session
+```
+
+Most Archipel applications already install `@nestjs/common`, `@nestjs/core`, `class-validator`, `class-transformer`, `reflect-metadata`, and `rxjs` through their NestJS setup.
+
+---
+
+## Root Module Configuration
+
+Register the bootstrap configuration entries in the root module so `ConfigRegistry` can validate and document them with the rest of the application config.
+
+```typescript
+import { Module } from '@nestjs/common';
+import {
+  ConfigModule,
+  EnvironmentConfigStrategy,
+} from '@breadstone/archipel-platform-configuration';
+import {
+  PLATFORM_SECURITY_CONFIG_ENTRIES,
+  PLATFORM_SERVER_CONFIG_ENTRIES,
+  PLATFORM_SESSION_CONFIG_ENTRIES,
+} from '@breadstone/archipel-platform-bootstrap';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      strategyFactory: () => new EnvironmentConfigStrategy(),
+    }),
+    ConfigModule.register('platform-bootstrap/server', PLATFORM_SERVER_CONFIG_ENTRIES),
+    ConfigModule.register('platform-bootstrap/security', PLATFORM_SECURITY_CONFIG_ENTRIES),
+    ConfigModule.register('platform-bootstrap/session', PLATFORM_SESSION_CONFIG_ENTRIES),
+  ],
+})
+export class AppModule {}
+```
+
+| Entry | Keys |
+| ----- | ---- |
+| `PLATFORM_SERVER_CONFIG_ENTRIES` | `PORT` |
+| `PLATFORM_SECURITY_CONFIG_ENTRIES` | `APP_CORS_ORIGIN`, `APP_RATE_LIMIT_WINDOW_MS`, `APP_RATE_LIMIT_MAX_REQUESTS` |
+| `PLATFORM_SESSION_CONFIG_ENTRIES` | `AUTH_SESSION_SECRET`, `AUTH_SESSION_SECURE`, `AUTH_SESSION_MAX_AGE` |
+
+`AUTH_SESSION_SECRET` is required when `useSession()` is part of the pipeline. The other entries provide documented defaults or host-provided values.
+
+---
+
+## Bootstrap Entry Point
+
+Keep the adapter and app type visible in `main.ts`. The builder receives the already-created Nest app and applies ordered steps.
+
+```typescript
+import { ConsoleLogger } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { ExpressAdapter, NestExpressApplication } from '@nestjs/platform-express';
+import { PlatformApplication, useApi } from '@breadstone/archipel-platform-bootstrap';
+import { useOpenApi } from '@breadstone/archipel-platform-bootstrap/openapi';
+import { useExpressServer } from '@breadstone/archipel-platform-bootstrap/server/express';
+import { useSecurity } from '@breadstone/archipel-platform-bootstrap/security';
+import { useSession } from '@breadstone/archipel-platform-bootstrap/session';
+import { AppModule } from './AppModule';
+
+async function main(): Promise<void> {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, new ExpressAdapter(), {
+    logger: new ConsoleLogger({
+      prefix: 'API',
+      colors: true,
+      forceConsole: true,
+      compact: true,
+      sorted: true,
+    }),
+  });
+
+  await PlatformApplication.from(app)
+    .use(useApi({ prefix: 'api' }))
+    .use(useExpressServer({ json: { limit: '1mb' }, urlEncoded: { extended: true, limit: '1mb' } }))
+    .use(useSecurity({ contentSecurityPolicy: 'swagger-compatible' }))
+    .use(useSession())
+    .use(useOpenApi())
+    .listenFromConfig({ fallbackPort: 3000 });
+}
+
+void main();
+```
+
+`listenFromConfig()` resolves the listening port from `PORT`, then `APP_PORT`, then `fallbackPort`. This matches hosted environments that inject `PORT` while preserving a local development default.
+
+---
+
+## Built-In Steps
+
+| Step | Import | Responsibility |
+| ---- | ------ | -------------- |
+| `useApi()` | `@breadstone/archipel-platform-bootstrap` | Global prefix, validation pipe, and global exception filter wiring. |
+| `useExpressServer()` | `@breadstone/archipel-platform-bootstrap/server/express` | JSON parser, URL-encoded parser, and compression middleware. |
+| `useSecurity()` | `@breadstone/archipel-platform-bootstrap/security` | CORS, Helmet, content security policy, and rate limiting. |
+| `useSession()` | `@breadstone/archipel-platform-bootstrap/session` | Express-compatible session middleware backed by typed config keys. |
+| `useOpenApi()` | `@breadstone/archipel-platform-bootstrap/openapi` | Multi-document Swagger UI discovery and setup. |
+
+Use the steps in the order requests should pass through middleware: parser and security first, session before authenticated routes, OpenAPI after modules and decorators are loaded.
+
+---
+
+## Custom Steps
+
+Application-specific startup logic can live in a local `use*` factory. A step receives the `PlatformBootstrapContext`, performs its work, and calls `next()` to continue the pipeline.
+
+```typescript
+import { INestApplication } from '@nestjs/common';
+import { PlatformBootstrapStep } from '@breadstone/archipel-platform-bootstrap';
+
+export function useShutdownHooks<TApplication extends INestApplication = INestApplication>(): PlatformBootstrapStep<TApplication> {
+  return async function shutdownHooksStep(context, next): Promise<void> {
+    context.app.enableShutdownHooks();
+    await next();
+  };
+}
+```
+
+Then place it where the behavior belongs:
+
+```typescript
+await PlatformApplication.from(app)
+  .use(useApi({ prefix: 'api' }))
+  .use(useShutdownHooks())
+  .use(useOpenApi())
+  .listenFromConfig({ fallbackPort: 3000 });
+```
+
+---
+
+## Testing Bootstrap Behavior
+
+The testing subpath exposes a lightweight application double for step-order and middleware assertions.
+
+```typescript
+import { describe, expect, it } from 'vitest';
+import { PlatformApplication, useApi } from '@breadstone/archipel-platform-bootstrap';
+import { createPlatformTestApplication } from '@breadstone/archipel-platform-bootstrap/testing';
+
+it('applies API bootstrap before initialization', async (): Promise<void> => {
+  const app = createPlatformTestApplication();
+
+  await PlatformApplication.from(app)
+    .use(useApi({ prefix: 'api' }))
+    .initialize();
+
+  expect(app.calls).toContain('setGlobalPrefix');
+  expect(app.calls.at(-1)).toBe('init');
+});
+```
+
+For full HTTP behavior, keep using Supertest against a real Nest application. The test helper is for the composition layer itself, not controller or middleware integration coverage.
+
+---
+
+## Production Checklist
+
+- Register all bootstrap config entries in the root module.
+- Keep `NestFactory.create()` in the application entrypoint so the adapter remains explicit.
+- Use `useSecurity({ contentSecurityPolicy: 'swagger-compatible' })` when serving Swagger UI.
+- Set `AUTH_SESSION_SECRET` in every environment that enables `useSession()`.
+- Prefer `listenFromConfig()` for deployed HTTP apps and `initialize()` for serverless handler exports or composition tests.
+
+See the [Bootstrap Pattern](/patterns/bootstrap-pattern) for the reusable design rules behind this package.

package/data/guides/email-templates.md

@@ -59,6 +59,8 @@ The strategy loads `AuthRegister.html`, `AuthRegister.txt`, `AuthVerify.html`, e
 
 ### Template Syntax
 
+::: v-pre
+
 Templates use a Handlebars-style syntax powered by `ContentTemplateEngine`:
 
 | Syntax                                | Description                       |
@@ -109,6 +111,8 @@ Please verify your email address by visiting the following link:
 If you did not create an account, you can safely ignore this email.
 ```
 
+:::
+
 ### Security
 
 When the format is `html`, `MailTemplateEngine` automatically **escapes all context values** (`&`, `<`, `>`, `"`, `'`) before interpolation to prevent XSS in email clients. Plain-text templates (`txt`) are not escaped.

package/data/guides/index.md

@@ -13,12 +13,11 @@ Practical guides for working with Archipel packages in your NestJS application.
 | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
 | [Getting Started](./getting-started)                      | Install packages, register your first module, implement ports, and run the app.                               |
 | [Configuration Management](./configuration)               | Type-safe config keys, strategy-based resolution, central registry, and validation.                           |
+| [Application Bootstrap](./application-bootstrap)           | Compose NestJS startup with platform-bootstrap, Express middleware, security, sessions, and OpenAPI.          |
 | [Implementing Ports](./implementing-ports)                | How the port/adapter pattern works, how to write adapters, and how to test them.                              |
 | [Controller Best Practices](./controller-best-practices)  | Structure, annotate, and implement controllers — regions, DI, ResponseReturn, guards, and the @Api decorator. |
 | [Request & Response DTOs](./request-response-dtos)        | DTO naming conventions, validation decorators, cross-field validation, and class-transformer integration.     |
 | [Testing](./testing)                                      | Unit testing services, testing port adapters, integration testing with real databases.                        |
-| [TSDoc Guidelines](./tsdoc-guidelines)                    | Documentation standards for public APIs and generated reference pages.                       ld validation, and class-transformer integration.     |
-| [Testing](./testing)                                      | Unit testing services, testing port adapters, integration testing with real databases.                        |
 | [TSDoc Guidelines](./tsdoc-guidelines)                    | Documentation standards for public APIs and generated reference pages.                                        |
 
 ## Security & Identity

package/data/guides/openapi-and-feature-discovery.md

@@ -174,7 +174,32 @@ export class TipController {
 
 ## Step 3: Bootstrap the Swagger UI
 
-In your application bootstrap (`main.ts`), wire up discovery and the multi-document service:
+The recommended application bootstrap path is `useOpenApi()` from `platform-bootstrap`. It runs the same feature discovery and multi-document Swagger setup while keeping the startup sequence consistent with the rest of the platform.
+
+```typescript
+import { NestFactory } from '@nestjs/core';
+import { ExpressAdapter, NestExpressApplication } from '@nestjs/platform-express';
+import { PlatformApplication, useApi } from '@breadstone/archipel-platform-bootstrap';
+import { useOpenApi } from '@breadstone/archipel-platform-bootstrap/openapi';
+import { useExpressServer } from '@breadstone/archipel-platform-bootstrap/server/express';
+import { useSecurity } from '@breadstone/archipel-platform-bootstrap/security';
+import { AppModule } from './AppModule';
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create<NestExpressApplication>(AppModule, new ExpressAdapter());
+
+  await PlatformApplication.from(app)
+    .use(useApi({ prefix: 'api' }))
+    .use(useExpressServer())
+    .use(useSecurity({ contentSecurityPolicy: 'swagger-compatible' }))
+    .use(useOpenApi())
+    .listenFromConfig({ fallbackPort: 3000 });
+}
+
+void bootstrap();
+```
+
+If you are wiring OpenAPI without `platform-bootstrap`, use the lower-level services directly:
 
 ```typescript
 import { NestFactory } from '@nestjs/core';

package/data/packages/platform-bootstrap/api/Class.PlatformApplication.md

@@ -0,0 +1,41 @@
+---
+title: 'Class: PlatformApplication'
+generated: true
+editUrl: false
+---
+# Class: PlatformApplication
+
+Defined in: [application/PlatformApplication.ts:10](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplication.ts#L10)
+
+Entry point for composing an existing NestJS application with Archipel bootstrap steps.
+
+## Methods
+
+### from()
+
+```ts
+static from<TApplication>(app, options?): PlatformApplicationBuilder<TApplication>;
+```
+
+Defined in: [application/PlatformApplication.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplication.ts#L33)
+
+Wraps an already-created NestJS application in a fluent bootstrap builder.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TApplication` *extends* `INestApplication`\<`any`\> |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `app` | `TApplication` | The NestJS application created by the consumer. |
+| `options?` | [`IPlatformApplicationOptions`](Interface.IPlatformApplicationOptions) | Optional platform-level bootstrap dependencies. |
+
+#### Returns
+
+[`PlatformApplicationBuilder`](Class.PlatformApplicationBuilder)\<`TApplication`\>
+
+A platform application builder.

package/data/packages/platform-bootstrap/api/Class.PlatformApplicationBuilder.md

@@ -0,0 +1,164 @@
+---
+title: 'Class: PlatformApplicationBuilder\<TApplication\>'
+generated: true
+editUrl: false
+---
+# Class: PlatformApplicationBuilder\<TApplication\>
+
+Defined in: [application/PlatformApplicationBuilder.ts:16](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L16)
+
+Fluent builder that composes NestJS bootstrap steps and executes them once.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TApplication` *extends* `INestApplication` | `INestApplication` |
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlatformApplicationBuilder<TApplication>(app, options?): PlatformApplicationBuilder<TApplication>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:28](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L28)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `app` | `TApplication` |
+| `options?` | [`IPlatformApplicationOptions`](Interface.IPlatformApplicationOptions) |
+
+#### Returns
+
+`PlatformApplicationBuilder`\<`TApplication`\>
+
+## Accessors
+
+### app
+
+#### Get Signature
+
+```ts
+get app(): TApplication;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L44)
+
+The wrapped NestJS application.
+
+##### Returns
+
+`TApplication`
+
+## Methods
+
+### initialize()
+
+```ts
+initialize(): Promise<TApplication>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:70](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L70)
+
+Executes the configured bootstrap pipeline and initializes the NestJS application.
+
+#### Returns
+
+`Promise`\<`TApplication`\>
+
+The wrapped NestJS application.
+
+***
+
+### listen()
+
+```ts
+listen(port, hostname?): Promise<TApplication>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:94](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L94)
+
+Executes the pipeline and starts the NestJS listener on the given port.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `port` | `number` | The HTTP port. |
+| `hostname?` | `string` | Optional hostname/interface binding. |
+
+#### Returns
+
+`Promise`\<`TApplication`\>
+
+The wrapped NestJS application.
+
+***
+
+### listenFromConfig()
+
+```ts
+listenFromConfig(options?): Promise<TApplication>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:113](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L113)
+
+Executes the pipeline and starts the listener using typed configuration keys.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options?` | [`IPlatformListenOptions`](Interface.IPlatformListenOptions) | Port resolution options. |
+
+#### Returns
+
+`Promise`\<`TApplication`\>
+
+The wrapped NestJS application.
+
+***
+
+### run()
+
+```ts
+run(): Promise<PlatformBootstrapContext<TApplication>>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:82](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L82)
+
+Executes the configured bootstrap pipeline without starting a listener.
+
+#### Returns
+
+`Promise`\<[`PlatformBootstrapContext`](Class.PlatformBootstrapContext)\<`TApplication`\>\>
+
+The bootstrap context used for the execution.
+
+***
+
+### use()
+
+```ts
+use(step): this;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:59](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L59)
+
+Adds a bootstrap step to the application pipeline.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `step` | [`PlatformBootstrapStep`](TypeAlias.PlatformBootstrapStep)\<`TApplication`\> | The step to execute during bootstrap. |
+
+#### Returns
+
+`this`
+
+The current builder for chaining.

package/data/packages/platform-bootstrap/api/Class.PlatformBootstrapContext.md

@@ -0,0 +1,164 @@
+---
+title: 'Class: PlatformBootstrapContext\<TApplication\>'
+generated: true
+editUrl: false
+---
+# Class: PlatformBootstrapContext\<TApplication\>
+
+Defined in: [context/PlatformBootstrapContext.ts:9](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L9)
+
+Runtime context shared by platform bootstrap steps.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TApplication` *extends* `INestApplication` | `INestApplication` |
+
+## Constructors
+
+### Constructor
+
+```ts
+new PlatformBootstrapContext<TApplication>(app, configService?): PlatformBootstrapContext<TApplication>;
+```
+
+Defined in: [context/PlatformBootstrapContext.ts:19](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L19)
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `app` | `TApplication` |
+| `configService?` | `ConfigService` |
+
+#### Returns
+
+`PlatformBootstrapContext`\<`TApplication`\>
+
+## Accessors
+
+### app
+
+#### Get Signature
+
+```ts
+get app(): TApplication;
+```
+
+Defined in: [context/PlatformBootstrapContext.ts:33](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L33)
+
+The wrapped NestJS application.
+
+##### Returns
+
+`TApplication`
+
+***
+
+### config
+
+#### Get Signature
+
+```ts
+get config(): ConfigService;
+```
+
+Defined in: [context/PlatformBootstrapContext.ts:42](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L42)
+
+The Archipel configuration service resolved from the app or builder options.
+
+##### Returns
+
+`ConfigService`
+
+## Methods
+
+### getConfigValue()
+
+```ts
+getConfigValue<TValue>(key): TValue;
+```
+
+Defined in: [context/PlatformBootstrapContext.ts:68](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L68)
+
+Reads a required value from the configuration service.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TValue` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `IConfigKey`\<`TValue`\> | The typed configuration key. |
+
+#### Returns
+
+`TValue`
+
+The typed configuration value.
+
+***
+
+### getService()
+
+```ts
+getService<TService>(token): TService;
+```
+
+Defined in: [context/PlatformBootstrapContext.ts:57](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L57)
+
+Resolves a provider from the NestJS application container.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TService` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `token` | `string` \| `symbol` \| `Type`\<`TService`\> | The provider token. |
+
+#### Returns
+
+`TService`
+
+The resolved provider instance.
+
+***
+
+### tryGetConfigValue()
+
+```ts
+tryGetConfigValue<TValue>(key, fallback): TValue;
+```
+
+Defined in: [context/PlatformBootstrapContext.ts:80](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/context/PlatformBootstrapContext.ts#L80)
+
+Reads an optional value from the configuration service.
+
+#### Type Parameters
+
+| Type Parameter |
+| ------ |
+| `TValue` |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `IConfigKey`\<`TValue`\> | The typed configuration key. |
+| `fallback` | `TValue` | The fallback value when the key is absent. |
+
+#### Returns
+
+`TValue`
+
+The typed configuration value or fallback.