quiver-cli 0.1.0

package/template/.agents/skills/data/prisma-client-api/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: prisma-client-api
+description: Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".
+license: MIT
+metadata:
+  author: prisma
+  version: "7.6.0"
+---
+
+# Prisma Client API Reference
+
+Complete API reference for Prisma Client. This skill provides guidance on model queries, filtering, relations, and client methods for current Prisma projects.
+
+## When to Apply
+
+Reference this skill when:
+- Writing database queries with Prisma Client
+- Performing CRUD operations (create, read, update, delete)
+- Filtering and sorting data
+- Working with relations
+- Using transactions
+- Configuring client options
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Client Construction | HIGH | `constructor` |
+| 2 | Model Queries | CRITICAL | `model-queries` |
+| 3 | Query Shape | HIGH | `query-options` |
+| 4 | Filtering | HIGH | `filters` |
+| 5 | Relations | HIGH | `relations` |
+| 6 | Transactions | CRITICAL | `transactions` |
+| 7 | Raw SQL | CRITICAL | `raw-queries` |
+| 8 | Client Methods | MEDIUM | `client-methods` |
+
+## Quick Reference
+
+- `constructor` - `PrismaClient` setup, adapter wiring, logging, and SQL commenter plugins
+- `model-queries` - CRUD operations and bulk operations
+- `query-options` - `select`, `include`, `omit`, sort, pagination
+- `filters` - scalar and logical filter operators
+- `relations` - relation reads and nested writes
+- `transactions` - array and interactive transaction patterns
+- `raw-queries` - `$queryRaw` and `$executeRaw` safety
+- `client-methods` - lifecycle methods, extensions, and `satisfies` patterns for `prisma-client`
+
+## Client Instantiation
+
+```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 })
+```
+
+## Model Query Methods
+
+| Method | Description |
+|--------|-------------|
+| `findUnique()` | Find one record by unique field |
+| `findUniqueOrThrow()` | Find one or throw error |
+| `findFirst()` | Find first matching record |
+| `findFirstOrThrow()` | Find first or throw error |
+| `findMany()` | Find multiple records |
+| `create()` | Create a new record |
+| `createMany()` | Create multiple records |
+| `createManyAndReturn()` | Create multiple and return them |
+| `update()` | Update one record |
+| `updateMany()` | Update multiple records |
+| `updateManyAndReturn()` | Update multiple and return them |
+| `upsert()` | Update or create record |
+| `delete()` | Delete one record |
+| `deleteMany()` | Delete multiple records |
+| `count()` | Count matching records |
+| `aggregate()` | Aggregate values (sum, avg, etc.) |
+| `groupBy()` | Group and aggregate |
+
+## Query Options
+
+| Option | Description |
+|--------|-------------|
+| `where` | Filter conditions |
+| `select` | Fields to include |
+| `include` | Relations to load |
+| `omit` | Fields to exclude |
+| `orderBy` | Sort order |
+| `take` | Limit results |
+| `skip` | Skip results (pagination) |
+| `cursor` | Cursor-based pagination |
+| `distinct` | Unique values only |
+
+## Client Methods
+
+| Method | Description |
+|--------|-------------|
+| `$connect()` | Explicitly connect to database |
+| `$disconnect()` | Disconnect from database |
+| `$transaction()` | Execute transaction |
+| `$queryRaw()` | Execute raw SQL query |
+| `$executeRaw()` | Execute raw SQL command |
+| `$on()` | Subscribe to events |
+| `$extends()` | Add extensions |
+
+## Quick Examples
+
+### Find records
+
+```typescript
+// Find by unique field
+const user = await prisma.user.findUnique({
+  where: { email: 'alice@prisma.io' }
+})
+
+// Find with filter
+const users = await prisma.user.findMany({
+  where: { role: 'ADMIN' },
+  orderBy: { createdAt: 'desc' },
+  take: 10
+})
+```
+
+### Create records
+
+```typescript
+const user = await prisma.user.create({
+  data: {
+    email: 'alice@prisma.io',
+    name: 'Alice',
+    posts: {
+      create: { title: 'Hello World' }
+    }
+  },
+  include: { posts: true }
+})
+```
+
+### Update records
+
+```typescript
+const user = await prisma.user.update({
+  where: { id: 1 },
+  data: { name: 'Alice Smith' }
+})
+```
+
+### Delete records
+
+```typescript
+await prisma.user.delete({
+  where: { id: 1 }
+})
+```
+
+### Transactions
+
+```typescript
+const [user, post] = await prisma.$transaction([
+  prisma.user.create({ data: { email: 'alice@prisma.io' } }),
+  prisma.post.create({ data: { title: 'Hello', authorId: 1 } })
+])
+```
+
+## Rule Files
+
+Detailed API documentation:
+
+```
+references/constructor.md        - PrismaClient constructor options
+references/model-queries.md      - CRUD operations
+references/query-options.md      - select, include, omit, where, orderBy
+references/filters.md            - Filter conditions and operators
+references/relations.md          - Relation queries and nested operations
+references/transactions.md       - Transaction API
+references/raw-queries.md        - $queryRaw, $executeRaw
+references/client-methods.md     - $connect, $disconnect, $on, $extends
+```
+
+## Filter Operators
+
+| Operator | Description |
+|----------|-------------|
+| `equals` | Exact match |
+| `not` | Not equal |
+| `in` | In array |
+| `notIn` | Not in array |
+| `lt`, `lte` | Less than |
+| `gt`, `gte` | Greater than |
+| `contains` | String contains |
+| `startsWith` | String starts with |
+| `endsWith` | String ends with |
+| `mode` | Case sensitivity |
+
+## Relation Filters
+
+| Operator | Description |
+|----------|-------------|
+| `some` | At least one related record matches |
+| `every` | All related records match |
+| `none` | No related records match |
+| `is` | Related record matches (1-to-1) |
+| `isNot` | Related record doesn't match |
+
+## Resources
+
+- [Prisma Client API Reference](https://www.prisma.io/docs/orm/reference/prisma-client-reference)
+- [CRUD Operations](https://www.prisma.io/docs/orm/prisma-client/queries/crud)
+- [Filtering and Sorting](https://www.prisma.io/docs/orm/prisma-client/queries/filtering-and-sorting)
+
+## How to Use
+
+Pick the category from the table above, then open the matching reference file for implementation details and examples.

package/template/.agents/skills/data/prisma-client-api/references/client-methods.md

@@ -0,0 +1,223 @@
+# Client Methods
+
+Prisma Client instance methods.
+
+## $connect()
+
+Explicitly connect to the database:
+
+```typescript
+const prisma = new PrismaClient({ adapter })
+
+// Explicit connection
+await prisma.$connect()
+```
+
+### When to use
+
+Usually not needed - Prisma connects automatically on first query. Use for:
+- Fail fast on startup
+- Health checks
+- Pre-warming connections
+
+```typescript
+async function main() {
+  try {
+    await prisma.$connect()
+    console.log('Database connected')
+  } catch (e) {
+    console.error('Failed to connect:', e)
+    process.exit(1)
+  }
+}
+```
+
+## $disconnect()
+
+Close database connection:
+
+```typescript
+await prisma.$disconnect()
+```
+
+### Graceful shutdown
+
+```typescript
+process.on('beforeExit', async () => {
+  await prisma.$disconnect()
+})
+
+// Or with SIGTERM
+process.on('SIGTERM', async () => {
+  await prisma.$disconnect()
+  process.exit(0)
+})
+```
+
+### In tests
+
+```typescript
+afterAll(async () => {
+  await prisma.$disconnect()
+})
+```
+
+## $on()
+
+Subscribe to events:
+
+### Query events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [{ level: 'query', emit: 'event' }]
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Params:', e.params)
+  console.log('Duration:', e.duration, 'ms')
+})
+```
+
+### Log events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [
+    { level: 'info', emit: 'event' },
+    { level: 'warn', emit: 'event' },
+    { level: 'error', emit: 'event' }
+  ]
+})
+
+prisma.$on('info', (e) => console.log(e.message))
+prisma.$on('warn', (e) => console.warn(e.message))
+prisma.$on('error', (e) => console.error(e.message))
+```
+
+## $extends()
+
+Add extensions for custom behavior:
+
+### Add custom methods
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  client: {
+    $log: (message: string) => console.log(message)
+  }
+})
+
+prisma.$log('Hello!')
+```
+
+### Add model methods
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  model: {
+    user: {
+      async findByEmail(email: string) {
+        return prisma.user.findUnique({ where: { email } })
+      }
+    }
+  }
+})
+
+const user = await prisma.user.findByEmail('alice@prisma.io')
+```
+
+### Query extensions
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  query: {
+    user: {
+      async findMany({ args, query }) {
+        // Add default filter
+        args.where = { ...args.where, deletedAt: null }
+        return query(args)
+      }
+    }
+  }
+})
+```
+
+### Result extensions
+
+```typescript
+const prisma = new PrismaClient({ adapter }).$extends({
+  result: {
+    user: {
+      fullName: {
+        needs: { firstName: true, lastName: true },
+        compute(user) {
+          return `${user.firstName} ${user.lastName}`
+        }
+      }
+    }
+  }
+})
+
+const user = await prisma.user.findFirst()
+console.log(user.fullName) // Computed field
+```
+
+### Chain extensions
+
+```typescript
+const prisma = new PrismaClient({ adapter })
+  .$extends(loggingExtension)
+  .$extends(softDeleteExtension)
+  .$extends(computedFieldsExtension)
+```
+
+## $transaction()
+
+See `transactions.md` for details.
+
+## $queryRaw() / $executeRaw()
+
+See `raw-queries.md` for details.
+
+## Type utilities
+
+### Prisma namespace
+
+```typescript
+import { Prisma } from '../generated/client'
+
+// Input types
+type UserCreateInput = Prisma.UserCreateInput
+type UserWhereInput = Prisma.UserWhereInput
+
+// Output types
+type User = Prisma.UserGetPayload<{}>
+type UserWithPosts = Prisma.UserGetPayload<{
+  include: { posts: true }
+}>
+```
+
+### Type-safe query fragments with satisfies
+
+Type-safe query fragments:
+
+```typescript
+import { Prisma } from '../generated/client'
+
+const userSelect = {
+  id: true,
+  email: true,
+  name: true
+} satisfies Prisma.UserSelect
+
+const user = await prisma.user.findUnique({
+  where: { id: 1 },
+  select: userSelect
+})
+```
+
+With the `prisma-client` generator, use TypeScript `satisfies` for typed query fragments. You may still see older examples that use `Prisma.validator()` with `prisma-client-js`.

package/template/.agents/skills/data/prisma-client-api/references/constructor.md

@@ -0,0 +1,208 @@
+# PrismaClient Constructor
+
+Configure Prisma Client when instantiating.
+
+## Basic Instantiation
+
+```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 })
+```
+
+## Constructor Options
+
+### adapter (Required for the SQL provider workflow)
+
+Driver adapter instance:
+
+```typescript
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({
+  connectionString: process.env.DATABASE_URL
+})
+
+const prisma = new PrismaClient({ adapter })
+```
+
+### accelerateUrl (For Accelerate users)
+
+```typescript
+import { withAccelerate } from '@prisma/extension-accelerate'
+
+const prisma = new PrismaClient({
+  accelerateUrl: process.env.DATABASE_URL,  // prisma:// URL
+}).$extends(withAccelerate())
+```
+
+### log
+
+Configure logging:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: ['query', 'info', 'warn', 'error'],
+})
+```
+
+#### Log levels
+
+| Level | Description |
+|-------|-------------|
+| `query` | All SQL queries |
+| `info` | Informational messages |
+| `warn` | Warnings |
+| `error` | Errors |
+
+#### Log to events
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [
+    { level: 'query', emit: 'event' },
+    { level: 'error', emit: 'stdout' },
+  ],
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Duration:', e.duration, 'ms')
+})
+```
+
+### errorFormat
+
+Control error formatting:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  errorFormat: 'pretty',  // 'pretty' | 'colorless' | 'minimal'
+})
+```
+
+### comments
+
+Attach SQL commenter plugins for observability, tracing, or query insights:
+
+```typescript
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+import { prismaQueryInsights } from '@prisma/sqlcommenter-query-insights'
+import { queryTags, withQueryTags } from '@prisma/sqlcommenter-query-tags'
+import { traceContext } from '@prisma/sqlcommenter-trace-context'
+
+const prisma = new PrismaClient({
+  adapter: new PrismaPg(process.env.DATABASE_URL!),
+  comments: [prismaQueryInsights(), traceContext(), queryTags()],
+})
+
+await withQueryTags({ route: '/api/users', requestId: 'req-123' }, () =>
+  prisma.user.findMany(),
+)
+```
+
+Use `comments` only for SQL providers. This is the clean way to add trace or query-shape metadata without changing your query calls.
+
+### transactionOptions
+
+Default transaction settings:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  transactionOptions: {
+    maxWait: 5000,      // Max wait to acquire transaction (ms)
+    timeout: 10000,     // Max transaction duration (ms)
+    isolationLevel: 'Serializable',
+  },
+})
+```
+
+## Singleton Pattern
+
+Prevent multiple client instances in development:
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '../generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const globalForPrisma = globalThis as unknown as {
+  prisma: PrismaClient | undefined
+}
+
+function createPrismaClient() {
+  const adapter = new PrismaPg({
+    connectionString: process.env.DATABASE_URL!
+  })
+  return new PrismaClient({ adapter })
+}
+
+export const prisma = globalForPrisma.prisma ?? createPrismaClient()
+
+if (process.env.NODE_ENV !== 'production') {
+  globalForPrisma.prisma = prisma
+}
+```
+
+## Next.js Pattern
+
+```typescript
+// lib/prisma.ts
+import { PrismaClient } from '@/generated/client'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const createAdapter = () => new PrismaPg({
+  connectionString: process.env.DATABASE_URL!
+})
+
+const prismaClientSingleton = () => {
+  return new PrismaClient({ adapter: createAdapter() })
+}
+
+declare const globalThis: {
+  prismaGlobal: ReturnType<typeof prismaClientSingleton>
+} & typeof global
+
+const prisma = globalThis.prismaGlobal ?? prismaClientSingleton()
+
+export default prisma
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.prismaGlobal = prisma
+}
+```
+
+## Query Events
+
+Listen to query events:
+
+```typescript
+const prisma = new PrismaClient({
+  adapter,
+  log: [{ level: 'query', emit: 'event' }],
+})
+
+prisma.$on('query', (e) => {
+  console.log('Query:', e.query)
+  console.log('Params:', e.params)
+  console.log('Duration:', e.duration)
+})
+```
+
+## Log Events
+
+```typescript
+prisma.$on('info', (e) => console.log(e.message))
+prisma.$on('warn', (e) => console.warn(e.message))
+prisma.$on('error', (e) => console.error(e.message))
+```