@breadstone/archipel-mcp 0.0.23 → 0.0.25

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

@@ -0,0 +1,168 @@
+---
+title: platform-queue
+description: Provider-agnostic queue infrastructure with support for in-memory FIFO, BullMQ (Redis), and Azure Service Bus.
+order: 19
+tags: [queue, job-queue, fifo, memory-queue, bullmq, redis, azure-service-bus, ports-and-adapters, health]
+package: '@breadstone/archipel-platform-queue'
+---
+
+# platform-queue
+
+Provider-agnostic queue infrastructure for NestJS. Exposes a unified `IQueue` contract with three ready-made implementations: in-memory FIFO (`MemoryQueue`), BullMQ/Redis (`BullMqQueue`), and Azure Service Bus (`AzureQueue`). Jobs follow a lifecycle from pending through processing to completed or failed, with full metadata tracking.
+
+**Package:** `@breadstone/archipel-platform-queue`
+
+## Architecture
+
+```mermaid
+graph TD
+    Core["@breadstone/archipel-platform-queue<br/><i>IQueue, models, errors, MemoryQueue</i>"]
+    BullMQ["@breadstone/archipel-platform-queue/bullmq<br/><i>BullMqQueue</i>"]
+    Azure["@breadstone/archipel-platform-queue/azure<br/><i>AzureQueue</i>"]
+
+    BullMQ -->|implements| Core
+    Azure -->|implements| Core
+
+    BullMQ -.-|requires| R["bullmq"]
+    Azure -.-|requires| S["@azure/service-bus"]
+```
+
+Each provider SDK is an **optional peer dependency**. Install only the one you need. `MemoryQueue` ships with the core entry point and requires no additional dependencies.
+
+---
+
+## Quick Start
+
+### 1. Install the provider SDK (optional)
+
+```bash
+# Pick one (or use MemoryQueue without any extra SDK):
+yarn add bullmq
+yarn add @azure/service-bus
+```
+
+### 2. Register the queue
+
+```typescript
+import { Module } from '@nestjs/common';
+import { IQueue, MemoryQueue } from '@breadstone/archipel-platform-queue';
+
+@Module({
+  providers: [
+    {
+      provide: 'IQueue',
+      useFactory: () => new MemoryQueue({ maxJobs: 5_000 }),
+    },
+  ],
+  exports: ['IQueue'],
+})
+export class AppModule {}
+```
+
+### Switching providers
+
+Replace the imports — no other code change needed:
+
+```typescript
+import { BullMqQueue } from '@breadstone/archipel-platform-queue/bullmq';
+
+{
+  provide: 'IQueue',
+  useFactory: () => new BullMqQueue({ redisUrl: 'redis://localhost:6379' }),
+}
+```
+
+---
+
+## Queue Providers
+
+### Memory (built-in)
+
+**Entry point:** `@breadstone/archipel-platform-queue`
+
+| Variable         | Required | Default | Description                           |
+| ---------------- | -------- | ------- | ------------------------------------- |
+| `QUEUE_MAX_JOBS` | No       | `10000` | Maximum jobs retained before eviction |
+
+### BullMQ
+
+**Subpath:** `@breadstone/archipel-platform-queue/bullmq`
+**SDK:** `bullmq` ≥ 5.0.0
+
+| Variable          | Required | Default | Description                                  |
+| ----------------- | -------- | ------- | -------------------------------------------- |
+| `BULLMQ_REDIS_URL`| Yes      | —       | Redis connection URL (e.g. `redis://localhost:6379`) |
+| `BULLMQ_PREFIX`   | No       | `""`    | Optional key prefix for all BullMQ queues    |
+
+```typescript
+import { BullMqQueue, BULLMQ_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/bullmq';
+```
+
+### Azure Service Bus
+
+**Subpath:** `@breadstone/archipel-platform-queue/azure`
+**SDK:** `@azure/service-bus` ≥ 7.0.0
+
+| Variable                  | Required | Default | Description                              |
+| ------------------------- | -------- | ------- | ---------------------------------------- |
+| `AZURE_CONNECTION_STRING` | Yes      | —       | Azure Service Bus connection string      |
+| `AZURE_RECEIVE_WAIT_MS`  | No       | `5000`  | Max wait time (ms) when receiving messages|
+
+```typescript
+import { AzureQueue, AZURE_CONFIG_ENTRIES } from '@breadstone/archipel-platform-queue/azure';
+```
+
+---
+
+## Job Lifecycle
+
+| Status       | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| `pending`    | Job is waiting to be picked up                       |
+| `processing` | Job has been dequeued and is being processed         |
+| `completed`  | Job finished successfully via `markCompleted()`      |
+| `failed`     | Job finished with an error via `markFailed()`        |
+
+---
+
+## Error Handling
+
+| Error Class             | Base Class   | When Thrown                                    |
+| ----------------------- | ------------ | ---------------------------------------------- |
+| `QueueError`            | `Error`      | Base class for all queue errors                |
+| `QueueJobNotFoundError` | `QueueError` | Job ID does not exist                          |
+| `QueueJobStateError`    | `QueueError` | Job is in wrong state for requested transition |
+| `QueueValidationError`  | `QueueError` | Empty queue name or error message              |
+
+---
+
+## Health Check
+
+The `QueueHealthIndicator` reports the queue subsystem as available. Import it from the `/health` subpath:
+
+```typescript
+import { QueueHealthIndicator } from '@breadstone/archipel-platform-queue/health';
+import { HealthModule } from '@breadstone/archipel-platform-health';
+
+@Module({
+  imports: [
+    QueueModule.register({ /* ... */ }),
+    HealthModule.withIndicators([QueueHealthIndicator]),
+  ],
+})
+export class AppModule {}
+```
+
+| Key | Check | Dependencies |
+| --- | ----- | ------------ |
+| `queue` | Always reports `up` | None |
+
+---
+
+## Peer Dependencies
+
+| Package              | Required | Notes                            |
+| -------------------- | -------- | -------------------------------- |
+| `@nestjs/common`    | Yes      | NestJS core                      |
+| `bullmq`            | Optional | Required for BullMQ provider     |
+| `@azure/service-bus` | Optional | Required for Azure Service Bus   |

