@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/gemini-cli/prisma-raw-queries/SKILL.md

@@ -0,0 +1,125 @@
+# Prisma Raw Queries
+
+> Execute type-safe raw SQL with $queryRaw, $executeRaw, and Prisma.sql template tag
+
+## When to Use
+
+- Running SQL queries that Prisma Client cannot express (CTEs, window functions, complex joins)
+- Performing bulk operations more efficiently than Prisma's generated queries
+- Calling database-specific features (full-text search, advisory locks, lateral joins)
+- Executing data migrations or one-off scripts
+
+## Instructions
+
+1. **Read query** — use `$queryRaw` with a tagged template literal. Always parameterize inputs:
+
+```typescript
+const users = await prisma.$queryRaw<User[]>`
+  SELECT id, email, name FROM "User" WHERE role = ${role}
+`;
+```
+
+The template tag automatically parameterizes `${role}` as a prepared statement parameter — never string-interpolated.
+
+2. **Write query** — use `$executeRaw` for INSERT, UPDATE, DELETE. Returns the affected row count:
+
+```typescript
+const count = await prisma.$executeRaw`
+  UPDATE "Post" SET "viewCount" = "viewCount" + 1 WHERE id = ${postId}
+`;
+```
+
+3. **Dynamic table or column names** — use `Prisma.raw()` for identifiers that cannot be parameterized:
+
+```typescript
+import { Prisma } from '@prisma/client';
+
+const column = Prisma.raw(`"${columnName}"`);
+const result = await prisma.$queryRaw`
+  SELECT ${column} FROM "User" WHERE id = ${userId}
+`;
+```
+
+Validate `columnName` against an allowlist before using `Prisma.raw()` to prevent SQL injection.
+
+4. **Build dynamic queries** with `Prisma.sql` and `Prisma.join`:
+
+```typescript
+const ids = [1, 2, 3];
+const result = await prisma.$queryRaw`
+  SELECT * FROM "User" WHERE id IN (${Prisma.join(ids)})
+`;
+```
+
+5. **Compose query fragments** with `Prisma.sql`:
+
+```typescript
+const where = searchTerm ? Prisma.sql`WHERE name ILIKE ${'%' + searchTerm + '%'}` : Prisma.empty;
+
+const users = await prisma.$queryRaw`SELECT * FROM "User" ${where}`;
+```
+
+6. **Type the result** — `$queryRaw` returns `unknown[]` by default. Pass a generic type or validate with Zod:
+
+```typescript
+import { z } from 'zod';
+
+const UserRow = z.object({ id: z.string(), email: z.string() });
+const raw = await prisma.$queryRaw`SELECT id, email FROM "User"`;
+const users = z.array(UserRow).parse(raw);
+```
+
+7. **Use raw queries inside transactions**:
+
+```typescript
+await prisma.$transaction(async (tx) => {
+  await tx.$executeRaw`LOCK TABLE "Inventory" IN EXCLUSIVE MODE`;
+  const [item] = await tx.$queryRaw<Inventory[]>`
+    SELECT * FROM "Inventory" WHERE sku = ${sku} FOR UPDATE
+  `;
+  await tx.$executeRaw`
+    UPDATE "Inventory" SET quantity = quantity - ${qty} WHERE sku = ${sku}
+  `;
+});
+```
+
+## Details
+
+Raw queries bypass Prisma's query engine and type generation. The SQL runs directly against the database connection, but parameter binding still uses prepared statements for safety.
+
+**Table and column naming:** Prisma maps model names to table names via `@@map` and field names to column names via `@map`. In raw SQL, you must use the actual database names, not the Prisma model names. Check with `prisma migrate diff --from-empty --to-schema-datamodel prisma/schema.prisma --script` to see the real table names.
+
+**Return type caveats:**
+
+- `$queryRaw` returns rows with exact database column names (not Prisma field names)
+- `BigInt` columns return JavaScript `BigInt`, which is not JSON-serializable — convert to `Number` or `String` before sending to clients
+- `Decimal` columns return `Prisma.Decimal` objects, not `number`
+- `DateTime` columns return `Date` objects
+
+**`$queryRawUnsafe` / `$executeRawUnsafe`:** Accept a plain string instead of a tagged template. These do NOT parameterize — you are responsible for preventing SQL injection. Avoid unless you are building a query builder that handles parameterization itself.
+
+**Performance advantages of raw SQL:**
+
+- CTEs and window functions are impossible with Prisma Client but often the most efficient solution
+- `INSERT ... ON CONFLICT` (upsert) on multiple rows is significantly faster than looping `prisma.model.upsert()`
+- Bulk updates with CASE expressions are faster than individual `update` calls
+
+## Source
+
+https://prisma.io/docs/orm/prisma-client/queries/raw-database-access
+
+## 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/gemini-cli/prisma-raw-queries/skill.yaml

