@prismakit/cli 2.2.3 → 3.0.0

package/skills/prismakit-nestjs/examples.md

@@ -0,0 +1,235 @@
+# PrismaKit NestJS examples
+
+Production-shaped snippets. Contract: skill `prismakit` + [SKILL.md](SKILL.md).
+
+## 1. App module (Redis, allowlist, slow-query log)
+
+```typescript
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { PrismaKitModule } from '@prismakit/nestjs';
+import { RedisCacheAdapter } from '@prismakit/redis';
+import { PrismaClientModule } from './infrastructure/prisma/prisma-client.module';
+import { PrismaService } from './infrastructure/prisma/prisma.service';
+import { UserModule } from './modules/users/user.module';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true }),
+    PrismaClientModule,
+    PrismaKitModule.forRootAsync({
+      imports: [PrismaClientModule],
+      inject: [PrismaService, ConfigService],
+      useFactory: (prisma: PrismaService, config: ConfigService) => ({
+        prisma,
+        cache: new RedisCacheAdapter({
+          url: config.get<string>('REDIS_URL'),
+          prefix: config.get<string>('CACHE_PREFIX') ?? 'myapp',
+        }),
+        cacheModels: ['user', 'product', 'wallet'],
+        schemaPath: 'prisma/schema.prisma',
+        validateCompose: true,
+        compose: { maxDepth: 6, parallel: true, setCache: true },
+        autoRegisterModels: true,
+        queryLog: {
+          slowThreshold: 500,
+          onSlowQuery: (e) => {
+            console.warn(`Slow ${e.model}.${e.method}: ${e.durationMs}ms`);
+          },
+        },
+      }),
+    }),
+    UserModule,
+  ],
+})
+export class AppModule {}
+```
+
+Prisma 5/6: pass `dmmf: Prisma.dmmf` instead of (or in addition to skipping) `schemaPath`. Prisma 7: `schemaPath` only.
+
+## 2. TypeMap binder
+
+```typescript
+// src/infrastructure/prisma/define-repo.ts
+import { createDefineRepo } from '@prismakit/nestjs';
+import type { Prisma } from '@prisma/client';
+
+export const defineRepo = createDefineRepo<Prisma.TypeMap>();
+```
+
+## 3. Feature repository + select presets
+
+```typescript
+// src/modules/users/repositories/user.repository.ts
+import { Prisma } from '@prisma/client';
+import { defineRepo } from '../../../infrastructure/prisma/define-repo';
+
+const DAY = 86_400;
+
+export const userSelectPresets = {
+  minimal: { id: true } satisfies Prisma.UserSelect,
+  general: {
+    id: true,
+    email: true,
+    name: true,
+  } satisfies Prisma.UserSelect,
+  withPassword: {
+    id: true,
+    email: true,
+    password: true,
+  } satisfies Prisma.UserSelect,
+};
+
+export const UserRepository = defineRepo({
+  model: 'user',
+  scalarFields: Prisma.UserScalarFieldEnum,
+  cache: {
+    ttl: DAY,
+    nullTtl: 60,
+    sensitiveFields: ['password'],
+    methods: { getFirst: { enabled: false } },
+  },
+  lock: true,
+});
+export type UserRepository = InstanceType<typeof UserRepository>;
+```
+
+## 4. Feature module + thin controller + service
+
+```typescript
+// src/modules/users/user.module.ts
+import { Module } from '@nestjs/common';
+import { UserController } from './user.controller';
+import { UserService } from './user.service';
+import { UserRepository } from './repositories/user.repository';
+
+@Module({
+  controllers: [UserController],
+  providers: [UserService, UserRepository],
+  exports: [UserService, UserRepository],
+})
+export class UserModule {}
+```
+
+```typescript
+// src/modules/users/user.controller.ts
+import { Controller, Get, Param } from '@nestjs/common';
+import { UserService } from './user.service';
+
+@Controller('users')
+export class UserController {
+  constructor(private readonly users: UserService) {}
+
+  @Get(':id')
+  getOne(@Param('id') id: string) {
+    return this.users.getProfile(id);
+  }
+}
+```
+
+```typescript
+// src/modules/users/user.service.ts
+import { Injectable } from '@nestjs/common';
+import { UserRepository, userSelectPresets } from './repositories/user.repository';
+
+@Injectable()
+export class UserService {
+  constructor(private readonly users: UserRepository) {}
+
+  getProfile(id: string) {
+    return this.users.getThrowById({
+      id,
+      select: userSelectPresets.general,
+      setCache: true,
+    });
+  }
+
+  async assertEmailFree(email: string) {
+    const hit = await this.users.getFirst({
+      where: { email },
+      select: userSelectPresets.minimal,
+    });
+    if (hit) throw new Error('email taken');
+  }
+}
+```
+
+## 5. Checkout — multi-repo `execTx`
+
+```typescript
+@Injectable()
+export class CheckoutService {
+  constructor(
+    private readonly tx: TransactionService,
+    private readonly orders: OrderRepository,
+    private readonly stocks: StockRepository,
+  ) {}
+
+  handleCheckout(input: { stockId: string; qty: number; userId: string }) {
+    return this.tx.execTx(
+      async (tx) => {
+        const order = await this.orders.create({
+          tx,
+          data: { userId: input.userId, stockId: input.stockId, qty: input.qty },
+          select: { id: true },
+          invalidate: 'none',
+        });
+        await this.stocks.updateById({
+          tx,
+          id: input.stockId,
+          data: { qty: { decrement: input.qty } },
+          invalidate: 'none',
+        });
+        return order;
+      },
+      async () => {
+        await this.orders.invalidateCache({});
+        await this.stocks.invalidateCache({ id: input.stockId });
+      },
+    );
+  }
+}
+```
+
+Register `OrderRepository` and `StockRepository` in the feature module `providers`. Both need `cache` config for `invalidate: 'none'` / `invalidateCache` to exist on the type.
+
+## 6. Wallet lock
+
+```typescript
+@Injectable()
+export class WalletService {
+  constructor(
+    private readonly tx: TransactionService,
+    private readonly wallets: WalletRepository,
+  ) {}
+
+  debit(id: string, amount: number) {
+    return this.tx.execTx(
+      async (tx) => {
+        const wallet = await this.wallets.getById({
+          tx,
+          id,
+          select: { id: true, balance: true },
+          lock: { mode: 'update' },
+        });
+        if (!wallet || wallet.balance < amount) {
+          throw new Error('insufficient funds');
+        }
+        return this.wallets.updateById({
+          tx,
+          id,
+          data: { balance: wallet.balance - amount },
+          select: { id: true, balance: true },
+          invalidate: 'none',
+        });
+      },
+      async () => {
+        await this.wallets.invalidateCache({ id });
+      },
+    );
+  }
+}
+```
+
+`WalletRepository` must set `lock: true` (or a table/client key). Never call `lock` outside `execTx`.