package/data/packages/platform-resources/api/Class.BlobResourceStrategy.md

@@ -0,0 +1,195 @@
+---
+title: 'Class: BlobResourceStrategy'
+generated: true
+editUrl: false
+---
+# Class: BlobResourceStrategy
+
+Defined in: [strategies/BlobResourceStrategy.ts:47](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L47)
+
+Strategy for loading resources from blob storage.
+
+## Implements
+
+- [`IResourceStrategy`](Interface.IResourceStrategy)
+
+## Constructors
+
+### Constructor
+
+```ts
+new BlobResourceStrategy(blobService, config?): BlobResourceStrategy;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:63](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L63)
+
+Constructs a new instance of the `BlobResourceStrategy` class.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `blobService` | [`IBlobServiceAdapter`](Interface.IBlobServiceAdapter) |
+| `config` | [`IBlobResourceStrategyConfig`](Interface.IBlobResourceStrategyConfig) |
+
+#### Returns
+
+`BlobResourceStrategy`
+
+## Accessors
+
+### name
+
+#### Get Signature
+
+```ts
+get name(): string;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:72](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L72)
+
+The unique name of this strategy.
+
+##### Returns
+
+`string`
+
+The unique name of this strategy.
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`name`](Interface.IResourceStrategy#name)
+
+## Methods
+
+### exists()
+
+```ts
+exists(key): boolean;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:136](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L136)
+
+Checks if a resource exists without loading it.
+Note: Blob storage is inherently async, so this delegates to existsAsync internally.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`boolean`
+
+True if the resource exists
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`exists`](Interface.IResourceStrategy#exists)
+
+***
+
+### existsAsync()
+
+```ts
+existsAsync(key): Promise<boolean>;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:147](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L147)
+
+Checks if a resource exists without loading it (asynchronous).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+Promise resolving to true if the resource exists
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`existsAsync`](Interface.IResourceStrategy#existsasync)
+
+***
+
+### load()
+
+```ts
+load(key): IResourceResult | undefined;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:88](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L88)
+
+Loads a resource by its key.
+Note: Blob storage is inherently async, so this delegates to loadAsync internally.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+[`IResourceResult`](Interface.IResourceResult) \| `undefined`
+
+The resource result or undefined if not found
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`load`](Interface.IResourceStrategy#load)
+
+***
+
+### loadAsync()
+
+```ts
+loadAsync(key): Promise<IResourceResult | undefined>;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:99](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L99)
+
+Loads a resource by its key (asynchronous).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`Promise`\<[`IResourceResult`](Interface.IResourceResult) \| `undefined`\>
+
+Promise resolving to the resource result or undefined if not found
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`loadAsync`](Interface.IResourceStrategy#loadasync)
+
+***
+
+### whatDoIHave()
+
+```ts
+whatDoIHave(): void;
+```
+
+Defined in: [strategies/BlobResourceStrategy.ts:163](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/BlobResourceStrategy.ts#L163)
+
+List all files and folders in the base paths for debugging purposes.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`whatDoIHave`](Interface.IResourceStrategy#whatdoihave)

package/data/packages/platform-resources/api/Class.EmbeddedResourceStrategy.md

@@ -0,0 +1,215 @@
+---
+title: 'Class: EmbeddedResourceStrategy'
+generated: true
+editUrl: false
+---
+# Class: EmbeddedResourceStrategy
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:14](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L14)
+
+Strategy for loading embedded resources from memory.
+
+## Implements
+
+- [`IResourceStrategy`](Interface.IResourceStrategy)
+
+## Constructors
+
+### Constructor
+
+```ts
+new EmbeddedResourceStrategy(resources?): EmbeddedResourceStrategy;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:29](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L29)
+
+Constructs a new instance of the `EmbeddedResourceStrategy` class.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `resources` | `Record`\<`string`, `string`\> |
+
+#### Returns
+
+`EmbeddedResourceStrategy`
+
+## Accessors
+
+### name
+
+#### Get Signature
+
+```ts
+get name(): string;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:37](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L37)
+
+The unique name of this strategy.
+
+##### Returns
+
+`string`
+
+The unique name of this strategy.
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`name`](Interface.IResourceStrategy#name)
+
+## Methods
+
+### exists()
+
+```ts
+exists(key): boolean;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:93](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L93)
+
+Checks if a resource exists without loading it.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`boolean`
+
+True if the resource exists
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`exists`](Interface.IResourceStrategy#exists)
+
+***
+
+### existsAsync()
+
+```ts
+existsAsync(key): Promise<boolean>;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:104](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L104)
+
+Checks if a resource exists without loading it (asynchronous).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+Promise resolving to true if the resource exists
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`existsAsync`](Interface.IResourceStrategy#existsasync)
+
+***
+
+### load()
+
+```ts
+load(key): IResourceResult | undefined;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:52](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L52)
+
+Loads a resource by its key.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+[`IResourceResult`](Interface.IResourceResult) \| `undefined`
+
+The resource result or undefined if not found
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`load`](Interface.IResourceStrategy#load)
+
+***
+
+### loadAsync()
+
+```ts
+loadAsync(key): Promise<IResourceResult | undefined>;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:82](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L82)
+
+Loads a resource by its key (asynchronous).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+
+#### Returns
+
+`Promise`\<[`IResourceResult`](Interface.IResourceResult) \| `undefined`\>
+
+Promise resolving to the resource result or undefined if not found
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`loadAsync`](Interface.IResourceStrategy#loadasync)
+
+***
+
+### register()
+
+```ts
+register(key, content): void;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:115](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L115)
+
+Registers a new embedded resource.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `key` | `string` | The resource key |
+| `content` | `string` | The resource content |
+
+#### Returns
+
+`void`
+
+***
+
+### whatDoIHave()
+
+```ts
+whatDoIHave(): void;
+```
+
+Defined in: [strategies/EmbeddedResourceStrategy.ts:124](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-resources/src/strategies/EmbeddedResourceStrategy.ts#L124)
+
+List all files and folders in the base paths for debugging purposes.
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+[`IResourceStrategy`](Interface.IResourceStrategy).[`whatDoIHave`](Interface.IResourceStrategy#whatdoihave)