@prisma-next/cli 0.7.0 → 0.8.0-dev.10

package/src/commands/init/errors.ts

@@ -236,3 +236,35 @@ export function errorInitEmitFailed(options: {
     },
   });
 }
+
+/**
+ * The project-level agent-skill install (`npx skills add
+ * prisma/prisma-next#v<version>`) failed after a successful dependency
+ * install + emit. The project's scaffold remains on disk; the user
+ * can either fix the underlying issue (network, registry, PATH) and
+ * run the install command manually, or re-run `init --no-skill` to
+ * proceed without the skill.
+ *
+ * Non-rolling-back, matching the existing install/emit failure
+ * semantics. Maps to exit code `6 = SKILL_INSTALL_FAILED`.
+ */
+export function errorInitSkillInstallFailed(options: {
+  readonly skillInstallCommand: string;
+  readonly filesWritten: readonly string[];
+  readonly cause: string;
+}): CliStructuredError {
+  return new CliStructuredError('5013', 'Failed to install Prisma Next skills', {
+    domain: 'CLI',
+    why: `\`${options.skillInstallCommand}\` exited with an error: ${options.cause}`,
+    fix:
+      'Either:\n' +
+      `  - Re-run \`prisma-next init --no-skill${options.filesWritten.length > 0 ? ' --force' : ''}\` to skip the skill install for this run, or\n` +
+      `  - Fix the underlying issue (network, npm registry, \`npx skills\` on PATH) and install manually:\n      ${options.skillInstallCommand}`,
+    docsUrl: 'https://prisma-next.dev/docs/cli/init#agent-skill',
+    meta: {
+      filesWritten: options.filesWritten,
+      skillInstallCommand: options.skillInstallCommand,
+      cause: options.cause,
+    },
+  });
+}

package/src/commands/init/exit-codes.ts

@@ -60,3 +60,13 @@ export const INIT_EXIT_INSTALL_FAILED = 4;
  * emit` manually.
  */
 export const INIT_EXIT_EMIT_FAILED = 5;
+
+/**
+ * The project-level Prisma Next skills install (`npx skills add
+ * prisma/prisma-next#v<version>`) failed after a successful dependency
+ * install + emit. The scaffolded project files remain on disk; the
+ * user can fix the underlying issue (network, registry reachability,
+ * `npx skills` not on PATH) and run the install manually, or re-run
+ * `init` with `--no-skill` to skip it.
+ */
+export const INIT_EXIT_SKILL_INSTALL_FAILED = 6;

package/src/commands/init/index.ts

@@ -11,6 +11,7 @@ import {
   INIT_EXIT_INTERNAL_ERROR,
   INIT_EXIT_OK,
   INIT_EXIT_PRECONDITION,
+  INIT_EXIT_SKILL_INSTALL_FAILED,
   INIT_EXIT_USER_ABORTED,
 } from './exit-codes';
 
