@breadstone/archipel-mcp 0.0.37 → 0.0.39

package/data/packages/platform-bootstrap/api/index.md

@@ -0,0 +1,65 @@
+---
+title: '@breadstone/archipel-platform-bootstrap'
+generated: true
+editUrl: false
+---
+# @breadstone/archipel-platform-bootstrap
+
+## Classes
+
+| Class | Description |
+| ------ | ------ |
+| [PlatformApplication](Class.PlatformApplication) | Entry point for composing an existing NestJS application with Archipel bootstrap steps. |
+| [PlatformApplicationBuilder](Class.PlatformApplicationBuilder) | Fluent builder that composes NestJS bootstrap steps and executes them once. |
+| [PlatformBootstrapContext](Class.PlatformBootstrapContext) | Runtime context shared by platform bootstrap steps. |
+| [PlatformBootstrapError](Class.PlatformBootstrapError) | Error raised when an Archipel platform bootstrap step fails. |
+
+## Interfaces
+
+| Interface | Description |
+| ------ | ------ |
+| [IApiStepOptions](Interface.IApiStepOptions) | Options for the generic Archipel API bootstrap step. |
+| [IApiValidationOptions](Interface.IApiValidationOptions) | Validation options used by the generic Archipel API bootstrap step. |
+| [IExpressServerStepOptions](Interface.IExpressServerStepOptions) | Options for the Express-compatible server bootstrap step. |
+| [IOpenApiStepOptions](Interface.IOpenApiStepOptions) | Options for the OpenAPI bootstrap step. |
+| [IPlatformApplicationOptions](Interface.IPlatformApplicationOptions) | Options for wrapping an existing NestJS application with Archipel platform bootstrap support. |
+| [IPlatformListenOptions](Interface.IPlatformListenOptions) | Options for resolving the HTTP listen port from typed configuration keys. |
+| [IPlatformTestApplication](Interface.IPlatformTestApplication) | In-memory application contract used by platform bootstrap tests. |
+| [ISecurityStepOptions](Interface.ISecurityStepOptions) | Options for the generic security bootstrap step. |
+| [ISessionStepOptions](Interface.ISessionStepOptions) | Options for the Express-compatible session bootstrap step. |
+
+## Type Aliases
+
+| Type Alias | Description |
+| ------ | ------ |
+| [PlatformBootstrapNext](TypeAlias.PlatformBootstrapNext) | Continues execution with the next platform bootstrap step. |
+| [PlatformBootstrapStep](TypeAlias.PlatformBootstrapStep) | A composable bootstrap step in the platform application pipeline. |
+| [PlatformContentSecurityPolicyMode](TypeAlias.PlatformContentSecurityPolicyMode) | Named content-security-policy modes supported by `platform-bootstrap/security`. |
+| [PlatformCorsOptions](TypeAlias.PlatformCorsOptions) | CORS options accepted by the security bootstrap step. |
+| [SecurityRateLimitOptions](TypeAlias.SecurityRateLimitOptions) | Rate-limit options accepted by the security bootstrap step. |
+
+## Variables
+
+| Variable | Description |
+| ------ | ------ |
+| [APP\_CORS\_ORIGIN](Variable.APP_CORS_ORIGIN) | Comma-separated list of allowed CORS origins. |
+| [APP\_RATE\_LIMIT\_MAX\_REQUESTS](Variable.APP_RATE_LIMIT_MAX_REQUESTS) | Maximum requests accepted within the rate-limit window. |
+| [APP\_RATE\_LIMIT\_WINDOW\_MS](Variable.APP_RATE_LIMIT_WINDOW_MS) | Rate-limit window in milliseconds. |
+| [AUTH\_SESSION\_MAX\_AGE](Variable.AUTH_SESSION_MAX_AGE) | Session cookie lifetime, for example `30d` or `86400000`. |
+| [AUTH\_SESSION\_SECRET](Variable.AUTH_SESSION_SECRET) | Secret used by Express-compatible session middleware. |
+| [AUTH\_SESSION\_SECURE](Variable.AUTH_SESSION_SECURE) | Whether session cookies should be marked secure. |
+| [PLATFORM\_SECURITY\_CONFIG\_ENTRIES](Variable.PLATFORM_SECURITY_CONFIG_ENTRIES) | Security step configuration entries provided by `platform-bootstrap/security`. |
+| [PLATFORM\_SERVER\_CONFIG\_ENTRIES](Variable.PLATFORM_SERVER_CONFIG_ENTRIES) | Server bootstrap configuration entries provided by `platform-bootstrap`. |
+| [PLATFORM\_SESSION\_CONFIG\_ENTRIES](Variable.PLATFORM_SESSION_CONFIG_ENTRIES) | Session step configuration entries provided by `platform-bootstrap/session`. |
+| [PORT](Variable.PORT) | HTTP port exposed by serverless hosts such as Vercel. |
+
+## Functions
+
+| Function | Description |
+| ------ | ------ |
+| [createPlatformTestApplication](Function.createPlatformTestApplication) | Creates a lightweight in-memory NestJS application double for platform bootstrap tests. |
+| [useApi](Function.useApi) | Creates the generic Archipel API bootstrap step. |
+| [useExpressServer](Function.useExpressServer) | Creates an Express-compatible server bootstrap step. |
+| [useOpenApi](Function.useOpenApi) | Creates the Archipel OpenAPI multi-document bootstrap step. |
+| [useSecurity](Function.useSecurity) | Creates the generic security bootstrap step. |
+| [useSession](Function.useSession) | Creates an Express-compatible session bootstrap step. |