package/skills/prismakit-nestjs/reference.md

@@ -0,0 +1,146 @@
+# PrismaKit NestJS reference
+
+API surface for `@prismakit/nestjs` 3.x. Repository methods, cache, compose, and locks are documented in skill `prismakit` (`reference.md` in that skill). This file covers the Nest adapter only.
+
+## `PrismaKitModuleOptions`
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `prisma` | yes | `PrismaClient` (or compatible). Provided as `PRISMAKIT_PRISMA` for repositories only. |
+| `cache` | no | `CacheAdapter` (`RedisCacheAdapter` / `MemoryCacheAdapter`). |
+| `dmmf` | no | `Prisma.dmmf` on Prisma 5/6. Skip on Prisma 7 — use `schemaPath`. |
+| `schemaPath` | no | Load meta from `schema.prisma` when `dmmf` is omitted (compose + locks). Defaults to `prisma/schema.prisma`. |
+| `validateCompose` | no | When `true`, `assertSelectComposeValid` on module init. |
+| `cacheModels` | no | Strict allowlist of model keys with `cache` config. Omit = fail-open. |
+| `compose` | no | `ComposeOptions`: `maxDepth` (default 10), `parallel` (default true), `setCache` (default true). `tx` is per-call only. |
+| `telemetry` | no | `{ enabled?: boolean; onEvent?: (event) => void }`. |
+| `queryLog` | no | `{ slowThreshold?: number; onSlowQuery?: (e) => void }`. Default threshold 500ms. Setting this enables telemetry. |
+| `autoRegisterModels` | no | `true` = stub repos for all schema/DMMF models; `string[]` = those client keys only. |
+
+`queryLog.onSlowQuery` receives `{ model?, method?, durationMs, thresholdMs }` for `query.complete` events at/above the threshold.
+
+## Async config
+
+```typescript
+export type PrismaKitModuleAsyncOptions = {
+  imports?: Array<Type<unknown> | DynamicModule | Promise<DynamicModule>>;
+  useFactory: (...args: unknown[]) => Promise<PrismaKitModuleOptions> | PrismaKitModuleOptions;
+  inject?: unknown[];
+};
+```
+
+```typescript
+PrismaKitModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    prisma: prismaClient,
+    cache: new RedisCacheAdapter({
+      url: config.get('REDIS_URL'),
+      prefix: config.get('CACHE_PREFIX') ?? 'myapp',
+    }),
+    cacheModels: ['user', 'product'],
+    schemaPath: 'prisma/schema.prisma',
+  }),
+});
+```
+
+## DI tokens
+
+| Token | Type | Allowed injectors |
+|-------|------|-------------------|
+| `PRISMAKIT_PRISMA` | `PrismaClientLike` | Injectable repositories / kit internals only |
+| `PRISMAKIT_CACHE` | `CacheAdapter` | Repositories / kit internals |
+| `PRISMAKIT_OPTIONS` | `PrismaKitModuleOptions` | Kit internals |
+
+`TransactionService`, `RepositoryRegistry`, and `AutoComposer` are Nest providers from `PrismaKitModule`.
+
+## `TransactionService`
+
+```typescript
+execTx<T, TClient = unknown>(
+  fn: (tx: TClient) => Promise<T>,
+  afterCommit?: () => Promise<void>,
+  options?: TransactionOptions,
+): Promise<T>
+```
+
+`TransactionOptions`: `{ maxWait?: number; timeout?: number; isolationLevel?: 'ReadUncommitted' | 'ReadCommitted' | 'RepeatableRead' | 'Serializable' | string }`.
+
+Type the client when useful:
+
+```typescript
+await this.tx.execTx<User, Prisma.TransactionClient>(async (tx) => { /* ... */ });
+```
+
+`afterCommit` runs only after `prisma.$transaction` resolves successfully.
+
+## Repository factories
+
+| Factory | When |
+|---------|------|
+| `createDefineRepo<Prisma.TypeMap>()` then local `defineRepo({ model, ... })` | **Default** for apps. Zero phantoms; `model` + `scalarFields` + `cache` / `lock`. |
+| `defineInjectableRepository({ model, select, create, update, where, orderBy, payload, ... })` | TypeMap unavailable. Package aliases: `defineRepository`. |
+| `createInjectableRepository({ model, ... })` | Thin / untyped. Results `unknown` unless `toPayload` is supplied. Alias: `createPrismaRepository`. |
+
+`createDefineRepo` runtime options: `model`, `scalarFields?`, `primaryKey?`, `cache?`, `lock?`, `schemaPath?`.
+
+When `cache` is set, the returned API includes `setCache` / `cacheTags` / `invalidate` / `tags` / `invalidateCache`. Otherwise those fields are omitted from the type (`HasCacheFromOptions`).
+
+`createDefineRepo` / `RepositoryApiFromTypeMap` includes the full runtime surface: `createMany`, `updateMany`, `upsert`, `deleteMany`, `lock` + `orderBy` on `getFirst`, `lock` on `getMany`, and composite-PK `id` on `*ById`. Derive the instance type from the constructor — do not restate model/cache as a second generic:
+
+Export the instance type:
+
+```typescript
+export type UserRepository = InstanceType<typeof UserRepository>;
+```
+
+## `defineInjectableRepository` shape (escape hatch)
+
+```typescript
+import { Prisma } from '@prisma/client';
+import { defineInjectableRepository } from '@prismakit/nestjs';
+
+type Of<S> = S extends Prisma.UserSelect
+  ? Prisma.UserGetPayload<{ select: S }>
+  : never;
+
+export const UserRepository = defineInjectableRepository({
+  model: 'user',
+  scalarFields: Prisma.UserScalarFieldEnum,
+  select: null! as Prisma.UserSelect,
+  create: null! as Prisma.UserCreateInput,
+  update: null! as Prisma.UserUpdateInput,
+  where: null! as Prisma.UserWhereInput,
+  orderBy: null! as Prisma.UserOrderByWithRelationInput,
+  payload: class {
+    declare readonly _select: unknown;
+    declare type: () => Of<this['_select']>;
+  },
+  cache: { ttl: 86_400, sensitiveFields: ['password'] },
+  lock: true,
+});
+```
+
+## Re-exports from core
+
+`@prismakit/nestjs` re-exports: `AutoComposer`, `RepositoryRegistry`, `CacheAdapter`, repository option/instance types, `RepoPayloadHKT`, `ComposeOptions`, `TelemetryOptions`, `TelemetryEvent`, `loadPrismaMetaFromDmmf`, `loadPrismaMetaFromSchema`, `setComposeOptions`, `setTelemetry`.
+
+Prefer importing Nest-only APIs from `@prismakit/nestjs` and core-only helpers from `@prismakit/core`.
+
+## Layout
+
+```
+src/
+  app.module.ts                          # PrismaKitModule.forRootAsync
+  infrastructure/prisma/
+    define-repo.ts                       # createDefineRepo<Prisma.TypeMap>()
+    prisma.service.ts                    # client construction only
+  modules/<feature>/
+    <feature>.module.ts                  # providers: [Service, XRepository]
+    <feature>.service.ts                 # inject repos + TransactionService
+    <feature>.controller.ts              # HTTP only
+    repositories/<feature>.repository.ts
+```
+
+Prisma client usage is allowed under `**/repositories/**` and `**/infrastructure/prisma/**` only.