@@ -33,6 +34,7 @@ interface InitCommandOptions extends CommonCommandOptions {
   readonly probeDb?: boolean;
   readonly strictProbe?: boolean;
   readonly install?: boolean;
+  readonly skill?: boolean;
 }
 
 export function createInitCommand(): Command {
@@ -52,7 +54,8 @@ export function createInitCommand(): Command {
       `  ${INIT_EXIT_PRECONDITION}   PRECONDITION          Bad flags / missing prerequisite (e.g. no package.json).\n` +
       `  ${INIT_EXIT_USER_ABORTED}   USER_ABORTED          User cancelled an interactive prompt.\n` +
       `  ${INIT_EXIT_INSTALL_FAILED}   INSTALL_FAILED        Dependency installation failed (init-specific).\n` +
-      `  ${INIT_EXIT_EMIT_FAILED}   EMIT_FAILED           \`contract emit\` failed after install (init-specific).`,
+      `  ${INIT_EXIT_EMIT_FAILED}   EMIT_FAILED           \`contract emit\` failed after install (init-specific).\n` +
+      `  ${INIT_EXIT_SKILL_INSTALL_FAILED}   SKILL_INSTALL_FAILED  Agent-skill install failed (re-run with --no-skill to skip).`,
   );
   setCommandExamples(command, [
     'prisma-next init',
@@ -60,6 +63,7 @@ export function createInitCommand(): Command {
     'prisma-next init --yes --target mongodb --authoring typescript --json',
     'prisma-next init --yes --force --target postgres --authoring psl  # overwrite an existing scaffold',
     'prisma-next init --no-install                                       # skip pnpm/npm install + emit',
+    'prisma-next init --no-skill                                         # skip the agent-skill install (air-gapped / restricted env)',
   ]);
 
   return addGlobalOptions(command)
@@ -83,6 +87,10 @@ export function createInitCommand(): Command {
       'Treat a failed --probe-db as fatal (no-op without --probe-db; init is offline-by-default)',
     )
     .option('--no-install', 'Skip dependency installation and contract emission')
+    .option(
+      '--no-skill',
+      'Skip Prisma Next skills install (air-gapped CI, restricted registries, etc.)',
+    )
     .action(async (options: InitCommandOptions) => {
       const { runInit } = await import('./init');
       const flags = parseGlobalFlags(options);

package/src/commands/init/init.ts

@@ -7,6 +7,13 @@ import { CliStructuredError } from '../../utils/cli-errors';
 import { formatErrorJson, formatErrorOutput } from '../../utils/formatters/errors';
 import type { GlobalFlags } from '../../utils/global-flags';
 import { TerminalUI } from '../../utils/terminal-ui';
+import {
+  DEFAULT_AGENT_SKILL_SOURCES,
+  formatClaudeSkillInstallCommand,
+  formatSkillInstallCommand,
+  LEGACY_SKILL_FILE,
+  runProjectLevelSkillInstall,
+} from './agent-skill-install';
 import {
   detectPackageManager,
   formatAddArgs,
@@ -29,6 +36,7 @@ import {
   INIT_EXIT_INTERNAL_ERROR,
   INIT_EXIT_OK,
   INIT_EXIT_PRECONDITION,
+  INIT_EXIT_SKILL_INSTALL_FAILED,
   INIT_EXIT_USER_ABORTED,
 } from './exit-codes';
 import { mergeGitattributes, requiredGitattributesLines } from './hygiene-gitattributes';
@@ -48,7 +56,6 @@ import {
 } from './output';
 import { type ProbeOutcome, type ProbeOverrides, probeServerVersion } from './probe-db';
 import { findStaleArtefacts, removeDependency } from './reinit-cleanup';
-import { agentSkillMd } from './templates/agent-skill';
 import { configFile, dbFile, starterSchema, targetPackageName } from './templates/code-templates';
 import { envExampleContent, envFileContent, MIN_SERVER_VERSION } from './templates/env';
 import { quickReferenceMd } from './templates/quick-reference';
@@ -72,6 +79,15 @@ interface InstallReport {
   readonly deps: readonly string[];
   readonly devDeps: readonly string[];
   readonly warnings: readonly string[];
+  /**
+   * The package manager that actually ran. Equal to the detected `pm`
+   * on the common path; differs when the FR7.2 pnpm → npm fallback
+   * fired, in which case it's `'npm'`. Threaded into the agent-skill
+   * install so the runner stays consistent with the install we just
+   * ran — re-trying through `pnpm dlx` when `pnpm install` just failed
+   * for workspace/catalog reasons would fail again for the same reason.
+   */
+  readonly effectivePm: PackageManager;
 }
 
 /**
@@ -156,10 +172,6 @@ export async function runInit(
       path: 'prisma-next.md',
       content: quickReferenceMd(inputs.target, inputs.authoring, inputs.schemaPath, pkgRun),
     },
-    {
-      path: '.agents/skills/prisma-next/SKILL.md',
-      content: agentSkillMd(inputs.target, inputs.authoring, inputs.schemaPath, pkgRun),
-    },
     { path: '.env.example', content: envExampleContent(inputs.target) },
   ];
 
@@ -172,6 +184,14 @@ export async function runInit(
   // and missing-on-disk-at-write-time is tolerated.
   const filesToDelete: string[] = inputs.reinit ? [...findStaleArtefacts(baseDir, schemaDir)] : [];
 
+  // `init` delegates the skill to `npx skills add prisma/prisma-next#v<version>`,
+  // so a hand-rolled `.agents/skills/prisma-next/SKILL.md` in the project
+  // would shadow the published package. Queue it for deletion on every
+  // run (not gated on `--reinit`).
+  if (existsSync(join(baseDir, LEGACY_SKILL_FILE))) {
+    filesToDelete.push(LEGACY_SKILL_FILE);
+  }
+
   // FR3.2: a real `.env` is only written when the user opted in. Never
   // overwrite an existing `.env` — secrets live there and clobbering
   // them is the most damaging possible side-effect of `init`.
@@ -416,6 +436,57 @@ export async function runInit(
     }
   }
 
+  // Agent-skill install. Project-level is unconditional modulo
+  // `--no-skill`. We deliberately do **not** offer a user-level
+  // (global) install path: the skill's behaviour and surface track
+  // the project's Prisma Next version, and a host-wide install would
+  // have to pick a single version for every project on the machine,
+  // which breaks the version-locking invariant the rest of the
+  // framework relies on. A project-level failure is fatal
+  // (`INIT_EXIT_SKILL_INSTALL_FAILED`).
+  //
+  // Runs after install + emit because (1) `node_modules` is in place,
+  // so any consumers downstream are coherent, and (2) the user has
+  // seen the scaffolding succeed before this network-bound step
+  // potentially fails. We skip the install when the user passed
+  // `--no-install` for the same reason — no `node_modules` means the
+  // workspace isn't ready to consume the skill yet anyway.
+  const manualProjectSkillCommands = DEFAULT_AGENT_SKILL_SOURCES.flatMap((source) => [
+    formatSkillInstallCommand(install.effectivePm, source),
+    formatClaudeSkillInstallCommand(install.effectivePm, source),
+  ]);
+  const manualProjectSkillSummary = manualProjectSkillCommands.map((c) => `\`${c}\``).join(' && ');
+  let skillRegistered = false;
+  if (!inputs.installProjectSkill) {
+    warnings.push(
+      `Skipped Prisma Next agent-skill install (--no-skill). To install the skills later, run: ${manualProjectSkillSummary}`,
+    );
+  } else if (install.skipped) {
+    warnings.push(
+      `Skipped Prisma Next agent-skill install because --no-install was passed. After you run install manually, install the skills with: ${manualProjectSkillSummary}`,
+    );
+  } else {
+    const spinner = ui.spinner();
+    spinner.start('Registering Prisma Next skills with the agent runtime...');
+    try {
+      const project = await runProjectLevelSkillInstall({
+        baseDir,
+        pm: install.effectivePm,
+        filesWritten,
+      });
+      spinner.stop(
+        `Registered Prisma Next skills (project level) — ran ${project.commands.map((c) => `\`${c}\``).join(', ')}`,
+      );
+      skillRegistered = true;
+    } catch (error) {
+      spinner.stop('Agent-skill install failed');
+      if (CliStructuredError.is(error)) {
+        return emitError(ui, flags, error);
+      }
+      throw error;
+    }
+  }
+
   const output: InitOutput = {
     ok: true,
     target: inputs.target === 'mongo' ? 'mongodb' : 'postgres',
@@ -434,6 +505,7 @@ export async function runInit(
       contractEmitted,
       emitCommand,
       schemaPath: inputs.schemaPath,
+      skillRegistered,
     }),
     warnings,
   };
@@ -525,6 +597,8 @@ export function exitCodeForError(error: { readonly code: string }): number {
       return INIT_EXIT_EMIT_FAILED;
     case '5009': // invalid output document — internal bug in prisma-next
       return INIT_EXIT_INTERNAL_ERROR;
+    case '5013': // agent-skill install failed
+      return INIT_EXIT_SKILL_INSTALL_FAILED;
     default:
       // Any unexpected code is treated as an internal bug rather than
       // mis-routed to PRECONDITION. Adding a new code requires an
@@ -646,7 +720,7 @@ async function runInstall(ctx: {
         'Manual steps',
       );
     }
-    return { skipped: true, deps: [], devDeps: [], warnings: catalogWarnings };
+    return { skipped: true, deps: [], devDeps: [], warnings: catalogWarnings, effectivePm: pm };
   }
 
   const exec = promisify(execFile);
@@ -661,7 +735,7 @@ async function runInstall(ctx: {
   try {
     await runPair(pm);
     spinner.stop(`Installed ${allPackages}`);
-    return { skipped: false, deps, devDeps, warnings: catalogWarnings };
+    return { skipped: false, deps, devDeps, warnings: catalogWarnings, effectivePm: pm };
   } catch (err) {
     const stderrText = redactSecrets(readChildStderr(err));
 
@@ -693,6 +767,7 @@ async function runInstall(ctx: {
           // catalog-honour warning to avoid a contradictory message
           // pair.
           warnings: [fallbackWarning],
+          effectivePm: 'npm',
         };
       } catch (npmErr) {
         spinner.stop('Installation failed');

package/src/commands/init/inputs.ts

@@ -31,6 +31,13 @@ export interface InitFlagOptions {
   readonly probeDb?: boolean;
   readonly strictProbe?: boolean;
   readonly install?: boolean;
+  /**
+   * `--no-skill` — skip the project-level skill install entirely.
+   * Documented escape hatch for air-gapped CI, restricted registries,
+   * and any environment where `npx skills` is
+   * not reachable.
+   */
+  readonly skill?: boolean;
 }
 
 /**
@@ -61,6 +68,14 @@ export interface ResolvedInitInputs {
    * is added separately via the install step.
    */
   readonly removePreviousFacade: string | null;
+  /**
+   * Whether to run `npx skills add prisma/prisma-next#v<version>` at the
+   * project level after install + emit. True by default; `--no-skill`
+   * sets it to `false`. The skill is always project-level (never
+   * user-level / global) so its version stays locked to the project's
+   * Prisma Next version — see `agent-skill-install.ts`.
+   */
+  readonly installProjectSkill: boolean;
 }
 
 const TARGET_ALIASES: ReadonlyMap<string, TargetId> = new Map([
@@ -161,6 +176,13 @@ export async function resolveInitInputs(ctx: {
     autoAcceptPrompts,
   });
 
+  // Skill-install gating. `--no-skill` (commander parses
+  // `options.skill === false`) is the only escape hatch; otherwise
+  // project-level install is unconditional. The skill is always
+  // installed at the project level so its version tracks the
+  // project's Prisma Next release.
+  const installProjectSkill = options.skill !== false;
+
   return {
     target: finalTarget,
     authoring: finalAuthoring,
@@ -171,6 +193,7 @@ export async function resolveInitInputs(ctx: {
     strictProbe: Boolean(options.strictProbe),
     reinit,
     removePreviousFacade,
+    installProjectSkill,
   };
 }
 

package/src/commands/init/output.ts

@@ -120,27 +120,32 @@ export function buildNextSteps(options: {
   readonly contractEmitted: boolean;
   readonly emitCommand: string;
   readonly schemaPath: string;
+  /**
+   * Whether the project-level Prisma Next skills install actually ran
+   * and succeeded during this `init`. When false (the user passed
+   * `--no-skill` or `--no-install`, so the install was skipped), the
+   * "registered with your agent runtime" step is omitted — the skip is
+   * already surfaced in the warnings array with a manual-install hint.
+   */
+  readonly skillRegistered: boolean;
 }): string[] {
   const steps: string[] = [];
-  steps.push('1. Set DATABASE_URL in your environment (export it or add it to .env).');
+  let stepNumber = 1;
+  const push = (text: string): void => {
+    steps.push(`${stepNumber}. ${text}`);
+    stepNumber += 1;
+  };
+  push('Set DATABASE_URL in your environment (export it or add it to .env).');
   if (!options.contractEmitted) {
-    steps.push(`2. Emit the contract: \`${options.emitCommand}\``);
-    steps.push(`3. Edit your schema at ${options.schemaPath}, then re-run the emit command.`);
-    steps.push(
-      '4. Open prisma-next.md for a quick reference on how to write your first typed query.',
-    );
-    steps.push(
-      '5. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',
-    );
+    push(`Emit the contract: \`${options.emitCommand}\``);
+    push(`Edit your schema at ${options.schemaPath}, then re-run the emit command.`);
   } else {
-    steps.push(
-      `2. Edit your schema at ${options.schemaPath}, then re-run \`${options.emitCommand}\`.`,
-    );
-    steps.push(
-      '3. Open prisma-next.md for a quick reference on how to write your first typed query.',
-    );
-    steps.push(
-      '4. The .agents/skills/prisma-next/SKILL.md file is wired up for AI-coding agents in this project.',
+    push(`Edit your schema at ${options.schemaPath}, then re-run \`${options.emitCommand}\`.`);
+  }
+  push('Open prisma-next.md for a quick reference on how to write your first typed query.');
+  if (options.skillRegistered) {
+    push(
+      'Prisma Next skills are registered with your agent runtime — open the project in your IDE and ask the agent to add a model, run a query, or plan a migration.',
     );
   }
   return steps;

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

@@ -253,7 +253,10 @@ export function dbFile(target: TargetId): string {
 import type { Contract } from './contract.d';
 import contractJson from './contract.json' with { type: 'json' };
 
-export const db = postgres<Contract>({ contractJson });
+export const db = postgres<Contract>({
+  contractJson,
+  url: process.env['DATABASE_URL']!,
+});
 `;
   }
 

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;