package/data/packages/platform-bootstrap/index.md

@@ -0,0 +1,162 @@
+---
+title: platform-bootstrap
+description: Generic NestJS application composition for APIs, Express middleware, security, sessions, and OpenAPI.
+order: 1
+tags: [application, bootstrap, server, security, openapi, nestjs]
+package: '@breadstone/archipel-platform-bootstrap'
+---
+
+# platform-bootstrap
+
+Generic NestJS application composition for Archipel APIs. It replaces repeated app-level bootstrap code with a fluent `PlatformApplication` builder and tree-shakable subpath steps.
+
+The package starts from an existing Nest application. Your entrypoint still calls `NestFactory.create()`, selects the HTTP adapter, and keeps the concrete application type visible. `platform-bootstrap` then applies reusable startup steps for API defaults, Express middleware, security, sessions, OpenAPI, and tests.
+
+**Package:** `@breadstone/archipel-platform-bootstrap`
+
+<InstallTabs />
+
+## When to Use
+
+Use this package when multiple NestJS apps need the same startup shape but still need explicit control over their adapter and deployment target.
+
+| Use Case | Fit |
+| -------- | --- |
+| HTTP APIs on Express | Built-in `server/express`, `security`, `session`, and `openapi` steps. |
+| Vercel-compatible NestJS apps | `NestFactory`, `ExpressAdapter`, and `NestExpressApplication` remain in the app entrypoint. |
+| Shared platform startup defaults | Compose a stable sequence once and reuse it across apps. |
+| Step-order tests | Use the `testing` subpath without starting a real HTTP server. |
+
+## Quick Start
+
+```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 { 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 { useOpenApi } from '@breadstone/archipel-platform-bootstrap/openapi';
+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();
+```
+
+For a full application setup, see the [Application Bootstrap](/guides/application-bootstrap) guide.
+
+## Entry Points
+
+| Import | Purpose |
+| ------ | ------- |
+| `@breadstone/archipel-platform-bootstrap` | `PlatformApplication`, builder types, API step, config keys |
+| `@breadstone/archipel-platform-bootstrap/server/express` | Express body parsers and compression middleware |
+| `@breadstone/archipel-platform-bootstrap/security` | CORS, Helmet, content-security-policy, rate limiting |
+| `@breadstone/archipel-platform-bootstrap/session` | Express-compatible session middleware |
+| `@breadstone/archipel-platform-bootstrap/openapi` | `SwaggerFeatureDiscovery.setupMultiDocumentSwagger()` step |
+| `@breadstone/archipel-platform-bootstrap/testing` | Lightweight bootstrap test application helpers |
+
+## Configuration
+
+Register the config entries in the root module so startup validation and configuration discovery see the same keys the steps read at runtime.
+
+```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` |
+
+`listenFromConfig()` resolves the HTTP port from `PORT`, then `APP_PORT`, then the provided fallback.
+
+## Built-In Steps
+
+| Step | Options | Purpose |
+| ---- | ------- | ------- |
+| `useApi()` | `IApiStepOptions` | Global prefix, validation, and global exception filters. |
+| `useExpressServer()` | `IExpressServerStepOptions` | JSON parser, URL-encoded parser, and compression middleware. |
+| `useSecurity()` | `ISecurityStepOptions` | CORS, Helmet, content security policy, and rate limiting. |
+| `useSession()` | `ISessionStepOptions` | Express-compatible sessions using typed config entries. |
+| `useOpenApi()` | `IOpenApiStepOptions` | Multi-document Swagger UI discovery and setup. |
+
+## Composition Model
+
+The platform builder uses bootstrap steps that receive a `PlatformBootstrapContext` and call `next()` to continue the pipeline. Built-in `use*` helpers are normal step factories, so application-specific setup can live beside them without introducing a new NestJS module.
+
+```typescript
+import { PlatformBootstrapStep } from '@breadstone/archipel-platform-bootstrap';
+
+export const useCustomBootstrap = (): PlatformBootstrapStep => {
+  return async function customBootstrapStep(context, next): Promise<void> {
+    context.app.enableShutdownHooks();
+    await next();
+  };
+};
+```
+
+Step factories should use the `use*` naming convention and option interfaces should end in `StepOptions`. The shared pattern is documented in [Bootstrap Pattern](/patterns/bootstrap-pattern).
+
+## Testing
+
+Use the `testing` subpath when the behavior under test is bootstrap composition rather than HTTP integration.
+
+```typescript
+import { describe, expect, it } from 'vitest';
+import { PlatformApplication, useApi } from '@breadstone/archipel-platform-bootstrap';
+import { createPlatformTestApplication } from '@breadstone/archipel-platform-bootstrap/testing';
+
+describe('bootstrap', (): void => {
+  it('initializes after applying API defaults', 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');
+  });
+});
+```
+
+## Current Scope
+
+The first implementation targets Express-compatible NestJS HTTP applications and keeps `NestFactory` in the consuming entrypoint. Fastify, serverless handler exports, and standalone worker bootstrap steps are planned as additive subpaths.

