@prisma-next/cli 0.3.0-dev.163 → 0.3.0-dev.164

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

@@ -0,0 +1,106 @@
+# 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}}` — 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

@@ -0,0 +1,19 @@
+import { dirname } from 'pathe';
+import type { TargetId } from './code-templates';
+import { renderTemplate } from './render';
+
+export const variables = ['schemaPath', 'schemaDir', 'dbImportPath', 'pkgRun'] as const;
+
+type TemplateVars = Record<(typeof variables)[number], string>;
+
+export function agentSkillMd(target: TargetId, schemaPath: string, pkgRun: string): string {
+  const schemaDir = dirname(schemaPath);
+  const vars: TemplateVars = {
+    schemaPath,
+    schemaDir,
+    dbImportPath: `./${schemaDir}/db`,
+    pkgRun,
+  };
+  const templateFile = `agent-skill-${target}.md`;
+  return renderTemplate(templateFile, variables, vars);
+}

package/src/commands/init/templates/code-templates.ts

@@ -0,0 +1,168 @@
+export type TargetId = 'postgres' | 'mongo';
+export type AuthoringId = 'psl' | 'typescript';
+
+export function targetPackageName(target: TargetId): string {
+  return target === 'postgres' ? '@prisma-next/postgres' : '@prisma-next/mongo';
+}
+
+export function targetLabel(target: TargetId): string {
+  return target === 'postgres' ? 'PostgreSQL' : 'MongoDB';
+}
+
+export function defaultSchemaPath(authoring: AuthoringId): string {
+  if (authoring === 'typescript') {
+    return 'prisma/contract.ts';
+  }
+  return 'prisma/contract.prisma';
+}
+
+export function starterSchema(target: TargetId, authoring: AuthoringId): string {
+  if (authoring === 'typescript') {
+    return target === 'mongo' ? starterSchemaTsMongo() : starterSchemaTsPostgres();
+  }
+  return target === 'mongo' ? starterSchemaPslMongo() : starterSchemaPslPostgres();
+}
+
+function starterSchemaPslPostgres(): string {
+  return `model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  posts     Post[]
+  createdAt DateTime @default(now())
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  title     String
+  content   String?
+  author    User     @relation(fields: [authorId], references: [id])
+  authorId  Int
+  createdAt DateTime @default(now())
+}
+`;
+}
+
+function starterSchemaPslMongo(): string {
+  return `model User {
+  id    ObjectId @id @map("_id")
+  email String   @unique
+  name  String?
+  posts Post[]
+  @@map("users")
+}
+
+model Post {
+  id       ObjectId @id @map("_id")
+  title    String
+  content  String?
+  author   User     @relation(fields: [authorId], references: [id])
+  authorId ObjectId
+  @@map("posts")
+}
+`;
+}
+
+function starterSchemaTsPostgres(): string {
+  return `import sqlFamily from '@prisma-next/family-sql/pack';
+import { defineContract } from '@prisma-next/sql-contract-ts/contract-builder';
+import postgresPack from '@prisma-next/target-postgres/pack';
+
+export const contract = defineContract(
+  { family: sqlFamily, target: postgresPack },
+  ({ field, model, rel }) => ({
+    models: {
+      User: model('User', {
+        fields: {
+          id: field.id.uuidv7(),
+          email: field.text().unique(),
+          name: field.text().optional(),
+          createdAt: field.createdAt(),
+        },
+      }).relations({
+        posts: rel.hasMany('Post', { by: 'authorId' }),
+      }),
+
+      Post: model('Post', {
+        fields: {
+          id: field.id.uuidv7(),
+          title: field.text(),
+          content: field.text().optional(),
+          authorId: field.uuid(),
+          createdAt: field.createdAt(),
+        },
+      }).relations({
+        author: rel.belongsTo('User', { from: 'authorId', to: 'id' }),
+      }),
+    },
+  }),
+);
+`;
+}
+
+function starterSchemaTsMongo(): string {
+  return `import mongoFamily from '@prisma-next/family-mongo/pack';
+import { defineContract, field, model, rel } from '@prisma-next/mongo-contract-ts/contract-builder';
+import mongoTarget from '@prisma-next/target-mongo/pack';
+
+const User = model('User', {
+  collection: 'users',
+  fields: {
+    _id: field.objectId(),
+    email: field.string(),
+    name: field.string().optional(),
+  },
+});
+
+const Post = model('Post', {
+  collection: 'posts',
+  fields: {
+    _id: field.objectId(),
+    title: field.string(),
+    content: field.string().optional(),
+    authorId: field.objectId(),
+  },
+  relations: {
+    author: rel.belongsTo(User, { from: 'authorId', to: User.ref('_id') }),
+  },
+});
+
+export const contract = defineContract({
+  family: mongoFamily,
+  target: mongoTarget,
+  models: { User, Post },
+});
+`;
+}
+
+export function configFile(target: TargetId, contractPath: string): string {
+  const pkg = targetPackageName(target);
+  return `import 'dotenv/config';
+import { defineConfig } from '${pkg}/config';
+
+export default defineConfig({
+  contract: ${JSON.stringify(contractPath)},
+  db: {
+    connection: process.env['DATABASE_URL']!,
+  },
+});
+`;
+}
+
+export function dbFile(target: TargetId): string {
+  if (target === 'postgres') {
+    return `import postgres from '@prisma-next/postgres/runtime';
+import type { Contract } from './contract.d';
+import contractJson from './contract.json' with { type: 'json' };
+
+export const db = postgres<Contract>({ contractJson });
+`;
+  }
+
+  return `import mongo from '@prisma-next/mongo/runtime';
+import type { Contract } from './contract.d';
+import contractJson from './contract.json' with { type: 'json' };
+
+export const db = mongo<Contract>({ contractJson });
+`;
+}

