@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/cursor/prisma-seeding-pattern/skill.yaml

@@ -0,0 +1,41 @@
+name: prisma-seeding-pattern
+version: "1.0.0"
+description: Seed databases idempotently with prisma/seed.ts, --seed flag, and environment branching
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "prisma/seed.ts"
+  - "prisma/seed.js"
+  - "**/prisma/**"
+related_skills:
+  - prisma-schema-design
+  - prisma-migrations
+  - prisma-client-queries
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - seeding
+  - seed
+  - database-fixtures
+  - idempotent
+  - test-data
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-migrate/workflows/seeding"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/prisma-soft-delete/SKILL.md

@@ -0,0 +1,172 @@
+# Prisma Soft Delete
+
+> Implement soft deletes in Prisma with middleware or $extends query extensions and deletedAt pattern
+
+## When to Use
+
+- Retaining records for audit trails instead of permanently deleting them
+- Implementing "trash" or "archive" features with restore capability
+- Meeting regulatory requirements that mandate data retention
+- Protecting against accidental deletion in production systems
+
+## Instructions
+
+1. **Add a `deletedAt` field** to models that need soft delete:
+
+```prisma
+model Post {
+  id        String    @id @default(cuid())
+  title     String
+  content   String
+  deletedAt DateTime?
+  createdAt DateTime  @default(now())
+  updatedAt DateTime  @updatedAt
+
+  @@index([deletedAt])
+}
+```
+
+2. **Use `$extends` (recommended)** to intercept delete operations and convert them to updates:
+
+```typescript
+const prisma = new PrismaClient().$extends({
+  query: {
+    post: {
+      async delete({ args, query }) {
+        return prisma.post.update({
+          ...args,
+          data: { deletedAt: new Date() },
+        });
+      },
+      async deleteMany({ args, query }) {
+        return prisma.post.updateMany({
+          ...args,
+          data: { deletedAt: new Date() },
+        });
+      },
+    },
+  },
+});
+```
+
+3. **Auto-filter deleted records** by extending `findMany`, `findFirst`, and `findUnique`:
+
+```typescript
+const prisma = new PrismaClient().$extends({
+  query: {
+    post: {
+      async findMany({ args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+      async findFirst({ args, query }) {
+        args.where = { ...args.where, deletedAt: null };
+        return query(args);
+      },
+      async findUnique({ args, query }) {
+        // findUnique cannot filter on non-unique fields;
+        // fall back to findFirst
+        return prisma.post.findFirst({
+          where: { ...args.where, deletedAt: null },
+        });
+      },
+    },
+  },
+});
+```
+
+4. **Create a reusable extension** for multiple models:
+
+```typescript
+function softDeleteExtension<T extends string>(modelName: T) {
+  return {
+    query: {
+      [modelName]: {
+        async delete({ args, query }: any) {
+          return (prisma as any)[modelName].update({
+            ...args,
+            data: { deletedAt: new Date() },
+          });
+        },
+        async findMany({ args, query }: any) {
+          args.where = { ...args.where, deletedAt: null };
+          return query(args);
+        },
+      },
+    },
+  };
+}
+```
+
+5. **Add a restore function** — either as a regular update or a model extension:
+
+```typescript
+// Restore a soft-deleted record
+await prisma.post.update({
+  where: { id: postId },
+  data: { deletedAt: null },
+});
+```
+
+6. **Hard delete when needed** — bypass the extension with `$executeRaw`:
+
+```typescript
+await prisma.$executeRaw`DELETE FROM "Post" WHERE id = ${postId}`;
+```
+
+7. **Filter relations** — ensure soft-deleted records are excluded from relation queries:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: userId },
+  include: { posts: { where: { deletedAt: null } } },
+});
+```
+
+## Details
+
+Soft delete replaces physical row deletion with a timestamp marker. The record remains in the database but is excluded from normal queries. This pattern is widely used for audit compliance, undo functionality, and data recovery.
+
+**`$extends` vs middleware:** Prisma deprecated middleware in favor of `$extends` (client extensions). Extensions are type-safe, composable, and scoped to specific models. Middleware applied globally and was hard to type correctly.
+
+**Index strategy:** Always add an index on `deletedAt`. Most queries filter on `WHERE "deletedAt" IS NULL`, so a partial index is ideal:
+
+```sql
+CREATE INDEX idx_post_active ON "Post" (id) WHERE "deletedAt" IS NULL;
+```
+
+Add this as a custom migration after Prisma generates the base migration.
+
+**Unique constraints with soft delete:** A unique constraint on `email` breaks if you soft-delete a user and create a new one with the same email. Solutions:
+
+- Use a partial unique index: `CREATE UNIQUE INDEX ON "User" (email) WHERE "deletedAt" IS NULL`
+- Append a suffix to soft-deleted records: `email_deleted_<timestamp>`
+- Use a composite unique: `@@unique([email, deletedAt])` (but `null` handling varies by database)
+
+**Cascading soft deletes:** Unlike `onDelete: Cascade`, soft deletes do not automatically cascade to related records. Implement cascading manually in the `$extends` delete handler or use database triggers.
+
+**Trade-offs:**
+
+- Soft delete increases table size over time — implement a purge job for records past the retention period
+- Every query must remember to filter `deletedAt` — the extension approach prevents this but adds overhead
+- Reporting queries that need deleted records must explicitly include them, which the auto-filter makes harder
+
+## Source
+
+https://prisma.io/docs/orm/prisma-client/queries/middleware/soft-delete-middleware
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/prisma-soft-delete/skill.yaml

@@ -0,0 +1,41 @@
+name: prisma-soft-delete
+version: "1.0.0"
+description: Implement soft deletes in Prisma with middleware or $extends query extensions and deletedAt pattern
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/prisma/**"
+  - "**/*.service.ts"
+  - "**/*.repository.ts"
+related_skills:
+  - prisma-client-queries
+  - prisma-schema-design
+  - prisma-filtering-sorting
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - soft-delete
+  - deletedAt
+  - middleware
+  - $extends
+  - query-extension
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-client/queries/middleware/soft-delete-middleware"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/prisma-transactions/SKILL.md

@@ -0,0 +1,147 @@
+# Prisma Transactions
+
+> Execute atomic operations with Prisma $transaction, interactive transactions, and nested writes
+
+## When to Use
+
+- Performing multiple database operations that must all succeed or all fail
+- Transferring data between records (e.g., balance transfers, inventory moves)
+- Executing a sequence of reads and writes that depend on each other
+- Running batch operations that need rollback on partial failure
+
+## Instructions
+
+1. **Sequential transaction** — pass an array of Prisma operations. They execute in order within a single transaction:
+
+```typescript
+const [order, payment] = await prisma.$transaction([
+  prisma.order.create({ data: { userId, total: 99.99 } }),
+  prisma.payment.create({ data: { userId, amount: 99.99, status: 'PENDING' } }),
+]);
+```
+
+2. **Interactive transaction** — pass an async callback for operations that depend on intermediate results:
+
+```typescript
+const transfer = await prisma.$transaction(async (tx) => {
+  const sender = await tx.account.update({
+    where: { id: senderId },
+    data: { balance: { decrement: amount } },
+  });
+
+  if (sender.balance < 0) {
+    throw new Error('Insufficient funds');
+  }
+
+  const receiver = await tx.account.update({
+    where: { id: receiverId },
+    data: { balance: { increment: amount } },
+  });
+
+  return { sender, receiver };
+});
+```
+
+Throwing inside the callback rolls back the entire transaction.
+
+3. **Set isolation level** to control read consistency:
+
+```typescript
+await prisma.$transaction(
+  async (tx) => {
+    /* ... */
+  },
+  { isolationLevel: Prisma.TransactionIsolationLevel.Serializable }
+);
+```
+
+4. **Set timeout** for long-running transactions:
+
+```typescript
+await prisma.$transaction(
+  async (tx) => {
+    /* ... */
+  },
+  { maxWait: 5000, timeout: 10000 }
+);
+```
+
+- `maxWait` — maximum time to wait for a connection from the pool (ms)
+- `timeout` — maximum time the transaction can run before auto-rollback (ms)
+
+5. **Nested writes are implicit transactions** — a single `create`/`update` with nested operations is already atomic:
+
+```typescript
+// This is already transactional — no $transaction wrapper needed
+const user = await prisma.user.create({
+  data: {
+    email: 'user@example.com',
+    profile: { create: { bio: 'Hello' } },
+    posts: { create: [{ title: 'Post 1' }, { title: 'Post 2' }] },
+  },
+});
+```
+
+6. **Use the `tx` client** inside interactive transactions, not the global `prisma` client. Queries on the global client run outside the transaction.
+
+7. **Batch operations** — combine `createMany`, `updateMany`, and `deleteMany` in a sequential transaction for bulk operations:
+
+```typescript
+await prisma.$transaction([
+  prisma.notification.deleteMany({ where: { read: true, createdAt: { lt: cutoff } } }),
+  prisma.auditLog.create({ data: { action: 'CLEANUP', count: deletedCount } }),
+]);
+```
+
+## Details
+
+Prisma supports two transaction modes: sequential (array) and interactive (callback). Both produce a real database transaction with ACID guarantees.
+
+**Sequential vs interactive:** Sequential transactions execute all operations in order but you cannot read intermediate results. Interactive transactions give you a transaction-scoped client (`tx`) that lets you read and branch on results. Use sequential for independent writes; use interactive when operations depend on each other.
+
+**Isolation levels:** `ReadUncommitted`, `ReadCommitted`, `RepeatableRead`, `Serializable`. The default varies by provider (PostgreSQL defaults to `ReadCommitted`). Higher isolation levels prevent more anomalies but increase lock contention and deadlock risk.
+
+**Interactive transaction pitfalls:**
+
+- Keep transactions short — long-running transactions hold locks and block other connections
+- Avoid external API calls inside transactions — if the API is slow, the transaction holds locks needlessly
+- The `tx` client is only valid inside the callback — do not pass it to background jobs
+- Default timeout is 5 seconds. Increase it explicitly for migrations or batch operations
+
+**Nested writes vs explicit transactions:** Nested writes (connect, create, connectOrCreate within a single operation) are cleaner and more performant than wrapping individual operations in `$transaction`. Use explicit transactions only when you need conditional logic between operations.
+
+**Deadlocks:** If two transactions lock the same rows in different order, the database detects the deadlock and aborts one transaction. Prisma surfaces this as error code `P2034`. Retry the transaction in application code:
+
+```typescript
+async function withRetry<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
+  for (let i = 0; i < retries; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (e.code === 'P2034' && i < retries - 1) continue;
+      throw e;
+    }
+  }
+  throw new Error('Unreachable');
+}
+```
+
+## Source
+
+https://prisma.io/docs/orm/prisma-client/queries/transactions
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/prisma-transactions/skill.yaml

@@ -0,0 +1,41 @@
+name: prisma-transactions
+version: "1.0.0"
+description: Execute atomic operations with Prisma $transaction, interactive transactions, and nested writes
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/prisma/**"
+  - "**/*.service.ts"
+  - "**/*.repository.ts"
+related_skills:
+  - prisma-client-queries
+  - prisma-performance-patterns
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - transactions
+  - $transaction
+  - interactive-transaction
+  - isolation-level
+  - nested-writes
+  - atomicity
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-client/queries/transactions"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/prisma-type-generation/SKILL.md

@@ -0,0 +1,180 @@
+# Prisma Type Generation
+
+> Use generated Prisma types like XxxCreateInput, XxxWhereInput, $Enums, and validator utilities
+
+## When to Use
+
+- Typing function parameters that accept Prisma query inputs
+- Building type-safe service layers that wrap Prisma operations
+- Accessing generated enum types in application code
+- Creating DTOs or API schemas that align with the Prisma data model
+
+## Instructions
+
+1. **Regenerate types** after schema changes:
+
+```bash
+npx prisma generate
+```
+
+This runs automatically after `migrate dev` but must be run manually after editing the schema without migrating.
+
+2. **Import generated types** from `@prisma/client`:
+
+```typescript
+import { Prisma, User, Post, Role } from '@prisma/client';
+```
+
+- `User`, `Post` — model types (the shape returned by queries)
+- `Role` — enum type
+- `Prisma` — namespace containing all input/output types
+
+3. **Use input types** for service function parameters:
+
+```typescript
+import { Prisma } from '@prisma/client';
+
+async function createUser(data: Prisma.UserCreateInput) {
+  return prisma.user.create({ data });
+}
+
+async function findUsers(where: Prisma.UserWhereInput) {
+  return prisma.user.findMany({ where });
+}
+```
+
+4. **Access enum values** from the `$Enums` export or directly:
+
+```typescript
+import { Role } from '@prisma/client';
+
+// Use as a type
+function isAdmin(role: Role): boolean {
+  return role === 'ADMIN';
+}
+
+// Use enum values
+const defaultRole: Role = 'USER';
+```
+
+5. **Extract return types** from queries using `Prisma.UserGetPayload`:
+
+```typescript
+type UserWithPosts = Prisma.UserGetPayload<{
+  include: { posts: true };
+}>;
+
+// UserWithPosts = User & { posts: Post[] }
+```
+
+6. **Type the result of `select`** queries:
+
+```typescript
+type UserSummary = Prisma.UserGetPayload<{
+  select: { id: true; name: true; email: true };
+}>;
+
+// UserSummary = { id: string; name: string | null; email: string }
+```
+
+7. **Use `Prisma.validator`** to create reusable, type-checked query objects:
+
+```typescript
+const userWithPosts = Prisma.validator<Prisma.UserDefaultArgs>()({
+  include: { posts: true },
+});
+
+// Use in queries
+const user = await prisma.user.findUnique({
+  where: { id },
+  ...userWithPosts,
+});
+```
+
+8. **Type service layers** that return a subset of fields:
+
+```typescript
+const userSelect = Prisma.validator<Prisma.UserSelect>()({
+  id: true,
+  email: true,
+  name: true,
+});
+
+type PublicUser = Prisma.UserGetPayload<{ select: typeof userSelect }>;
+
+async function getPublicUser(id: string): Promise<PublicUser | null> {
+  return prisma.user.findUnique({ where: { id }, select: userSelect });
+}
+```
+
+9. **Use `Prisma.UserScalarFieldEnum`** for dynamic field selection:
+
+```typescript
+const sortableFields = ['createdAt', 'name', 'email'] as const;
+
+function buildOrderBy(field: (typeof sortableFields)[number]): Prisma.UserOrderByWithRelationInput {
+  return { [field]: 'desc' };
+}
+```
+
+10. **Handle `JsonValue`** types from Json fields:
+
+```typescript
+import { Prisma } from '@prisma/client';
+
+// Prisma.JsonValue = string | number | boolean | null | Prisma.JsonObject | Prisma.JsonArray
+function parseMetadata(json: Prisma.JsonValue): Record<string, unknown> {
+  if (typeof json === 'object' && json !== null && !Array.isArray(json)) {
+    return json as Record<string, unknown>;
+  }
+  return {};
+}
+```
+
+## Details
+
+Prisma generates TypeScript types in `node_modules/.prisma/client/index.d.ts` based on your schema. These types power autocompletion, compile-time checking, and the entire Prisma Client API.
+
+**Type categories:**
+
+- **Model types** (`User`, `Post`) — plain objects representing a full database row
+- **Input types** (`UserCreateInput`, `UserUpdateInput`, `UserWhereInput`) — types for query arguments
+- **Output types** (`UserGetPayload<T>`) — types derived from specific select/include combinations
+- **Enum types** (`Role`, `Status`) — string literal unions matching schema enums
+- **Scalar field enums** (`UserScalarFieldEnum`) — union of field name strings
+
+**`UserCreateInput` vs `UserUncheckedCreateInput`:** The `Create` input uses relation fields (`author: { connect: { id } }`). The `Unchecked` variant uses raw foreign keys (`authorId: string`). Both produce the same SQL. Use the standard version for type safety; use the unchecked version when working with raw IDs.
+
+**Keeping types in sync:** Types are generated into `node_modules` and are not committed to version control. Run `prisma generate` in CI before type-checking. Add it to your build pipeline:
+
+```json
+{ "scripts": { "build": "prisma generate && tsc" } }
+```
+
+**Zod integration:** Use `zod-prisma-types` or `prisma-zod-generator` to auto-generate Zod schemas from your Prisma models. This eliminates manual synchronization between Prisma types and runtime validation:
+
+```prisma
+generator zod {
+  provider = "zod-prisma-types"
+}
+```
+
+## Source
+
+https://prisma.io/docs/orm/prisma-client/type-safety
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/prisma-type-generation/skill.yaml

@@ -0,0 +1,42 @@
+name: prisma-type-generation
+version: "1.0.0"
+description: Use generated Prisma types like XxxCreateInput, XxxWhereInput, $Enums, and validator utilities
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/prisma/**"
+  - "**/*.service.ts"
+  - "**/*.dto.ts"
+related_skills:
+  - prisma-schema-design
+  - prisma-client-queries
+  - ts-utility-types
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - type-generation
+  - Prisma.XxxCreateInput
+  - Prisma.XxxWhereInput
+  - $Enums
+  - inferSelect
+  - TypeScript
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-client/type-safety"
+state:
+  persistent: false
+  files: []
+depends_on: []