@breadstone/archipel-mcp 0.0.1

package/src/knowledge/queryPattern.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel query pattern.
+ * Returned by the get-query-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QUERY_PATTERN_WITH_MODEL = exports.QUERY_PATTERN_KNOWLEDGE = void 0;
+exports.QUERY_PATTERN_KNOWLEDGE = `# Archipel Query Pattern (v1)
+
+## Overview
+
+In Archipel, data access follows the **Repository + Query** pattern. Repositories never expose
+raw Prisma delegate methods to services. Instead, every data operation is wrapped in a
+**query factory function** that returns an \`IRepositoryQuery\` object. Services call
+\`repository.execute(someQuery(...))\` — never \`repository.findFirst(...)\` directly.
+
+## Core Interface
+
+\`\`\`typescript
+export interface IRepositoryQuery<TDelegate, TResult> {
+  readonly name: string;
+  run(model: TDelegate): Promise<TResult>;
+}
+\`\`\`
+
+- \`TDelegate\` — the Prisma delegate type (e.g. \`Prisma.UserDelegate\`)
+- \`TResult\` — the query's return type
+- \`name\` — identifier used for logging and debugging
+
+## Factory Function
+
+\`\`\`typescript
+import { IRepositoryQuery } from '@breadstone/archipel-platform-database';
+
+export function query<TDelegate, TResult>(
+  name: string,
+  run: (model: TDelegate) => Promise<TResult>,
+): IRepositoryQuery<TDelegate, TResult> {
+  return { name, run };
+}
+\`\`\`
+
+## Type Extraction
+
+\`\`\`typescript
+export type QueryResultType<T> = T extends IRepositoryQuery<unknown, infer R> ? R : never;
+\`\`\`
+
+Use this to derive the result type from a query factory without duplicating types:
+\`\`\`typescript
+type UserProfileResult = QueryResultType<ReturnType<typeof findUserProfileQuery>>;
+\`\`\`
+
+## How to Write a Query
+
+### Step 1: Define the query factory function
+
+Each query is a **named function** that returns an \`IRepositoryQuery\`. The function may accept
+parameters — these become the query's runtime arguments.
+
+\`\`\`typescript
+import { Prisma } from '@prisma/client';
+import { query } from '@breadstone/archipel-platform-database';
+
+export function findUserByEmailQuery(email: string) {
+  return query<Prisma.UserDelegate, { id: string; email: string; name: string } | null>(
+    'findUserByEmail',
+    (model) =>
+      model.findFirst({
+        where: { email },
+        select: { id: true, email: true, name: true },
+      }),
+  );
+}
+\`\`\`
+
+### Step 2: Call from a service via repository.execute()
+
+\`\`\`typescript
+// In the service:
+const user = await this._userRepository.execute(findUserByEmailQuery(email));
+\`\`\`
+
+### Step 3: Extract result type if needed for mapping
+
+\`\`\`typescript
+type FindUserByEmailResult = QueryResultType<ReturnType<typeof findUserByEmailQuery>>;
+\`\`\`
+
+## Transactional Queries
+
+For operations that span multiple models, use \`transactionalQuery\`:
+
+\`\`\`typescript
+import { Prisma } from '@prisma/client';
+import { transactionalQuery } from '@breadstone/archipel-platform-database';
+
+export function createOrderWithItemsQuery(data: { userId: string; items: Array<{ productId: string; quantity: number }> }) {
+  return transactionalQuery<{ orderId: string }>(
+    'createOrderWithItems',
+    async (tx: Prisma.TransactionClient) => {
+      const order = await tx.order.create({
+        data: { userId: data.userId },
+        select: { id: true },
+      });
+
+      await tx.orderItem.createMany({
+        data: data.items.map((item) => ({
+          orderId: order.id,
+          productId: item.productId,
+          quantity: item.quantity,
+        })),
+      });
+
+      return { orderId: order.id };
+    },
+  );
+}
+\`\`\`
+
+Called via:
+\`\`\`typescript
+const result = await this._orderRepository.executeTransactional(
+  createOrderWithItemsQuery({ userId, items }),
+);
+\`\`\`
+
+## Rules
+
+1. **Never call Prisma delegate methods directly from services.** Always go through \`execute(query)\`.
+2. **Always select only the fields you need.** Use \`select\` — never return full records.
+3. **Query names must be descriptive.** Use the pattern: \`verbModelByConditionQuery\`
+   (e.g. \`findUserByEmailQuery\`, \`countOrdersByStatusQuery\`, \`updateUserNameQuery\`).
+4. **One query per file** for non-trivial queries. Small related queries may share a file.
+5. **Type the result explicitly.** The second generic parameter of \`query()\` should be an inline
+   object type or a dedicated interface matching the \`select\` shape.
+6. **Each query factory is a standalone function** (not a class method). Import \`query\` from
+   \`@breadstone/archipel-platform-database\`.
+`;
+const QUERY_PATTERN_WITH_MODEL = (modelName, fields) => `
+## 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());
+\`\`\`
+`;
+exports.QUERY_PATTERN_WITH_MODEL = QUERY_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 === '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=queryPattern.js.map

package/src/knowledge/repositoryPattern.d.ts

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

package/src/knowledge/repositoryPattern.js

@@ -0,0 +1,367 @@
+"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

@@ -0,0 +1,5 @@
+/**
+ * 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";