zilmate 1.7.8 → 1.8.0

package/.agents/skills/prisma-client-api/references/relations.md

@@ -0,0 +1,308 @@
+# Relation Queries
+
+Query and modify related records.
+
+## Include Relations
+
+Load related records:
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: true,
+    profile: true
+  }
+})
+```
+
+### Filtered include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      take: 5,
+      select: { id: true, title: true }
+    }
+  }
+})
+```
+
+### Nested include
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  include: {
+    posts: {
+      include: {
+        comments: {
+          include: { author: true }
+        }
+      }
+    }
+  }
+})
+```
+
+## Select Relations
+
+```typescript
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: {
+    name: true,
+    posts: {
+      select: { title: true }
+    }
+  }
+})
+```
+
+## Nested Writes
+
+### Create with relations
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    posts: {
+      create: [
+        { title: 'Post 1' },
+        { title: 'Post 2' }
+      ]
+    },
+    profile: {
+      create: { bio: 'Hello!' }
+    }
+  }
+})
+```
+
+### Create or connect
+
+```typescript
+const post = await prisma.post.create({
+  data: {
+    title: 'New Post',
+    author: {
+      connectOrCreate: {
+        where: { email: 'alice@prisma.io' },
+        create: { email: 'alice@prisma.io', name: 'Alice' }
+      }
+    }
+  }
+})
+```
+
+### Connect existing
+
+```typescript
+const post = await prisma.post.create({
+  data: {
+    title: 'New Post',
+    author: {
+      connect: { id: 1 }
+    }
+  }
+})
+
+// Shorthand for foreign key
+const post = await prisma.post.create({
+  data: {
+    title: 'New Post',
+    authorId: 1
+  }
+})
+```
+
+## Update Relations
+
+### Update related records
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      update: {
+        where: { id: 1 },
+        data: { title: 'Updated Title' }
+      }
+    }
+  }
+})
+```
+
+### Update many related
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      updateMany: {
+        where: { published: false },
+        data: { published: true }
+      }
+    }
+  }
+})
+```
+
+### Upsert related
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    profile: {
+      upsert: {
+        create: { bio: 'New bio' },
+        update: { bio: 'Updated bio' }
+      }
+    }
+  }
+})
+```
+
+### Disconnect
+
+```typescript
+// 1-to-1 optional
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    profile: { disconnect: true }
+  }
+})
+
+// Many-to-many
+const post = await prisma.post.update({
+  where: { id: 1 },
+  data: {
+    tags: {
+      disconnect: [{ id: 1 }, { id: 2 }]
+    }
+  }
+})
+```
+
+### Delete related
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      delete: { id: 1 }
+    }
+  }
+})
+
+// Delete many
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      deleteMany: { published: false }
+    }
+  }
+})
+```
+
+### Set (replace all)
+
+```typescript
+// Replace all related records
+const post = await prisma.post.update({
+  where: { id: 1 },
+  data: {
+    tags: {
+      set: [{ id: 1 }, { id: 2 }]
+    }
+  }
+})
+```
+
+## Relation Filters
+
+### some
+
+At least one matches:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    posts: { some: { published: true } }
+  }
+})
+```
+
+### every
+
+All match:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    posts: { every: { published: true } }
+  }
+})
+```
+
+### none
+
+None match:
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    posts: { none: { published: true } }
+  }
+})
+```
+
+### is / isNot (1-to-1)
+
+```typescript
+const users = await prisma.user.findMany({
+  where: {
+    profile: { is: { country: 'USA' } }
+  }
+})
+```
+
+## Count Relations
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    name: true,
+    _count: {
+      select: { posts: true, followers: true }
+    }
+  }
+})
+// { name: 'Alice', _count: { posts: 5, followers: 100 } }
+```
+
+### Filter counted relations
+
+```typescript
+const users = await prisma.user.findMany({
+  select: {
+    name: true,
+    _count: {
+      select: {
+        posts: { where: { published: true } }
+      }
+    }
+  }
+})
+```

package/.agents/skills/prisma-client-api/references/transactions.md