package/data/patterns/bootstrap-pattern.md

@@ -0,0 +1,145 @@
+---
+title: Bootstrap Pattern
+description: Composable NestJS application startup with PlatformApplication, PlatformBootstrapStep, typed config, and ordered use* helpers.
+order: 10
+---
+
+# Archipel Bootstrap Pattern
+
+## Overview
+
+Application startup is an ordered pipeline. The Nest application is created by the consuming app, then passed into `PlatformApplication.from(app)` so reusable startup concerns can be composed as `PlatformBootstrapStep` functions.
+
+This pattern keeps platform defaults reusable without hiding the HTTP adapter, serverless shape, or application type chosen by the consuming app.
+
+## Canonical Shape
+
+```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 main(): 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 main();
+```
+
+## Step Contract
+
+A `PlatformBootstrapStep` receives a `PlatformBootstrapContext` and a `next` callback. The step may configure the app, resolve services from the app container, and then continue the pipeline.
+
+```typescript
+import { PlatformBootstrapStep } from '@breadstone/archipel-platform-bootstrap';
+
+export function useRequestLogging(): PlatformBootstrapStep {
+  return async function requestLoggingStep(context, next): Promise<void> {
+    context.app.use((request, response, nextMiddleware): void => {
+      response.setHeader('x-platform', 'archipel');
+      nextMiddleware();
+    });
+
+    await next();
+  };
+}
+```
+
+A step should call `await next()` exactly once unless it intentionally terminates startup because of a validation or configuration failure.
+
+## Naming Rules
+
+| Artifact | Rule | Example |
+| -------- | ---- | ------- |
+| Step factory | Starts with `use` and describes the application concern. | `useSecurity()` |
+| Options interface | Uses the same concern name and ends with `StepOptions`. | `ISecurityStepOptions` |
+| Step function name | Describes the runtime work and ends with `Step`. | `securityStep` |
+| Import path | Uses the package root for core types and subpaths for optional concerns. | `@breadstone/archipel-platform-bootstrap/security` |
+
+Do not introduce alternative public names for the same concept. The shared vocabulary is `PlatformApplication`, `PlatformApplicationBuilder`, `PlatformBootstrapContext`, `PlatformBootstrapStep`, and `use*` helpers.
+
+## Ordering Rules
+
+Recommended HTTP API order:
+
+1. `useApi()` for prefix, validation, and global filters.
+2. `useExpressServer()` for parsers and compression.
+3. `useSecurity()` for CORS, Helmet, content security policy, and rate limiting.
+4. `useSession()` when route handlers or guards need session state.
+5. `useOpenApi()` after modules and decorators are loaded.
+6. Application-specific steps placed next to the platform step they affect.
+
+The builder executes once. Calling `initialize()`, `run()`, `listen()`, or `listenFromConfig()` reuses the same execution promise, which prevents duplicate middleware registration during concurrent startup paths.
+
+## Configuration Rules
+
+- Define config keys with `createConfigKey<T>()` in `env.ts`.
+- Export grouped config entry arrays, such as `PLATFORM_SERVER_CONFIG_ENTRIES`.
+- Register those entries through `ConfigModule.register()` in the root module.
+- Resolve config through `ConfigService` inside steps, never through direct environment access.
+- Let required entries fail during startup instead of failing on the first request.
+
+## Custom Step Template
+
+```typescript
+import { INestApplication } from '@nestjs/common';
+import { PlatformBootstrapStep } from '@breadstone/archipel-platform-bootstrap';
+
+export interface IShutdownHooksStepOptions {
+  readonly signals?: ReadonlyArray<string>;
+}
+
+export function useShutdownHooks<TApplication extends INestApplication = INestApplication>(
+  options?: IShutdownHooksStepOptions,
+): PlatformBootstrapStep<TApplication> {
+  return async function shutdownHooksStep(context, next): Promise<void> {
+    context.app.enableShutdownHooks(options?.signals);
+    await next();
+  };
+}
+```
+
+Use a generic `TApplication extends INestApplication` when a step needs to preserve the concrete application type. Keep options immutable and optional unless the step cannot operate safely without them.
+
+## Testing Rules
+
+Use the testing subpath for composition tests:
+
+```typescript
+import { expect, it } from 'vitest';
+import { PlatformApplication, useApi } from '@breadstone/archipel-platform-bootstrap';
+import { createPlatformTestApplication } from '@breadstone/archipel-platform-bootstrap/testing';
+
+it('initializes after applying bootstrap steps', async (): Promise<void> => {
+  const app = createPlatformTestApplication();
+
+  await PlatformApplication.from(app)
+    .use(useApi({ prefix: 'api' }))
+    .initialize();
+
+  expect(app.calls).toEqual(expect.arrayContaining(['setGlobalPrefix', 'useGlobalPipes', 'init']));
+});
+```
+
+Use a real Nest app with Supertest when validating HTTP middleware behavior, route responses, cookies, or Swagger endpoints.
+
+## Checklist
+
+- `NestFactory` remains in the consuming entrypoint.
+- Startup concerns are added through `.use(useSomething())`.
+- Step option interfaces are named `I*StepOptions`.
+- Steps call `await next()` once in the normal path.
+- Config entries are registered before the builder reads them.
+- Swagger-compatible content security policy is enabled when OpenAPI UI is served.
+- Tests cover step order and failure behavior for custom steps.

