@prismakit/cli 3.1.0 → 3.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismakit/cli",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "CLI for PrismaKit — generate modules, validate compose, install agent skills",
   "license": "Apache-2.0",
   "engines": {
@@ -28,11 +28,18 @@
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
   "dependencies": {
-    "@prismakit/core": "3.1.0"
+    "@prismakit/core": "workspace:*"
   },
   "peerDependencies": {
-    "@prismakit/core": ">=3.1.0 <4"
+    "@prismakit/core": ">=3.2.0 <4"
   },
   "devDependencies": {
     "typescript": "^5.9.2",
@@ -56,12 +63,5 @@
     "prismakit",
     "cursor",
     "skills"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "tsc -p tsconfig.json --noEmit",
-    "clean": "rm -rf dist"
-  }
-}
+  ]
+}

package/skills/prismakit/SKILL.md

@@ -52,8 +52,9 @@ Helpers may inject repositories — never the Prisma client.
 | Existence / uniqueness / auth | `getFirst` — **no** `setCache` |
 | List | `getMany` + `setCache: true` + optional `cacheTags` |
 | Paginated list | `getManyPaginate` |
-| Large / infinite list | `getManyCursor` |
+| Large / infinite list | `getManyCursor` (with `cursor` → default `skip: 1`) |
 | Count / exists check | `count` / `exists` (no `setCache` on auth paths) |
+| Composite PK row | `id: { a, b }` object — kit maps to Prisma `a_b: { a, b }` |
 | Aggregations | `aggregate` / `groupBy` |
 | Create / update / delete | matching mutation; default invalidation is enough outside tx |
 | Multi-step write | one transaction; pass `tx` into every repo call |
