@breadstone/archipel-mcp 0.0.46 → 0.0.47

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

@@ -5,7 +5,7 @@ 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)
+Defined in: [application/PlatformApplicationBuilder.ts:99](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L99)
 
 Fluent builder that composes NestJS bootstrap steps and executes them once.
 
@@ -23,7 +23,7 @@ Fluent builder that composes NestJS bootstrap steps and executes them once.
 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)
+Defined in: [application/PlatformApplicationBuilder.ts:111](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L111)
 
 #### Parameters
 
@@ -46,7 +46,7 @@ Defined in: [application/PlatformApplicationBuilder.ts:28](https://github.com/Ru
 get app(): TApplication;
 ```
 
-Defined in: [application/PlatformApplicationBuilder.ts:44](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L44)
+Defined in: [application/PlatformApplicationBuilder.ts:205](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L205)
 
 The wrapped NestJS application.
 
@@ -56,13 +56,80 @@ The wrapped NestJS application.
 
 ## Methods
 
+### createWithComposition()
+
+```ts
+static createWithComposition<TApp>(composer, options?): Promise<PlatformApplicationBuilder<TApp>>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:163](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L163)
+
+Creates a new application builder using composition-based module assembly.
+
+This factory bootstraps a lightweight composition context to read configuration
+values, then invokes the provided composer function to determine which modules
+to import. The resulting modules are assembled into a dynamic root module
+and a NestJS application is created from it.
+
+The composition context is automatically closed after the composer function completes.
+
+#### Type Parameters
+
+| Type Parameter | Default type | Description |
+| ------ | ------ | ------ |
+| `TApp` *extends* `INestApplication`\<`any`\> | `INestApplication`\<`any`\> | The NestJS application type. Defaults to INestApplication. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `composer` | (`context`) => \| [`CompositionImport`](TypeAlias.CompositionImport)[] \| `Promise`\<[`CompositionImport`](TypeAlias.CompositionImport)[]\> | A function that receives the composition context and returns an array of modules to import. |
+| `options?` | [`ICreateWithCompositionOptions`](Interface.ICreateWithCompositionOptions)\<`TApp`\> | Options for creating the composed application. |
+
+#### Returns
+
+`Promise`\<`PlatformApplicationBuilder`\<`TApp`\>\>
+
+A promise that resolves to a configured PlatformApplicationBuilder.
+
+#### Example
+
+```typescript
+import { PlatformApplicationBuilder } from '@breadstone/archipel-platform-bootstrap';
+import { ExpressAdapter, NestExpressApplication } from '@nestjs/platform-express';
+
+const builder = await PlatformApplicationBuilder.createWithComposition<NestExpressApplication>(
+    async (context) => {
+        const imports: CompositionImport[] = [AppModule];
+
+        const driver = context.tryGetConfigValue({ key: 'MAIL_DRIVER' }, 'log');
+        if (driver === 'smtp') {
+            const { MailModule } = await import('@breadstone/archipel-platform-mailing');
+            const { SmtpDeliveryStrategy } = await import('@breadstone/archipel-platform-mailing/delivering/smtp');
+            imports.push(MailModule.register({ deliveryStrategy: SmtpDeliveryStrategy }));
+        }
+
+        return imports;
+    },
+    {
+        appFactory: (module) => NestFactory.create<NestExpressApplication>(module, new ExpressAdapter()),
+    }
+);
+
+await builder
+    .use(useApi({ prefix: 'api' }))
+    .listenFromConfig({ fallbackPort: 3000 });
+```
+
+***
+
 ### 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)
+Defined in: [application/PlatformApplicationBuilder.ts:231](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L231)
 
 Executes the configured bootstrap pipeline and initializes the NestJS application.
 
@@ -80,7 +147,7 @@ The wrapped NestJS application.
 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)
+Defined in: [application/PlatformApplicationBuilder.ts:255](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L255)
 
 Executes the pipeline and starts the NestJS listener on the given port.
 
@@ -105,7 +172,7 @@ The wrapped NestJS application.
 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)
+Defined in: [application/PlatformApplicationBuilder.ts:274](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L274)
 
 Executes the pipeline and starts the listener using typed configuration keys.
 
@@ -129,7 +196,7 @@ The wrapped NestJS application.
 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)