package/src/commands/init/templates/quick-reference-mongo.md

@@ -0,0 +1,93 @@
+# Welcome to Prisma Next!
+
+Prisma Next lets you query your database in simple, easy-to-read TypeScript. Define what your data looks like, and Prisma Next gives you a fully typed client — with autocomplete for every collection, field, and relation.
+
+This project is set up for MongoDB. Prisma Next also supports other databases.
+
+## Your data contract
+
+Your data contract is the heart of your application. It lives at [`{{schemaPath}}`]({{schemaPath}}) and describes your models:
+
+```prisma
+model User {
+  id    ObjectId @id @map("_id")
+  email String   @unique
+  name  String?
+  posts Post[]
+  @@map("users")
+}
+```
+
+Every model you define in your contract can be queried from your app. Your editor will autocomplete the query methods and show you what type each field is:
+
+```typescript
+import { db } from '{{dbImportPath}}';
+
+const client = await db.connect(process.env['DATABASE_URL']!, 'mydb');
+
+const user = await client.orm.User
+  .where({ email: 'alice@example.com' })
+  .first();
+
+// Your editor will show the type of user as
+// { id: ObjectId; email: string; name: string | null; posts: Post[] } | null
+```
+
+Your contract has two companion files in the same directory:
+
+- **`contract.json`** — this tells your application what models exist, just like `package-lock.json` tells your package manager what dependencies your project has
+- **`contract.d.ts`** — this powers autocomplete and type checking in your editor
+
+Commit both files to git. When you change your contract, run `{{pkgRun}} contract emit` to update them.
+
+If you use a framework like Next.js or Vite, the Prisma Next plugin will do this for you automatically.
+
+## Configuration
+
+[`prisma-next.config.ts`](prisma-next.config.ts) tells the CLI where your contract lives and how to connect to your database. It loads environment variables from `.env` automatically:
+
+```typescript
+import 'dotenv/config';
+import { defineConfig } from '@prisma-next/mongo/config';
+
+export default defineConfig({
+  contract: './{{schemaPath}}',
+  db: {
+    connection: process.env['DATABASE_URL']!,
+  },
+});
+```
+
+Notice the `DATABASE_URL` above? It's defined in your [`.env`](./.env) file:
+
+```env
+DATABASE_URL="mongodb://localhost:27017/mydb"
+```
+
+You can customize how your environment variables are loaded by changing or removing the `import 'dotenv/config'` line.
+
+## Quick reference
+
+### Commands
+
+```bash
+{{pkgRun}} contract emit       # Update contract.json and contract.d.ts
+{{pkgRun}} db init             # Create collections in the database
+{{pkgRun}} migration status    # Show migration status
+```
+
+### Files
+
+| File | Purpose |
+|---|---|
+| [`{{schemaPath}}`]({{schemaPath}}) | Your data contract — define your models here |
+| [`prisma-next.config.ts`](prisma-next.config.ts) | CLI configuration |
+| [`{{schemaDir}}/db.ts`]({{schemaDir}}/db.ts) | Database client — `import { db } from '{{dbImportPath}}'` |
+| `{{schemaDir}}/contract.json` | Compiled contract (generated) |
+| `{{schemaDir}}/contract.d.ts` | Contract types (generated) |
+
+### Workflow
+
+1. Edit [`{{schemaPath}}`]({{schemaPath}}) to add or change models.
+2. Run `{{pkgRun}} contract emit` to regenerate the contract.
+3. Query your models — your IDE will autocomplete everything.