package/skills/prismakit-nestjs/review-checklist.md

@@ -0,0 +1,57 @@
+# PrismaKit NestJS review checklist
+
+Copy this list and tick every item before marking a Nest data-access change done. Also complete skill `prismakit` `review-checklist.md` (layering, cache, compose, locks).
+
+```
+Task Progress:
+- [ ] Core contract (skill prismakit checklist)
+- [ ] Module wiring
+- [ ] Repository factory
+- [ ] DI
+- [ ] Transactions
+- [ ] Feature shape
+```
+
+## Core contract
+
+- [ ] Skill `prismakit` review checklist is complete for this change
+
+## Module wiring
+
+- [ ] `PrismaKitModule.forRoot` or `forRootAsync` is imported once at the app root
+- [ ] `prisma` is the shared client instance
+- [ ] Prisma meta is loaded: `dmmf: Prisma.dmmf` (Prisma 5/6) or `schemaPath: 'prisma/schema.prisma'` (Prisma 7)
+- [ ] Production cache uses `RedisCacheAdapter` with a stable `prefix`
+- [ ] `cacheModels` lists every model whose repository sets `cache`
+- [ ] `validateCompose: true` is on for apps that nest relations in `select`
+
+## Repository factory
+
+- [ ] App has a single binder: `createDefineRepo<Prisma.TypeMap>()` in `src/infrastructure/prisma/define-repo.ts` (or equivalent)
+- [ ] Feature repos call that binder — not `createInjectableRepository` unless types are intentionally thin
+- [ ] `export type XRepository = InstanceType<typeof XRepository>`
+- [ ] Repo class is in `providers` and `exports` of the feature module
+- [ ] `lock: true` (or table/client key) is set when any call uses `lock`
+
+## DI
+
+- [ ] Services inject `*Repository` and `TransactionService` — never `PRISMAKIT_PRISMA`, `PrismaClient`, or `PrismaService`
+- [ ] Controllers inject services — not repositories, not Prisma
+- [ ] `PRISMAKIT_PRISMA` appears only inside `**/repositories/**` or kit internals
+
+## Transactions
+
+- [ ] Multi-step writes use `this.tx.execTx(fn, afterCommit)`
+- [ ] No `prisma.$transaction` / `.$transaction` in feature code
+- [ ] Every repo call inside `fn` receives `tx`
+- [ ] Writes use `invalidate: 'none'`
+- [ ] Matching `invalidateCache` calls live in `afterCommit`
+- [ ] Row locks run only inside `execTx`
+
+## Feature shape
+
+- [ ] HTTP mapping stays in the controller; orchestration in the service; Prisma in the repository
+- [ ] Select presets live next to the repository (`minimal` / `general` / `withPassword`)
+- [ ] After `prismakit generate --full`, the new `*Module` is imported in `AppModule`
+- [ ] After repo-only generate, the class is registered in feature `providers`
+- [ ] ESLint `prismakit.configs.recommended` passes