@@ -0,0 +1,41 @@
+name: prisma-raw-queries
+version: "1.0.0"
+description: Execute type-safe raw SQL with $queryRaw, $executeRaw, and Prisma.sql template tag
+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-transactions
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - raw-query
+  - $queryRaw
+  - $executeRaw
+  - Prisma.sql
+  - type-safe
+  - SQL
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-client/queries/raw-database-access"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/prisma-relations-pattern/SKILL.md

@@ -0,0 +1,151 @@
+# Prisma Relations Pattern
+
+> Model one-to-one, one-to-many, many-to-many, and self-relations with @relation in Prisma
+
+## When to Use
+
+- Adding foreign key relationships between Prisma models
+- Modeling one-to-one, one-to-many, or many-to-many associations
+- Creating self-referential relations (e.g., manager/employee, parent/child)
+- Resolving ambiguous relations when two models have multiple connections
+
+## Instructions
+
+1. **One-to-many** — place the scalar foreign key and `@relation` on the "many" side. The "one" side gets an array field:
+
+```prisma
+model User {
+  id    String @id @default(cuid())
+  posts Post[]
+}
+
+model Post {
+  id       String @id @default(cuid())
+  author   User   @relation(fields: [authorId], references: [id])
+  authorId String
+}
+```
+
+2. **One-to-one** — identical to one-to-many but the relation field is singular on both sides. Add `@unique` to the foreign key:
+
+```prisma
+model User {
+  id      String   @id @default(cuid())
+  profile Profile?
+}
+
+model Profile {
+  id     String @id @default(cuid())
+  user   User   @relation(fields: [userId], references: [id])
+  userId String @unique
+}
+```
+
+3. **Many-to-many (implicit)** — use array fields on both sides. Prisma creates the join table automatically:
+
+```prisma
+model Post {
+  id   String @id @default(cuid())
+  tags Tag[]
+}
+
+model Tag {
+  id    String @id @default(cuid())
+  posts Post[]
+}
+```
+
+4. **Many-to-many (explicit)** — create an explicit join model when you need extra fields on the relationship:
+
+```prisma
+model PostTag {
+  post   Post   @relation(fields: [postId], references: [id])
+  postId String
+  tag    Tag    @relation(fields: [tagId], references: [id])
+  tagId  String
+  assignedAt DateTime @default(now())
+
+  @@id([postId, tagId])
+}
+```
+
+5. **Self-relations** — reference the same model. Use named `@relation` to disambiguate:
+
+```prisma
+model Employee {
+  id         String     @id @default(cuid())
+  manager    Employee?  @relation("ManagerReports", fields: [managerId], references: [id])
+  managerId  String?
+  reports    Employee[] @relation("ManagerReports")
+}
+```
+
+6. **Disambiguate multiple relations** between the same two models using the relation name string:
+
+```prisma
+model User {
+  id            String @id @default(cuid())
+  writtenPosts  Post[] @relation("Author")
+  editedPosts   Post[] @relation("Editor")
+}
+
+model Post {
+  id       String @id @default(cuid())
+  author   User   @relation("Author", fields: [authorId], references: [id])
+  authorId String
+  editor   User?  @relation("Editor", fields: [editorId], references: [id])
+  editorId String?
+}
+```
+
+7. **Referential actions** — set `onDelete` and `onUpdate` behavior:
+
+```prisma
+author User @relation(fields: [authorId], references: [id], onDelete: Cascade, onUpdate: Cascade)
+```
+
+Options: `Cascade`, `Restrict`, `NoAction`, `SetNull`, `SetDefault`.
+
+8. Always add `@@index([foreignKeyField])` on relation scalar fields for query performance.
+
+## Details
+
+Prisma relations are defined at the Prisma schema level and map to foreign keys in the database. The `@relation` attribute is required on the side that stores the foreign key (the scalar field side).
+
+**Implicit vs explicit many-to-many:** Implicit join tables follow the naming convention `_ModelAToModelB` (alphabetical). You cannot query the join table directly or add columns to it. Switch to explicit if you ever need metadata on the relationship.
+
+**Referential integrity modes:**
+
+- `foreignKeys` (default for relational databases) — enforced by the database
+- `prisma` — enforced by Prisma Client at the application level, required for databases that do not support foreign keys (e.g., PlanetScale with Vitess)
+
+**Cascade gotchas:**
+
+- `onDelete: Cascade` on a required relation means deleting a parent deletes all children — this is often not what you want for audit-sensitive data
+- `onDelete: SetNull` requires the foreign key field to be optional (`String?`)
+- The default referential action varies by provider — PostgreSQL defaults to `NoAction`, which throws on violation
+
+**Performance considerations:**
+
+- Every `include` on a relation triggers an additional SQL query (not a JOIN). For deeply nested includes, consider using raw queries with explicit JOINs
+- Implicit many-to-many creates an unindexed join table — add indexes manually via a migration if query performance degrades
+
+## Source
+
+https://prisma.io/docs/orm/prisma-schema/data-model/relations
+
+## 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/gemini-cli/prisma-relations-pattern/skill.yaml

