@breadstone/archipel-mcp 0.0.21 → 0.0.22

package/src/knowledge/repositoryPattern.js

@@ -1,367 +0,0 @@
-"use strict";
-/**
- * Static knowledge content for the Archipel repository class pattern.
- * Returned by the get-repository-pattern tool.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.REPOSITORY_PATTERN_WITH_MODEL = exports.REPOSITORY_PATTERN_KNOWLEDGE = void 0;
-exports.REPOSITORY_PATTERN_KNOWLEDGE = `# 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.
-`;
-const REPOSITORY_PATTERN_WITH_MODEL = (modelName, fields) => `
-## Example: Repository for "${modelName}"
-
-Given a Prisma model \`${modelName}\` with fields: ${fields.map((f) => `\`${f}\``).join(', ')}
-
-### Repository Class
-
-\`\`\`typescript
-// repositories/${modelName}Repository.ts
-import { Injectable } from '@nestjs/common';
-import { Prisma } from '@prisma/client';
-import {
-  DatabaseService,
-  DelegateArgs,
-  DelegateReturnTypes,
-  RepositoryBase,
-} from '@breadstone/archipel-platform-database';
-import { I${modelName}Entity } from '../models/entities/I${modelName}Entity';
-
-@Injectable()
-export class ${modelName}Repository extends RepositoryBase<
-  Prisma.${modelName}Delegate,
-  DelegateArgs<Prisma.${modelName}Delegate>,
-  DelegateReturnTypes<Prisma.${modelName}Delegate>,
-  I${modelName}Entity
-> {
-
-  // #region Ctor
-
-  public constructor(db: DatabaseService) {
-    super(db, db.client.${lowerFirst(modelName)});
-  }
-
-  // #endregion
-
-}
-\`\`\`
-
-### Entity Interface
-
-\`\`\`typescript
-// models/entities/I${modelName}Entity.ts
-export interface I${modelName}Entity {
-${fields.map((f) => `  readonly ${f}: ${inferFieldType(f)};`).join('\n')}
-}
-\`\`\`
-
-### Query Factories
-
-\`\`\`typescript
-// queries/find${modelName}ByIdQuery.ts
-import { Prisma } from '@prisma/client';
-import { query } from '@breadstone/archipel-platform-database';
-import { I${modelName}Entity } from '../models/entities/I${modelName}Entity';
-
-export function find${modelName}ByIdQuery(id: string) {
-  return query<Prisma.${modelName}Delegate, I${modelName}Entity | null>(
-    'find${modelName}ById',
-    (model) => model.findFirst({
-      where: { id },
-      select: { ${fields.map((f) => `${f}: true`).join(', ')} },
-    }),
-  );
-}
-
-export function findAll${modelName}sQuery(skip = 0, take = 20) {
-  return query<Prisma.${modelName}Delegate, I${modelName}Entity[]>(
-    'findAll${modelName}s',
-    (model) => model.findMany({
-      skip,
-      take,
-      select: { ${fields.map((f) => `${f}: true`).join(', ')} },
-      orderBy: { ${fields.includes('createdAt') ? 'createdAt' : fields[0]}: 'desc' },
-    }),
-  );
-}
-
-export function count${modelName}sQuery() {
-  return query<Prisma.${modelName}Delegate, number>(
-    'count${modelName}s',
-    (model) => model.count(),
-  );
-}
-\`\`\`
-
-### Module Registration
-
-\`\`\`typescript
-import { DatabaseModule } from '@breadstone/archipel-platform-database';
-import { ${modelName}Repository } from './repositories/${modelName}Repository';
-import { ${modelName}Service } from './services/${modelName}Service';
-
-@Module({
-  imports: [DatabaseModule.register()],
-  providers: [${modelName}Repository, ${modelName}Service],
-  exports: [${modelName}Service],
-})
-export class ${modelName}Module {}
-\`\`\`
-
-### Service Usage
-
-\`\`\`typescript
-@Injectable()
-export class ${modelName}Service {
-
-  // #region Fields
-
-  private readonly _${lowerFirst(modelName)}Repository: ${modelName}Repository;
-
-  // #endregion
-
-  // #region Ctor
-
-  public constructor(${lowerFirst(modelName)}Repository: ${modelName}Repository) {
-    this._${lowerFirst(modelName)}Repository = ${lowerFirst(modelName)}Repository;
-  }
-
-  // #endregion
-
-  // #region Methods
-
-  public async findById(id: string): Promise<I${modelName}Entity | null> {
-    return this._${lowerFirst(modelName)}Repository.execute(find${modelName}ByIdQuery(id));
-  }
-
-  public async findAll(skip = 0, take = 20): Promise<I${modelName}Entity[]> {
-    return this._${lowerFirst(modelName)}Repository.execute(findAll${modelName}sQuery(skip, take));
-  }
-
-  public async count(): Promise<number> {
-    return this._${lowerFirst(modelName)}Repository.execute(count${modelName}sQuery());
-  }
-
-  // #endregion
-
-}
-\`\`\`
-`;
-exports.REPOSITORY_PATTERN_WITH_MODEL = REPOSITORY_PATTERN_WITH_MODEL;
-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 === 'price')
-        return 'number';
-    return 'string';
-}
-function lowerFirst(str) {
-    return str.charAt(0).toLowerCase() + str.slice(1);
-}
-//# sourceMappingURL=repositoryPattern.js.map

package/src/knowledge/testingPattern.d.ts

@@ -1,5 +0,0 @@
-/**
- * Static knowledge content for the Archipel testing pattern.
- * Returned by the get-testing-pattern tool.
- */
-export declare const TESTING_PATTERN_KNOWLEDGE = "# Archipel Testing Pattern\n\n## Overview\n\nArchipel uses **Vitest** for unit and integration tests with **vi mocking**. Tests follow\nthe Arrange-Act-Assert (AAA) pattern with descriptive `describe`/`it` blocks. Each test\nfile covers a single class or module.\n\n## Test Framework\n\n- **Runner:** Vitest\n- **Mocking:** `vi.fn()`, `vi.mock()`, `vi.spyOn()`\n- **Assertions:** Vitest built-in (`expect`)\n- **E2E:** Supertest against a bootstrapped NestJS app\n\n## File Naming & Location\n\n| Test Type | File Pattern | Location |\n|-----------|-------------|----------|\n| Unit test | `*.spec.ts` | Next to the source file |\n| E2E test | `*.e2e-spec.ts` | `test/` directory |\n\n## Basic Test Structure\n\n```typescript\nimport { beforeEach, describe, expect, it, vi } from 'vitest';\n\ndescribe('UserService', () => {\n\n  // #region Fields\n\n  let service: UserService;\n  let mockRepository: { execute: ReturnType<typeof vi.fn> };\n  let mockMappingService: { map: ReturnType<typeof vi.fn> };\n\n  // #endregion\n\n  // #region Methods\n\n  beforeEach(() => {\n    vi.restoreAllMocks();\n\n    mockRepository = {\n      execute: vi.fn(),\n    };\n\n    mockMappingService = {\n      map: vi.fn(),\n    };\n\n    service = new UserService(\n      mockRepository as unknown as UserRepository,\n      mockMappingService as unknown as MappingService,\n    );\n  });\n\n  describe('findById', () => {\n    it('should return entity when user exists', async () => {\n      // arrange\n      const mockUser = { id: '1', email: 'test@example.com', name: 'Test' };\n      mockRepository.execute.mockResolvedValue(mockUser);\n\n      // act\n      const result = await service.findById('1');\n\n      // assert\n      expect(result).toEqual(mockUser);\n      expect(mockRepository.execute).toHaveBeenCalledOnce();\n    });\n\n    it('should throw UserNotFoundError when user does not exist', async () => {\n      // arrange\n      mockRepository.execute.mockResolvedValue(null);\n\n      // act & assert\n      await expect(() => service.findById('nonexistent'))\n        .rejects.toThrow(UserNotFoundError);\n    });\n  });\n\n  // #endregion\n\n});\n```\n\n## Mocking Patterns\n\n### Mocking Prisma Delegates (for Repository Tests)\n\n```typescript\nvi.mock('@prisma/client/runtime/client', () => ({\n  PrismaClientKnownRequestError: class PrismaClientKnownRequestError extends Error {\n    public code: string;\n    public meta?: Record<string, unknown>;\n    public clientVersion: string;\n    public constructor(message: string, opts: { code: string; clientVersion: string; meta?: Record<string, unknown> }) {\n      super(message);\n      this.name = 'PrismaClientKnownRequestError';\n      this.code = opts.code;\n      this.clientVersion = opts.clientVersion;\n      this.meta = opts.meta;\n    }\n  },\n  PrismaClientUnknownRequestError: class PrismaClientUnknownRequestError extends Error {\n    public clientVersion: string;\n    public constructor(message: string, opts: { clientVersion: string }) {\n      super(message);\n      this.name = 'PrismaClientUnknownRequestError';\n      this.clientVersion = opts.clientVersion;\n    }\n  },\n}));\n```\n\n### Creating a Mock Delegate\n\n```typescript\ntype MockDelegate = Record<\n  | 'aggregate' | 'count' | 'create' | 'createMany' | 'createManyAndReturn'\n  | 'delete' | 'deleteMany' | 'findFirst' | 'findFirstOrThrow'\n  | 'findMany' | 'findUnique' | 'findUniqueOrThrow'\n  | 'groupBy' | 'update' | 'updateMany' | 'upsert',\n  ReturnType<typeof vi.fn>\n>;\n\nfunction createMockDelegate(): MockDelegate {\n  return {\n    findUnique: vi.fn(),\n    findFirst: vi.fn(),\n    findMany: vi.fn(),\n    create: vi.fn(),\n    createMany: vi.fn(),\n    createManyAndReturn: vi.fn(),\n    update: vi.fn(),\n    updateMany: vi.fn(),\n    upsert: vi.fn(),\n    delete: vi.fn(),\n    deleteMany: vi.fn(),\n    aggregate: vi.fn(),\n    count: vi.fn(),\n    groupBy: vi.fn(),\n    findFirstOrThrow: vi.fn(),\n    findUniqueOrThrow: vi.fn(),\n  };\n}\n```\n\n### Mocking DatabaseService\n\n```typescript\nconst mockDb = {\n  transactionCallback: vi.fn(),\n  client: {\n    user: createMockDelegate(),\n  },\n} as unknown as DatabaseService;\n```\n\n### Mocking a Query\n\n```typescript\nconst mockQuery = {\n  name: 'findUserById',\n  run: vi.fn().mockResolvedValue({ id: '1', email: 'test@example.com' }),\n};\n```\n\n## Repository Test Pattern\n\n```typescript\nimport { beforeEach, describe, expect, it, vi } from 'vitest';\n\n// Mock Prisma runtime errors BEFORE importing test subject\nvi.mock('@prisma/client/runtime/client', () => ({ /* ... */ }));\nimport { PrismaClientKnownRequestError } from '@prisma/client/runtime/client';\n\ndescribe('UserRepository', () => {\n\n  let repository: TestRepository;\n  let mockModel: MockDelegate;\n  let mockDb: DatabaseService;\n\n  beforeEach(() => {\n    vi.restoreAllMocks();\n    mockModel = createMockDelegate();\n    mockDb = { transactionCallback: vi.fn() } as unknown as DatabaseService;\n    repository = new TestRepository(mockDb, mockModel);\n  });\n\n  describe('execute', () => {\n    it('should execute a query against the model', async () => {\n      // arrange\n      const mockQuery = {\n        name: 'testQuery',\n        run: vi.fn().mockResolvedValue({ id: '1' }),\n      };\n\n      // act\n      const result = await repository.execute(mockQuery);\n\n      // assert\n      expect(mockQuery.run).toHaveBeenCalledWith(mockModel);\n      expect(result).toEqual({ id: '1' });\n    });\n\n    it('should wrap PrismaClientKnownRequestError as RepositoryError', async () => {\n      // arrange\n      const prismaError = new PrismaClientKnownRequestError('Not found', {\n        code: 'P2025',\n        clientVersion: '6.0.0',\n      });\n      const mockQuery = {\n        name: 'failingQuery',\n        run: vi.fn().mockRejectedValue(prismaError),\n      };\n\n      // act & assert\n      await expect(() => repository.execute(mockQuery))\n        .rejects.toThrow(RepositoryError);\n    });\n  });\n\n});\n```\n\n## Service Test Pattern\n\n```typescript\ndescribe('ProductService', () => {\n\n  let service: ProductService;\n  let mockRepo: { execute: ReturnType<typeof vi.fn> };\n\n  beforeEach(() => {\n    vi.restoreAllMocks();\n    mockRepo = { execute: vi.fn() };\n    service = new ProductService(mockRepo as unknown as ProductRepository);\n  });\n\n  describe('findById', () => {\n    it('should return entity when found', async () => {\n      // arrange\n      const expected = { id: '1', name: 'Product A', barcode: '123' };\n      mockRepo.execute.mockResolvedValue(expected);\n\n      // act\n      const result = await service.findById('1');\n\n      // assert\n      expect(result).toEqual(expected);\n    });\n\n    it('should throw domain error when not found', async () => {\n      // arrange\n      mockRepo.execute.mockResolvedValue(null);\n\n      // act & assert\n      await expect(() => service.findById('unknown'))\n        .rejects.toThrow(ProductNotFoundError);\n    });\n  });\n\n});\n```\n\n## Mapping Profile Test Pattern\n\n```typescript\ndescribe('ProductMappingProfile', () => {\n\n  let mappingService: MappingService;\n\n  beforeEach(() => {\n    mappingService = new MappingService();\n    const profile = new ProductMappingProfile();\n    mappingService.registerProfile(profile);\n  });\n\n  it('should map input to response correctly', () => {\n    // arrange\n    const input: IProductMappingInput = {\n      id: '1',\n      barcode: '123',\n      name: 'Product A',\n      categoryId: 'cat-1',\n      createdAt: new Date('2026-01-01'),\n    };\n\n    // act\n    const result = mappingService.map(PRODUCT_MAPPING_KEY, input);\n\n    // assert\n    expect(result).toBeInstanceOf(ProductResponse);\n    expect(result.id).toBe('1');\n    expect(result.barcode).toBe('123');\n    expect(result.name).toBe('Product A');\n  });\n\n});\n```\n\n## Test Conventions\n\n### Comments\n\n```typescript\n// Use AAA comments:\n// arrange \u2014 set up test data and mocks\n// act \u2014 call the method under test\n// act & assert \u2014 when the assertion is on the thrown error\n// assert \u2014 verify the outcome\n```\n\n### Regions\n\n```typescript\ndescribe('MyClass', () => {\n\n  // #region Fields\n  let service: MyService;\n  // #endregion\n\n  // #region Methods\n  beforeEach(() => { ... });\n\n  describe('methodName', () => { ... });\n  // #endregion\n\n});\n```\n\n### Naming\n\n- `describe` blocks: Class name or method name\n- `it` blocks: `'should <expected behavior> when <condition>'`\n\n## Rules\n\n1. **Every public service method needs at least one happy-path and one failure-path test.**\n2. **Use `vi.restoreAllMocks()` in `beforeEach`** \u2014 prevent mock leakage between tests.\n3. **Mock at the boundary** \u2014 mock repositories in service tests, mock delegates in repository tests.\n4. **AAA pattern** \u2014 clearly separate arrange, act, assert with comments.\n5. **`vi.mock()` for modules must appear before imports** of the mocked module.\n6. **No real database in unit tests** \u2014 use mocks. Use Testcontainers for integration tests.\n7. **Assert on behavior, not implementation** \u2014 verify return values and thrown errors, not internal calls\n   (unless the call IS the behavior, e.g., verifying a repository was called).\n8. **Use `mockResolvedValue` / `mockRejectedValue`** for async mocks.\n";