@@ -63,7 +64,7 @@ Helpers may inject repositories — never the Prisma client.
 ## Create a repository (core)
 
 ```typescript
-import { Prisma, PrismaClient } from '@prisma/client';
+import { PrismaClient } from '@prisma/client';
 import { createRepository } from '@prismakit/core';
 import { RedisCacheAdapter } from '@prismakit/redis';
 
@@ -71,9 +72,8 @@ const DAY = 86_400;
 
 const UserRepoClass = createRepository({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
   cache: { ttl: DAY, nullTtl: 60, sensitiveFields: ['password'] },
-  lock: true, // table + columns from Prisma meta
+  lock: true, // table + columns resolved from Prisma schema meta
 });
 
 const prisma = new PrismaClient();
@@ -83,14 +83,16 @@ export const users = new UserRepoClass({ prisma, cache });
 
 `defineRepository` and `createPrismaRepository` are aliases of `createRepository`.
 
+**NestJS apps:** use `createDefineRepo` / `defineAppRepo` with app-wide cache defaults instead — see skill `prismakit-nestjs`.
+
 | Option | Description |
 |--------|-------------|
 | `model` | Prisma client key (`prisma.user` → `'user'`). Needed for cache + compose. |
-| `scalarFields` | Usually `Prisma.XScalarFieldEnum`. Enables select-split + compose. Optional if DMMF/schema meta is loaded. |
-| `cache` | `CacheOptions` or `true` → `{ ttl: 86400, sensitiveFields: ['password'] }`. |
+| `scalarFields` | Usually `Prisma.XScalarFieldEnum`. **Optional** when `schemaPath` / DMMF meta is loaded (default since 3.1). |
+| `cache` | `CacheOptions` or `true` (uses app defaults when bound via `createDefineRepo`). |
 | `lock` | `true` / client key / `@@map` table / `{ tableName, columns }`. |
 | `primaryKey` | Override only. Defaults to schema `@id` / `@@id` (composite `string[]`) or `id`. |
-| `schemaPath` | Path to `schema.prisma` when meta is not loaded globally. |
+| `schemaPath` | Path to `schema.prisma` when meta is not loaded globally. Default: `prisma/schema.prisma`. |
 | `getDelegate` | Optional. Defaults to `(c) => c[model]`. |
 
 Put files under `**/repositories/**`. Keep Prisma client construction under `**/infrastructure/prisma/**`.
@@ -124,7 +126,9 @@ await users.getFirst({
 | `count` / `exists` | `{ count }` / `{ exists }` |
 | `aggregate` / `groupBy` | Prisma delegate results |
 
-`id` is `string` or `Record<string, string>` for composite PKs.
+`id` is `string` or `Record<string, string>` for composite PKs (object form for `@@id([a,b])`).
+
+`getManyCursor`: when `cursor` is set, default `skip` is `1` so the cursor row is not repeated. Pass `skip: 0` only for inclusive semantics.
 
 ## Writes
 
@@ -234,6 +238,11 @@ export default [prismakit.configs.recommended];
 
 Allowed Prisma usage: `**/repositories/**`, `**/infrastructure/prisma/**`. Rules: `no-prisma-service-outside-repos`, `no-direct-prisma-delegate`, `require-transaction-service`, `require-cached-repo-provider`.
 
+## Observability
+
+- Core: `setTelemetry({ enabled, onEvent })` or Nest `telemetry` / `queryLog.slowThreshold`.
+- Optional: `@prismakit/opentelemetry` → `createPrismaKitTelemetry({ slowThreshold })`.
+
 ## Clean code
 
 - One repository per Prisma model, file `*.repository.ts` under `repositories/`.
@@ -241,6 +250,7 @@ Allowed Prisma usage: `**/repositories/**`, `**/infrastructure/prisma/**`. Rules
 - Named TTL constants (`const DAY = 86_400`), not magic numbers scattered in call sites.
 - Pass `tx` into **every** repo call in a unit of work. Do not mix cached reads with half-committed writes.
 - Tests: `@prismakit/memory` `MemoryCacheAdapter`. Production: `@prismakit/redis`.
+- Library CI proves PG+Redis paths under `FORCE_INTEGRATION=1` (CRUD, compose, locks, stampede, fail-open).
 
 ## Anti-patterns (BAD → GOOD)
 

package/skills/prismakit/reference.md

@@ -9,16 +9,18 @@ API surface for `@prismakit/core` 3.x. Read [SKILL.md](SKILL.md) first.
 | `@prismakit/core` | `createRepository`, AutoComposer, locks, pagination, `CacheAdapter` |
 | `@prismakit/redis` | `RedisCacheAdapter` |
 | `@prismakit/memory` | `MemoryCacheAdapter` (tests / local) |
+| `@prismakit/opentelemetry` | Map telemetry → OTel metrics/spans |
 | `@prismakit/cli` | `prismakit generate / validate / skills` |
 | `@prismakit/eslint-plugin` | Repository-only data-access rules |
 
-Node ≥ 20. Install:
+Node ≥ 20. Line **3.2.x**. Install:
 
 ```bash
 pnpm add @prismakit/core
 pnpm add @prismakit/redis ioredis          # optional production cache
 pnpm add -D @prismakit/eslint-plugin @prismakit/cli
 # tests: pnpm add -D @prismakit/memory
+# optional: pnpm add @prismakit/opentelemetry @opentelemetry/api
 ```
 
 ## Factory
@@ -40,7 +42,7 @@ Aliases: `defineRepository`, `createPrismaRepository`.
 | `cache` | `CacheOptions \| true` | `true` → `{ ttl: 86400, sensitiveFields: ['password'] }`. |
 | `lock` | `true \| string \| RepositoryLockConfig` | `true` / client key / Pascal name / `@@map` table. |
 | `schemaPath` | `string` | Lock/schema helpers when global meta is missing. |
-| `primaryKey` | `string \| string[]` | `*ById` + row locks. Default: meta PK or `id`. |
+| `primaryKey` | `string \| string[]` | `*ById` + row locks. Default: meta PK or `id`. Composite → Prisma `a_b: { a, b }` where. |
 | `getDelegate` | `(client) => delegate` | Default `(c) => c[model]`. |
 | `toPayload` | `(data) => payload` | Default identity. Prefer typed factories over this. |
 
@@ -59,7 +61,7 @@ All methods accept optional `tx`. Cached repos also accept cache fields (see bel
 | `getFirst` | `where?`, `select?`, `lock?`, `setCache?`, `cacheTags?` | `T \| null` |
 | `getMany` | `where?`, `select?`, `orderBy?`, `take?`, `skip?`, `lock?`, `setCache?`, `cacheTags?` | `T[]` |
 | `getManyPaginate` | `where?`, `select?`, `orderBy?`, `page?`, `pageSize?`, `setCache?`, `cacheTags?` | `PaginatedResult<T>` |
-| `getManyCursor` | `where?`, `select?`, `orderBy?`, `cursor?`, `take?`, `skip?`, `setCache?`, `cacheTags?` | `CursorPage<T>` |
+| `getManyCursor` | `where?`, `select?`, `orderBy?`, `cursor?`, `take?`, `skip?`, `setCache?`, `cacheTags?` | `CursorPage<T>`; with `cursor`, default `skip: 1` |
 | `count` | `where?`, `select?`, `setCache?`, `cacheTags?` | `{ count: number }` |
 | `exists` | `where?`, `setCache?`, `cacheTags?` | `{ exists: boolean }` |
 | `aggregate` | Prisma aggregate args + `setCache?`, `cacheTags?` | delegate result |

package/skills/prismakit-nestjs/SKILL.md

@@ -45,37 +45,65 @@ export class AppModule {}
 
 ## Factory (one default)
 
-Bind `Prisma.TypeMap` once, then define repos with runtime options only.
+Bind `Prisma.TypeMap` once with app-wide cache defaults, then define repos with per-model overrides only.
 
 ```typescript
-// src/infrastructure/prisma/define-repo.ts
+// src/infrastructure/prisma/define-app-repo.ts
 import { createDefineRepo } from '@prismakit/nestjs';
-import type { Prisma } from '@prisma/client';
+import type { Prisma } from '@prisma/client'; // or generated client path
 
-export const defineRepo = createDefineRepo<Prisma.TypeMap>();
+const DAY = 86_400;
+
+export const defineAppRepo = createDefineRepo<Prisma.TypeMap>({
+  cache: {
+    ttl: DAY,
+    nullTtl: 60,
+    defaultSetCache: true,
+  },
+});
 ```
 
 ```typescript
 // src/modules/users/repositories/user.repository.ts
-import { Prisma } from '@prisma/client';
-import { defineRepo } from '../../../infrastructure/prisma/define-repo';
-
-const DAY = 86_400;
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
 
-export class UserRepository extends defineRepo({
+export class UserRepository extends defineAppRepo({
   model: 'user',
-  scalarFields: Prisma.UserScalarFieldEnum,
-  cache: { ttl: DAY, nullTtl: 60, sensitiveFields: ['password'] },
-  lock: true,
+  cache: {
+    defaultSetCache: false,       // auth lookups pass setCache explicitly
+    sensitiveFields: ['password'],
+    methods: { getFirst: { enabled: false } },
+  },
 }) {}
 ```
 
+```typescript
+// src/modules/category/repositories/category.repository.ts
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
+
+export class CategoryRepository extends defineAppRepo({
+  model: 'category',
+  cache: true, // inherits app-wide defaults (ttl, nullTtl, defaultSetCache)
+}) {}
+```
+
+```typescript
+// Uncached repo — TypeScript omits setCache / invalidateCache
+import { defineAppRepo } from 'src/infrastructure/prisma/define-app-repo';
+
+export class AuditLogRepository extends defineAppRepo({
+  model: 'auditLog',
+}) {}
+```
+
+`scalarFields` is **optional** when `schemaPath` or DMMF meta is loaded (default since 3.1). Omit it in new repos.
+
 Escape hatches (do not use as the app default):
 
 - `defineInjectableRepository` from `@prismakit/nestjs` (package alias `defineRepository`) — phantoms + payload HKT when TypeMap is unavailable.
 - `createInjectableRepository` without a types bag — thin, results are `unknown`. Alias: `createPrismaRepository`.
 
-Do not import `defineRepo` from `@prismakit/nestjs` in apps that already bind `createDefineRepo` as `defineRepo`.
+Do not import `defineRepo` from `@prismakit/nestjs` in apps that already bind `createDefineRepo` as `defineAppRepo`.
 
 ## Register and inject
 
@@ -196,8 +224,8 @@ Repository `cache` is the source of truth. Omit `cacheModels` (fail-open). Pass
 | `validateCompose: true` | Assert compose-safe selects on boot |
 | `strictCachedRepos` | Fail boot if a `cache` repo class is not in Nest `providers` (default `true`) |
 | `compose` | `{ maxDepth, parallel, setCache }` |
-| `telemetry` | `{ enabled: true, onEvent }` |
-| `queryLog` | `{ slowThreshold, onSlowQuery }` — enables telemetry |
+| `telemetry` | `{ enabled: true, onEvent }` or `createPrismaKitTelemetry()` from `@prismakit/opentelemetry` |
+| `queryLog` | `{ slowThreshold, onSlowQuery }` — enables telemetry / `query.slow` |
 | `autoRegisterModels` | `true` or `string[]` — stub repos for compose-only models |
 
 ## Scaffolding
@@ -205,12 +233,15 @@ Repository `cache` is the source of truth. Omit `cacheModels` (fail-open). Pass
 ```bash
 npx prismakit generate product --cache
 npx prismakit generate product --cache --full --route products
+npx prismakit skills   # refresh .cursor/skills after upgrades
 ```
 
 Repo-only: add the class to feature `providers`. `--full`: import `*Module` in `AppModule`. Then `npx prismakit validate`.
 
 Enable ESLint `prismakit.configs.recommended` (see skill `prismakit`).
 
+Reference app: [starter-prismakit-nestjs](https://github.com/fikiap23/starter-prismakit-nestjs) (Nest 11 + Prisma 7 + Redis).
+
 ## Clean code (Nest)
 
 - One `defineRepo` binder under `src/infrastructure/prisma/`. Do not call `createDefineRepo` per feature.