+Defined in: [application/PlatformApplicationBuilder.ts:243](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L243)
 
 Executes the configured bootstrap pipeline without starting a listener.
 
@@ -147,7 +214,7 @@ The bootstrap context used for the execution.
 use(step): this;
 ```
 
-Defined in: [application/PlatformApplicationBuilder.ts:59](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L59)
+Defined in: [application/PlatformApplicationBuilder.ts:220](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L220)
 
 Adds a bootstrap step to the application pipeline.
 

package/data/packages/platform-bootstrap/api/Function.createCompositionContext.md

@@ -0,0 +1,56 @@
+---
+title: 'Function: createCompositionContext()'
+generated: true
+editUrl: false
+---
+# Function: createCompositionContext()
+
+```ts
+function createCompositionContext(options?): Promise<ICompositionContext>;
+```
+
+Defined in: composition/factory/createCompositionContext.ts:88
+
+Creates a temporary NestJS context for stage-aware module composition.
+
+This function bootstraps a minimal NestJS application context that provides
+access to configuration. Use this context to make decisions about which
+modules should be dynamically imported into the real application.
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `options?` | [`ICreateCompositionContextOptions`](Interface.ICreateCompositionContextOptions) | Optional configuration for the composition context. |
+
+## Returns
+
+`Promise`\<[`ICompositionContext`](Interface.ICompositionContext)\>
+
+A promise that resolves to the composition context.
+
+## Remarks
+
+The composition context must be closed after the real application has been
+created by calling [ICompositionContext.close](Interface.ICompositionContext#close). Use a try/finally block
+to ensure proper cleanup.
+
+## Example
+
+```typescript
+async function bootstrap(): Promise<void> {
+    const composition = await createCompositionContext();
+
+    try {
+        const appModule = await createAppModule(composition);
+        const app = await NestFactory.create(appModule);
+
+        await PlatformApplicationBuilder
+            .from(app)
+            .use(useApi({ ... }))
+            .listenFromConfig();
+    } finally {
+        await composition.close();
+    }
+}
+```

package/data/packages/platform-bootstrap/api/Interface.ICompositionContext.md

@@ -0,0 +1,179 @@
+---
+title: 'Interface: ICompositionContext'
+generated: true
+editUrl: false
+---
+# Interface: ICompositionContext
+
+Defined in: composition/context/ICompositionContext.ts:35
+
+Pre-bootstrap context for stage-aware module composition.
+
+This context is created before the main application module graph is built.
+It provides access to configuration and lightweight composition services
+that help determine which modules should be dynamically imported.
+
+## Remarks
+
+The composition context uses a temporary NestJS application context internally.
+This context must be closed after the real application has been created by
+calling [ICompositionContext.close](#close).
+
+## Example
+
+```typescript
+const composition = await createCompositionContext();
+
+try {
+    const appModule = await createAppModule(composition);
+    const app = await NestFactory.create(appModule);
+    await app.listen(3000);
+} finally {
+    await composition.close();
+}
+```
+
+## Properties
+
+### config
+
+```ts
+readonly config: ConfigService;
+```
+
+Defined in: composition/context/ICompositionContext.ts:53
+
+The Archipel configuration service.
+
+Provides typed access to environment configuration values.
+
+***
+
+### context
+
+```ts
+readonly context: INestApplicationContext;
+```
+
+Defined in: composition/context/ICompositionContext.ts:44
+
+The temporary NestJS application context.
+
+Used only for dependency injection resolution during composition.
+Do not use this context for runtime services.
+
+## Methods
+
+### close()
+
+```ts
+close(): Promise<void>;
+```
+
+Defined in: composition/context/ICompositionContext.ts:100
+
+Closes the temporary composition context.
+
+Must be called after the real application has been created to release
+resources held by the composition context.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the context is closed.
+
+***
+
+### getConfigValue()
+
+```ts
+getConfigValue<T>(key): T;
+```
+
+Defined in: composition/context/ICompositionContext.ts:65
+
+Reads a required configuration value.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The expected type of the configuration value. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `IConfigKey`\<`T`\> | The typed configuration key. |
+
+#### Returns
+
+`T`
+
+The typed configuration value.
+
+#### Throws
+
+When the configuration key is not found.
+
+***
+
+### getService()
+
+```ts
+getService<T>(token): T;
+```
+
+Defined in: composition/context/ICompositionContext.ts:88
+
+Resolves a provider from the composition context.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The type of the provider. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `token` | (...`args`) => `T` | The provider token (class, string, or symbol). |
+
+#### Returns
+
+`T`
+
+The resolved provider instance.
+
+***
+
+### tryGetConfigValue()
+
+```ts
+tryGetConfigValue<T>(key, fallback): T;
+```
+
+Defined in: composition/context/ICompositionContext.ts:77
+
+Reads an optional configuration value with a fallback.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` | The expected type of the configuration value. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `IConfigKey`\<`T`\> | The typed configuration key. |
+| `fallback` | `T` | The fallback value when the key is absent. |
+
+#### Returns
+
+`T`
+
+The typed configuration value or the fallback.

