@prisma-next/cli 0.8.0 → 0.9.0-dev.1

package/src/cli.ts

@@ -12,17 +12,44 @@ import { createDbSchemaCommand } from './commands/db-schema';
 import { createDbSignCommand } from './commands/db-sign';
 import { createDbUpdateCommand } from './commands/db-update';
 import { createDbVerifyCommand } from './commands/db-verify';
-import { createMigrationApplyCommand } from './commands/migration-apply';
+import { createMigrateCommand } from './commands/migrate';
+import { createMigrationCheckCommand } from './commands/migration-check';
+import { createMigrationGraphCommand } from './commands/migration-graph';
+import { createMigrationListCommand } from './commands/migration-list';
+import { createMigrationLogCommand } from './commands/migration-log';
 import { createMigrationNewCommand } from './commands/migration-new';
 import { createMigrationPlanCommand } from './commands/migration-plan';
-import { createMigrationRefCommand } from './commands/migration-ref';
 import { createMigrationShowCommand } from './commands/migration-show';
 import { createMigrationStatusCommand } from './commands/migration-status';
+import { createRefCommand } from './commands/ref';
 import { setCommandDescriptions } from './utils/command-helpers';
 import { formatCommandHelp, formatRootHelp } from './utils/formatters/help';
 import { parseGlobalFlags } from './utils/global-flags';
 import { suggestCommands } from './utils/suggest-command';
 
+/**
+ * Lookup table mapping removed subcommands to their replacement verbs.
+ * Keyed by `<parent>:<subcommand>` (e.g. `migration:apply`).
+ * The handler consults this before falling back to the fuzzy suggest engine.
+ */
+const removedVerbRedirects: Record<string, string> = {
+  'migration:apply': 'Use `prisma-next migrate --to <contract>` instead.',
+  'migration:ref': 'Use `prisma-next ref set|list|delete` instead.',
+};
+
+/**
+ * Removed flags on specific subcommands. Keyed by `<parent>:<sub>:<flag>`.
+ * Checked during the pre-parse argv scan before commander sees the flags.
+ */
+const removedFlagRedirects: Record<string, string> = {
+  'migration:status:graph': 'Use `prisma-next migration graph` to view the migration graph.',
+  'migration:status:all':
+    'Use `prisma-next migration log --db <url>` to view the full execution history.',
+  'migration:status:limit':
+    'Use `prisma-next migration log --db <url>` to view the full execution history.',
+  'migration:status:ref': 'Use `--to <contract>` instead of `--ref`.',
+};
+
 /**
  * Formats the "Did you mean ...?" hint for an unknown command.
  */
@@ -177,9 +204,6 @@ contractCommand.addCommand(contractEmitCommand);
 const contractInferCommand = createContractInferCommand();
 contractCommand.addCommand(contractInferCommand);
 