package/src/commands/init/templates/quick-reference-postgres.md

@@ -0,0 +1,91 @@
+# Welcome to Prisma Next!
+
+Prisma Next lets you query your database in simple, easy-to-read TypeScript. Define what your data looks like, and Prisma Next gives you a fully typed client — with autocomplete for every table, column, and relation.
+
+This project is set up for PostgreSQL. Prisma Next also supports other databases.
+
+## Your data contract
+
+Your data contract is the heart of your application. It lives at [`{{schemaPath}}`]({{schemaPath}}) and describes your models:
+
+```prisma
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  posts     Post[]
+  createdAt DateTime @default(now())
+}
+```
+
+Every model you define in your contract can be queried from your app. Your editor will autocomplete the query methods and show you what type each model field is:
+
+```typescript
+import { db } from '{{dbImportPath}}';
+
+const user = await db.orm.User
+  .where({ email: 'alice@example.com' })
+  .first();
+
+// Your editor will show the type of user as
+// { id: number; email: string; createdAt: Date, name: string, posts: Post[] } | null
+```
+
+Your contract has two companion files in the same directory:
+
+- **`contract.json`** — this tells your application what models exist, just like `package-lock.json` tells your package manager what dependencies your project has
+- **`contract.d.ts`** — this powers autocomplete and type checking in your editor
+
+Commit both files to git. When you change your contract, run `{{pkgRun}} contract emit` to update them.
+
+If you use a framework like Next.js or Vite, the Prisma Next plugin will do this for you automatically.
+
+## Configuration
+
+[`prisma-next.config.ts`](prisma-next.config.ts) tells the CLI where your contract lives and how to connect to your database. It loads environment variables from `.env` automatically:
+
+```typescript
+import 'dotenv/config';
+import { defineConfig } from '@prisma-next/postgres/config';
+
+export default defineConfig({
+  contract: './{{schemaPath}}',
+  db: {
+    connection: process.env['DATABASE_URL']!,
+  },
+});
+```
+
+Notice the `DATABASE_URL` above? It's defined in your [`.env`](./.env) file:
+
+```env
+DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
+```
+
+You can customize how your environment variables are loaded by changing or removing the `import 'dotenv/config'` line.
+
+## Quick reference
+
+### Commands
+
+```bash
+{{pkgRun}} contract emit       # Update contract.json and contract.d.ts
+{{pkgRun}} db init             # Create tables in the database
+{{pkgRun}} migration status    # Show migration status
+```
+
+### Files
+
+| File | Purpose |
+|---|---|
+| [`{{schemaPath}}`]({{schemaPath}}) | Your data contract — define your models here |
+| [`prisma-next.config.ts`](prisma-next.config.ts) | CLI configuration |
+| [`{{schemaDir}}/db.ts`]({{schemaDir}}/db.ts) | Database client — `import { db } from '{{dbImportPath}}'` |
+| `{{schemaDir}}/contract.json` | Compiled contract (generated) |
+| `{{schemaDir}}/contract.d.ts` | Contract types (generated) |
+
+### Workflow
+
+1. Edit [`{{schemaPath}}`]({{schemaPath}}) to add or change models.
+2. Run `{{pkgRun}} contract emit` to regenerate the contract.
+3. Query your models — your IDE will autocomplete everything.

package/src/commands/init/templates/quick-reference.ts

@@ -0,0 +1,19 @@
+import { dirname } from 'pathe';
+import type { TargetId } from './code-templates';
+import { renderTemplate } from './render';
+
+export const variables = ['schemaPath', 'schemaDir', 'dbImportPath', 'pkgRun'] as const;
+
+type TemplateVars = Record<(typeof variables)[number], string>;
+
+export function quickReferenceMd(target: TargetId, schemaPath: string, pkgRun: string): string {
+  const schemaDir = dirname(schemaPath);
+  const vars: TemplateVars = {
+    schemaPath,
+    schemaDir,
+    dbImportPath: `./${schemaDir}/db`,
+    pkgRun,
+  };
+  const templateFile = `quick-reference-${target}.md`;
+  return renderTemplate(templateFile, variables, vars);
+}

