@prisma-next/cli 0.11.0 → 0.12.0

package/src/commands/db-sign.ts

@@ -5,7 +5,6 @@ import type {
 } 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 { join, relative, resolve } from 'pathe';
@@ -25,13 +24,13 @@ import {
 } from '../utils/cli-errors';
 import {
   addGlobalOptions,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import {
   formatSchemaVerifyJson,
@@ -99,9 +98,14 @@ async function executeDbSignCommand(
 
   if (effectiveContractArg) {
     try {
-      const { appMigrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
-      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
+      const { migrationsDir } = resolveMigrationPaths(options.config, config);
+      const loaded = await buildReadAggregate(config, { migrationsDir });
+      if (!loaded.ok) {
+        return notOk(loaded.failure);
+      }
+      const graph = loaded.value.aggregate.app.graph();
+      const bundles = loaded.value.aggregate.app.packages;
+      const refs = loaded.value.aggregate.app.refs;
       const refResult = parseContractRef(effectiveContractArg, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));

package/src/commands/db-update.ts

@@ -1,7 +1,6 @@
 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';
@@ -21,12 +20,12 @@ import {
 } from '../utils/cli-errors';
 import type { MigrationCommandOptions } from '../utils/command-helpers';
 import {
-  loadMigrationPackages,
   resolveMigrationPaths,
   sanitizeErrorMessage,
   setCommandDescriptions,
   setCommandExamples,
 } from '../utils/command-helpers';
+import { buildReadAggregate } from '../utils/contract-space-aggregate-loader';
 import {
   formatMigrationApplyOutput,
   formatMigrationJson,
@@ -38,11 +37,18 @@ import {
   addMigrationCommandOptions,
   prepareMigrationContext,
 } from '../utils/migration-command-scaffold';
+import {
+  buildRefAdvancementFields,
+  computeRefAdvancementName,
+  type RefAdvancementFields,
+  readContractIR,
+} from '../utils/ref-advancement';
 import { handleResult } from '../utils/result-handler';
 import { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
 interface DbUpdateOptions extends MigrationCommandOptions {
   readonly to?: string;
+  readonly advanceRef?: string;
 }
 
 /**
@@ -101,15 +107,18 @@ async function executeDbUpdateCommand(
   }
   const { client, config, dbConnection, onProgress, contractPathAbsolute } = ctxResult.value;
   let { contractJson } = ctxResult.value;
-  const { migrationsDir, appMigrationsDir, refsDir } = resolveMigrationPaths(
-    options.config,
-    config,
-  );
+  let contractJsonPathForSnapshot = contractPathAbsolute;
+  const { migrationsDir, refsDir } = resolveMigrationPaths(options.config, config);
 
   if (options.to) {
     try {
-      const { bundles, graph } = await loadMigrationPackages(appMigrationsDir);
-      const refs = await readRefs(refsDir);
+      const loaded = await buildReadAggregate(config, { migrationsDir });
+      if (!loaded.ok) {
+        return notOk(loaded.failure);
+      }
+      const graph = loaded.value.aggregate.app.graph();
+      const bundles = loaded.value.aggregate.app.packages;
+      const refs = loaded.value.aggregate.app.refs;
       const refResult = parseContractRef(options.to, { graph, refs });
       if (!refResult.ok) {
         return notOk(mapRefResolutionError(refResult.failure));
@@ -130,6 +139,7 @@ async function executeDbUpdateCommand(
       const endContractPath = join(matchingBundle.dirPath, 'end-contract.json');
       const raw = await readFile(endContractPath, 'utf-8');
       contractJson = JSON.parse(raw) as Record<string, unknown>;
+      contractJsonPathForSnapshot = endContractPath;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -157,6 +167,39 @@ async function executeDbUpdateCommand(
       return notOk(mapDbUpdateFailure(result.failure));
     }
 
+    const advancementHash =
+      result.value.mode === 'apply'
+        ? (result.value.marker?.storageHash ?? result.value.destination.storageHash)
+        : result.value.destination.storageHash;
+
+    let refAdvancementFields: RefAdvancementFields = {
+      advancedRef: null,
+      plannedAdvanceRef: null,
+    };
+    if (
+      computeRefAdvancementName({
+        ...ifDefined('advanceRef', options.advanceRef),
+        ...ifDefined('db', options.db),
+      }) !== null
+    ) {
+      try {
+        const contractIR = await readContractIR(contractJson, contractJsonPathForSnapshot);
+        refAdvancementFields = await buildRefAdvancementFields({
+          ...ifDefined('advanceRef', options.advanceRef),
+          ...ifDefined('db', options.db),
+          refsDir,
+          contractIR,
+          mode: result.value.mode,
+          hash: advancementHash,
+        });
+      } catch (error) {
+        if (MigrationToolsError.is(error)) {
+          return notOk(mapMigrationToolsError(error));
+        }
+        throw error;
+      }
+    }
+
     // Convert success result to CLI output format
     const dbUpdateResult: MigrationCommandResult = {
       ok: true,
@@ -193,6 +236,8 @@ async function executeDbUpdateCommand(
           : undefined,
       ),
       ...ifDefined('perSpace', result.value.perSpace),
+      advancedRef: refAdvancementFields.advancedRef,
+      plannedAdvanceRef: refAdvancementFields.plannedAdvanceRef,
       summary: result.value.summary,
       timings: { total: Date.now() - startTime },
     };
@@ -245,6 +290,7 @@ export function createDbUpdateCommand(): Command {
     '--to <contract>',
     'Target contract reference (hash, prefix, ref name, migration dir name, <dir>^, or ./path)',
   );
+  command.option('--advance-ref <name>', 'Ref to advance to the post-command contract hash');
   command.action(async (options: DbUpdateOptions) => {
     const flags = parseGlobalFlagsOrExit(options);
     const startTime = Date.now();

package/src/commands/init/hygiene-gitattributes.ts

@@ -20,7 +20,7 @@ import type { TargetId } from './templates/code-templates';
  * `db/contract.json linguist-generated` — not the workspace-glob form
  * `<glob>/contract.json` (which would over-match any unrelated
  * `contract.json` the user has elsewhere) and not the absolute
- * `prisma/contract.json` (which would silently break for a non-default
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json` (which would silently break for a non-default
  * schema path).
  */
 const ARTEFACT_FILENAMES: readonly string[] = [
@@ -59,7 +59,7 @@ export function requiredGitattributesLines(
  *
  * Equivalence is exact-line: a user-customised line like
  * `prisma/*.json linguist-generated` is *not* recognised as covering
- * `prisma/contract.json linguist-generated`. We accept that
+ * `DEFAULT_CONTRACT_SOURCE_DIR/contract.json linguist-generated`. We accept that
  * over-specification — preserving the user's broad pattern *and*
  * appending the narrow one — because the narrow lines are what the
  * acceptance criteria pin (FR3.4 AC).

package/src/commands/init/index.ts

@@ -15,6 +15,7 @@ import {
   INIT_EXIT_SKILL_INSTALL_FAILED,
   INIT_EXIT_USER_ABORTED,
 } from './exit-codes';
+import { defaultSchemaPath } from './templates/code-templates';
 
 /**
  * Commander.js parsed options for `init`. The init-specific options live
@@ -72,7 +73,7 @@ export function createInitCommand(): Command {
     .option('--authoring <style>', 'Schema authoring style: psl or typescript')
     .option(
       '--schema-path <path>',
-      'Where to write the starter schema (default: prisma/contract.prisma)',
+      `Where to write the starter schema (default: ${defaultSchemaPath('psl')})`,
     )
     .option('--force', 'Overwrite an existing scaffold without prompting')
     .option(

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

@@ -1,3 +1,5 @@
+import { DEFAULT_CONTRACT_SOURCE_DIR } from '@prisma-next/config/config-types';
+
 export type TargetId = 'postgres' | 'mongo';
 export type AuthoringId = 'psl' | 'typescript';
 
@@ -11,9 +13,9 @@ export function targetLabel(target: TargetId): string {
 
 export function defaultSchemaPath(authoring: AuthoringId): string {
   if (authoring === 'typescript') {
-    return 'prisma/contract.ts';
+    return `${DEFAULT_CONTRACT_SOURCE_DIR}/contract.ts`;
   }
-  return 'prisma/contract.prisma';
+  return `${DEFAULT_CONTRACT_SOURCE_DIR}/contract.prisma`;
 }
 
 export function starterSchema(target: TargetId, authoring: AuthoringId): string {

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

@@ -1,7 +1,7 @@
 import type { TargetId } from './code-templates';
 
 /**
- * The minimum supported server version for each target (FR8.1). The
+ * The minimum supported server version for each target. The
  * authoritative source of truth is each target package's
  * `package.json#prismaNext.minServerVersion` field — this module
  * mirrors those values and a workspace-level test asserts the two
@@ -9,13 +9,13 @@ import type { TargetId } from './code-templates';
  *
  * Bumping a value here in isolation is **not** safe: edit the
  * corresponding target package's `package.json` first, then mirror
- * here. The scaffold's `.env.example` (FR3.1, FR8.2) and the
- * "Requirements" section of `prisma-next.md` both read from this
- * constant, so a stale value lies to every freshly initialised user.
+ * here. The scaffold's `.env.example` and the "Requirements" section
+ * of `prisma-next.md` both read from this constant, so a stale value
+ * lies to every freshly initialised user.
  */
 export const MIN_SERVER_VERSION: Record<TargetId, string> = {
-  postgres: '14',
-  mongo: '6.0',
+  postgres: '17',
+  mongo: '8.0',
 };
 
 export const TARGET_LABEL: Record<TargetId, string> = {
@@ -41,7 +41,7 @@ function envPlaceholderBody(target: TargetId): string {
     lines.push('DATABASE_URL="postgresql://user:password@localhost:5432/mydb"');
   } else {
     lines.push(
-      '# Standalone local mongod / `docker run mongo:7` — no replica set required for first-run queries.',
+      '# Standalone local mongod / `docker run mongo:8` — no replica set required for first-run queries.',
     );
     lines.push(
       '# Transactions and change streams need a replica set; add ?replicaSet=... only after initiating one.',
@@ -54,7 +54,7 @@ function envPlaceholderBody(target: TargetId): string {
 }
 
 /**
- * Renders the `.env.example` content for a given target (FR3.1):
+ * Renders the `.env.example` content for a given target:
  *
  * - Carries a "Copy this file to `.env`…" intro that only makes sense
  *   for the example file (the real `.env` is the destination of that
@@ -63,8 +63,7 @@ function envPlaceholderBody(target: TargetId): string {
  *   shape (Postgres: standard `postgresql://`, Mongo: `mongodb://` plus
  *   a `mydb` database segment so the lazy facade has a `dbName`).
  * - Carries a `# Requires <db> >= <version>` comment so a fresh user
- *   knows the minimum supported server before they first try to
- *   connect (FR8.2).
+ *   knows the minimum supported server before they first try to connect.
  */
 export function envExampleContent(target: TargetId): string {
   const lines: string[] = [];
@@ -77,10 +76,10 @@ export function envExampleContent(target: TargetId): string {
 
 /**
  * Renders the initial `.env` content for `--write-env` / interactive
- * opt-in (FR3.2). Same placeholder body as `.env.example`, **without**
- * the example file's "Copy this file to `.env`…" intro: the real `.env`
- * is the destination of that copy, so the line would lie. Writing this
- * file is gitignored (FR3.3 ensures `.env` lands in `.gitignore`).
+ * opt-in. Same placeholder body as `.env.example`, **without** the
+ * example file's "Copy this file to `.env`…" intro: the real `.env` is
+ * the destination of that copy, so the line would lie. Writing this
+ * file is gitignored (`.env` lands in `.gitignore` during init).
  */
 export function envFileContent(target: TargetId): string {
   return envPlaceholderBody(target);

package/src/commands/migrate.ts

@@ -2,19 +2,18 @@ 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 { loadConfig } from '../config-loader';
 import { createControlClient } from '../control-api/client';
 import type {
-  AggregatePerSpaceExecutionEntry,
   MigrationApplyFailure,
   MigrationApplyPathDecision,
+  PerSpaceExecutionEntry,
 } from '../control-api/types';
 import {
   CliStructuredError,
@@ -23,6 +22,8 @@ import {
   errorDatabaseConnectionRequired,
   errorDriverRequired,
   errorFileNotFound,
+  errorMarkerMismatch,
+  errorPathUnreachable,
   errorRuntime,
   errorTargetMigrationNotSupported,
   errorUnexpected,
@@ -32,7 +33,6 @@ import {
 import {
   addGlobalOptions,
   collectDeclaredInvariants,
-  loadMigrationPackages,
   maskConnectionUrl,
   resolveContractPath,
   resolveMigrationPaths,
@@ -40,10 +40,17 @@ import {
   setCommandExamples,
   targetSupportsMigrations,
 } from '../utils/command-helpers';
+import { mapContractAtError } from '../utils/contract-at-errors';
+import {
+  loadContractSpaceAggregateForCli,
+  refuseContractSpaceIntegrity,
+} from '../utils/contract-space-aggregate-loader';
+import { toDeclaredExtensionsFromRaw } from '../utils/extension-pack-inputs';
 import { formatMigrationApplyCommandOutput } from '../utils/formatters/migrations';
 import { formatStyledHeader } from '../utils/formatters/styled';
 import type { CommonCommandOptions } 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 { createTerminalUI, type TerminalUI } from '../utils/terminal-ui';
 
@@ -51,6 +58,7 @@ interface MigrateCommandOptions extends CommonCommandOptions {
   readonly db?: string;
   readonly config?: string;
   readonly to?: string;
+  readonly advanceRef?: string;
 }
 
 export interface MigrateResult {
@@ -67,14 +75,18 @@ export interface MigrateResult {
     readonly operationsExecuted: number;
   }[];
   readonly summary: string;
-  readonly perSpace: readonly AggregatePerSpaceExecutionEntry[];
+  readonly perSpace: readonly PerSpaceExecutionEntry[];
   readonly pathDecision?: MigrationApplyPathDecision;
   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.',
@@ -89,8 +101,10 @@ async function executeMigrateCommand(
   startTime: number,
 ): Promise<Result<MigrateResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, appMigrationsDir, appMigrationsRelative, refsDir } =
-    resolveMigrationPaths(options.config, config);
+  const { configPath, migrationsDir, appMigrationsRelative, refsDir } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
 
   const dbConnection = options.db ?? config.db?.connection;
   if (!dbConnection) {
@@ -118,31 +132,8 @@ async function executeMigrateCommand(
     );
   }
 
-  let refEntry: RefEntry | undefined;
   const toArg = options.to;
 
-  if (toArg) {
-    try {
-      const refs = await readRefs(refsDir);
-      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));
-      }
-      throw error;
-    }
-  }
-
   // Construct the family instance up-front so the on-disk contract read
   // crosses the serializer seam (`familyInstance.deserializeContract`) at
   // the read site. The downstream `client.migrationApply({ contract })`
@@ -184,6 +175,44 @@ async function executeMigrateCommand(
     );
   }
 
+  const loadedAggregate = await loadContractSpaceAggregateForCli({
+    targetId: config.target.targetId,
+    migrationsDir,
+    appContract: contractRaw,
+    extensionPacks: config.extensionPacks ?? [],
+    deserializeContract: (json) => familyInstance.deserializeContract(json),
+  });
+  if (!loadedAggregate.ok) {
+    return notOk(loadedAggregate.failure);
+  }
+  const aggregate = loadedAggregate.value;
+  const integrityFailure = refuseContractSpaceIntegrity(aggregate, {
+    declaredExtensions: toDeclaredExtensionsFromRaw(
+      (config.extensionPacks ?? []) as ReadonlyArray<unknown>,
+    ),
+    checkContracts: true,
+  });
+  if (integrityFailure) {
+    return notOk(integrityFailure);
+  }
+
+  let refEntry: RefEntry | undefined;
+  let refName: string | undefined;
+  if (toArg) {
+    const refs = aggregate.app.refs;
+    const refResult = parseContractRef(toArg, { graph: aggregate.app.graph(), refs });
+    if (!refResult.ok) {
+      return notOk(mapRefResolutionError(refResult.failure));
+    }
+    if (refResult.value.provenance.kind === 'ref') {
+      refName = refResult.value.provenance.refName;
+      const resolved = refs[refName];
+      if (resolved) refEntry = resolved;
+    } else {
+      refEntry = { hash: refResult.value.hash, invariants: [] };
+    }
+  }
+
   if (!flags.json && !flags.quiet) {
     const details: Array<{ label: string; value: string }> = [
       { label: 'config', value: configPath },
@@ -208,15 +237,7 @@ async function executeMigrateCommand(
     ui.stderr(header);
   }
 
-  let appPackages: Awaited<ReturnType<typeof loadMigrationPackages>>;
-  try {
-    appPackages = await loadMigrationPackages(appMigrationsDir);
-  } catch (error) {
-    if (MigrationToolsError.is(error)) {
-      return notOk(mapMigrationToolsError(error));
-    }
-    throw error;
-  }
+  const appGraph = aggregate.app.graph();
 
   const client = createControlClient({
     family: config.family,
@@ -229,10 +250,21 @@ async function executeMigrateCommand(
   try {
     await client.connect(dbConnection);
 
+    const allMarkers = await client.readAllMarkers();
+    const appMarker = allMarkers.get('app') ?? null;
+
+    if (appMarker !== null && !isGraphNode(appMarker.storageHash, appGraph)) {
+      return notOk(
+        errorMarkerMismatch(
+          appMarker.storageHash,
+          [...appGraph.nodes].sort(),
+          findLatestMigration(appGraph)?.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 declared = collectDeclaredInvariants(appGraph);
       const known = new Set<string>(declared);
       for (const id of appMarker?.invariants ?? []) known.add(id);
       const unknown = refEntry.invariants.filter((id) => !known.has(id));
@@ -253,10 +285,36 @@ async function executeMigrateCommand(
       ui.step('Loading contract spaces…');
     }
 
+    // When `--to` resolves to an on-disk graph node with a matching bundle,
+    // verify and apply against THAT bundle's destination contract via
+    // `contractAt` — not the emitted `contract.json`. With `--to` omitted,
+    // or a target with no matching bundle, the emitted contract stays the
+    // apply contract (the only migrate-specific default). The same
+    // `contractAt` artifacts feed the optional ref-advancement snapshot.
+    let applyContract: Contract = contractRaw;
+    let snapshotContractJson: Record<string, unknown> = JSON.parse(contractContent);
+    let snapshotContractDts: string | undefined;
+    if (toArg && refEntry) {
+      const targetHash = refEntry.hash;
+      const matchingBundle = aggregate.app.packages.find((p) => p.metadata.to === targetHash);
+      if (matchingBundle) {
+        try {
+          const at = await aggregate.app.contractAt(
+            targetHash,
+            refName !== undefined ? { refName } : undefined,
+          );
+          applyContract = at.contract;
+          snapshotContractJson = at.contractJson as Record<string, unknown>;
+          snapshotContractDts = at.contractDts;
+        } catch (error) {
+          return mapContractAtError(error, { artifactRole: 'to' });
+        }
+      }
+    }
+
     const applyResult = await client.migrationApply({
-      contract: contractRaw,
+      contract: applyContract,
       migrationsDir,
-      appMigrationPackages: appPackages.bundles,
       ...ifDefined('refHash', refEntry?.hash),
       ...(refEntry?.invariants ? { refInvariants: refEntry.invariants } : {}),
       ...(refEntry !== undefined ? ifDefined('refName', toArg) : {}),
@@ -268,6 +326,27 @@ async function executeMigrateCommand(
 
     const { value } = applyResult;
 
+    let advancedRef: { name: string; hash: string } | null = null;
+    if (options.advanceRef !== undefined) {
+      try {
+        const contractIR =
+          snapshotContractDts !== undefined
+            ? { contract: snapshotContractJson, contractDts: snapshotContractDts }
+            : await readContractIR(snapshotContractJson, contractPathAbsolute);
+        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 +357,7 @@ async function executeMigrateCommand(
       perSpace: value.perSpace,
       ...ifDefined('pathDecision', value.pathDecision),
       timings: { total: Date.now() - startTime },
+      advancedRef,
     });
   } catch (error) {
     if (CliStructuredError.is(error)) {
@@ -318,6 +398,7 @@ 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 = parseGlobalFlagsOrExit(options);
       const startTime = Date.now();