package/data/packages/platform-bootstrap/api/Interface.ICreateCompositionContextOptions.md

@@ -0,0 +1,54 @@
+---
+title: 'Interface: ICreateCompositionContextOptions'
+generated: true
+editUrl: false
+---
+# Interface: ICreateCompositionContextOptions
+
+Defined in: composition/factory/createCompositionContext.ts:17
+
+Options for creating the composition context.
+
+## Properties
+
+### enableLogging?
+
+```ts
+readonly optional enableLogging?: boolean;
+```
+
+Defined in: composition/factory/createCompositionContext.ts:49
+
+Whether to enable logging for the composition context.
+
+Defaults to `false` to keep composition silent.
+
+***
+
+### module?
+
+```ts
+readonly optional module?: Type<unknown>;
+```
+
+Defined in: composition/factory/createCompositionContext.ts:40
+
+Custom composition module to use instead of the default [CompositionModule](Class.CompositionModule).
+
+Use this to provide application-specific composition services such as
+custom [CompositionResolver](Class.CompositionResolver) implementations.
+
+#### Example
+
+```typescript
+@Module({
+    imports: [ConfigModule.forRoot({ strategyFactory: () => new EnvironmentConfigStrategy() })],
+    providers: [AppCompositionResolver],
+    exports: [ConfigModule, AppCompositionResolver]
+})
+export class AppCompositionModule {}
+
+const context = await createCompositionContext({
+    module: AppCompositionModule
+});
+```

package/data/packages/platform-bootstrap/api/Interface.ICreateWithCompositionOptions.md