package/src/__tests__/skills.spec.ts

@@ -0,0 +1,117 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { findSkillsRoot, runSkills } from '../commands/skills';
+
+const repoSkills = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../skills',
+);
+
+const tmpDirs: string[] = [];
+
+function tmpDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'prismakit-skills-'));
+  tmpDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tmpDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe('findSkillsRoot', () => {
+  it('finds bundled or monorepo skills/ from this test file', () => {
+    const found = findSkillsRoot(path.dirname(fileURLToPath(import.meta.url)));
+    expect(found).toBeTruthy();
+    expect(fs.existsSync(path.join(found!, 'prismakit', 'SKILL.md'))).toBe(
+      true,
+    );
+    expect(
+      fs.existsSync(path.join(found!, 'prismakit-nestjs', 'SKILL.md')),
+    ).toBe(true);
+  });
+});
+
+describe('runSkills', () => {
+  it('lists bundled skills', () => {
+    const result = runSkills({ list: true, skillsRoot: repoSkills });
+    expect(result.installed).toEqual([]);
+    expect(result.dest).toBe(repoSkills);
+  });
+
+  it('installs both skills into a project .cursor/skills', () => {
+    const cwd = tmpDir();
+    const result = runSkills({ cwd, skillsRoot: repoSkills });
+    expect(result.installed).toEqual(['prismakit', 'prismakit-nestjs']);
+    expect(
+      fs.existsSync(path.join(cwd, '.cursor/skills/prismakit/SKILL.md')),
+    ).toBe(true);
+    expect(
+      fs.existsSync(
+        path.join(cwd, '.cursor/skills/prismakit-nestjs/SKILL.md'),
+      ),
+    ).toBe(true);
+    expect(
+      fs.readFileSync(
+        path.join(cwd, '.cursor/skills/prismakit/SKILL.md'),
+        'utf-8',
+      ),
+    ).toContain('name: prismakit');
+  });
+
+  it('installs a single skill and overwrites on re-run', () => {
+    const cwd = tmpDir();
+    runSkills({ cwd, skillsRoot: repoSkills, skill: ['prismakit'] });
+    const skillFile = path.join(cwd, '.cursor/skills/prismakit/SKILL.md');
+    fs.appendFileSync(skillFile, '\n# dirty\n');
+    runSkills({ cwd, skillsRoot: repoSkills, skill: ['prismakit'] });
+    expect(fs.readFileSync(skillFile, 'utf-8')).not.toContain('# dirty');
+    expect(
+      fs.existsSync(path.join(cwd, '.cursor/skills/prismakit-nestjs')),
+    ).toBe(false);
+  });
+
+  it('dry-run does not write files', () => {
+    const cwd = tmpDir();
+    runSkills({ cwd, skillsRoot: repoSkills, dryRun: true });
+    expect(fs.existsSync(path.join(cwd, '.cursor'))).toBe(false);
+  });
+
+  it('copies the data-access rule with --with-rules', () => {
+    const cwd = tmpDir();
+    const rulesPath = path.resolve(
+      repoSkills,
+      '../templates/cursor-rules/data-access.mdc',
+    );
+    const result = runSkills({
+      cwd,
+      skillsRoot: repoSkills,
+      withRules: true,
+      rulesPath,
+      skill: ['prismakit'],
+    });
+    expect(result.ruleDest).toBe(
+      path.join(cwd, '.cursor/rules/data-access.mdc'),
+    );
+    expect(fs.existsSync(result.ruleDest!)).toBe(true);
+    expect(fs.readFileSync(result.ruleDest!, 'utf-8')).toContain(
+      'repository-only',
+    );
+  });
+
+  it('rejects unknown skill names', () => {
+    expect(() =>
+      runSkills({
+        cwd: tmpDir(),
+        skillsRoot: repoSkills,
+        skill: ['nope'],
+      }),
+    ).toThrow(/Unknown skill/);
+  });
+});

