@prisma-next/cli 0.3.0-pr.99.6 → 0.3.0

package/src/commands/init/index.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander';
+import { setCommandDescriptions, setCommandExamples } from '../../utils/command-helpers';
+
+export function createInitCommand(): Command {
+  const command = new Command('init');
+  setCommandDescriptions(
+    command,
+    'Initialize a new Prisma Next project',
+    'Scaffolds config, schema, and runtime files, installs dependencies,\n' +
+      'and emits the contract. Gets you from zero to typed queries in one step.',
+  );
+  setCommandExamples(command, ['prisma-next init', 'prisma-next init --no-install']);
+  command
+    .option('--no-install', 'Skip dependency installation and contract emission')
+    .action(async (options: { readonly install?: boolean }) => {
+      const { runInit } = await import('./init');
+      await runInit(process.cwd(), { noInstall: !options.install });
+    });
+
+  return command;
+}

package/src/commands/init/init.ts

@@ -0,0 +1,203 @@
+import { execFile } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { promisify } from 'node:util';
+import * as clack from '@clack/prompts';
+import { dirname, extname, isAbsolute, join, normalize } from 'pathe';
+import { TerminalUI } from '../../utils/terminal-ui';
+import {
+  detectPackageManager,
+  formatAddArgs,
+  formatAddDevArgs,
+  formatRunCommand,
+  hasProjectManifest,
+} from './detect-package-manager';
+import { agentSkillMd } from './templates/agent-skill';
+import {
+  type AuthoringId,
+  configFile,
+  dbFile,
+  defaultSchemaPath,
+  starterSchema,
+  type TargetId,
+  targetPackageName,
+} from './templates/code-templates';
+import { quickReferenceMd } from './templates/quick-reference';
+import { defaultTsConfig, mergeTsConfig } from './templates/tsconfig';
+
+export interface InitOptions {
+  readonly noInstall?: boolean;
+}
+
+interface FileEntry {
+  readonly path: string;
+  readonly content: string;
+}
+
+export async function runInit(baseDir: string, options: InitOptions): Promise<void> {
+  const ui = new TerminalUI();
+
+  clack.intro('prisma-next init', { output: process.stderr });
+
+  if (!hasProjectManifest(baseDir)) {
+    ui.error(
+      'No package.json or deno.json found. Initialize your project first (e.g. npm init or deno init), then re-run prisma-next init.',
+    );
+    process.exit(1);
+  }
+
+  const pm = await detectPackageManager(baseDir);
+  const pkgRun = formatRunCommand(pm, 'prisma-next', '').trimEnd();
+
+  if (existsSync(join(baseDir, 'prisma-next.config.ts'))) {
+    const reinit = await clack.confirm({
+      message:
+        'This project is already initialized. Re-initialize? This will overwrite all generated files.',
+      initialValue: false,
+      output: process.stderr,
+    });
+    if (clack.isCancel(reinit) || !reinit) {
+      clack.cancel('Init cancelled.', { output: process.stderr });
+      process.exit(0);
+    }
+  }
+
+  const targetResult = await clack.select({
+    message: 'What database are you using?',
+    options: [
+      { value: 'postgres' as TargetId, label: 'PostgreSQL' },
+      { value: 'mongo' as TargetId, label: 'MongoDB' },
+    ],
+    output: process.stderr,
+  });
+  if (clack.isCancel(targetResult)) {
+    clack.cancel('Init cancelled.', { output: process.stderr });
+    process.exit(0);
+  }
+  const target = targetResult as TargetId;
+
+  const authoringResult = await clack.select({
+    message: 'How do you want to write your schema?',
+    options: [
+      { value: 'psl' as AuthoringId, label: 'Prisma Schema Language (.prisma)' },
+      { value: 'typescript' as AuthoringId, label: 'TypeScript (.ts)' },
+    ],
+    output: process.stderr,
+  });
+  if (clack.isCancel(authoringResult)) {
+    clack.cancel('Init cancelled.', { output: process.stderr });
+    process.exit(0);
+  }
+  const authoring = authoringResult as AuthoringId;
+
+  const schemaPathResult = await clack.text({
+    message: 'Where should the schema file go?',
+    initialValue: defaultSchemaPath(authoring),
+    validate(value = '') {
+      const trimmed = value.trim();
+      if (trimmed.length === 0) return 'Path cannot be empty';
+      if (trimmed.endsWith('/') || trimmed.endsWith('\\'))
+        return 'Path must be a file, not a directory';
+      if (!extname(trimmed)) return 'Path must include a file extension (e.g. .prisma or .ts)';
+      return undefined;
+    },
+    output: process.stderr,
+  });
+  if (clack.isCancel(schemaPathResult)) {
+    clack.cancel('Init cancelled.', { output: process.stderr });
+    process.exit(0);
+  }
+  const schemaPath = normalize((schemaPathResult as string).trim());
+
+  const schemaDir = dirname(schemaPath);
+  const configPath = isAbsolute(schemaPath) ? schemaPath : `./${schemaPath}`;
+
+  const files: FileEntry[] = [
+    { path: schemaPath, content: starterSchema(target, authoring) },
+    { path: 'prisma-next.config.ts', content: configFile(target, configPath) },
+    { path: join(schemaDir, 'db.ts'), content: dbFile(target) },
+    { path: 'prisma-next.md', content: quickReferenceMd(target, schemaPath, pkgRun) },
+    {
+      path: '.agents/skills/prisma-next/SKILL.md',
+      content: agentSkillMd(target, schemaPath, pkgRun),
+    },
+  ];
+
+  for (const file of files) {
+    const fullPath = join(baseDir, file.path);
+    mkdirSync(dirname(fullPath), { recursive: true });
+    writeFileSync(fullPath, file.content, 'utf-8');
+  }
+
+  const tsconfigPath = join(baseDir, 'tsconfig.json');
+  if (existsSync(tsconfigPath)) {
+    const existing = readFileSync(tsconfigPath, 'utf-8');
+    writeFileSync(tsconfigPath, mergeTsConfig(existing), 'utf-8');
+    ui.log('Updated tsconfig.json with required compiler options.');
+  } else {
+    writeFileSync(tsconfigPath, defaultTsConfig(), 'utf-8');
+  }
+
+  const emitCommand = formatRunCommand(pm, 'prisma-next', 'contract emit');
+
+  if (options.noInstall) {
+    const pkg = targetPackageName(target);
+    ui.note(
+      [
+        'Run the following commands to complete setup:',
+        '',
+        '  1. Install dependencies:',
+        `     ${pm} ${formatAddArgs(pm, [pkg, 'dotenv']).join(' ')}`,
+        `     ${pm} ${formatAddDevArgs(pm, ['@prisma-next/cli']).join(' ')}`,
+        '',
+        '  2. Emit the contract:',
+        `     ${emitCommand}`,
+      ].join('\n'),
+      'Manual steps',
+    );
+  } else {
+    const pkg = targetPackageName(target);
+    const spinner = ui.spinner();
+    let installSucceeded = false;
+
+    const exec = promisify(execFile);
+
+    spinner.start(`Installing ${pkg}, dotenv, and @prisma-next/cli...`);
+    try {
+      await exec(pm, formatAddArgs(pm, [pkg, 'dotenv']), { cwd: baseDir });
+      await exec(pm, formatAddDevArgs(pm, ['@prisma-next/cli']), { cwd: baseDir });
+      spinner.stop(`Installed ${pkg}, dotenv, and @prisma-next/cli`);
+      installSucceeded = true;
+    } catch (err) {
+      spinner.stop('Installation failed');
+      const stderr =
+        err instanceof Error && 'stderr' in err ? (err as { stderr: string }).stderr : '';
+      ui.warn(
+        [
+          'Could not install dependencies automatically.',
+          ...(stderr ? [`  ${stderr.trim()}`] : []),
+          '',
+          'Run manually:',
+          `  ${pm} ${formatAddArgs(pm, [pkg, 'dotenv']).join(' ')}`,
+          `  ${pm} ${formatAddDevArgs(pm, ['@prisma-next/cli']).join(' ')}`,
+        ].join('\n'),
+      );
+    }
+
+    if (installSucceeded) {
+      spinner.start('Emitting contract...');
+      try {
+        const { executeContractEmit } = await import('../../control-api/operations/contract-emit');
+        const configFilePath = join(baseDir, 'prisma-next.config.ts');
+        await executeContractEmit({ configPath: configFilePath });
+        spinner.stop('Contract emitted');
+      } catch {
+        spinner.stop('Contract emission failed');
+        ui.warn(
+          ['Could not emit contract automatically. Run manually:', `  ${emitCommand}`].join('\n'),
+        );
+      }
+    }
+  }
+
+  clack.outro('Done! Open prisma-next.md to get started.', { output: process.stderr });
+}

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

@@ -0,0 +1,106 @@
+# 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}}` — 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
+
+Always use the ORM (`db.orm`). Only fall back to `db.sql` if the user explicitly asks for raw queries 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: ObjectId; email: string; ... } | null
+
+// Find multiple records
+const users = await db.orm.User
+  .select('id', 'email')
+  .take(10)
+  .all();
+// Returns Array<{ id: ObjectId; 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-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 });
+`;
+}