@breadstone/archipel-mcp 0.0.21 → 0.0.23

package/{src/knowledge/testingPattern.js → data/patterns/testing-pattern.md}

@@ -1,35 +1,34 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel testing pattern.
- * Returned by the get-testing-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.TESTING_PATTERN_KNOWLEDGE = void 0;
-exports.TESTING_PATTERN_KNOWLEDGE = `# Archipel Testing Pattern
+---
+title: Testing Pattern
+description: Vitest conventions, mocking patterns for repositories/services/delegates, AAA structure, and test naming conventions.
+order: 9
+---
+
+# Archipel Testing Pattern
 
 ## Overview
 
 Archipel uses **Vitest** for unit and integration tests with **vi mocking**. Tests follow
-the Arrange-Act-Assert (AAA) pattern with descriptive \`describe\`/\`it\` blocks. Each test
+the Arrange-Act-Assert (AAA) pattern with descriptive `describe`/`it` blocks. Each test
 file covers a single class or module.
 
 ## Test Framework
 
 - **Runner:** Vitest
-- **Mocking:** \`vi.fn()\`, \`vi.mock()\`, \`vi.spyOn()\`
-- **Assertions:** Vitest built-in (\`expect\`)
+- **Mocking:** `vi.fn()`, `vi.mock()`, `vi.spyOn()`
+- **Assertions:** Vitest built-in (`expect`)
 - **E2E:** Supertest against a bootstrapped NestJS app
 
 ## File Naming & Location
 
 | Test Type | File Pattern | Location |
 |-----------|-------------|----------|
-| Unit test | \`*.spec.ts\` | Next to the source file |
-| E2E test | \`*.e2e-spec.ts\` | \`test/\` directory |
+| Unit test | `*.spec.ts` | Next to the source file |
+| E2E test | `*.e2e-spec.ts` | `test/` directory |
 
 ## Basic Test Structure
 
-\`\`\`typescript
+```typescript
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 describe('UserService', () => {
@@ -88,13 +87,13 @@ describe('UserService', () => {
   // #endregion
 
 });
-\`\`\`
+```
 
 ## Mocking Patterns
 
 ### Mocking Prisma Delegates (for Repository Tests)
 
-\`\`\`typescript
+```typescript
 vi.mock('@prisma/client/runtime/client', () => ({
   PrismaClientKnownRequestError: class PrismaClientKnownRequestError extends Error {
     public code: string;
@@ -117,11 +116,11 @@ vi.mock('@prisma/client/runtime/client', () => ({
     }
   },
 }));
-\`\`\`
+```
 
 ### Creating a Mock Delegate
 
-\`\`\`typescript
+```typescript
 type MockDelegate = Record<
   | 'aggregate' | 'count' | 'create' | 'createMany' | 'createManyAndReturn'
   | 'delete' | 'deleteMany' | 'findFirst' | 'findFirstOrThrow'
@@ -150,31 +149,31 @@ function createMockDelegate(): MockDelegate {
     findUniqueOrThrow: vi.fn(),
   };
 }
-\`\`\`
+```
 
 ### Mocking DatabaseService
 
-\`\`\`typescript
+```typescript
 const mockDb = {
   transactionCallback: vi.fn(),
   client: {
     user: createMockDelegate(),
   },
 } as unknown as DatabaseService;
-\`\`\`
+```
 
 ### Mocking a Query
 
-\`\`\`typescript
+```typescript
 const mockQuery = {
   name: 'findUserById',
   run: vi.fn().mockResolvedValue({ id: '1', email: 'test@example.com' }),
 };
-\`\`\`
+```
 
 ## Repository Test Pattern
 
-\`\`\`typescript
+```typescript
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 // Mock Prisma runtime errors BEFORE importing test subject
@@ -228,11 +227,11 @@ describe('UserRepository', () => {
   });
 
 });
-\`\`\`
+```
 
 ## Service Test Pattern
 
-\`\`\`typescript
+```typescript
 describe('ProductService', () => {
 
   let service: ProductService;
@@ -268,11 +267,11 @@ describe('ProductService', () => {
   });
 
 });
-\`\`\`
+```
 
 ## Mapping Profile Test Pattern
 
-\`\`\`typescript
+```typescript
 describe('ProductMappingProfile', () => {
 
   let mappingService: MappingService;
@@ -304,23 +303,23 @@ describe('ProductMappingProfile', () => {
   });
 
 });
-\`\`\`
+```
 
 ## Test Conventions
 
 ### Comments
 
-\`\`\`typescript
+```typescript
 // Use AAA comments:
 // arrange — set up test data and mocks
 // act — call the method under test
 // act & assert — when the assertion is on the thrown error
 // assert — verify the outcome
-\`\`\`
+```
 
 ### Regions
 
-\`\`\`typescript
+```typescript
 describe('MyClass', () => {
 
   // #region Fields
@@ -334,23 +333,21 @@ describe('MyClass', () => {
   // #endregion
 
 });
-\`\`\`
+```
 
 ### Naming
 
-- \`describe\` blocks: Class name or method name
-- \`it\` blocks: \`'should <expected behavior> when <condition>'\`
+- `describe` blocks: Class name or method name
+- `it` blocks: `'should <expected behavior> when <condition>'`
 
 ## Rules
 
 1. **Every public service method needs at least one happy-path and one failure-path test.**
-2. **Use \`vi.restoreAllMocks()\` in \`beforeEach\`** — prevent mock leakage between tests.
+2. **Use `vi.restoreAllMocks()` in `beforeEach`** — prevent mock leakage between tests.
 3. **Mock at the boundary** — mock repositories in service tests, mock delegates in repository tests.
 4. **AAA pattern** — clearly separate arrange, act, assert with comments.
-5. **\`vi.mock()\` for modules must appear before imports** of the mocked module.
+5. **`vi.mock()` for modules must appear before imports** of the mocked module.
 6. **No real database in unit tests** — use mocks. Use Testcontainers for integration tests.
 7. **Assert on behavior, not implementation** — verify return values and thrown errors, not internal calls
    (unless the call IS the behavior, e.g., verifying a repository was called).
-8. **Use \`mockResolvedValue\` / \`mockRejectedValue\`** for async mocks.
-`;
-//# sourceMappingURL=testingPattern.js.map
+8. **Use `mockResolvedValue` / `mockRejectedValue`** for async mocks.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.21",
-  "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
+  "version": "0.0.23",
+  "description": "MCP server providing Archipel platform knowledge - documentation, query patterns, and coding conventions - to AI development tools.",
   "type": "commonjs",
   "main": "./src/main.js",
   "bin": "./src/main.js",

package/src/PatternsLoader.d.ts

@@ -0,0 +1,12 @@
+import type { IPatternDoc } from './models/IPatternDoc';
+/**
+ * Loads and indexes Archipel code patterns from the `.docs/patterns/`
+ * directory (monorepo dev) or from the bundled `data/patterns/` directory
+ * (published npm package).
+ */
+export declare class PatternsLoader {
+    private readonly _patterns;
+    get patterns(): ReadonlyMap<string, IPatternDoc>;
+    load(): void;
+    private resolvePatternsDirectory;
+}

package/src/PatternsLoader.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PatternsLoader = void 0;
+const tslib_1 = require("tslib");
+const gray_matter_1 = tslib_1.__importDefault(require("gray-matter"));
+const fs = tslib_1.__importStar(require("node:fs"));
+const path = tslib_1.__importStar(require("node:path"));
+/**
+ * Loads and indexes Archipel code patterns from the `.docs/patterns/`
+ * directory (monorepo dev) or from the bundled `data/patterns/` directory
+ * (published npm package).
+ */
+class PatternsLoader {
+    // #region Fields
+    _patterns = new Map();
+    // #endregion
+    // #region Properties
+    get patterns() {
+        return this._patterns;
+    }
+    // #endregion
+    // #region Methods
+    load() {
+        const patternsDirectory = this.resolvePatternsDirectory();
+        if (!patternsDirectory) {
+            process.stderr.write('[archipel-mcp] Warning: Could not locate patterns directory.\n');
+            return;
+        }
+        const files = fs.readdirSync(patternsDirectory).filter((file) => file.endsWith('.md') && file !== 'index.md');
+        for (const file of files) {
+            const filePath = path.join(patternsDirectory, file);
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            const parsed = (0, gray_matter_1.default)(raw);
+            const name = path.basename(file, '.md');
+            this._patterns.set(name, {
+                name,
+                title: parsed.data['title'] || name,
+                description: parsed.data['description'] || '',
+                order: parsed.data['order'] || 999,
+                content: parsed.content.trim(),
+            });
+        }
+        process.stderr.write(`[archipel-mcp] Loaded ${this._patterns.size} pattern(s)\n`);
+    }
+    resolvePatternsDirectory() {
+        // 1. Bundled data (published npm package)
+        const bundledPath = path.resolve(__dirname, '..', 'data', 'patterns');
+        if (fs.existsSync(bundledPath)) {
+            return bundledPath;
+        }
+        // 2. Workspace root (monorepo dev)
+        const cwdPath = path.resolve(process.cwd(), '.docs', 'patterns');
+        if (fs.existsSync(cwdPath)) {
+            return cwdPath;
+        }
+        // 3. Relative from compiled source (dist/tools/mcp/src/)
+        const relativePath = path.resolve(__dirname, '..', '..', '..', '..', '.docs', 'patterns');
+        if (fs.existsSync(relativePath)) {
+            return relativePath;
+        }
+        return null;
+    }
+}
+exports.PatternsLoader = PatternsLoader;
+//# sourceMappingURL=PatternsLoader.js.map

package/src/generators/mappingPatternGenerator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a full mapping example (input interface, key, profile, module registration,
+ * controller usage) for a given entity and its target response class.
+ */
+export declare function MAPPING_PATTERN_WITH_CONTEXT(entityName: string, fields: string[], responseName: string): string;

package/src/generators/mappingPatternGenerator.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAPPING_PATTERN_WITH_CONTEXT = MAPPING_PATTERN_WITH_CONTEXT;
+/**
+ * Generates a full mapping example (input interface, key, profile, module registration,
+ * controller usage) for a given entity and its target response class.
+ */
+function MAPPING_PATTERN_WITH_CONTEXT(entityName, fields, responseName) {
+    return `
+## Example: Mapping for "${entityName}" → "${responseName}"
+
+Given an entity \`${entityName}\` with fields: ${fields.map((f) => `\`${f}\``).join(', ')}
+
+### 1. Input Interface
+
+\`\`\`typescript
+// models/mapping-inputs/I${entityName}MappingInput.ts
+
+export interface I${entityName}MappingInput {
+${fields.map((f) => `  readonly ${f}: ${inferMappingFieldType(f)};`).join('\n')}
+}
+\`\`\`
+
+### 2. Mapping Key
+
+\`\`\`typescript
+// constants/MappingKeys.ts
+import { createMappingKey } from '@breadstone/archipel-platform-mapping';
+import { I${entityName}MappingInput } from '../models/mapping-inputs/I${entityName}MappingInput';
+import { ${responseName} } from '../dtos/${responseName}';
+
+export const ${toConstantCase(entityName)}_MAPPING_KEY = createMappingKey<I${entityName}MappingInput, ${responseName}>('${toDotNotation(entityName)}');
+\`\`\`
+
+### 3. Mapping Profile
+
+\`\`\`typescript
+// mappers/${entityName}MappingProfile.ts
+import { MappingProfileBase, IMappingBuilder } from '@breadstone/archipel-platform-mapping';
+import { ${toConstantCase(entityName)}_MAPPING_KEY } from '../constants/MappingKeys';
+import { I${entityName}MappingInput } from '../models/mapping-inputs/I${entityName}MappingInput';
+import { ${responseName} } from '../dtos/${responseName}';
+
+export class ${entityName}MappingProfile extends MappingProfileBase {
+
+  // #region Methods
+
+  public configure(builder: IMappingBuilder): void {
+    builder.createKeyedMap(${toConstantCase(entityName)}_MAPPING_KEY, (input: I${entityName}MappingInput) => {
+      const response = new ${responseName}();
+${fields.map((f) => `      response.${f} = input.${f};`).join('\n')}
+
+      return response;
+    });
+  }
+
+  // #endregion
+
+}
+\`\`\`
+
+### 4. Module Registration
+
+\`\`\`typescript
+import { MappingModule } from '@breadstone/archipel-platform-mapping';
+import { ${entityName}MappingProfile } from './mappers/${entityName}MappingProfile';
+
+@Module({
+  imports: [
+    MappingModule.withProfiles([${entityName}MappingProfile]),
+  ],
+})
+export class ${entityName}Module {}
+\`\`\`
+
+### 5. Controller Usage
+
+\`\`\`typescript
+// In a controller method:
+const entity = await this._${lowerFirst(entityName)}Service.findById(id);
+const response = this._mappingService.map(${toConstantCase(entityName)}_MAPPING_KEY, entity);
+\`\`\`
+`;
+}
+function inferMappingFieldType(fieldName) {
+    if (fieldName === 'id')
+        return 'string';
+    if (fieldName.endsWith('Id'))
+        return 'string';
+    if (fieldName.endsWith('At') || fieldName === 'createdAt' || fieldName === 'updatedAt')
+        return 'Date';
+    if (fieldName.startsWith('is') || fieldName.startsWith('has'))
+        return 'boolean';
+    if (fieldName === 'count' || fieldName === 'quantity' || fieldName === 'amount' || fieldName === 'price')
+        return 'number';
+    return 'string';
+}
+function toConstantCase(name) {
+    return name.replace(/([a-z])([A-Z])/g, '$1_$2').toUpperCase();
+}
+function toDotNotation(name) {
+    return name.replace(/([a-z])([A-Z])/g, '$1.$2').toLowerCase();
+}
+function lowerFirst(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+//# sourceMappingURL=mappingPatternGenerator.js.map

package/src/generators/modulePatternGenerator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a dynamic NestJS module example with ports, options interface,
+ * module class, and consumer registration for the given module and port names.
+ */
+export declare function MODULE_PATTERN_WITH_CONTEXT(moduleName: string, ports: string[]): string;

package/src/generators/modulePatternGenerator.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULE_PATTERN_WITH_CONTEXT = MODULE_PATTERN_WITH_CONTEXT;
+/**
+ * Generates a dynamic NestJS module example with ports, options interface,
+ * module class, and consumer registration for the given module and port names.
+ */
+function MODULE_PATTERN_WITH_CONTEXT(moduleName, ports) {
+    return `
+## Example: Dynamic Module "${moduleName}"
+
+With ports: ${ports.map((p) => `\`${p}\``).join(', ')}
+
+### Port Definitions
+
+${ports
+        .map((port) => `\`\`\`typescript
+// contracts/${port}.ts
+
+export abstract class ${port} {
+
+  // Define abstract methods for the port contract
+  public abstract execute(/* args */): Promise<void>;
+
+}
+\`\`\``)
+        .join('\n\n')}
+
+### Options Interface
+
+\`\`\`typescript
+// interfaces/I${moduleName}Options.ts
+import { Type } from '@nestjs/common';
+${ports.map((port) => `import { ${port} } from '../contracts/${port}';`).join('\n')}
+
+export interface I${moduleName}Options {
+${ports.map((port) => `  ${lowerFirstChar(port)}: Type<${port}>;`).join('\n')}
+  isGlobal?: boolean;
+}
+\`\`\`
+
+### Module Class
+
+\`\`\`typescript
+// ${moduleName}.ts
+import { ConfigModule } from '@breadstone/archipel-platform-core';
+import { type DynamicModule, Module, type Type } from '@nestjs/common';
+import { I${moduleName}Options } from './interfaces/I${moduleName}Options';
+${ports.map((port) => `import { ${port} } from './contracts/${port}';`).join('\n')}
+
+@Module({})
+export class ${moduleName} {
+
+  public static register(options: I${moduleName}Options): DynamicModule {
+    const portProviders = [
+${ports.map((port) => `      { provide: ${port}, useClass: options.${lowerFirstChar(port)} },`).join('\n')}
+    ];
+
+    return {
+      global: options.isGlobal ?? false,
+      module: ${moduleName},
+      imports: [
+        ConfigModule.register('${toKebabCase(moduleName)}', PLATFORM_${toUpperSnakeCase(moduleName)}_CONFIG_ENTRIES),
+      ],
+      providers: [
+        ...portProviders,
+        // Add services, guards, interceptors here
+      ],
+      exports: [
+        // Export public services, guards, interceptors
+      ],
+    };
+  }
+
+}
+\`\`\`
+
+### Consumer Usage
+
+\`\`\`typescript
+@Module({
+  imports: [
+    ${moduleName}.register({
+${ports.map((port) => `      ${lowerFirstChar(port)}: My${port}Adapter,`).join('\n')}
+    }),
+  ],
+})
+export class AppModule {}
+\`\`\`
+`;
+}
+function lowerFirstChar(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+function toKebabCase(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .toLowerCase()
+        .replace(/module$/, '');
+}
+function toUpperSnakeCase(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, '$1_$2')
+        .toUpperCase()
+        .replace(/MODULE$/, '');
+}
+//# sourceMappingURL=modulePatternGenerator.js.map