package/src/bin.ts

@@ -1,14 +1,14 @@
 import { runGenerate } from './commands/generate';
-import { runCodegen } from './commands/codegen';
 import { runValidate } from './commands/validate';
+import { runSkills } from './commands/skills';
 
 function printHelp(): void {
   console.log(`prismakit — PrismaKit CLI
 
 Usage:
   prismakit generate <name> [--cache] [--full] [--helpers] [--dto] [--route <path>] [--prisma-import <path>] [--dry-run]
-  prismakit codegen [--schema <path>] [--write] [--out <file>]
-  prismakit validate [--no-assert]
+  prismakit validate [--schema <path>] [--auto-register] [--no-assert]
+  prismakit skills [--global] [--with-rules] [--skill <name>] [--project <path>] [--list] [--dry-run]
   prismakit help
 
 By default, generate writes only the repository file.
@@ -18,8 +18,10 @@ Pass --helpers / --dto with --full for helpers and Swagger DTOs.
 Examples:
   prismakit generate product --cache
   prismakit generate product --cache --full --helpers --dto --route products
-  prismakit codegen --write
-  prismakit validate
+  prismakit validate --auto-register
+  prismakit skills
+  prismakit skills --global
+  prismakit skills --with-rules
 `);
 }
 
@@ -34,10 +36,12 @@ function parseArgs(argv: string[]): {
 
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
-    if (arg.startsWith('--')) {
+    if (arg === '-g') {
+      flags.global = true;
+    } else if (arg.startsWith('--')) {
       const key = arg.slice(2);
       const next = rest[i + 1];
-      if (next && !next.startsWith('--')) {
+      if (next && !next.startsWith('-')) {
         flags[key] = next;
         i++;
       } else {
@@ -80,18 +84,29 @@ function main(): void {
         });
         break;
       }
-      case 'codegen': {
-        runCodegen({
+      case 'validate': {
+        runValidate({
+          assert: !flags['no-assert'],
           schemaPath:
             typeof flags.schema === 'string' ? flags.schema : undefined,
-          write: !!flags.write,
-          outFile: typeof flags.out === 'string' ? flags.out : undefined,
+          autoRegisterModels: !!flags['auto-register'],
         });
         break;
       }
-      case 'validate': {
-        runValidate({
-          assert: !flags['no-assert'],
+      case 'skills':
+      case 'skill': {
+        const skillFlag = flags.skill;
+        runSkills({
+          global: !!flags.global,
+          withRules: !!flags['with-rules'],
+          dryRun: !!flags['dry-run'],
+          list: !!flags.list,
+          projectRoot:
+            typeof flags.project === 'string' ? flags.project : undefined,
+          skill:
+            typeof skillFlag === 'string'
+              ? skillFlag.split(',').map((s) => s.trim()).filter(Boolean)
+              : undefined,
         });
         break;
       }