package/src/commands/init/templates/render.ts

@@ -0,0 +1,20 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'pathe';
+
+export function renderTemplate(
+  templateFile: string,
+  variableNames: readonly string[],
+  vars: Record<string, string>,
+): string {
+  const templatePath = join(import.meta.dirname, templateFile);
+  const raw = readFileSync(templatePath, 'utf-8');
+  let result = raw;
+  for (const key of variableNames) {
+    const value = vars[key];
+    if (value === undefined) {
+      throw new Error(`Template variable '${key}' is not defined`);
+    }
+    result = result.replaceAll(`{{${key}}}`, value);
+  }
+  return result;
+}

package/src/commands/init/templates/tsconfig.ts

@@ -0,0 +1,35 @@
+export const REQUIRED_COMPILER_OPTIONS: Record<string, string | boolean> = {
+  module: 'preserve',
+  moduleResolution: 'bundler',
+  resolveJsonModule: true,
+};
+
+export function defaultTsConfig(): string {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: 'ES2022',
+        ...REQUIRED_COMPILER_OPTIONS,
+        strict: true,
+        skipLibCheck: true,
+        esModuleInterop: true,
+        outDir: 'dist',
+      },
+      include: ['**/*.ts'],
+    },
+    null,
+    2,
+  );
+}
+
+export function mergeTsConfig(existing: string): string {
+  const config = JSON.parse(existing) as Record<string, unknown>;
+  const compilerOptions = (config['compilerOptions'] ?? {}) as Record<string, unknown>;
+
+  for (const [key, value] of Object.entries(REQUIRED_COMPILER_OPTIONS)) {
+    compilerOptions[key] = value;
+  }
+
+  config['compilerOptions'] = compilerOptions;
+  return JSON.stringify(config, null, 2);
+}

package/src/control-api/operations/contract-emit.ts

@@ -162,6 +162,13 @@ export async function executeContractEmit(
   await unlessAborted(writeFile(outputJsonPath, emitResult.contractJson, 'utf-8'));
   await unlessAborted(writeFile(outputDtsPath, emitResult.contractDts, 'utf-8'));
 
+  // Validate that contract.d.ts type imports are resolvable
+  const { validateContractDeps } = await import('../../utils/validate-contract-deps');
+  const depsValidation = validateContractDeps(emitResult.contractDts, dirname(outputDtsPath));
+  if (depsValidation.warning) {
+    process.stderr.write(`\n⚠ ${depsValidation.warning}\n`);
+  }
+
   return {
     storageHash: emitResult.storageHash,
     ...ifDefined('executionHash', emitResult.executionHash),

package/src/utils/validate-contract-deps.ts

@@ -0,0 +1,49 @@
+import { createRequire } from 'node:module';
+
+const IMPORT_PATTERN = /import\s+type\s+.*?\s+from\s+['"](@[^/]+\/[^/'"]+)/g;
+
+export function extractPackageSpecifiers(dtsContent: string): string[] {
+  const packages = new Set<string>();
+  for (const match of dtsContent.matchAll(IMPORT_PATTERN)) {
+    const pkg = match[1];
+    if (pkg) packages.add(pkg);
+  }
+  return [...packages];
+}
+
+export interface ContractDepsValidation {
+  readonly missing: readonly string[];
+  readonly warning?: string;
+}
+
+export function validateContractDeps(
+  dtsContent: string,
+  projectRoot: string,
+): ContractDepsValidation {
+  const packages = extractPackageSpecifiers(dtsContent);
+  const resolve = createRequire(`${projectRoot}/package.json`);
+
+  const missing: string[] = [];
+  for (const pkg of packages) {
+    try {
+      resolve.resolve(`${pkg}/package.json`);
+    } catch {
+      missing.push(pkg);
+    }
+  }
+
+  if (missing.length === 0) {
+    return { missing };
+  }
+
+  const list = missing.map((p) => `  - ${p}`).join('\n');
+  const warning = [
+    'contract.d.ts imports types from packages that are not installed:',
+    list,
+    '',
+    'Install them with your package manager:',
+    ...missing.map((p) => `  ${p}`),
+  ].join('\n');
+
+  return { missing, warning };
+}