npm - @breadstone/archipel-mcp - Versions diffs - 0.0.21 → 0.0.23 - Mend

@breadstone/archipel-mcp 0.0.21 → 0.0.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (143) hide show

package/data/packages/platform-resources/index.md ADDED Viewed

@@ -0,0 +1,135 @@
+---
+title: platform-resources
+description: Multi-strategy resource management with MIME type detection and optional caching.
+order: 3
+tags: [resources, files, blob, mime, caching]
+package: '@breadstone/archipel-platform-resources'
+---
+# platform-resources
+Multi-strategy resource management for NestJS applications. Loads files from the file system, embedded buffers, or blob storage with MIME type detection and optional caching. Extracted from `platform-core` to provide a focused, independently versionable resource module.
+**Package:** `@breadstone/archipel-platform-resources`
+## Installation
+```typescript
+import {
+  ResourceModule,
+  ResourceManager,
+  FileResourceStrategy,
+  BlobResourceStrategy,
+  EmbeddedResourceStrategy,
+  ResourceNotFoundError,
+} from '@breadstone/archipel-platform-resources';
+```
+---
+## Module Registration
+Register the module with one or more resource strategies:
+```typescript
+import { Module } from '@nestjs/common';
+import { ResourceModule, FileResourceStrategy, EmbeddedResourceStrategy } from '@breadstone/archipel-platform-resources';
+import { join } from 'node:path';
+@Module({
+  imports: [
+    ResourceModule.forRoot({
+      strategies: [
+        new FileResourceStrategy({
+          basePath: join(__dirname, '..', 'assets'),
+        }),
+        new EmbeddedResourceStrategy([
+          { name: 'fallback.html', buffer: Buffer.from('<html>Fallback</html>') },
+        ]),
+      ],
+    }),
+  ],
+})
+export class AppModule {}
+```
+## Using ResourceManager
+Inject and use `ResourceManager` to load resources at runtime:
+```typescript
+import { Injectable } from '@nestjs/common';
+import { ResourceManager } from '@breadstone/archipel-platform-resources';
+@Injectable()
+export class TemplateService {
+  constructor(private readonly _resourceManager: ResourceManager) {}
+  public async loadTemplate(name: string): Promise<string> {
+    const result = await this._resourceManager.get(name);
+    return result.buffer.toString('utf-8');
+  }
+}
+```
+---
+## Strategies
+| Strategy                    | Description                                                       |
+| --------------------------- | ----------------------------------------------------------------- |
+| `FileResourceStrategy`     | Loads resources from the local file system with glob support       |
+| `BlobResourceStrategy`     | Loads resources from a blob storage adapter (Vercel, Azure, S3)    |
+| `EmbeddedResourceStrategy` | Serves pre-loaded in-memory buffers                                |
+### BlobResourceStrategy
+For loading resources from cloud blob storage, provide an adapter that implements `IBlobServiceAdapter`:
+```typescript
+import { BlobResourceStrategy, type IBlobServiceAdapter } from '@breadstone/archipel-platform-resources';
+const blobStrategy = new BlobResourceStrategy({
+  adapter: myBlobAdapter,
+  containerName: 'templates',
+});
+```
+### Custom Strategies
+Implement `IResourceStrategy` to create your own resource loading strategy:
+```typescript
+import type { IResourceStrategy, IResourceResult } from '@breadstone/archipel-platform-resources';
+export class CustomStrategy implements IResourceStrategy {
+  public async get(name: string): Promise<IResourceResult | undefined> {
+    // Custom loading logic
+  }
+}
+```
+---
+## Interfaces
+| Interface              | Description                              |
+| ---------------------- | ---------------------------------------- |
+| `IResourceResult`     | Result object with `buffer` and `metadata` |
+| `IResourceMetadata`   | Metadata including `mimeType` and `size`  |
+| `IResourceStrategy`   | Strategy contract for resource loading    |
+| `IBlobServiceAdapter`  | Adapter contract for blob storage access  |
+---
+## Error Classes
+| Error                    | Description                                   |
+| ------------------------ | --------------------------------------------- |
+| `ResourceNotFoundError` | Thrown when a requested resource is not found   |
+---
+## API Reference
+The auto-generated API reference is published when API docs are generated for this package.

package/data/packages/platform-telemetry/api/Class.OtelSdkHolder.md CHANGED Viewed

