@breadstone/archipel-mcp 0.0.21 → 0.0.22

package/data/patterns/repository-pattern.md

@@ -0,0 +1,208 @@
+---
+title: Repository Pattern
+description: RepositoryBase subclasses, DelegateArgs/DelegateReturnTypes helpers, module registration, and service injection.
+order: 8
+---
+
+# Archipel Repository Pattern
+
+## Overview
+
+Every Prisma model gets a dedicated **Repository class** extending `RepositoryBase`.
+Repositories are the ONLY code that touches Prisma delegates. Services never call
+Prisma directly — they call `repository.execute(someQuery(...))` or
+`repository.executeTransactional(someTxQuery(...))`.
+
+## RepositoryBase Signature
+
+```typescript
+import { RepositoryBase } from '@breadstone/archipel-platform-database';
+
+export abstract class RepositoryBase<
+  TDelegate extends Record<RepositoryOperations, (args: any) => Promise<any>>,
+  TArgs extends Record<RepositoryOperations, unknown>,
+  TReturn extends Record<RepositoryOperations, unknown>,
+  TEntity = unknown
+>
+```
+
+### Generic Parameters
+
+| Param | Purpose | Example |
+|-------|---------|---------|
+| `TDelegate` | Prisma delegate type from generated client | `Prisma.UserDelegate` |
+| `TArgs` | Argument shapes for each operation | `Prisma.UserFindManyArgs`, etc. |
+| `TReturn` | Return shapes for each operation | `User`, `User[]`, etc. |
+| `TEntity` | Domain entity interface (optional) | `IUserEntity` |
+
+### Helper Types
+
+```typescript
+import { DelegateArgs, DelegateReturnTypes } from '@breadstone/archipel-platform-database';
+
+// These extract args and return types from a delegate automatically:
+type UserArgs = DelegateArgs<Prisma.UserDelegate>;
+type UserReturns = DelegateReturnTypes<Prisma.UserDelegate>;
+```
+
+## How to Create a Repository
+
+### Step 1: Create the repository class
+
+```typescript
+// repositories/UserRepository.ts
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import {
+  DatabaseService,
+  DelegateArgs,
+  DelegateReturnTypes,
+  RepositoryBase,
+} from '@breadstone/archipel-platform-database';
+
+@Injectable()
+export class UserRepository extends RepositoryBase<
+  Prisma.UserDelegate,
+  DelegateArgs<Prisma.UserDelegate>,
+  DelegateReturnTypes<Prisma.UserDelegate>,
+  IUserEntity
+> {
+
+  // #region Ctor
+
+  public constructor(db: DatabaseService) {
+    super(db, db.client.user);
+  }
+
+  // #endregion
+
+}
+```
+
+The constructor receives `DatabaseService` and passes both the service and the
+Prisma delegate (`db.client.user`) to the base class.
+
+### Step 2: Register as a provider in a module
+
+```typescript
+@Module({
+  imports: [DatabaseModule.register()],
+  providers: [UserRepository, UserService],
+  exports: [UserService],
+})
+export class UserModule {}
+```
+
+### Step 3: Inject into a service
+
+```typescript
+@Injectable()
+export class UserService {
+
+  // #region Fields
+
+  private readonly _userRepository: UserRepository;
+
+  // #endregion
+
+  // #region Ctor
+
+  public constructor(userRepository: UserRepository) {
+    this._userRepository = userRepository;
+  }
+
+  // #endregion
+
+  // #region Methods
+
+  public async findById(id: string): Promise<IUserEntity | null> {
+    return this._userRepository.execute(findUserByIdQuery(id));
+  }
+
+  public async findAll(skip = 0, take = 20): Promise<IUserEntity[]> {
+    return this._userRepository.execute(findAllUsersQuery(skip, take));
+  }
+
+  // #endregion
+
+}
+```
+
+## Key Methods on RepositoryBase
+
+### execute(query)
+
+Primary method for data access. Delegates to a query object.
+
+```typescript
+public execute<TResult>(query: IRepositoryQuery<TDelegate, TResult>): Promise<TResult>
+```
+
+### executeTransactional(query)
+
+For multi-model operations within a transaction.
+
+```typescript
+public executeTransactional<TResult>(query: ITransactionalRepositoryQuery<TResult>): Promise<TResult>
+```
+
+### Direct Methods (for legacy or internal use only)
+
+The base class also exposes `findUnique`, `findMany`, `findFirst`, `create`,
+`createMany`, `update`, `updateMany`, `upsert`, `delete`, `deleteMany`,
+`aggregate`, `count`, `groupBy`, `merge`.
+
+**Important:** New code should use `execute(query)` exclusively.
+Direct method calls are available but violate the query pattern convention.
+
+### findMany with Pagination
+
+```typescript
+// Direct method (legacy)
+const results = await this._repository.findMany(args, { page: 1, perPage: 20 });
+```
+
+## Error Handling
+
+All Prisma errors are caught by the base class `tryCatch` wrapper and re-thrown
+as `RepositoryError`:
+
+- `PrismaClientKnownRequestError` → `RepositoryError` with code `'R_KNOWN'`
+- `PrismaClientUnknownRequestError` → `RepositoryError` with code `'R_UNKNOWN'`
+- Other errors are re-thrown unchanged
+
+The global `RepositoryExceptionFilter` catches `RepositoryError` and returns
+HTTP 500 with a structured envelope.
+
+## Query Integration
+
+Repositories work with query factories from the query pattern:
+
+```typescript
+// queries/findUserByIdQuery.ts
+import { Prisma } from '@prisma/client';
+import { query } from '@breadstone/archipel-platform-database';
+
+export function findUserByIdQuery(id: string) {
+  return query<Prisma.UserDelegate, IUserEntity | null>(
+    'findUserById',
+    (model) => model.findFirst({
+      where: { id },
+      select: { id: true, email: true, name: true, createdAt: true },
+    }),
+  );
+}
+
+// Service usage:
+const user = await this._userRepository.execute(findUserByIdQuery(id));
+```
+
+## Rules
+
+1. **One repository per Prisma model** — e.g. `UserRepository`, `OrderRepository`.
+2. **Constructor receives `DatabaseService`** and passes the delegate via `db.client.<model>`.
+3. **Use `DelegateArgs` and `DelegateReturnTypes`** helper types for the RepositoryBase generics.
+4. **New code uses `execute(query)`** — never direct calls like `repository.findFirst()` from services.
+5. **Register as provider** in the feature module, import `DatabaseModule.register()`.
+6. **Repositories are `@Injectable()`** — they participate in NestJS DI.
+7. **Domain entity interface as fourth generic** (`TEntity`) is optional but recommended.

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,6 +1,6 @@
 {
   "name": "@breadstone/archipel-mcp",
-  "version": "0.0.21",
+  "version": "0.0.22",
   "description": "MCP server providing Archipel platform knowledge — documentation, query patterns, and coding conventions — to AI development tools.",
   "type": "commonjs",
   "main": "./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;