@@ -0,0 +1,128 @@
+---
+title: 'Interface: ICreateWithCompositionOptions\<TApplication\>'
+generated: true
+editUrl: false
+---
+# Interface: ICreateWithCompositionOptions\<TApplication\>
+
+Defined in: [application/PlatformApplicationBuilder.ts:22](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L22)
+
+Options for creating a composed application.
+
+## Type Parameters
+
+| Type Parameter | Default type |
+| ------ | ------ |
+| `TApplication` *extends* `INestApplication` | `INestApplication` |
+
+## Properties
+
+### adapter?
+
+```ts
+readonly optional adapter?: unknown;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:70](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L70)
+
+Custom HTTP adapter to use.
+
+#### Example
+
+```typescript
+import { ExpressAdapter } from '@nestjs/platform-express';
+
+const builder = await PlatformApplicationBuilder.createWithComposition({
+    adapter: new ExpressAdapter(),
+    // ...
+});
+```
+
+***
+
+### appFactory?
+
+```ts
+readonly optional appFactory?: (composedModule) => Promise<TApplication>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:91](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L91)
+
+Factory function that creates the application type.
+
+If provided, this takes precedence over the default `NestFactory.create()` call.
+Use this for custom application types or adapters.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `composedModule` | `DynamicModule` |
+
+#### Returns
+
+`Promise`\<`TApplication`\>
+
+#### Example
+
+```typescript
+const builder = await PlatformApplicationBuilder.createWithComposition({
+    appFactory: (module) => NestFactory.create<NestExpressApplication>(
+        module,
+        new ExpressAdapter()
+    ),
+    // ...
+});
+```
+
+***
+
+### compositionModule?
+
+```ts
+readonly optional compositionModule?: Type<unknown>;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:30](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L30)
+
+Custom composition module that provides the composition services.
+
+If not provided, the default [CompositionModule](Class.CompositionModule) is used.
+
+***
+
+### enableCompositionLogging?
+
+```ts
+readonly optional enableCompositionLogging?: boolean;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:39](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L39)
+
+Whether to enable logging for the composition context.
+
+Defaults to `false`.
+
+***
+
+### nestOptions?
+
+```ts
+readonly optional nestOptions?: NestApplicationOptions;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:46](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L46)
+
+NestJS application options passed to `NestFactory.create()`.
+
+***
+
+### platformOptions?
+
+```ts
+readonly optional platformOptions?: IPlatformApplicationOptions;
+```
+
+Defined in: [application/PlatformApplicationBuilder.ts:53](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-bootstrap/src/application/PlatformApplicationBuilder.ts#L53)
+
+Platform application options for the builder.

package/data/packages/platform-bootstrap/api/Interface.IProviderDecision.md

@@ -0,0 +1,36 @@
+---
+title: 'Interface: IProviderDecision'
+generated: true
+editUrl: false
+---
+# Interface: IProviderDecision
+
+Defined in: composition/types/IProviderDecision.ts:12
+
+Represents the result of a provider composition decision.
+
+## Properties
+
+### imports
+
+```ts
+readonly imports: readonly CompositionImport[];
+```
+
+Defined in: composition/types/IProviderDecision.ts:27
+
+The modules to import when [shouldImport](#shouldimport) is `true`.
+
+When [shouldImport](#shouldimport) is `false`, this array should be empty or omitted.
+
+***
+
+### shouldImport
+
+```ts
+readonly shouldImport: boolean;
+```
+
+Defined in: composition/types/IProviderDecision.ts:18
+
+Whether the provider should be imported into the application module graph.

package/data/packages/platform-bootstrap/api/TypeAlias.CompositionImport.md

@@ -0,0 +1,20 @@
+---
+title: 'Type Alias: CompositionImport'
+generated: true
+editUrl: false
+---
+# Type Alias: CompositionImport
+
+```ts
+type CompositionImport = 
+  | Type<unknown>
+  | DynamicModule
+  | Promise<DynamicModule>
+| ForwardReference<unknown>;
+```
+
+Defined in: composition/types/CompositionImport.ts:14
+
+Represents a valid NestJS module import that can be used during composition.
+
+This type mirrors the allowed import types in NestJS module metadata.

package/data/packages/platform-bootstrap/api/TypeAlias.ProviderComposer.md

@@ -0,0 +1,53 @@
+---
+title: 'Type Alias: ProviderComposer\<TContext\>'
+generated: true
+editUrl: false
+---
+# Type Alias: ProviderComposer\<TContext\>
+
+```ts
+type ProviderComposer<TContext> = (context) => Promise<IProviderDecision>;
+```
+
+Defined in: composition/types/ProviderComposer.ts:37
+
+Function signature for a provider composer.
+
+A provider composer is responsible for determining which modules should be
+imported based on the current composition context (configuration, stage, etc.).
+
+## Type Parameters
+
+| Type Parameter | Default type | Description |
+| ------ | ------ | ------ |
+| `TContext` *extends* [`ICompositionContext`](Interface.ICompositionContext) | [`ICompositionContext`](Interface.ICompositionContext) | The composition context type. Defaults to [ICompositionContext](Interface.ICompositionContext). |
+
+## Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `context` | `TContext` |
+
+## Returns
+
+`Promise`\<[`IProviderDecision`](Interface.IProviderDecision)\>
+
+## Example
+
+```typescript
+const composeMailProvider: ProviderComposer = async (context) => {
+    const driver = context.config.tryGet('MAIL_DRIVER', 'log');
+
+    if (driver === 'smtp') {
+        const { MailModule } = await import('@breadstone/archipel-platform-mailing');
+        const { SmtpDeliveryStrategy } = await import('@breadstone/archipel-platform-mailing/delivering/smtp');
+
+        return {
+            shouldImport: true,
+            imports: [MailModule.register({ deliveryStrategy: SmtpDeliveryStrategy })]
+        };
+    }
+
+    return { shouldImport: false, imports: [] };
+};
+```