@@ -0,0 +1,42 @@
+name: prisma-relations-pattern
+version: "1.0.0"
+description: Model one-to-one, one-to-many, many-to-many, and self-relations with @relation in Prisma
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "schema.prisma"
+  - "prisma/schema.prisma"
+  - "**/prisma/**"
+related_skills:
+  - prisma-schema-design
+  - prisma-client-queries
+  - prisma-filtering-sorting
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - relations
+  - one-to-many
+  - many-to-many
+  - self-relation
+  - foreign-key
+  - join-table
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-schema/data-model/relations"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/prisma-schema-design/SKILL.md

@@ -0,0 +1,108 @@
+# Prisma Schema Design
+
+> Design Prisma schemas with datasource, generator, models, field types, and field attributes
+
+## When to Use
+
+- Creating a new Prisma project and defining the initial schema
+- Adding new models or fields to an existing Prisma schema
+- Choosing the correct field types, attributes, and defaults for a data model
+- Configuring datasource (PostgreSQL, MySQL, SQLite) and generator blocks
+
+## Instructions
+
+1. Start every schema with a `datasource` block specifying the provider and connection string via `env()`:
+
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+2. Add a `generator` block for Prisma Client. Place it immediately after the datasource:
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+}
+```
+
+3. Define models with PascalCase names. Every model must have exactly one `@id` field or a `@@id` composite key:
+
+```prisma
+model User {
+  id        String   @id @default(cuid())
+  email     String   @unique
+  name      String?
+  role      Role     @default(USER)
+  posts     Post[]
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+}
+```
+
+4. Use the correct scalar types: `String`, `Int`, `BigInt`, `Float`, `Decimal`, `Boolean`, `DateTime`, `Json`, `Bytes`. Append `?` for optional fields.
+
+5. Apply field-level attributes in this order: `@id`, `@unique`, `@default(...)`, `@map("column_name")`, `@db.VarChar(255)`.
+
+6. Use `@@map("table_name")` to decouple Prisma model names from database table names when working with legacy databases.
+
+7. Use `@@unique([fieldA, fieldB])` for composite unique constraints and `@@index([fieldA, fieldB])` for composite indexes.
+
+8. Define enums at the schema level and reference them as field types:
+
+```prisma
+enum Role {
+  USER
+  ADMIN
+  MODERATOR
+}
+```
+
+9. Use `@default(autoincrement())` for integer IDs, `@default(cuid())` or `@default(uuid())` for string IDs. Prefer `cuid()` unless your system requires UUID format.
+
+10. Add `@updatedAt` to a `DateTime` field to auto-set the timestamp on every update. Only one `@updatedAt` per model.
+
+## Details
+
+Prisma schema is the single source of truth for your database structure and the generated TypeScript client. The schema file (`prisma/schema.prisma`) is declarative and uses its own DSL.
+
+**Datasource providers:** `postgresql`, `mysql`, `sqlite`, `sqlserver`, `mongodb`, `cockroachdb`. Each provider supports a different subset of native types (e.g., `@db.VarChar(255)` for PostgreSQL, `@db.Text` for MySQL).
+
+**Native type annotations** let you override the default database column type. Without them, Prisma maps scalar types to sensible defaults (e.g., `String` maps to `text` on PostgreSQL). Use `@db.VarChar(n)` when you need a length constraint at the database level.
+
+**Multi-file schemas** are supported via the `prismaSchemaFolder` preview feature. Split large schemas into multiple `.prisma` files within the `prisma/schema/` directory.
+
+**Trade-offs:**
+
+- `cuid()` IDs are shorter and URL-safe but not a standard format; `uuid()` is universally recognized but longer
+- `Json` fields bypass Prisma's type system — validate JSON content at the application layer or use Zod
+- `@default(now())` is evaluated at the database level; `@default(dbgenerated("gen_random_uuid()"))` delegates to database functions
+- `Decimal` preserves precision for financial data; `Float` introduces IEEE 754 rounding
+
+**Common mistakes:**
+
+- Forgetting `@updatedAt` means the field stays at its initial value forever
+- Using `Int` for IDs on tables that will exceed 2.1 billion rows — use `BigInt` instead
+- Not adding `@@index` on foreign key fields — Prisma does not create indexes automatically for relation fields
+
+## Source
+
+https://prisma.io/docs/orm/prisma-schema
+
+## 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/gemini-cli/prisma-schema-design/skill.yaml

@@ -0,0 +1,46 @@
+name: prisma-schema-design
+version: "1.0.0"
+description: Design Prisma schemas with datasource, generator, models, field types, and field attributes
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "schema.prisma"
+  - "prisma/schema.prisma"
+  - "**/prisma/**"
+related_skills:
+  - prisma-relations-pattern
+  - prisma-migrations
+  - prisma-type-generation
+  - ts-utility-types
+stack_signals:
+  - prisma
+  - typescript
+  - postgresql
+  - mysql
+  - sqlite
+keywords:
+  - prisma
+  - schema
+  - model
+  - datasource
+  - generator
+  - field-types
+  - id
+  - default
+  - unique
+metadata:
+  author: community
+  upstream: "prisma.io/docs/orm/prisma-schema"
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/prisma-seeding-pattern/SKILL.md

@@ -0,0 +1,168 @@
+# Prisma Seeding Pattern
+
+> Seed databases idempotently with prisma/seed.ts, --seed flag, and environment branching
+
+## When to Use
+
+- Populating a development database with test data after `prisma migrate reset`
+- Setting up required reference data (roles, categories, config records)
+- Creating reproducible test fixtures for integration tests
+- Bootstrapping demo environments with sample data
+
+## Instructions
+
+1. **Create the seed file** at `prisma/seed.ts`:
+
+```typescript
+import { PrismaClient } from '@prisma/client';
+
+const prisma = new PrismaClient();
+
+async function main() {
+  // Reference data — always needed
+  const adminRole = await prisma.role.upsert({
+    where: { name: 'ADMIN' },
+    update: {},
+    create: { name: 'ADMIN', permissions: ['read', 'write', 'delete'] },
+  });
+
+  // Development data — sample records
+  const user = await prisma.user.upsert({
+    where: { email: 'admin@example.com' },
+    update: {},
+    create: {
+      email: 'admin@example.com',
+      name: 'Admin User',
+      roleId: adminRole.id,
+    },
+  });
+
+  console.log({ adminRole, user });
+}
+
+main()
+  .then(() => prisma.$disconnect())
+  .catch(async (e) => {
+    console.error(e);
+    await prisma.$disconnect();
+    process.exit(1);
+  });
+```
+
+2. **Configure the seed command** in `package.json`:
+
+```json
+{
+  "prisma": {
+    "seed": "tsx prisma/seed.ts"
+  }
+}
+```
+
+Use `tsx` or `ts-node` for TypeScript seeds. Ensure the runner is in `devDependencies`.
+
+3. **Make seeds idempotent** — use `upsert` instead of `create` so the seed can run multiple times without duplicating data:
+
+```typescript
+await prisma.category.upsert({
+  where: { slug: 'technology' },
+  update: { name: 'Technology' },
+  create: { slug: 'technology', name: 'Technology' },
+});
+```
+
+4. **Branch by environment** to seed different data for dev, staging, and testing:
+
+```typescript
+async function main() {
+  await seedReferenceData(); // Always runs
+
+  if (process.env.NODE_ENV !== 'production') {
+    await seedDevelopmentData(); // Sample users, posts, etc.
+  }
+
+  if (process.env.SEED_DEMO === 'true') {
+    await seedDemoData(); // Curated demo content
+  }
+}
+```
+
+5. **Run the seed manually**:
+
+```bash
+npx prisma db seed
+```
+
+The seed also runs automatically after `prisma migrate reset` and `prisma migrate dev` (when a new migration is created).
+
+6. **Use factories for volume** — when you need many records, use a helper function:
+
+```typescript
+function createRandomUser() {
+  return {
+    email: `user-${crypto.randomUUID()}@example.com`,
+    name: `User ${Math.random().toString(36).slice(2)}`,
+  };
+}
+
+await prisma.user.createMany({
+  data: Array.from({ length: 100 }, createRandomUser),
+  skipDuplicates: true,
+});
+```
+
+7. **Seed in correct dependency order** — create parent records before children. For circular dependencies, create records without relations first, then update with connections.
+
+8. **Reset and reseed** in one command:
+
+```bash
+npx prisma migrate reset --force
+```
+
+This drops the database, applies all migrations, and runs the seed script.
+
+## Details
+
+Prisma seeding runs as a standalone Node.js script invoked by the Prisma CLI. It has full access to Prisma Client and can include any business logic needed to set up the data.
+
+**Seed vs migration data:** Reference data that must exist for the application to function (enum-like lookup tables, system config) belongs in migrations as `INSERT` statements, not in seeds. Seeds are for development convenience; migrations are for production correctness.
+
+**Performance for large seeds:** `createMany` is significantly faster than individual `create` calls because it batches into a single `INSERT` with multiple value tuples. However, `createMany` does not support nested creates — use it for flat data and fall back to `create` for relational data.
+
+**Testing seeds:** Create a separate seed function that returns the created data for use in integration tests:
+
+```typescript
+export async function seedTestData(prisma: PrismaClient) {
+  const user = await prisma.user.create({ data: { ... } });
+  return { user };
+}
+```
+
+Call this from your test setup with a transaction that rolls back after each test.
+
+**Common mistakes:**
+
+- Not disconnecting the client — the seed script hangs if `prisma.$disconnect()` is not called
+- Using `create` instead of `upsert` — the seed fails on second run
+- Hardcoding IDs — use `cuid()` or let the database auto-generate. Hardcoded IDs collide across environments
+- Seeding production — guard with environment checks and never include `prisma.seed` configuration in production images
+
+## Source
+
+https://prisma.io/docs/orm/prisma-migrate/workflows/seeding
+
+## 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.