@@ -61,7 +61,7 @@ setSdk(sdk): void;
 Defined in: [OtelSdkHolder.ts:30](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/OtelSdkHolder.ts#L30)
 Stores the SDK reference so it can be shut down later.
-Can only be called once — subsequent calls are ignored.
+Can only be called once - subsequent calls are ignored.
 #### Parameters

package/data/packages/platform-telemetry/api/Variable.TELEMETRY_ENABLED.md CHANGED Viewed

@@ -9,4 +9,4 @@ editUrl: false
 const TELEMETRY_ENABLED: typeof TELEMETRY_ENABLED;
 ```
-Defined in: [tokens.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens.ts#L4)
+Defined in: [tokens/TelemetryTokens.ts:4](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens/TelemetryTokens.ts#L4)

package/data/packages/platform-telemetry/api/Variable.TELEMETRY_FACADE.md CHANGED Viewed

@@ -9,4 +9,4 @@ editUrl: false
 const TELEMETRY_FACADE: typeof TELEMETRY_FACADE;
 ```
-Defined in: [tokens.ts:3](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens.ts#L3)
+Defined in: [tokens/TelemetryTokens.ts:3](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens/TelemetryTokens.ts#L3)

package/data/packages/platform-telemetry/api/Variable.TELEMETRY_OPTIONS.md CHANGED Viewed

@@ -9,4 +9,4 @@ editUrl: false
 const TELEMETRY_OPTIONS: typeof TELEMETRY_OPTIONS;
 ```
-Defined in: [tokens.ts:2](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens.ts#L2)
+Defined in: [tokens/TelemetryTokens.ts:2](https://github.com/RueDeRennes/archipel/blob/main/libs/platform-telemetry/src/tokens/TelemetryTokens.ts#L2)

package/{src/knowledge/configPattern.js → data/patterns/config-pattern.md} RENAMED Viewed

@@ -1,46 +1,45 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel configuration pattern.
- * Returned by the get-config-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONFIG_PATTERN_KNOWLEDGE = void 0;
-exports.CONFIG_PATTERN_KNOWLEDGE = `# Archipel Configuration Pattern
+---
+title: Configuration Pattern
+description: Typed config keys, ConfigRegistry, ConfigService, env.ts conventions, and ConfigModule integration.
+order: 1
+---
+# Archipel Configuration Pattern
 ## Overview
 Archipel uses a **typed configuration key** system with a **central registry**.
-Each platform library declares its required and optional config keys in an \`env.ts\`
-file, which are registered into the global \`ConfigRegistry\`. At runtime, the
-\`ConfigService\` resolves values through a pluggable strategy (environment variables,
+Each platform library declares its required and optional config keys in an `env.ts`
+file, which are registered into the global `ConfigRegistry`. At runtime, the
+`ConfigService` resolves values through a pluggable strategy (environment variables,
 Azure App Configuration, etc.).
-**Rule:** No direct \`process.env\` access outside of config strategy implementations.
+**Rule:** No direct `process.env` access outside of config strategy implementations.
 ## Core Types
-### IConfigKey<TType>
+### `IConfigKey<TType>`
-\`\`\`typescript
+```typescript
 export interface IConfigKey<TType = unknown> {
   readonly _type?: TType;  // Phantom type for compile-time safety
   readonly key: string;     // The actual config key string
 }
-\`\`\`
+```
-### createConfigKey<TType>
+### `createConfigKey<TType>`
-\`\`\`typescript
+```typescript
 import { createConfigKey } from '@breadstone/archipel-platform-core';
 export const APP_URL = createConfigKey<string>('APP_URL');
 export const APP_PORT = createConfigKey<number>('APP_PORT');
 export const FEATURE_ENABLED = createConfigKey<boolean>('FEATURE_ENABLED');
-\`\`\`
+```
 ## ConfigService API
-\`\`\`typescript
+```typescript
 @Injectable()
 export class ConfigService {
@@ -54,18 +53,18 @@ export class ConfigService {
   public compare<T>(key: string, value: T): boolean;
 }
-\`\`\`
+```
 **Auto-parsing:** String values are automatically converted:
-- \`'true'\` / \`'false'\` → \`boolean\`
-- Numeric strings → \`number\`
-- Empty strings → \`null\`
+- `'true'` / `'false'` → `boolean`
+- Numeric strings → `number`
+- Empty strings → `null`
 ## ConfigRegistry
 A static global registry that collects all declared config keys at module initialization.
-\`\`\`typescript
+```typescript
 export class ConfigRegistry {
   // Register keys for a module
@@ -78,11 +77,11 @@ export class ConfigRegistry {
   public static getModules(): ReadonlyArray<string>;
 }
-\`\`\`
+```
 ### IConfigRegistryEntry
-\`\`\`typescript
+```typescript
 export interface IConfigRegistryEntry<TType = unknown> {
   readonly key: IConfigKey<TType>;
   readonly module: string;
@@ -90,13 +89,13 @@ export interface IConfigRegistryEntry<TType = unknown> {
   readonly defaultValue?: TType;
   readonly description?: string;
 }
-\`\`\`
+```
 ## How to Add Configuration to a Library
 ### Step 1: Define typed config keys in env.ts
-\`\`\`typescript
+```typescript
 // src/env.ts
 import { createConfigKey } from '@breadstone/archipel-platform-core';
 import { ConfigRegistry, IConfigRegistryEntry } from '@breadstone/archipel-platform-core';
@@ -118,25 +117,25 @@ export const PLATFORM_PAYMENTS_CONFIG_ENTRIES: ReadonlyArray<Omit<IConfigRegistr
   { key: STRIPE_WEBHOOK_SECRET, required: true, description: 'Stripe webhook signing secret.' },
   { key: PAYMENT_CURRENCY, required: false, defaultValue: 'EUR', description: 'Default payment currency.' },
 ];
-\`\`\`
+```
 ### Step 2: Register in ConfigModule
-\`\`\`typescript
+```typescript
 // In the module's register() method:
 imports: [ConfigModule.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES)]
-\`\`\`
+```
 Or for libraries without a dedicated module (self-registration):
-\`\`\`typescript
+```typescript
 // At the bottom of env.ts:
 ConfigRegistry.register('platform-payments', PLATFORM_PAYMENTS_CONFIG_ENTRIES);
-\`\`\`
+```
 ### Step 3: Use in services
-\`\`\`typescript
+```typescript
 @Injectable()
 export class StripeClient {
@@ -151,41 +150,41 @@ export class StripeClient {
   }
 }
-\`\`\`
+```
 ## ConfigModule
 ### register() — Per-library config registration
-Declares which config keys a library needs. Used in \`imports\` of feature modules.
+Declares which config keys a library needs. Used in `imports` of feature modules.
-\`\`\`typescript
+```typescript
 ConfigModule.register('platform-authentication', PLATFORM_AUTHENTICATION_CONFIG_ENTRIES)
-\`\`\`
+```
 ### forRoot() — Application bootstrap
 Configures the global strategy and static overrides. Used once in the root module.
-\`\`\`typescript
+```typescript
 ConfigModule.forRoot({
   strategyFactory: () => new EnvironmentConfigStrategy(),
   statics: { APP_VERSION: '1.0.0' },
 })
-\`\`\`
+```
 ## ConfigStrategyBase
 Pluggable strategy for resolving config values:
-\`\`\`typescript
+```typescript
 export abstract class ConfigStrategyBase {
   public abstract initialize(): void;
   public abstract resolve<T>(key: string): T;
   public abstract tryResolve<T>(key: string, fallback: T): T;
   public abstract has(key: string): boolean;
 }
-\`\`\`
+```
 Implementations can read from environment variables, Azure App Configuration, Consul, etc.
@@ -200,12 +199,10 @@ Implementations can read from environment variables, Azure App Configuration, Co
 ## Rules
-1. **All config keys defined via \`createConfigKey<T>()\`** — never raw \`process.env\` access.
-2. **Each library declares entries in \`env.ts\`** with required flag, default value, and description.
-3. **Registration via \`ConfigModule.register()\`** in the module, or self-registration for libraries without modules.
-4. **\`ConfigService.get()\` throws on missing required keys** — fail-fast at startup.
-5. **Use \`tryGet()\` with fallback** for optional keys.
+1. **All config keys defined via `createConfigKey<T>()`** — never raw `process.env` access.
+2. **Each library declares entries in `env.ts`** with required flag, default value, and description.
+3. **Registration via `ConfigModule.register()`** in the module, or self-registration for libraries without modules.
+4. **`ConfigService.get()` throws on missing required keys** — fail-fast at startup.
+5. **Use `tryGet()` with fallback** for optional keys.
 6. **Config key names use UPPER_SNAKE_CASE** matching environment variable conventions.
 7. **Group related keys** with comment separators in env.ts.
-`;
-//# sourceMappingURL=configPattern.js.map

package/{src/knowledge/dtoPattern.js → data/patterns/dto-pattern.md} RENAMED Viewed

@@ -1,24 +1,23 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel DTO & validation pattern.
- * Returned by the get-dto-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DTO_PATTERN_KNOWLEDGE = void 0;
-exports.DTO_PATTERN_KNOWLEDGE = `# Archipel DTO & Validation Pattern
+---
+title: DTO & Validation Pattern
+description: Request/Response DTOs, class-validator decorators, cross-field validation, query parameter DTOs, OpenAPI integration, and naming conventions.
+order: 2
+---
+# Archipel DTO & Validation Pattern
 ## Overview
 Archipel uses **class-based DTOs** with **class-validator** decorators for input validation
-and **class-transformer** decorators for serialization control. A global \`ValidationPipe\`
+and **class-transformer** decorators for serialization control. A global `ValidationPipe`
 enforces validation on all incoming requests automatically.
 Request DTOs validate input; Response classes define the output shape with
-\`@ApiProperty\` decorators for OpenAPI documentation.
+`@ApiProperty` decorators for OpenAPI documentation.
 ## Global Validation Pipe
-\`\`\`typescript
+```typescript
 // In main.ts bootstrap:
 app.useGlobalPipes(
   new ValidationPipe({
@@ -27,11 +26,11 @@ app.useGlobalPipes(
     transform: true,             // Auto-transform payloads to DTO instances
   }),
 );
-\`\`\`
+```
 ## Request DTO (Input Validation)
-\`\`\`typescript
+```typescript
 // dtos/CreateUserRequest.ts
 import { Expose } from 'class-transformer';
 import { IsEmail, IsString, MinLength, MaxLength } from 'class-validator';
@@ -58,11 +57,11 @@ export class CreateUserRequest {
   public password!: string;
 }
-\`\`\`
+```
 ## Response DTO (Output Shape)
-\`\`\`typescript
+```typescript
 // dtos/UserResponse.ts
 import { Expose } from 'class-transformer';
 import { ApiProperty } from '@nestjs/swagger';
@@ -88,7 +87,7 @@ export class UserResponse {
   // Note: password is intentionally NOT exposed
 }
-\`\`\`
+```
 ## Common Validators
@@ -96,48 +95,48 @@ export class UserResponse {
 | Decorator | Purpose |
 |-----------|---------|
-| \`@IsString()\` | Must be a string |
-| \`@IsNumber()\` | Must be a number |
-| \`@IsBoolean()\` | Must be a boolean |
-| \`@IsEmail()\` | Must be a valid email |
-| \`@IsUUID()\` | Must be a valid UUID |
-| \`@IsDate()\` | Must be a Date instance |
-| \`@IsEnum(MyEnum)\` | Must be a value from the enum |
-| \`@IsOptional()\` | Field is optional (skip validation if undefined) |
+| `@IsString()` | Must be a string |
+| `@IsNumber()` | Must be a number |
+| `@IsBoolean()` | Must be a boolean |
+| `@IsEmail()` | Must be a valid email |
+| `@IsUUID()` | Must be a valid UUID |
+| `@IsDate()` | Must be a Date instance |
+| `@IsEnum(MyEnum)` | Must be a value from the enum |
+| `@IsOptional()` | Field is optional (skip validation if undefined) |
 ### String Constraints
 | Decorator | Purpose |
 |-----------|---------|
-| \`@MinLength(n)\` | Minimum string length |
-| \`@MaxLength(n)\` | Maximum string length |
-| \`@Matches(regex)\` | Must match a regex pattern |
-| \`@IsNotEmpty()\` | Must not be empty string |
+| `@MinLength(n)` | Minimum string length |
+| `@MaxLength(n)` | Maximum string length |
+| `@Matches(regex)` | Must match a regex pattern |
+| `@IsNotEmpty()` | Must not be empty string |
 ### Number Constraints
 | Decorator | Purpose |
 |-----------|---------|
-| \`@Min(n)\` | Minimum value |
-| \`@Max(n)\` | Maximum value |
-| \`@IsPositive()\` | Must be > 0 |
-| \`@IsInt()\` | Must be integer |
+| `@Min(n)` | Minimum value |
+| `@Max(n)` | Maximum value |
+| `@IsPositive()` | Must be > 0 |
+| `@IsInt()` | Must be integer |
 ### Nested & Array
 | Decorator | Purpose |
 |-----------|---------|
-| \`@ValidateNested()\` | Validate nested objects |
-| \`@Type(() => Cls)\` | Transform to class instance (class-transformer) |
-| \`@IsArray()\` | Must be an array |
-| \`@ArrayMinSize(n)\` | Minimum array length |
-| \`@ArrayMaxSize(n)\` | Maximum array length |
+| `@ValidateNested()` | Validate nested objects |
+| `@Type(() => Cls)` | Transform to class instance (class-transformer) |
+| `@IsArray()` | Must be an array |
+| `@ArrayMinSize(n)` | Minimum array length |
+| `@ArrayMaxSize(n)` | Maximum array length |
 ## Cross-Field Validation
 For fields that depend on each other, use custom class-level validators:
-\`\`\`typescript
+```typescript
 import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments, Validate } from 'class-validator';
 @ValidatorConstraint({ name: 'Match', async: false })
@@ -153,7 +152,7 @@ export class MatchConstraint implements ValidatorConstraintInterface {
   public defaultMessage(args: ValidationArguments): string {
     const [relatedPropertyName] = args.constraints;
-    return \\\`\\\${args.property} must match \\\${relatedPropertyName}\\\`;
+    return `${args.property} must match ${relatedPropertyName}`;
   }
 }
@@ -172,13 +171,13 @@ export class ResetPasswordRequest {
   public confirmPassword!: string;
 }
-\`\`\`
+```
 ## Query Parameter DTOs
-For GET request query parameters, use \`@Transform()\` and \`@Type()\` for type coercion:
+For GET request query parameters, use `@Transform()` and `@Type()` for type coercion:
-\`\`\`typescript
+```typescript
 import { Type } from 'class-transformer';
 import { IsOptional, IsInt, Min, Max, IsString } from 'class-validator';
 import { ApiPropertyOptional } from '@nestjs/swagger';
@@ -206,13 +205,13 @@ export class PaginationQuery {
   public search?: string;
 }
-\`\`\`
+```
 ## OpenAPI / Swagger Integration
 ### @ApiProperty Decorators
-\`\`\`typescript
+```typescript
 @ApiProperty({
   description: 'User email address',
   example: 'user@example.com',
@@ -225,11 +224,11 @@ public email!: string;
   maxLength: 500,
 })
 public bio?: string;
-\`\`\`
+```
 ### Controller Response Decorators
-\`\`\`typescript
+```typescript
 @Controller('/users')
 @ApiTags('Users')
 export class UsersController {
@@ -244,23 +243,23 @@ export class UsersController {
   }
 }
-\`\`\`
+```
 ## Naming Conventions
 | Type | Naming Pattern | Example |
 |------|---------------|---------|
-| Create input | \`Create{Entity}Request\` | \`CreateUserRequest\` |
-| Update input | \`Update{Entity}Request\` | \`UpdateUserRequest\` |
-| Query params | \`{Entity}Query\` or \`Pagination{Entity}Query\` | \`UserQuery\` |
-| Response | \`{Entity}Response\` | \`UserResponse\` |
-| List response | \`{Entity}ListResponse\` | \`UserListResponse\` |
+| Create input | `Create{Entity}Request` | `CreateUserRequest` |
+| Update input | `Update{Entity}Request` | `UpdateUserRequest` |
+| Query params | `{Entity}Query` or `Pagination{Entity}Query` | `UserQuery` |
+| Response | `{Entity}Response` | `UserResponse` |
+| List response | `{Entity}ListResponse` | `UserListResponse` |
 ## Constants for Bounds
 Define and reuse constants for upper limits:
-\`\`\`typescript
+```typescript
 // constants/ValidationConstants.ts
 export const MAX_PAGE_SIZE = 100;
 export const MAX_SEARCH_LIMIT = 50;
@@ -270,17 +269,15 @@ export const MAX_BIO_LENGTH = 500;
 // In DTO:
 @Max(MAX_PAGE_SIZE)
 public perPage?: number;
-\`\`\`
+```
 ## Rules
-1. **Every field has \`@Expose()\`** for serialization control.
-2. **Every field has \`@ApiProperty()\`** for OpenAPI documentation.
+1. **Every field has `@Expose()`** for serialization control.
+2. **Every field has `@ApiProperty()`** for OpenAPI documentation.
 3. **Request DTOs use class-validator decorators** — validation is automatic via global pipe.
 4. **Response DTOs have no validation decorators** — they're output-only shapes.
 5. **Cross-field validation uses custom class-level validators** — never imperative checks in services.
-6. **Query parameters use \`@Type(() => Number)\`** for type coercion from strings.
-7. **Upper bounds (\`@Max\`, \`@MaxLength\`) defined as exported constants** — never inline magic numbers.
-8. **\`whitelist: true\` + \`forbidNonWhitelisted: true\`** strips and rejects unknown properties.
-`;
-//# sourceMappingURL=dtoPattern.js.map
+6. **Query parameters use `@Type(() => Number)`** for type coercion from strings.
+7. **Upper bounds (`@Max`, `@MaxLength`) defined as exported constants** — never inline magic numbers.
+8. **`whitelist: true` + `forbidNonWhitelisted: true`** strips and rejects unknown properties.