package/src/generators/queryPatternGenerator.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Generates model-specific query factory examples based on a Prisma model name and its fields.
+ */
+export declare function QUERY_PATTERN_WITH_MODEL(modelName: string, fields: string[]): string;

package/src/generators/queryPatternGenerator.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_PATTERN_WITH_MODEL = QUERY_PATTERN_WITH_MODEL;
+/**
+ * Generates model-specific query factory examples based on a Prisma model name and its fields.
+ */
+function QUERY_PATTERN_WITH_MODEL(modelName, fields) {
+    return `
+## Example: Queries for "${modelName}"
+
+Given a Prisma model \`${modelName}\` with fields: ${fields.map((f) => `\`${f}\``).join(', ')}
+
+### findFirst query
+\`\`\`typescript
+import { Prisma } from '@prisma/client';
+import { query } from '@breadstone/archipel-platform-database';
+
+export function find${modelName}ByIdQuery(id: string) {
+  return query<Prisma.${modelName}Delegate, { ${fields.map((f) => `${f}: ${inferFieldType(f)}`).join('; ')} } | null>(
+    'find${modelName}ById',
+    (model) =>
+      model.findFirst({
+        where: { id },
+        select: { ${fields.map((f) => `${f}: true`).join(', ')} },
+      }),
+  );
+}
+\`\`\`
+
+### findMany query
+\`\`\`typescript
+export function findAll${modelName}sQuery(skip = 0, take = 20) {
+  return query<Prisma.${modelName}Delegate, Array<{ ${fields.map((f) => `${f}: ${inferFieldType(f)}`).join('; ')} }>>(
+    'findAll${modelName}s',
+    (model) =>
+      model.findMany({
+        skip,
+        take,
+        select: { ${fields.map((f) => `${f}: true`).join(', ')} },
+        orderBy: { ${fields.includes('createdAt') ? 'createdAt' : fields[0]}: 'desc' },
+      }),
+  );
+}
+\`\`\`
+
+### count query
+\`\`\`typescript
+export function count${modelName}sQuery() {
+  return query<Prisma.${modelName}Delegate, number>(
+    'count${modelName}s',
+    (model) => model.count(),
+  );
+}
+\`\`\`
+
+### Service usage
+\`\`\`typescript
+// In a service method:
+const item = await this._${lowerFirst(modelName)}Repository.execute(find${modelName}ByIdQuery(id));
+const items = await this._${lowerFirst(modelName)}Repository.execute(findAll${modelName}sQuery(0, 50));
+const total = await this._${lowerFirst(modelName)}Repository.execute(count${modelName}sQuery());
+\`\`\`
+`;
+}
+function inferFieldType(fieldName) {
+    if (fieldName === 'id')
+        return 'string';
+    if (fieldName.endsWith('Id'))
+        return 'string';
+    if (fieldName.endsWith('At') || fieldName === 'createdAt' || fieldName === 'updatedAt')
+        return 'Date';
+    if (fieldName.startsWith('is') || fieldName.startsWith('has'))
+        return 'boolean';
+    if (fieldName === 'count' || fieldName === 'quantity' || fieldName === 'amount' || fieldName === 'order')
+        return 'number';
+    if (fieldName === 'email' || fieldName === 'name' || fieldName === 'title' || fieldName === 'description')
+        return 'string';
+    return 'unknown';
+}
+function lowerFirst(str) {
+    return str.charAt(0).toLowerCase() + str.slice(1);
+}
+//# sourceMappingURL=queryPatternGenerator.js.map

package/src/generators/repositoryPatternGenerator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generates a full repository class, entity interface, query factories, module
+ * registration, and service usage example for a given Prisma model.
+ */
+export declare function REPOSITORY_PATTERN_WITH_MODEL(modelName: string, fields: string[]): string;