-// Register contract command
-program.addCommand(contractCommand);
-
 // Register db subcommand
 const dbCommand = new Command('db');
 setCommandDescriptions(
@@ -216,9 +240,6 @@ dbCommand.addCommand(dbSchemaCommand);
 const dbSignCommand = createDbSignCommand();
 dbCommand.addCommand(dbSignCommand);
 
-// Register db command
-program.addCommand(dbCommand);
-
 // Register migration subcommand
 const migrationCommand = new Command('migration');
 setCommandDescriptions(
@@ -247,17 +268,38 @@ migrationCommand.addCommand(migrationShowCommand);
 const migrationStatusCommand = createMigrationStatusCommand();
 migrationCommand.addCommand(migrationStatusCommand);
 
-const migrationApplyCommand = createMigrationApplyCommand();
-migrationCommand.addCommand(migrationApplyCommand);
+const migrationLogCommand = createMigrationLogCommand();
+migrationCommand.addCommand(migrationLogCommand);
 
-const migrationRefCommand = createMigrationRefCommand();
-migrationCommand.addCommand(migrationRefCommand);
+const migrationListCommand = createMigrationListCommand();
+migrationCommand.addCommand(migrationListCommand);
 
-program.addCommand(migrationCommand);
+const migrationGraphCommand = createMigrationGraphCommand();
+migrationCommand.addCommand(migrationGraphCommand);
+
+const migrationCheckCommand = createMigrationCheckCommand();
+migrationCommand.addCommand(migrationCheckCommand);
+
+// Top-level migrate command
+const migrateCommand = createMigrateCommand();
 
-// Register init command (top-level, not nested)
+// Top-level ref command (replaces `migration ref`)
+const refCommand = createRefCommand();
+
+// Top-level init command
 const initCommand = createInitCommand();
+
+// Register top-level commands in the order the spec's intended-surface
+// diagram lists them: verbs (init, migrate) first, then subject
+// namespaces (contract, db, migration, ref). The order shows up in
+// `prisma-next --help` and is the first thing a new user sees, so it
+// matches the order spec.md uses to introduce the surface.
 program.addCommand(initCommand);
+program.addCommand(migrateCommand);
+program.addCommand(contractCommand);
+program.addCommand(dbCommand);
+program.addCommand(migrationCommand);
+program.addCommand(refCommand);
 
 // Create help command
 const helpCommand = new Command('help')
@@ -324,7 +366,28 @@ if (args.length > 0) {
       const helpText = formatRootHelp({ program, flags });
       process.stderr.write(`${helpText}\n`);
       process.exit(2);
-    } else if (command.commands.length > 0 && args.length === 1) {
+    } else if (command.commands.length > 0 && args.length >= 2) {
+      const subcommandName = args[1];
+      const redirectKey = `${commandName}:${subcommandName}`;
+      const redirect = removedVerbRedirects[redirectKey];
+      if (redirect) {
+        process.stderr.write(`Unknown command: ${subcommandName}\n${redirect}\n`);
+        process.exit(2);
+      }
+      for (let i = 2; i < args.length; i++) {
+        const arg = args[i]!;
+        if (!arg.startsWith('--')) continue;
+        const flagName = arg.slice(2);
+        const flagKey = `${commandName}:${subcommandName}:${flagName}`;
+        const flagRedirect = removedFlagRedirects[flagKey];
+        if (flagRedirect) {
+          process.stderr.write(`Unknown option: ${arg}\n${flagRedirect}\n`);
+          process.exit(2);
+        }
+      }
+    }
+
+    if (command.commands.length > 0 && args.length === 1) {
       // Parent command called with no subcommand. Same shape as the
       // no-args case above: the user did not request help, we are
       // voluntarily rendering it as decoration around an underspecified

package/src/commands/db-sign.ts

@@ -3,9 +3,12 @@ import type {
   SignDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+import { readRefs } from '@prisma-next/migration-tools/refs';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
-import { relative, resolve } from 'pathe';
+import { join, relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import { ContractValidationError } from '../control-api/errors';
@@ -15,12 +18,17 @@ import {
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFileNotFound,
+  errorRuntime,
   errorUnexpected,
+  mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
+  resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
@@ -40,6 +48,7 @@ import { TerminalUI } from '../utils/terminal-ui';
 interface DbSignOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
+  readonly contract?: string;
 }
 
 /**
@@ -54,11 +63,11 @@ type DbSignFailure = CliStructuredError | VerifyDatabaseSchemaResult;
  * Failure: CliStructuredError (infra error) or VerifyDatabaseSchemaResult (schema mismatch)
  */
 async function executeDbSignCommand(
+  contractArg: string | undefined,
   options: DbSignOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
 ): Promise<Result<SignDatabaseResult, DbSignFailure>> {
-  // Load config
   const config = await loadConfig(options.config);
   const configPath = options.config
     ? relative(process.cwd(), resolve(options.config))
@@ -66,11 +75,12 @@ async function executeDbSignCommand(
   const contractPathAbsolute = resolveContractPath(config);
   const contractPath = relative(process.cwd(), contractPathAbsolute);
 
-  // Output header
+  const effectiveContractArg = contractArg ?? options.contract;
+
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
-      { label: 'contract', value: contractPath },
+      { label: 'contract', value: effectiveContractArg ?? contractPath },
     ];
     if (options.db) {
       details.push({ label: 'database', value: maskConnectionUrl(options.db) });
@@ -85,36 +95,79 @@ async function executeDbSignCommand(
     ui.stderr(header);
   }
 
-  // Load contract file
-  let contractJsonContent: string;
-  try {
-    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
-  } catch (error) {
-    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+  let contractJson: Record<string, unknown>;
+
+  if (effectiveContractArg) {
+    try {
+      const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
+      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
+      const refs = await readRefs(refsDir);
+      const refResult = parseContractRef(effectiveContractArg, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      const targetHash = refResult.value.hash;
+      const matchingBundle = bundles.find((p) => p.metadata.to === targetHash);
+      if (matchingBundle) {
+        const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
+        const raw = await readFile(endContractPath, 'utf-8');
+        contractJson = JSON.parse(raw) as Record<string, unknown>;
+      } else {
+        const defaultRaw = await readFile(contractPathAbsolute, 'utf-8');
+        const defaultContract = JSON.parse(defaultRaw) as Record<string, unknown>;
+        const storageHash = (defaultContract['storage'] as Record<string, unknown> | undefined)?.[
+          'storageHash'
+        ];
+        if (storageHash === targetHash) {
+          contractJson = defaultContract;
+        } else {
+          return notOk(
+            errorRuntime(`No contract file found for hash "${targetHash}"`, {
+              why: `Resolved contract reference "${effectiveContractArg}" to hash "${targetHash}" but no migration produces that hash and the emitted contract does not match.`,
+              fix: 'Ensure the target contract exists on disk — either as a migration endpoint or as the emitted contract.json.',
+            }),
+          );
+        }
+      }
+    } catch (error) {
+      if (MigrationToolsError.is(error)) return notOk(mapMigrationToolsError(error));
+      if (error instanceof CliStructuredError) return notOk(error);
       return notOk(
-        errorFileNotFound(contractPathAbsolute, {
-          why: `Contract file not found at ${contractPathAbsolute}`,
-          fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+        errorUnexpected(error instanceof Error ? error.message : String(error), {
+          why: `Failed to resolve contract reference: ${error instanceof Error ? error.message : String(error)}`,
+        }),
+      );
+    }
+  } else {
+    let contractJsonContent: string;
+    try {
+      contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
+    } catch (error) {
+      if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+        return notOk(
+          errorFileNotFound(contractPathAbsolute, {
+            why: `Contract file not found at ${contractPathAbsolute}`,
+            fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+          }),
+        );
+      }
+      return notOk(
+        errorUnexpected(error instanceof Error ? error.message : String(error), {
+          why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
         }),
       );
     }
-    return notOk(
-      errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
-      }),
-    );
-  }
 
-  let contractJson: Record<string, unknown>;
-  try {
-    contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
-  } catch (error) {
-    return notOk(
-      errorContractValidationFailed(
-        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
-        { where: { path: contractPathAbsolute } },
-      ),
-    );
+    try {
+      contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
+    } catch (error) {
+      return notOk(
+        errorContractValidationFailed(
+          `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+          { where: { path: contractPathAbsolute } },
+        ),
+      );
+    }
   }
 
   // Resolve database connection (--db flag or config.db.connection)
@@ -203,16 +256,33 @@ export function createDbSignCommand(): Command {
       'in CI/deployment pipelines. The signature records that this database instance is aligned\n' +
       'with a specific contract version.',
   );
-  setCommandExamples(command, ['prisma-next db sign --db $DATABASE_URL']);
+  setCommandExamples(command, [
+    'prisma-next db sign --db $DATABASE_URL',
+    'prisma-next db sign production --db $DATABASE_URL',
+    'prisma-next db sign --contract production --db $DATABASE_URL',
+  ]);
   addGlobalOptions(command)
+    .argument('[contract]', 'Contract reference (hash, prefix, ref name, or migration dir name)')
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .action(async (options: DbSignOptions) => {
+    .option(
+      '--contract <contract>',
+      'Contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .action(async (positionalContract: string | undefined, options: DbSignOptions) => {
       const flags = parseGlobalFlags(options);
 
+      if (positionalContract && options.contract) {
+        process.stderr.write(
+          'Cannot specify both a positional contract argument and --contract flag.\n',
+        );
+        process.exit(2);
+        return;
+      }
+
       const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
 
-      const result = await executeDbSignCommand(options, flags, ui);
+      const result = await executeDbSignCommand(positionalContract, options, flags, ui);
 
       if (result.ok) {
         // Success - format sign output

package/src/commands/db-update.ts

@@ -1,6 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
+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 { ContractValidationError } from '../control-api/errors';
 import type { DbUpdateFailure } from '../control-api/types';
 import {
@@ -11,9 +16,12 @@ import {
   errorMigrationPlanningFailed,
   errorRunnerFailed,
   errorUnexpected,
+  mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
+  loadMigrationPackages,
   resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
@@ -33,7 +41,9 @@ import {
 import { handleResult } from '../utils/result-handler';
 import { TerminalUI } from '../utils/terminal-ui';
 
-type DbUpdateOptions = MigrationCommandOptions;
+interface DbUpdateOptions extends MigrationCommandOptions {
+  readonly to?: string;
+}
 
 /**
  * Maps a DbUpdateFailure to a CliStructuredError for consistent error handling.
@@ -81,9 +91,47 @@ async function executeDbUpdateCommand(
   if (!ctxResult.ok) {
     return ctxResult;
   }
-  const { client, config, contractJson, dbConnection, onProgress, contractPathAbsolute } =
-    ctxResult.value;
-  const { migrationsDir } = resolveMigrationPaths(options.config, config);
+  const { client, config, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
+  let { contractJson } = ctxResult.value;
+  const { migrationsDir, appMigrationsDir, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  if (options.to) {
+    try {
+      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
+      const refs = await readRefs(refsDir);
+      const refResult = parseContractRef(options.to, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      const targetHash = refResult.value.hash;
+      const matchingBundle = bundles.find((p) => p.metadata.to === targetHash);
+      if (!matchingBundle) {
+        return notOk(
+          errorUnexpected(
+            `No migration bundle found for --to "${options.to}" (resolved hash: ${targetHash})`,
+            {
+              why: `The ref resolved successfully but no on-disk migration package has an end-contract hash matching ${targetHash}.`,
+              fix: 'Provide a ref or hash that corresponds to an existing migration package, or run `migration list` to see available migrations.',
+            },
+          ),
+        );
+      }
+      const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
+      const raw = await readFile(endContractPath, 'utf-8');
+      contractJson = JSON.parse(raw) as Record<string, unknown>;
+    } catch (error) {
+      if (MigrationToolsError.is(error)) {
+        return notOk(mapMigrationToolsError(error));
+      }
+      if (CliStructuredError.is(error)) {
+        return notOk(error);
+      }
+      throw error;
+    }
+  }
 
   try {
     await client.connect(dbConnection);
@@ -185,6 +233,10 @@ export function createDbUpdateCommand(): Command {
     'prisma-next db update --db $DATABASE_URL --dry-run',
   ]);
   addMigrationCommandOptions(command);
+  command.option(
+    '--to <contract>',
+    'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+  );
   command.action(async (options: DbUpdateOptions) => {
     const flags = parseGlobalFlags(options);
     const startTime = Date.now();

package/src/commands/db-verify.ts

@@ -1,9 +1,11 @@
 import { readFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
 import type {
   VerifyDatabaseResult,
   VerifyDatabaseSchemaResult,
 } from '@prisma-next/framework-components/control';
 import {
+  createControlStack,
   VERIFY_CODE_HASH_MISMATCH,
   VERIFY_CODE_MARKER_MISSING,
   VERIFY_CODE_TARGET_MISMATCH,
@@ -236,7 +238,7 @@ async function resolveVerifyPaths(options: DbVerifyOptions) {
 type VerifyPaths = Awaited<ReturnType<typeof resolveVerifyPaths>>;
 
 interface VerifySetup extends VerifyPaths {
-  readonly contractJson: Record<string, unknown>;
+  readonly contractJson: Contract;
   readonly dbConnection: string;
 }
 
@@ -266,10 +268,24 @@ async function resolveVerifySetup(
     );
   }
 
-  let contractJson: Record<string, unknown>;
+  // Cross the family `deserializeContract` seam at the read site, just
+  // like every other CLI on-disk read (TML-2536). The downstream
+  // `dbVerify` op accepts the hydrated `Contract` directly and no
+  // longer re-deserializes.
+  const stack = createControlStack(config);
+  const familyInstance = config.family.create(stack);
+
+  let contractJson: Contract;
   try {
-    contractJson = JSON.parse(contractJsonContent) as Record<string, unknown>;
+    contractJson = familyInstance.deserializeContract(JSON.parse(contractJsonContent) as unknown);
   } catch (error) {
+    if (error instanceof ContractValidationError) {
+      return notOk(
+        errorContractValidationFailed(`Contract validation failed: ${error.message}`, {
+          where: { path: contractPathAbsolute },
+        }),
+      );
+    }
     return notOk(
       errorContractValidationFailed(
         `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,