@@ -0,0 +1,184 @@
+# Transactions
+
+Execute multiple operations atomically.
+
+## Sequential Transactions
+
+Array of operations executed in order:
+
+```typescript
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: { email: 'alice@prisma.io' } }),
+  prisma.post.create({ data: { title: 'Hello', authorId: 1 } })
+])
+```
+
+### All or nothing
+
+If any operation fails, all are rolled back:
+
+```typescript
+try {
+  await prisma.$transaction([
+    prisma.user.create({ data: { email: 'alice@prisma.io' } }),
+    prisma.user.create({ data: { email: 'alice@prisma.io' } }) // Duplicate!
+  ])
+} catch (e) {
+  // Both operations rolled back
+}
+```
+
+## Interactive Transactions
+
+For complex logic and dependent operations:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  // Decrement sender balance
+  const sender = await tx.account.update({
+    where: { id: senderId },
+    data: { balance: { decrement: amount } }
+  })
+  
+  // Check balance
+  if (sender.balance < 0) {
+    throw new Error('Insufficient funds')
+  }
+  
+  // Increment recipient balance
+  await tx.account.update({
+    where: { id: recipientId },
+    data: { balance: { increment: amount } }
+  })
+})
+```
+
+### Transaction options
+
+```typescript
+await prisma.$transaction(
+  async (tx) => {
+    // operations
+  },
+  {
+    maxWait: 5000,    // Max wait to acquire lock (ms)
+    timeout: 10000,   // Max transaction duration (ms)
+    isolationLevel: 'Serializable'  // Isolation level
+  }
+)
+```
+
+### Isolation levels
+
+| Level | Description |
+|-------|-------------|
+| `ReadUncommitted` | Lowest isolation, can read uncommitted changes |
+| `ReadCommitted` | Only read committed changes |
+| `RepeatableRead` | Consistent reads within transaction |
+| `Serializable` | Highest isolation, serialized execution |
+
+## Nested Writes
+
+Automatic transactions for nested operations:
+
+```typescript
+// This is automatically a transaction
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    posts: {
+      create: [
+        { title: 'Post 1' },
+        { title: 'Post 2' }
+      ]
+    },
+    profile: {
+      create: { bio: 'Hello!' }
+    }
+  }
+})
+```
+
+## Transaction Client
+
+The `tx` parameter is a Prisma Client scoped to the transaction:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  // Use tx instead of prisma
+  await tx.user.create({ ... })
+  await tx.post.create({ ... })
+  
+  // Can call methods
+  const count = await tx.user.count()
+})
+```
+
+## OrThrow in Transactions
+
+Use with interactive transactions:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  // If not found, throws and rolls back entire transaction
+  const user = await tx.user.findUniqueOrThrow({
+    where: { id: 1 }
+  })
+  
+  await tx.post.create({
+    data: { title: 'New Post', authorId: user.id }
+  })
+})
+```
+
+## Best Practices
+
+### Keep transactions short
+
+```typescript
+// Good - only DB operations in transaction
+const data = prepareData() // Outside transaction
+await prisma.$transaction(async (tx) => {
+  await tx.user.create({ data })
+})
+```
+
+### Handle errors
+
+```typescript
+try {
+  await prisma.$transaction(async (tx) => {
+    // operations
+  })
+} catch (e) {
+  if (e.code === 'P2002') {
+    // Handle unique constraint violation
+  }
+  throw e
+}
+```
+
+### Use appropriate isolation
+
+```typescript
+// Default is fine for most cases
+await prisma.$transaction(async (tx) => {
+  // operations
+})
+
+// Use Serializable for strict consistency
+await prisma.$transaction(
+  async (tx) => { /* operations */ },
+  { isolationLevel: 'Serializable' }
+)
+```
+
+## Sequential vs Interactive
+
+| Feature | Sequential | Interactive |
+|---------|------------|-------------|
+| Syntax | Array | Async function |
+| Dependent ops | No | Yes |
+| Conditional logic | No | Yes |
+| Performance | Better | More flexible |
+| Use case | Simple batch | Complex logic |

package/.agents/skills/prisma-database-setup/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: prisma-database-setup
+description: Guides for configuring Prisma with different database providers (PostgreSQL, MySQL, SQLite, MongoDB, etc.). Use when setting up a new project, changing databases, or troubleshooting connection issues. Triggers on "configure postgres", "connect to mysql", "setup mongodb", "sqlite setup".
+license: MIT
+metadata:
+  author: prisma
+  version: "7.6.0"
+---
+
+# Prisma Database Setup
+
+Comprehensive guides for configuring Prisma ORM with various database providers.
+
+## When to Apply
+
+Reference this skill when:
+- Initializing a new Prisma project
+- Switching database providers
+- Configuring connection strings and environment variables
+- Troubleshooting database connection issues
+- Setting up database-specific features
+- Generating and instantiating Prisma Client
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Provider Guides | CRITICAL | provider names |
+| 2 | Prisma Postgres | HIGH | `prisma-postgres` |
+| 3 | Client Setup | CRITICAL | `prisma-client-setup` |
+
+## System Prerequisites
+
+- **Node.js 20.19.0+**
+- **TypeScript 5.4.0+**
+
+## Bun Runtime
+
+If you're using Bun, run Prisma CLI commands with `bunx --bun prisma ...` so Prisma uses the Bun runtime instead of falling back to Node.js.
+
+## Supported Databases
+
+| Database | Provider String | Notes |
+|----------|-----------------|-------|
+| PostgreSQL | `postgresql` | Default, full feature support |
+| MySQL | `mysql` | Widespread support, some JSON diffs |
+| SQLite | `sqlite` | Local file-based, no enum/scalar lists |
+| MongoDB | `mongodb` | Mongo-specific workflow; do not apply SQL driver-adapter guidance |
+| SQL Server | `sqlserver` | Microsoft ecosystem |
+| CockroachDB | `cockroachdb` | Distributed SQL, Postgres-compatible |
+| Prisma Postgres | `postgresql` | Managed serverless database |
+
+## Configuration Files
+
+Your configuration shape depends on the provider and Prisma major version:
+
+1. **All providers** use **`prisma/schema.prisma`**.
+2. **Prisma 7 SQL setups** typically use **`prisma.config.ts`** for datasource URLs.
+3. **MongoDB projects should stay on Prisma 6.x**, keep `url = env("DATABASE_URL")` in the schema, and continue using the classic MongoDB setup.
+
+## Driver Adapters
+
+The standard SQL workflow uses a driver adapter. Choose the adapter and driver for your database and pass the adapter to `PrismaClient`.
+
+| Database | Adapter | JS Driver |
+|----------|---------|-----------|
+| PostgreSQL | `@prisma/adapter-pg` | `pg` |
+| CockroachDB | `@prisma/adapter-pg` | `pg` |
+| Prisma Postgres (Node.js) | `@prisma/adapter-pg` | `pg` |
+| Prisma Postgres (edge/serverless) | `@prisma/adapter-ppg` | `@prisma/ppg` |
+| MySQL / MariaDB | `@prisma/adapter-mariadb` | `mariadb` |
+| SQLite | `@prisma/adapter-better-sqlite3` | `better-sqlite3` |
+| SQLite (Turso/LibSQL) | `@prisma/adapter-libsql` | `@libsql/client` |
+| SQL Server | `@prisma/adapter-mssql` | `node-mssql` |
+
+MongoDB should not follow the Prisma 7 SQL adapter workflow. Use the latest Prisma 6.x release for MongoDB projects and do not install a SQL `@prisma/adapter-*` package for it.
+
+Example (PostgreSQL):
+
+```ts
+import 'dotenv/config'
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
+const prisma = new PrismaClient({ adapter })
+```
+
+## Prisma Client Setup (Required)
+
+Prisma Client must be installed and generated for any database.
+
+1. Install Prisma CLI and Prisma Client:
+   ```bash
+   npm install prisma --save-dev
+   npm install @prisma/client
+   ```
+
+1. Add a generator block (`prisma-client` requires an explicit output path):
+   ```prisma
+   generator client {
+     provider = "prisma-client"
+     output   = "../generated"
+   }
+   ```
+
+1. Generate Prisma Client:
+   ```bash
+   npx prisma generate
+   ```
+
+1. For SQL providers, instantiate Prisma Client with the database-specific driver adapter:
+   ```typescript
+   import { PrismaClient } from '../generated/client'
+   import { PrismaPg } from '@prisma/adapter-pg'
+
+   const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
+   const prisma = new PrismaClient({ adapter })
+   ```
+
+1. Re-run `prisma generate` after every schema change.
+
+## Quick Reference
+
+### PostgreSQL
+```prisma
+datasource db {
+  provider = "postgresql"
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../generated"
+}
+```
+
+### MySQL
+```prisma
+datasource db {
+  provider = "mysql"
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../generated"
+}
+```
+
+### SQLite
+```prisma
+datasource db {
+  provider = "sqlite"
+}
+
+generator client {
+  provider = "prisma-client"
+  output   = "../generated"
+}
+```
+
+### MongoDB
+```prisma
+datasource db {
+  provider = "mongodb"
+  url      = env("DATABASE_URL")
+}
+
+generator client {
+  provider = "prisma-client-js"
+}
+```
+
+For MongoDB, stay on the latest Prisma 6.x line and keep the connection URL in `schema.prisma`. Do not move a MongoDB project to the Prisma 7 SQL adapter setup.
+
+## Rule Files
+
+See individual rule files for detailed setup instructions:
+
+```
+references/postgresql.md
+references/mysql.md
+references/sqlite.md
+references/mongodb.md
+references/sqlserver.md
+references/cockroachdb.md
+references/prisma-postgres.md
+references/prisma-client-setup.md
+```
+
+## How to Use
+
+Choose the provider reference file for your database, then apply `references/prisma-client-setup.md` to complete client generation and adapter setup. For MongoDB, use `references/mongodb.md` instead of copying the SQL adapter examples or Prisma 7 config pattern.