@prisma-next/cli 0.8.0-dev.7 → 0.8.0-dev.8

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/{migration-apply.ts → migrate.ts}

@@ -1,8 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
 import { errorUnknownInvariant, MigrationToolsError } from '@prisma-next/migration-tools/errors';
+import { parseContractRef } from '@prisma-next/migration-tools/ref-resolution';
 import type { RefEntry } from '@prisma-next/migration-tools/refs';
-import { readRefs, resolveRef } 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';
@@ -25,6 +26,7 @@ import {
   errorTargetMigrationNotSupported,
   errorUnexpected,
   mapMigrationToolsError,
+  mapRefResolutionError,
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
@@ -44,29 +46,16 @@ import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
 import { TerminalUI } from '../utils/terminal-ui';
 
-interface MigrationApplyCommandOptions extends CommonCommandOptions {
+interface MigrateCommandOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
-  readonly ref?: string;
+  readonly to?: string;
 }
 
-/**
- * Per-space breakdown of an apply run. The CLI command surfaces these
- * for both the JSON shape (`appliedSpaces[]`) and the human-readable
- * formatter (per-space block — same shape `db init` / `db update`
- * use, M6 sub-spec § Output shape contract).
- */
-export interface MigrationApplyResult {
+export interface MigrateResult {
   readonly ok: boolean;
-  /** Number of contract spaces that had non-zero pending operations applied. */
   readonly migrationsApplied: number;
-  /** Total contract spaces visible in the aggregate (pending + already-up-to-date). */
   readonly migrationsTotal: number;
-  /**
-   * Marker hash for the **app member** post-apply. Surfaced for
-   * back-compat with single-space callers; per-space markers live on
-   * `perSpace[].marker.storageHash`.
-   */
   readonly markerHash: string;
   readonly applied: readonly {
     readonly spaceId: string;
@@ -77,17 +66,7 @@ export interface MigrationApplyResult {
     readonly operationsExecuted: number;
   }[];
   readonly summary: string;
-  /**
-   * Per-space breakdown in canonical schedule order (extensions
-   * alphabetically, then app). Always present for the aggregate-walking
-   * apply path.
-   */
   readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
-  /**
-   * Path-decision data for the app member. Surfaced for back-compat
-   * with single-space callers (cli-journeys invariant tests).
-   * Absent for no-op applies where the app had nothing to do.
-   */
   readonly pathDecision?: MigrationApplyPathDecision;
   readonly timings: {
     readonly total: number;
@@ -97,17 +76,17 @@ export interface MigrationApplyResult {
 function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType {
   return errorRuntime(failure.summary, {
     why: failure.why ?? 'Migration runner failed',
-    fix: 'Fix the issue and re-run `prisma-next migration apply` — previously applied migrations are preserved.',
+    fix: 'Fix the issue and re-run `prisma-next migrate --to <contract>` — previously applied migrations are preserved.',
     meta: failure.meta ?? {},
   });
 }
 
-async function executeMigrationApplyCommand(
-  options: MigrationApplyCommandOptions,
+async function executeMigrateCommand(
+  options: MigrateCommandOptions,
   flags: GlobalFlags,
   ui: TerminalUI,
   startTime: number,
-): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
+): Promise<Result<MigrateResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
   const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
     resolveMigrationPaths(options.config, config);
@@ -116,8 +95,8 @@ async function executeMigrationApplyCommand(
   if (!dbConnection) {
     return notOk(
       errorDatabaseConnectionRequired({
-        why: `Database connection is required for migration apply (set db.connection in ${configPath}, or pass --db <url>)`,
-        commandName: 'migration apply',
+        why: `Database connection is required for migrate (set db.connection in ${configPath}, or pass --db <url>)`,
+        commandName: 'migrate',
       }),
     );
   }
@@ -125,7 +104,7 @@ async function executeMigrationApplyCommand(
   if (!config.driver) {
     return notOk(
       errorDriverRequired({
-        why: 'Config.driver is required for migration apply',
+        why: 'Config.driver is required for migrate',
       }),
     );
   }
@@ -139,12 +118,22 @@ async function executeMigrationApplyCommand(
   }
 
   let refEntry: RefEntry | undefined;
-  const refName = options.ref;
+  const toArg = options.to;
 
-  if (refName) {
+  if (toArg) {
     try {
       const refs = await readRefs(refsDir);
-      refEntry = resolveRef(refs, refName);
+      const { graph } = await loadMigrationPackages(appMigrationsDir);
+      const refResult = parseContractRef(toArg, { graph, refs });
+      if (!refResult.ok) {
+        return notOk(mapRefResolutionError(refResult.failure));
+      }
+      if (refResult.value.provenance.kind === 'ref') {
+        const resolved = refs[refResult.value.provenance.refName];
+        if (resolved) refEntry = resolved;
+      } else {
+        refEntry = { hash: refResult.value.hash, invariants: [] };
+      }
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -153,8 +142,6 @@ async function executeMigrationApplyCommand(
     }
   }
 
-  // Resolve and parse the contract envelope. The aggregate-walking
-  // operation needs the validated app contract to load the aggregate.
   const contractPathAbsolute = resolveContractPath(config);
   let contractRaw: Contract;
   try {
@@ -165,7 +152,7 @@ async function executeMigrationApplyCommand(
       return notOk(
         errorFileNotFound(contractPathAbsolute, {
           why: `Contract file not found at ${contractPathAbsolute}`,
-          fix: 'Run `prisma-next contract emit` to generate a valid contract.json, then retry apply.',
+          fix: 'Run `prisma-next contract emit` to generate a valid contract.json, then retry.',
         }),
       );
     }
@@ -188,21 +175,19 @@ async function executeMigrationApplyCommand(
         value: maskConnectionUrl(dbConnection),
       });
     }
-    if (refName) {
-      details.push({ label: 'ref', value: refName });
+    if (toArg) {
+      details.push({ label: 'to', value: toArg });
     }
     const header = formatStyledHeader({
-      command: 'migration apply',
-      description: 'Apply planned migrations to the database',
-      url: 'https://pris.ly/migration-apply',
+      command: 'migrate',
+      description: 'Apply planned migrations to advance the database',
+      url: 'https://pris.ly/migrate',
       details,
       flags,
     });
     ui.stderr(header);
   }
 
-  // Load app-space migration packages — the aggregate operation
-  // needs them to hydrate the app member's graph for graph-walk.
   let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
   try {
     appPackages = await loadMigrationPackages(appMigrationsDir);
@@ -224,13 +209,6 @@ async function executeMigrationApplyCommand(
   try {
     await client.connect(dbConnection);
 
-    // Pre-check unknown invariants against `(declared by app graph) ∪
-    // (already on the app marker)`. The marker side of the union
-    // catches the case where the ref carries an invariant whose
-    // declaring migration was retired (history rewritten) but whose
-    // id is recorded on the marker — surfacing UNKNOWN_INVARIANT
-    // there would be misleading because the database has already
-    // satisfied the requirement.
     if (refEntry && refEntry.invariants.length > 0) {
       const allMarkers = await client.readAllMarkers();
       const appMarker = allMarkers.get('app') ?? null;
@@ -242,7 +220,7 @@ async function executeMigrationApplyCommand(
         return notOk(
           mapMigrationToolsError(
             errorUnknownInvariant({
-              ...ifDefined('refName', refName),
+              ...ifDefined('refName', toArg),
               unknown,
               declared: [...declared].sort(),
             }),
@@ -261,7 +239,7 @@ async function executeMigrationApplyCommand(
       appMigrationPackages: appPackages.bundles,
       ...ifDefined('refHash', refEntry?.hash),
       ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
-      ...(refEntry !== undefined ? ifDefined('refName', refName) : {}),
+      ...(refEntry !== undefined ? ifDefined('refName', toArg) : {}),
     });
 
     if (!applyResult.ok) {
@@ -290,7 +268,7 @@ async function executeMigrationApplyCommand(
     }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
-        why: `Unexpected error during migration apply: ${error instanceof Error ? error.message : String(error)}`,
+        why: `Unexpected error during migrate: ${error instanceof Error ? error.message : String(error)}`,
       }),
     );
   } finally {
@@ -298,23 +276,29 @@ async function executeMigrationApplyCommand(
   }
 }
 
-export function createMigrationApplyCommand(): Command {
-  const command = new Command('apply');
+export function createMigrateCommand(): Command {
+  const command = new Command('migrate');
   setCommandDescriptions(
     command,
-    'Apply planned migrations to the database',
+    'Apply planned migrations to advance the database',
     'Walks every contract space (app + extensions) and applies pending\n' +
       'on-disk migrations in canonical order (extensions alphabetically,\n' +
-      'then app). Graph-walks the on-disk migration graph for every space —\n' +
-      "no introspection, no synth. Each space's marker advances inside its\n" +
-      "transaction; per-space failure rolls back every space's writes.",
+      'then app). Graph-walks the on-disk migration graph for every space.\n' +
+      'Use --to to target a specific contract (hash, ref name, migration dir).',
   );
-  setCommandExamples(command, ['prisma-next migration apply --db $DATABASE_URL']);
+  setCommandExamples(command, [
+    'prisma-next migrate --db $DATABASE_URL',
+    'prisma-next migrate --to production --db $DATABASE_URL',
+    'prisma-next migrate --to sha256:abc123 --db $DATABASE_URL',
+  ]);
   addGlobalOptions(command)
     .option('--db <url>', 'Database connection string')
     .option('--config <path>', 'Path to prisma-next.config.ts')
-    .option('--ref <name>', 'App-space target ref name from migrations/app/refs/')
-    .action(async (options: MigrationApplyCommandOptions) => {
+    .option(
+      '--to <contract>',
+      'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
+    )
+    .action(async (options: MigrateCommandOptions) => {
       const flags = parseGlobalFlags(options);
       const startTime = Date.now();
 
@@ -323,13 +307,13 @@ export function createMigrationApplyCommand(): Command {
         interactive: flags.interactive,
       });
 
-      const result = await executeMigrationApplyCommand(options, flags, ui, startTime);
+      const result = await executeMigrateCommand(options, flags, ui, startTime);
 
-      const exitCode = handleResult(result, flags, ui, (applyResult) => {
+      const exitCode = handleResult(result, flags, ui, (migrateResult) => {
         if (flags.json) {
-          ui.output(JSON.stringify(applyResult, null, 2));
+          ui.output(JSON.stringify(migrateResult, null, 2));
         } else if (!flags.quiet) {
-          ui.log(formatMigrationApplyCommandOutput(applyResult, flags));
+          ui.log(formatMigrationApplyCommandOutput(migrateResult, flags));
         }
       });
 

package/src/commands/migration-check/exit-codes.ts

@@ -0,0 +1,3 @@
+export const OK = 0;
+export const PRECONDITION = 2;
+export const INTEGRITY_FAILED = 4;