package/data/patterns/index.md

@@ -0,0 +1,21 @@
+---
+title: Patterns
+description: Reusable implementation patterns for Archipel platform libraries and applications.
+---
+
+# Patterns
+
+These patterns document repeatable implementation shapes used across Archipel. Use them when adding platform library code, application integration code, or AI-assisted scaffolding that must follow repository conventions.
+
+| Pattern | What it covers |
+| ------- | -------------- |
+| [Configuration Pattern](./config-pattern) | Typed config keys, registry entries, and `ConfigModule` integration. |
+| [DTO & Validation Pattern](./dto-pattern) | Request and response classes, validation decorators, and OpenAPI metadata. |
+| [Error Handling Pattern](./error-handling-pattern) | Domain errors, exception filters, and structured error envelopes. |
+| [Guard & Interceptor Pattern](./guard-pattern) | Metadata decorators, guards, interceptors, and request enforcement. |
+| [Mapping Pattern](./mapping-pattern) | Type-safe mapping keys, profiles, and `MappingService` usage. |
+| [Dynamic Module Pattern](./module-pattern) | NestJS dynamic module registration and dependency wiring. |
+| [Query Pattern](./query-pattern) | Repository query objects and transactional query execution. |
+| [Repository Pattern](./repository-pattern) | `RepositoryBase` subclasses and Prisma delegate isolation. |
+| [Testing Pattern](./testing-pattern) | Vitest structure, mocks, and integration test conventions. |
+| [Bootstrap Pattern](./bootstrap-pattern) | Composable NestJS startup with `PlatformApplication` and `PlatformBootstrapStep`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "description": "MCP server providing Archipel platform knowledge - documentation, query patterns, and coding conventions - to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",
@@ -33,7 +33,7 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "gray-matter": "4.0.3",
     "tslib": "2.8.1",
-    "zod": "4.3.6"
+    "zod": "4.4.3"
   },
   "types": "./src/main.d.ts"
 }