@prisma-next/cli 0.7.0 → 0.8.0-dev.2

package/src/commands/init/templates/agent-skill-mongo.md

@@ -1,138 +0,0 @@
-# Prisma Next — project skill
-
-This project uses **Prisma Next** with **MongoDB** via `@prisma-next/mongo`. Prisma Next lets the user define data models in a contract file and query them with a fully typed ORM.
-
-## Files
-
-- **Contract**: `{{schemaPath}}` ({{authoringLabel}} authoring) — the user's data models. Edit this to add or change models.
-- **Config**: `prisma-next.config.ts` — tells the CLI where the contract is and how to connect to the database. Loads `.env` via `dotenv/config`.
-- **Database client**: `{{schemaDir}}/db.ts` — `import { db } from '{{dbImportPath}}'`. This is the entry point for all queries.
-- **Generated files** (do not edit by hand):
-  - `{{schemaDir}}/contract.json` — compiled contract, used at runtime
-  - `{{schemaDir}}/contract.d.ts` — TypeScript types for the contract, used for autocomplete and type checking
-
-## Commands
-
-- `{{pkgRun}} contract emit` — regenerate `contract.json` and `contract.d.ts` after changing the contract
-- `{{pkgRun}} db init` — bootstrap a database to match the contract (creates collections, indexes, constraints). Additive only — won't drop existing structures.
-- `{{pkgRun}} db update` — update the database to match the current contract. Prompts for confirmation on destructive changes. Use `--dry-run` to preview.
-- `{{pkgRun}} migration plan` — create a new migration from contract changes (offline, no database needed). Use `--name <slug>` to name it.
-- `{{pkgRun}} migration apply` — apply pending migrations to the database
-- `{{pkgRun}} migration status` — show which migrations are applied and which are pending
-- `{{pkgRun}} migration show <name>` — show details of a specific migration
-
-## How to write queries
-
-Use the ORM (`db.orm`). Each root accessor is the lowercased plural form emitted by `prisma-next contract emit` (typically the `@@map`-ped collection name) — for `model User { @@map("users") }` use `db.orm.users`, for `model Post { @@map("posts") }` use `db.orm.posts`. The Mongo facade has no raw-SQL surface. Two escape hatches exist for cases the ORM can't express; both are covered under "Escape hatches" below.
-
-```typescript
-import { db } from '{{dbImportPath}}';
-
-// Find one record
-const user = await db.orm.users
-  .where({ email: 'alice@example.com' })
-  .first();
-// Returns { _id: ObjectId; email: string; ... } | null
-
-// Find multiple records — `.all()` returns an AsyncIterableResult, consume
-// either as an async iterable (below) or by `await`ing it to materialise an Array.
-for await (const user of db.orm.users
-  .select('_id', 'email')
-  .take(10)
-  .all()) {
-  // Each `user` is { _id: ObjectId; email: string }
-}
-// Returns AsyncIterableResult<{ _id: ObjectId; email: string }>
-
-// Filter, order, limit
-const recentPosts = await db.orm.posts
-  .where({ authorId: userId })
-  .orderBy({ createdAt: -1 })
-  .select('_id', 'title', 'createdAt')
-  .take(50)
-  .all();
-
-// Include relations (reference relations only — embedded relations come back automatically)
-const usersWithPosts = await db.orm.users
-  .select('_id', 'email')
-  .include('posts')
-  .take(10)
-  .all();
-```
-
-### Key ORM methods
-
-- `.where({ field: value, ... })` — filter records by an equality object. Pass a raw filter expression for `$gt`/`$in`/`$regex` etc.
-- `.select('field1', 'field2', ...)` — pick which fields to return
-- `.orderBy({ field: 1 | -1 })` — sort results (1 = ascending, -1 = descending)
-- `.take(n)` / `.skip(n)` — limit and offset
-- `.all()` — execute and return all matching records as an `AsyncIterableResult`
-- `.first()` — execute with limit 1 and return the first matching row, or `null`
-- `.include('relationName')` — eager-load a reference relation (`$lookup`); embedded relations are already part of the row
-- `.variant('VariantName')` — narrow a polymorphic collection to a discriminator value
-
-## Escape hatches
-
-The ORM covers the common cases. When you genuinely need something it can't express, prefer these — in order — over reaching for `db.runtime()` (which is an internal executor surface, not a `mongodb`-driver handle):
-
-1. **Typed raw aggregations — `db.query`.** The facade exposes a `db.query` builder that runs aggregation pipelines through the same runtime + middleware + codec stack as `db.orm`, so results stay typed against the contract. Use this for `$lookup`/`$facet`/`$graphLookup`/window-function pipelines that the ORM doesn't surface.
-
-2. **Direct `mongodb` driver control — `mongoClient` binding.** If you need a raw `MongoClient` (e.g. for transactions, change streams, sessions, or a driver feature Prisma Next doesn't expose), construct one yourself and pass it to `mongo({ mongoClient, dbName, contractJson })`. Your code keeps the `MongoClient` reference and uses it directly, while the same `db` object still gives you the typed ORM surface:
-
-   ```typescript
-   import { MongoClient } from 'mongodb';
-   import mongo from '@prisma-next/mongo/runtime';
-   import type { Contract } from './contract.d';
-   import contractJson from './contract.json' with { type: 'json' };
-
-   const client = new MongoClient(process.env['DATABASE_URL']!);
-   await client.connect();
-
-   export const db = mongo<Contract>({ contractJson, mongoClient: client, dbName: 'mydb' });
-
-   const session = client.startSession();
-   try {
-     await session.withTransaction(async () => {
-       await db.orm.users.createAll([{ /* ... */ }]);
-     });
-   } finally {
-     await session.endSession();
-   }
-   ```
-
-## Rules
-
-- **Never hand-edit** `contract.json` or `contract.d.ts`. Always regenerate them with `contract emit`.
-- **Always emit after contract changes.** When you modify `{{schemaPath}}`, run `{{pkgRun}} contract emit` before writing any code that depends on the new or changed models.
-- **Don't restructure `db.ts`.** It's scaffolded by init and works as-is. `db` connects lazily on the first query — there is no `db.connect(...)` step.
-- **Root accessors are emitter-driven.** Use the lowercased plural collection name (e.g. `db.orm.users`, `db.orm.posts`) — not the PascalCase model name. Re-run `{{pkgRun}} contract emit` if a new model's accessor isn't appearing on `db.orm`.
-- **Connection string** is `DATABASE_URL` in `.env`. If the user reports connection errors, check this value and the `.env` file.
-- **Transactions and change streams** require a MongoDB **replica set**. The Mongo facade does not yet expose `db.transaction(...)` — for now, use the `mongoClient` escape hatch above to drive transactions/sessions directly. See the quick reference for dev-environment options; the typed transaction API is tracked under [TML-2313](https://linear.app/prisma-company/issue/TML-2313/mongo-dev-replica-set-story-is-missing-transactions-change-streams).
-- **Don't reach for `db.runtime()`** as an escape hatch. It returns the internal executor (`MongoRuntime`), not a `mongodb` `MongoClient` or `Db`. Use `db.query` for raw aggregations and the `mongoClient` binding for direct driver control.
-
-## Workflow for common tasks
-
-**User wants to add a new model or field:**
-1. Edit `{{schemaPath}}`
-2. Run `{{pkgRun}} contract emit`
-3. Write query code using `db.orm.<collection>` (lowercased plural, see Rules above)
-
-**User wants to query data:**
-1. Import `db` from `{{dbImportPath}}`
-2. Use `db.orm.<collection>` with `.where()`, `.select()`, `.all()`, `.first()`, etc.
-
-**User wants to set up or change the database connection:**
-1. Edit `DATABASE_URL` in `.env`
-2. The config file (`prisma-next.config.ts`) reads it automatically via `dotenv/config`
-
-**User wants to set up the database for the first time:**
-1. Run `{{pkgRun}} db init`
-
-**User wants to update the database after changing the contract:**
-1. Quick path: `{{pkgRun}} db update` — compares the database to the contract and applies changes directly
-2. Migration path (for production workflows):
-   - `{{pkgRun}} migration plan --name describe-the-change` — creates a migration
-   - `{{pkgRun}} migration apply` — applies pending migrations
-
-**User wants to check what migrations need to be applied:**
-1. Run `{{pkgRun}} migration status`

package/src/commands/init/templates/agent-skill-postgres.md

@@ -1,106 +0,0 @@
-# Prisma Next — project skill
-
-This project uses **Prisma Next** with **PostgreSQL** via `@prisma-next/postgres`. Prisma Next lets the user define data models in a contract file and query them with a fully typed ORM.
-
-## Files
-
-- **Contract**: `{{schemaPath}}` ({{authoringLabel}} authoring) — the user's data models. Edit this to add or change models.
-- **Config**: `prisma-next.config.ts` — tells the CLI where the contract is and how to connect to the database. Loads `.env` via `dotenv/config`.
-- **Database client**: `{{schemaDir}}/db.ts` — `import { db } from '{{dbImportPath}}'`. This is the entry point for all queries.
-- **Generated files** (do not edit by hand):
-  - `{{schemaDir}}/contract.json` — compiled contract, used at runtime
-  - `{{schemaDir}}/contract.d.ts` — TypeScript types for the contract, used for autocomplete and type checking
-
-## Commands
-
-- `{{pkgRun}} contract emit` — regenerate `contract.json` and `contract.d.ts` after changing the contract
-- `{{pkgRun}} db init` — bootstrap a database to match the contract (creates tables, indexes, constraints). Additive only — won't drop existing structures.
-- `{{pkgRun}} db update` — update the database to match the current contract. Prompts for confirmation on destructive changes. Use `--dry-run` to preview.
-- `{{pkgRun}} migration plan` — create a new migration from contract changes (offline, no database needed). Use `--name <slug>` to name it.
-- `{{pkgRun}} migration apply` — apply pending migrations to the database
-- `{{pkgRun}} migration status` — show which migrations are applied and which are pending
-- `{{pkgRun}} migration show <name>` — show details of a specific migration
-
-## How to write queries
-
-Always use the ORM (`db.orm`). Only fall back to `db.sql` if the user explicitly asks for raw SQL or the ORM doesn't support the operation.
-
-```typescript
-import { db } from '{{dbImportPath}}';
-
-// Find one record
-const user = await db.orm.User
-  .where(user => user.email.eq('alice@example.com'))
-  .first();
-// Returns { id: number; email: string; ... } | null
-
-// Find multiple records
-const users = await db.orm.User
-  .select('id', 'email')
-  .take(10)
-  .all();
-// Returns Array<{ id: number; email: string }>
-
-// Filter, order, limit
-const recentPosts = await db.orm.Post
-  .where(post => post.authorId.eq(userId))
-  .orderBy(post => post.createdAt.desc())
-  .select('id', 'title', 'createdAt')
-  .take(50)
-  .all();
-
-// Include relations
-const usersWithPosts = await db.orm.User
-  .select('id', 'email')
-  .include('posts', post =>
-    post.select('id', 'title').orderBy(p => p.createdAt.desc()).take(5)
-  )
-  .take(10)
-  .all();
-```
-
-### Key ORM methods
-
-- `.where(predicate)` — filter records. Predicate receives a model accessor with `.eq()`, `.neq()`, `.ilike()`, `.lt()`, `.gt()`, etc.
-- `.select('field1', 'field2', ...)` — pick which fields to return
-- `.orderBy(accessor => accessor.field.asc()` or `.desc())` — sort results
-- `.take(n)` — limit number of results
-- `.all()` — execute and return all matching records as an array
-- `.first()` — execute and return the first matching record, or `null`
-- `.first({ id: value })` — find a single record by primary key, or `null`
-- `.include('relation', builder => ...)` — eager-load a relation
-
-## Rules
-
-- **Never hand-edit** `contract.json` or `contract.d.ts`. Always regenerate them with `contract emit`.
-- **Always emit after contract changes.** When you modify `{{schemaPath}}`, run `{{pkgRun}} contract emit` before writing any code that depends on the new or changed models.
-- **Don't restructure `db.ts`.** It's scaffolded by init and works as-is.
-- **Use `db.orm` for queries**, not `db.sql`. The ORM is the primary query surface.
-- **Connection string** is `DATABASE_URL` in `.env`. If the user reports connection errors, check this value and the `.env` file.
-
-## Workflow for common tasks
-
-**User wants to add a new model or field:**
-1. Edit `{{schemaPath}}`
-2. Run `{{pkgRun}} contract emit`
-3. Write query code using `db.orm.ModelName`
-
-**User wants to query data:**
-1. Import `db` from `{{dbImportPath}}`
-2. Use `db.orm.ModelName` with `.where()`, `.select()`, `.all()`, `.first()`, etc.
-
-**User wants to set up or change the database connection:**
-1. Edit `DATABASE_URL` in `.env`
-2. The config file (`prisma-next.config.ts`) reads it automatically via `dotenv/config`
-
-**User wants to set up the database for the first time:**
-1. Run `{{pkgRun}} db init`
-
-**User wants to update the database after changing the contract:**
-1. Quick path: `{{pkgRun}} db update` — compares the database to the contract and applies changes directly
-2. Migration path (for production workflows):
-   - `{{pkgRun}} migration plan --name describe-the-change` — creates a migration
-   - `{{pkgRun}} migration apply` — applies pending migrations
-
-**User wants to check what migrations need to be applied:**
-1. Run `{{pkgRun}} migration status`

package/src/commands/init/templates/agent-skill.ts

@@ -1,41 +0,0 @@
-import { dirname } from 'pathe';
-import type { AuthoringId, TargetId } from './code-templates';
-import { renderTemplate } from './render';
-
-export const variables = [
-  'schemaPath',
-  'schemaDir',
-  'dbImportPath',
-  'pkgRun',
-  'authoringLabel',
-] as const;
-
-type TemplateVars = Record<(typeof variables)[number], string>;
-
-/**
- * Renders the per-project agent skill (FR5.2). The skill template is
- * target-specific (Postgres vs Mongo query syntax differs); the authoring
- * style enters via:
- *
- * - `schemaPath` — already routed through {@link agentSkillMd}'s caller
- *   (the AC says a TS-authoring scaffold must reference `prisma/contract.ts`).
- * - `authoringLabel` — a short human-readable note (`PSL` / `TypeScript`)
- *   the skill template uses when describing the contract file.
- */
-export function agentSkillMd(
-  target: TargetId,
-  authoring: AuthoringId,
-  schemaPath: string,
-  pkgRun: string,
-): string {
-  const schemaDir = dirname(schemaPath);
-  const vars: TemplateVars = {
-    schemaPath,
-    schemaDir,
-    dbImportPath: `./${schemaDir}/db`,
-    pkgRun,
-    authoringLabel: authoring === 'typescript' ? 'TypeScript' : 'PSL',
-  };
-  const templateFile = `agent-skill-${target}.md`;
-  return renderTemplate(templateFile, variables, vars);
-}