@prisma-next/cli 0.10.0 → 0.11.0-dev.10

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

@@ -40,7 +40,14 @@ function envPlaceholderBody(target: TargetId): string {
   if (target === 'postgres') {
     lines.push('DATABASE_URL="postgresql://user:password@localhost:5432/mydb"');
   } else {
-    lines.push('DATABASE_URL="mongodb://localhost:27017/mydb"');
+    lines.push(
+      '# Standalone local mongod / `docker run mongo:7` — no replica set required for first-run queries.',
+    );
+    lines.push(
+      '# Transactions and change streams need a replica set; add ?replicaSet=... only after initiating one.',
+    );
+    lines.push('');
+    lines.push('DATABASE_URL="mongodb://user:password@localhost:27017/mydb"');
   }
   lines.push('');
   return lines.join('\n');

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

@@ -22,7 +22,7 @@ const user = await db.orm.users
   .first();
 
 // Your editor will show the type of user as
-// { _id: ObjectId; email: string; name: string | null; posts: Post[] } | null
+// { _id: ObjectId; email: string; username: string | null; name: string | null; posts: Post[] } | null
 ```
 
 `db` connects to MongoDB lazily on the first query, so there is no manual `connect(...)` step in your application code. Call `await db.close()` if you need to release the underlying connection (typically only in tests or short-lived scripts). After `close()` the client is single-shot — any further query, `connect()`, or `runtime()` call rejects with `"Mongo client is closed"`. Construct a new `mongo({...})` if you need to use it again.

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

@@ -22,7 +22,7 @@ const user = await db.orm.User
   .first();
 
 // Your editor will show the type of user as
-// { id: number; email: string; createdAt: Date, name: string, posts: Post[] } | null
+// { id: number; email: string; username: string | null; name: string | null; createdAt: Date; posts: Post[] } | null
 ```
 
 Your contract has two companion files in the same directory:

package/src/commands/init/templates/readme-mongo.md

@@ -0,0 +1,35 @@
+# {{projectName}}
+
+Generated by `prisma-next init` with the Minimal template.
+
+## First run
+
+1. `{{runDbUp}}` — start the local MongoDB replica set with `mongodb-memory-server`. Data persists in `.mongo-data/` across restarts.
+2. `{{runDev}}` — runs `src/index.ts`, which writes one row and reads it back.
+
+## Available scripts
+
+- `{{runDev}}` — run the Prisma Next sample script
+
+### Database and migrations
+
+- `{{runContractEmit}}` — emit contract artifacts after contract changes
+- `{{runDbUp}}` — start the local MongoDB replica set with `mongodb-memory-server`. Data persists in `.mongo-data/` across restarts.
+- `{{runDbDown}}` — stop the local MongoDB process (data preserved)
+- `{{runDbReset}}` — stop and wipe `.mongo-data/` for a clean slate
+- `{{runMigrationPlan}}` — create a MongoDB migration plan
+- `{{runMigrate}}` — apply the planned MongoDB migration
+- `{{runDbSeed}}` — insert sample users manually
+
+## Prisma Next
+
+Prisma Next setup is scaffolded in:
+
+- `{{contractPath}}`
+- `prisma-next.config.ts`
+- `prisma/db.ts`
+- `src/lib/prisma.ts`
+
+For provider-specific Prisma Next reference docs, see `prisma-next.md`. Prisma Next skills live in the upstream `skills/` directory: https://github.com/prisma/prisma-next/tree/main/skills.
+
+Node-based Prisma Next projects expect Node.js 24 LTS or newer.

package/src/commands/init/templates/readme-postgres.md

@@ -0,0 +1,34 @@
+# {{projectName}}
+
+Generated by `prisma-next init` with the Minimal template.
+
+## First run
+
+1. `{{runDbInit}}` — applies your contract to the database (creates tables, signs the marker).
+2. `{{runDev}}` — runs `src/index.ts`, which writes one row and reads it back.
+
+## Available scripts
+
+- `{{runDev}}` — run the Prisma Next sample script
+
+### Database and migrations
+
+- `{{runContractEmit}}` — emit contract artifacts after contract changes
+- `{{runDbInit}}` — initialize database state manually
+- `{{runDbUpdate}}` — update database state manually
+- `{{runMigrationPlan}}` — create a migration plan
+- `{{runMigrate}}` — apply a planned migration
+- `{{runDbSeed}}` — insert sample users manually (run after `db:init`)
+
+## Prisma Next
+
+Prisma Next setup is scaffolded in:
+
+- `{{contractPath}}`
+- `prisma-next.config.ts`
+- `prisma/db.ts`
+- `src/lib/prisma.ts`
+
+For provider-specific Prisma Next reference docs, see `prisma-next.md`. Prisma Next skills live in the upstream `skills/` directory: https://github.com/prisma/prisma-next/tree/main/skills.
+
+Node-based Prisma Next projects expect Node.js 24 LTS or newer.

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

@@ -0,0 +1,62 @@
+import { formatRunScriptCommand, type PackageManager } from '../detect-package-manager';
+import type { TargetId } from './code-templates';
+import { renderTemplate } from './render';
+
+const sharedVariables = ['projectName', 'contractPath', 'runDev', 'runContractEmit'] as const;
+
+export const postgresVariables = [
+  ...sharedVariables,
+  'runDbInit',
+  'runDbUpdate',
+  'runMigrationPlan',
+  'runMigrate',
+  'runDbSeed',
+] as const;
+
+export const mongoVariables = [
+  ...sharedVariables,
+  'runDbUp',
+  'runDbDown',
+  'runDbReset',
+  'runMigrationPlan',
+  'runMigrate',
+  'runDbSeed',
+] as const;
+
+type PostgresVars = Record<(typeof postgresVariables)[number], string>;
+type MongoVars = Record<(typeof mongoVariables)[number], string>;
+
+export function minimalProjectReadmeMd(
+  target: TargetId,
+  schemaPath: string,
+  projectName: string,
+  pm: PackageManager,
+): string {
+  const run = (script: string): string => formatRunScriptCommand(pm, script);
+  const shared = {
+    projectName,
+    contractPath: schemaPath,
+    runDev: run('dev'),
+    runContractEmit: run('contract:emit'),
+    runMigrationPlan: run('migration:plan'),
+    runMigrate: run('migrate'),
+    runDbSeed: run('db:seed'),
+  };
+
+  if (target === 'mongo') {
+    const vars: MongoVars = {
+      ...shared,
+      runDbUp: run('db:up'),
+      runDbDown: run('db:down'),
+      runDbReset: run('db:reset'),
+    };
+    return renderTemplate('readme-mongo.md', mongoVariables, vars);
+  }
+
+  const vars: PostgresVars = {
+    ...shared,
+    runDbInit: run('db:init'),
+    runDbUpdate: run('db:update'),
+  };
+  return renderTemplate('readme-postgres.md', postgresVariables, vars);
+}

package/src/commands/migrate.ts

@@ -2,13 +2,14 @@ import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { createControlStack } from '@prisma-next/framework-components/control';
 import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { findLatestMigration, isGraphNode } from '@prisma-next/migration-tools/migration-graph';
 import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
 import { readRefs } from '@prisma-next/migration-tools/refs';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-
+import { join } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import type {
@@ -23,6 +24,8 @@ import {
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFileNotFound,
+  errorMarkerMismatch,
+  errorPathUnreachable,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -43,14 +46,16 @@ import {
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { executeRefAdvancement, readContractIR } from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrateCommandOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
   readonly to?: string;
+  readonly advanceRef?: string;
 }
 
 export interface MigrateResult {
@@ -72,9 +77,13 @@ export interface MigrateResult {
   readonly timings: {
     readonly total: number;
   };
+  readonly advancedRef?: { readonly name: string; readonly hash: string } | null;
 }
 
 function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
+  if (failure.code === 'MIGRATION_PATH_NOT_FOUND') {
+    return errorPathUnreachable(failure);
+  }
   return errorRuntime(failure.summary, {
     why: failure.why ?? 'Migration runner failed',
     fix: 'Fix the issue and re-run `prisma-next migrate --to <contract>` — previously applied migrations are preserved.',
@@ -229,9 +238,21 @@ async function executeMigrateCommand(
   try {
     await client.connect(dbConnection);
 
+    const allMarkers = await client.readAllMarkers();
+    const appMarker = allMarkers.get('app') ?? null;
+    const { graph } = appPackages;
+
+    if (appMarker !== null && !isGraphNode(appMarker.storageHash, graph)) {
+      return notOk(
+        errorMarkerMismatch(
+          appMarker.storageHash,
+          [...graph.nodes].sort(),
+          findLatestMigration(graph)?.to ?? null,
+        ),
+      );
+    }
+
     if (refEntry && refEntry.invariants.length > 0) {
-      const allMarkers = await client.readAllMarkers();
-      const appMarker = allMarkers.get('app') ?? null;
       const declared = collectDeclaredInvariants(appPackages.graph);
       const known = new Set<string>(declared);
       for (const id of appMarker?.invariants ?? []) known.add(id);
@@ -268,6 +289,53 @@ async function executeMigrateCommand(
 
     const { value } = applyResult;
 
+    let advancedRef: { name: string; hash: string } | null = null;
+    if (options.advanceRef !== undefined) {
+      let contractJsonPathForSnapshot = contractPathAbsolute;
+      let contractJsonForSnapshot: Record<string, unknown> = JSON.parse(contractContent) as Record<
+        string,
+        unknown
+      >;
+      if (toArg && refEntry) {
+        const matchingBundle = appPackages.bundles.find((p) => p.metadata.to === refEntry.hash);
+        if (matchingBundle) {
+          const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
+          contractJsonPathForSnapshot = endContractPath;
+          try {
+            const raw = await readFile(endContractPath, 'utf-8');
+            contractJsonForSnapshot = JSON.parse(raw) as Record<string, unknown>;
+          } catch (error) {
+            if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+              return notOk(
+                errorFileNotFound(endContractPath, {
+                  why: `Bundle end-contract not found at ${endContractPath}`,
+                  fix: 'Re-emit the migration bundle or pick a different --to target.',
+                }),
+              );
+            }
+            throw error;
+          }
+        }
+      }
+      try {
+        const contractIR = await readContractIR(
+          contractJsonForSnapshot,
+          contractJsonPathForSnapshot,
+        );
+        advancedRef = await executeRefAdvancement(
+          refsDir,
+          options.advanceRef,
+          value.markerHash,
+          contractIR,
+        );
+      } catch (error) {
+        if (MigrationToolsError.is(error)) {
+          return notOk(mapMigrationToolsError(error));
+        }
+        throw error;
+      }
+    }
+
     return ok({
       ok: true,
       migrationsApplied: value.migrationsApplied,
@@ -278,6 +346,7 @@ async function executeMigrateCommand(
       perSpace: value.perSpace,
       ...ifDefined('pathDecision', value.pathDecision),
       timings: { total: Date.now() - startTime },
+      advancedRef,
     });
   } catch (error) {
     if (CliStructuredError.is(error)) {
@@ -318,14 +387,12 @@ export function createMigrateCommand(): Command {
       '--to <contract>',
       'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
     )
+    .option('--advance-ref <name>', 'Advance the named ref to the post-apply marker after success')
     .action(async (options: MigrateCommandOptions) => {
-      const flags = parseGlobalFlags(options);
+      const flags = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();
 
-      const ui = new TerminalUI({
-        color: flags.color,
-        interactive: flags.interactive,
-      });
+      const ui = createTerminalUI(flags);
 
       const result = await executeMigrateCommand(options, flags, ui, startTime);
 

package/src/commands/migration-check.ts

@@ -17,8 +17,8 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
-import { TerminalUI } from '../utils/terminal-ui';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 import { INTEGRITY_FAILED, OK, PRECONDITION } from './migration-check/exit-codes';
 
 interface MigrationCheckOptions extends CommonCommandOptions {
@@ -335,8 +335,8 @@ export function createMigrationCheckCommand(): Command {
     .argument('[migration]', 'Migration reference (directory name or hash) to check')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (target: string | undefined, options: MigrationCheckOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       let result: MigrationCheckResult;
       let exitCode: number;

package/src/commands/migration-graph.ts

@@ -23,10 +23,10 @@ import { migrationGraphToRenderInput } from '../utils/formatters/graph-migration
 import { graphRenderer } from '../utils/formatters/graph-render';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import type { StatusRef } from '../utils/migration-types';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationGraphOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -130,8 +130,8 @@ export function createMigrationGraphCommand(): Command {
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .option('--dot', 'Output in Graphviz DOT format')
     .action(async (options: MigrationGraphOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationGraphCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (graphResult) => {
         // Explicit format flags win over the auto-JSON default. `flags.json`

package/src/commands/migration-list.ts

@@ -20,9 +20,9 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationListOptions extends CommonCommandOptions {
   readonly config?: string;
@@ -130,8 +130,8 @@ export function createMigrationListCommand(): Command {
   addGlobalOptions(command)
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationListOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationListCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (listResult) => {
         if (flags.json) {

package/src/commands/migration-log.ts

@@ -8,7 +8,7 @@ import { Command } from 'commander';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import {
-  type CliStructuredError,
+  CliStructuredError,
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorUnexpected,
@@ -26,9 +26,9 @@ import {
 } from '../utils/command-helpers';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface MigrationLogOptions extends CommonCommandOptions {
   readonly db?: string;
@@ -159,6 +159,7 @@ async function executeMigrationLogCommand(
       summary: `${entries.length} migration(s) applied`,
     });
   } catch (error) {
+    if (CliStructuredError.is(error)) return notOk(error);
     if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
@@ -192,8 +193,8 @@ export function createMigrationLogCommand(): Command {
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationLogOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
       const result = await executeMigrationLogCommand(options, flags, ui);
       const exitCode = handleResult(result, flags, ui, (logResult) => {
         if (flags.json) {

package/src/commands/migration-new.ts

@@ -49,9 +49,9 @@ import {
 import { formatStyledHeader } from '../utils/formatters/styled';
 import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
 import type { CommonCommandOptions } from '../utils/global-flags';
-import { parseGlobalFlags } from '../utils/global-flags';
+import { parseGlobalFlagsOrExit } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
-import { TerminalUI } from '../utils/terminal-ui';
+import { createTerminalUI } from '../utils/terminal-ui';
 
 interface MigrationNewOptions extends CommonCommandOptions {
   readonly name?: string;
@@ -287,8 +287,8 @@ export function createMigrationNewCommand(): Command {
     .option('--from <hash>', 'Starting contract hash (default: latest migration target)')
     .option('--config <path>', 'Path to prisma-next.config.ts')
     .action(async (options: MigrationNewOptions) => {
-      const flags = parseGlobalFlags(options);
-      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const flags = parseGlobalFlagsOrExit(options);
+      const ui = createTerminalUI(flags);
 
       if (!flags.json && !flags.quiet) {
         const header = formatStyledHeader({