@prisma-next/cli 0.5.0-dev.25 → 0.5.0-dev.26

package/src/cli.ts

@@ -50,8 +50,18 @@ program.configureOutput({
   writeErr: () => {
     // Suppress all default error output - we handle errors in exitOverride
   },
-  writeOut: () => {
-    // Suppress all default output - our custom formatters handle everything
+  writeOut: (str) => {
+    // Commander routes explicitly-requested `--help` (success-path help)
+    // through writeOut; per the Style Guide § Output Conventions rule 8,
+    // user-requested help is data and goes to stdout. Error-path help
+    // (e.g. usage shown after an unknown command) goes through writeErr,
+    // which stays suppressed because we render that ourselves with the
+    // matching error envelope.
+    //
+    // Explicit `--version` is short-circuited before `program.parse()`
+    // (see the argv pre-scan at the bottom of this file), so it does not
+    // reach this writer.
+    process.stdout.write(str);
   },
 });
 
@@ -261,14 +271,25 @@ const helpCommand = new Command('help')
   .action(() => {
     const flags = parseGlobalFlags({});
     const helpText = formatRootHelp({ program, flags });
-    // Help is decoration → stderr
-    process.stderr.write(`${helpText}\n`);
+    // The `help` command was invoked explicitly: help is the data the
+    // caller asked for. Per Style Guide § Output Conventions rule 8,
+    // explicit help goes to stdout with exit code 0.
+    process.stdout.write(`${helpText}\n`);
     process.exit(0);
   });
 
 program.addCommand(helpCommand);
 
-// Set help as the default action when no command is provided
+// Set help as the default action when no command is provided. The user
+// did not invoke `--help`; we are voluntarily showing usage to help them
+// recover from an underspecified invocation, so the help text is
+// decoration around an implicit "what did you want me to do?" and goes
+// to stderr (Style Guide § Output Conventions rule 8).
+//
+// FOLLOW-UP: the exit code here is 0 today, but a no-arg invocation is
+// arguably a usage error (PRECONDITION → exit 2) for consistency with
+// the unknown-command path. Out of scope for the explicit-help routing
+// work; revisit when tightening exit-code semantics across the CLI.
 program.action(() => {
   const flags = parseGlobalFlags({});
   const helpText = formatRootHelp({ program, flags });
@@ -304,7 +325,12 @@ if (args.length > 0) {
       process.stderr.write(`${helpText}\n`);
       process.exit(2);
     } else if (command.commands.length > 0 && args.length === 1) {
-      // Parent command called with no subcommand - show help and exit with 0
+      // 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
+      // invocation, so it goes to stderr per Style Guide § Output
+      // Conventions rule 8. Exit code 0 today; the FOLLOW-UP note on
+      // `program.action` applies here too (arguably should be 2).
       const flags = parseGlobalFlags({});
       const helpText = formatCommandHelp({ command, flags });
       process.stderr.write(`${helpText}\n`);

package/src/migration-cli.ts

@@ -15,7 +15,8 @@
  * entrypoint (`node migration.ts`), the CLI:
  *
  * 1. Detects whether the file is the direct entrypoint (no-op when imported).
- * 2. Parses CLI args (`--help`, `--dry-run`, `--config <path>`).
+ * 2. Parses CLI args (`--help`, `--dry-run`, `--config <path>`) via
+ *    [clipanion](https://github.com/arcanis/clipanion).
  * 3. Loads the project's `prisma-next.config.ts` via the same `loadConfig`
  *    the CLI commands use, walking up from the migration file's directory.
  * 4. Probe-instantiates the migration class without a stack so it can read
@@ -34,21 +35,27 @@
  * on-disk persistence. `@prisma-next/migration-tools` owns the pure
  * conversion from a `Migration` instance to artifact strings; `Migration`
  * stays a pure abstract class.
+ *
+ * Parser library: clipanion (chosen over Commander/citty/`node:util.parseArgs`
+ * for its in-process testability and runtime-agnostic execution surface; see
+ * `docs/architecture docs/research/commander-friction-points.md` for the
+ * evaluation rubric and the durable rationale that drove the choice).
  */
 
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import type { Writable } from 'node:stream';
 import { fileURLToPath } from 'node:url';
-import { CliStructuredError, errorMigrationCliInvalidConfigArg } from '@prisma-next/errors/control';
+import {
+  CliStructuredError,
+  errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
+} from '@prisma-next/errors/control';
 import { errorMigrationTargetMismatch } from '@prisma-next/errors/migration';
 import { createControlStack } from '@prisma-next/framework-components/control';
 import { errorInvalidJson, MigrationToolsError } from '@prisma-next/migration-tools/errors';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
-import {
-  buildMigrationArtifacts,
-  isDirectEntrypoint,
-  type Migration,
-  printMigrationHelp,
-} from '@prisma-next/migration-tools/migration';
+import { buildMigrationArtifacts, type Migration } from '@prisma-next/migration-tools/migration';
+import { Cli, Command, Option, UsageError } from 'clipanion';
 import { dirname, join } from 'pathe';
 import { loadConfig } from './config-loader';
 
@@ -70,54 +77,75 @@ import { loadConfig } from './config-loader';
 // biome-ignore lint/suspicious/noExplicitAny: see JSDoc - rest args with any are the idiomatic TS pattern for accepting arbitrary subclass constructor signatures
 export type MigrationConstructor = new (...args: any[]) => Migration;
 
-interface ParsedArgs {
-  readonly help: boolean;
-  readonly dryRun: boolean;
-  readonly configPath: string | undefined;
-}
-
 /**
- * Parse the subset of `process.argv` that `MigrationCLI.run` cares about.
- * Recognised flags: `--help`, `--dry-run`, `--config <path>` /
- * `--config=<path>`. Unknown flags are ignored to keep the surface
- * forgiving for ad-hoc tooling that wraps a migration file.
+ * Stream surface accepted by `MigrationCLI.run`'s `options.stdout` /
+ * `options.stderr`. Aliases node's `Writable` because clipanion's
+ * `BaseContext.stdout`/`stderr` are typed as `Writable`, and the CLI
+ * forwards the injected streams into clipanion's context.
  *
- * Throws `errorMigrationCliInvalidConfigArg` (`PN-CLI-4012`) when
- * `--config` is missing its path argument or is followed by another flag
- * (e.g. `--config --dry-run`); silently consuming the next flag would
- * either drop dry-run handling or serialize against the wrong project.
+ * `process.stdout` and `process.stderr` are `Writable`-shaped, so the
+ * default-fallback path remains a no-op for existing two-argument
+ * callers like `MigrationCLI.run(import.meta.url, MyMigration)`.
  *
- * NOTE: this hand-rolled parser is a known wart, tracked separately by
- * TML-2318 ("Migration CLI: replace handrolled arg parser with shared
- * CLI library"). Until that lands the surface is intentionally tiny.
+ * Tests inject a `Writable` subclass that captures chunks for
+ * assertions.
  */
-function parseArgs(argv: readonly string[]): ParsedArgs {
-  let help = false;
-  let dryRun = false;
-  let configPath: string | undefined;
-
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i]!;
-    if (arg === '--help' || arg === '-h') {
-      help = true;
-    } else if (arg === '--dry-run') {
-      dryRun = true;
-    } else if (arg === '--config') {
-      const next = argv[i + 1];
-      if (next === undefined) {
-        throw errorMigrationCliInvalidConfigArg();
-      }
-      if (next.startsWith('-')) {
-        throw errorMigrationCliInvalidConfigArg({ nextToken: next });
-      }
-      configPath = next;
-      i++;
-    } else if (arg.startsWith('--config=')) {
-      configPath = arg.slice('--config='.length);
-    }
-  }
+export type MigrationCliWritable = Writable;
 
-  return { help, dryRun, configPath };
+/**
+ * Flags exposed by the migration-file CLI.
+ *
+ * Must stay in sync with the `Option` declarations on
+ * `MigrationFileCommand` below. This list is rendered in the
+ * `errorMigrationCliUnknownFlag` envelope's `fix` text and `meta`,
+ * so order matters for user-visible output (declaration order is the
+ * order users see when they run `--help`).
+ */
+const KNOWN_FLAGS: readonly string[] = ['--help', '--dry-run', '--config'];
+
+/**
+ * The clipanion command that owns the migration-file CLI's option
+ * declarations. The class is internal — `MigrationCLI.run` is the
+ * stable public surface. Adding a flag here automatically updates
+ * `--help` rendering and the `KNOWN_FLAGS` list (the latter must be
+ * updated in tandem).
+ */
+class MigrationFileCommand extends Command {
+  static override paths = [Command.Default];
+
+  static override usage = Command.Usage({
+    description: 'Self-emit ops.json and migration.json from a class-flow migration',
+    details: `
+      Loads the project's prisma-next.config.ts, assembles a ControlStack
+      from the configured target/adapter/extensions, and serializes the
+      migration's operations + metadata next to this file.
+    `,
+    examples: [
+      ['Self-emit ops.json + migration.json next to migration.ts', '$0'],
+      ['Preview without writing files', '$0 --dry-run'],
+      ['Use a non-default config path', '$0 --config ./custom.config.ts'],
+    ],
+  });
+
+  dryRun = Option.Boolean('--dry-run', false, {
+    description: 'Print operations to stdout without writing files',
+  });
+
+  config = Option.String('--config', {
+    description: 'Path to prisma-next.config.ts',
+  });
+
+  /**
+   * Unused: orchestration runs inside `MigrationCLI.run` so error
+   * routing stays under our control (clipanion's `cli.run` writes
+   * error output to `context.stdout`, but our contract requires
+   * structured errors on stderr). `cli.process` is used to parse
+   * argv into a populated `MigrationFileCommand` instance whose
+   * fields drive the orchestration directly.
+   */
+  override async execute(): Promise<number> {
+    return 0;
+  }
 }
 
 /**
@@ -135,66 +163,297 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
 // biome-ignore lint/complexity/noStaticOnlyClass: see JSDoc - intentional class facade for the migration-file CLI surface; future methods will share state derived from argv/config.
 export class MigrationCLI {
   /**
-   * Orchestrates a class-flow `migration.ts` script run. Awaitable:
-   * callers may `await MigrationCLI.run(...)` to surface async failures
-   * from config loading, but the typical usage pattern (top-level call
-   * after the class definition) does not require awaiting because
-   * node's module evaluation keeps the promise alive until completion.
+   * Orchestrates a class-flow `migration.ts` script run.
+   *
+   * The third argument is the in-process testability surface: callers
+   * (and tests) may inject `argv`, `stdout`, and `stderr` instead of
+   * relying on `process.argv` / `process.stdout` / `process.stderr`.
+   * Each option defaults to its `process` global when omitted, so
+   * existing two-argument call sites
+   * (`MigrationCLI.run(import.meta.url, MyMigration)`) continue to
+   * compile and behave identically.
+   *
+   * Returns the exit code so the caller can branch on it. Also writes
+   * the same code to `process.exitCode` so script-style callers that
+   * don't await the return value still surface a non-zero exit when
+   * something fails.
    *
-   * Any throwable inside this function must surface through the internal
-   * try/catch — script callers do not await, so an unhandled rejection
-   * would silently exit 0. Treat the try/catch as load-bearing for the
-   * no-await usage pattern.
+   * Exit codes:
+   * - 0 — success, or `--help`, or imported-not-entrypoint no-op.
+   * - 1 — runtime/orchestration error (config not found, target
+   *   mismatch, etc.).
+   * - 2 — usage error (unknown flag, malformed `--config`). Aligns
+   *   with `docs/CLI Style Guide.md` § Exit Codes.
    */
-  static async run(importMetaUrl: string, MigrationClass: MigrationConstructor): Promise<void> {
-    if (!importMetaUrl) return;
-    if (!isDirectEntrypoint(importMetaUrl)) return;
+  static async run(
+    importMetaUrl: string,
+    MigrationClass: MigrationConstructor,
+    options: {
+      readonly argv?: readonly string[];
+      readonly stdout?: MigrationCliWritable;
+      readonly stderr?: MigrationCliWritable;
+    } = {},
+  ): Promise<number> {
+    if (!importMetaUrl) {
+      return 0;
+    }
 
-    try {
-      const args = parseArgs(process.argv.slice(2));
+    const argv = options.argv ?? process.argv;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
 
-      if (args.help) {
-        printMigrationHelp();
-        return;
-      }
+    if (!isDirectEntrypoint(importMetaUrl, argv)) {
+      return 0;
+    }
 
-      const migrationFile = fileURLToPath(importMetaUrl);
-      const migrationDir = dirname(migrationFile);
-
-      const config = await loadConfig(args.configPath);
-
-      // Probe-instantiate without a stack so we can read `targetId` before
-      // any target-specific constructor side effects (e.g.
-      // `PostgresMigration`'s `stack.adapter.create(stack)`) run. Concrete
-      // subclasses are required to accept the no-arg form; the abstract
-      // `Migration` constructor declares `stack?` and target subclasses
-      // (Postgres, Mongo) propagate that optionality. This makes the
-      // target-mismatch guard fail fast with `PN-MIG-2006` before any
-      // stack-driven adapter construction begins, even if the wrong-target
-      // adapter's `create` would otherwise succeed and silently misshapen
-      // the stored adapter cast.
-      const probe = new MigrationClass();
-
-      if (probe.targetId !== config.target.targetId) {
-        throw errorMigrationTargetMismatch({
-          migrationTargetId: probe.targetId,
-          configTargetId: config.target.targetId,
-        });
-      }
+    const exitCode = await orchestrate(importMetaUrl, MigrationClass, {
+      argv,
+      stdout,
+      stderr,
+    });
+    // Preserve any pre-existing non-zero `process.exitCode` set by code
+    // running alongside `MigrationCLI.run` (an unhandled rejection
+    // upstream, an explicit `process.exitCode = N` from another
+    // module). Overwriting it with our success would mask the upstream
+    // failure for script-style callers that don't await the return
+    // value. Failures we return here are still surfaced — non-zero
+    // codes always win over the prior status — but successes never
+    // clear it.
+    if (exitCode !== 0 || !process.exitCode) {
+      process.exitCode = exitCode;
+    }
+    return exitCode;
+  }
+}
+
+/**
+ * Argv-aware variant of the entrypoint guard. The shared
+ * `@prisma-next/migration-tools` helper of the same name reads
+ * `process.argv[1]` directly, which doesn't compose with the new
+ * in-process testability surface (tests inject `argv` without mutating
+ * the process global). Inlined here so the migration-file CLI's check
+ * follows the injected `argv[1]` consistently.
+ */
+function isDirectEntrypoint(importMetaUrl: string, argv: readonly string[]): boolean {
+  const argv1 = argv[1];
+  if (!argv1) {
+    return false;
+  }
+  try {
+    return realpathSync(fileURLToPath(importMetaUrl)) === realpathSync(argv1);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Argv-and-stream-driven orchestration body. Pulled out of the static
+ * method so the entrypoint guard / process-default plumbing stays
+ * separate from the parse + load + serialize steps.
+ */
+async function orchestrate(
+  importMetaUrl: string,
+  MigrationClass: MigrationConstructor,
+  ctx: {
+    readonly argv: readonly string[];
+    readonly stdout: MigrationCliWritable;
+    readonly stderr: MigrationCliWritable;
+  },
+): Promise<number> {
+  const cli = Cli.from([MigrationFileCommand], {
+    binaryName: 'migration.ts',
+    binaryLabel: 'Migration file CLI',
+  });
 
-      const stack = createControlStack(config);
-      const instance = new MigrationClass(stack);
+  const input = ctx.argv.slice(2);
+
+  // Pre-scan for malformed `--config` (no value, or value-shaped-as-flag)
+  // before delegating to clipanion. The legacy parser surfaced both as
+  // `errorMigrationCliInvalidConfigArg` (`PN-CLI-4012`); pre-scanning
+  // here keeps that contract independent of how clipanion classifies
+  // the error internally (it variably throws `UnknownSyntaxError` or
+  // accepts the flag-shaped token as the value depending on what other
+  // options are registered).
+  const configError = detectInvalidConfig(input);
+  if (configError) {
+    writeStructuredError(ctx.stderr, configError);
+    return 2;
+  }
+
+  let parsed: MigrationFileCommand;
+  try {
+    const command = cli.process({
+      input: [...input],
+      context: { stdout: ctx.stdout, stderr: ctx.stderr },
+    });
+    if (!(command instanceof MigrationFileCommand)) {
+      // The only registered command class is `MigrationFileCommand`;
+      // any other concrete type indicates clipanion emitted its
+      // built-in `HelpCommand`. Render usage directly so we don't
+      // depend on calling `cli.run` (which routes errors to stdout —
+      // wrong stream for our contract).
+      ctx.stdout.write(cli.usage(MigrationFileCommand, { detailed: true }));
+      return 0;
+    }
+    parsed = command;
+  } catch (err) {
+    return renderParseError(err, input, ctx.stderr);
+  }
 
-      serializeMigrationToDisk(instance, migrationDir, args.dryRun);
-    } catch (err) {
-      if (CliStructuredError.is(err) || MigrationToolsError.is(err)) {
-        process.stderr.write(`${err.message}: ${err.why}\n`);
-      } else {
-        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+  if (parsed.help) {
+    ctx.stdout.write(cli.usage(MigrationFileCommand, { detailed: true }));
+    return 0;
+  }
+
+  try {
+    await runMigration(importMetaUrl, MigrationClass, parsed, ctx);
+    return 0;
+  } catch (err) {
+    if (CliStructuredError.is(err)) {
+      writeStructuredError(ctx.stderr, err);
+    } else if (MigrationToolsError.is(err)) {
+      // Migration-tools errors (e.g. `errorInvalidJson` thrown by
+      // `readExistingMetadata` when migration.json is malformed) carry
+      // their own `code`/`why`/`fix` shape. Render them with the same
+      // visual structure as `CliStructuredError` so consumers grepping
+      // for `MIGRATION.<CODE>` see consistent output across surfaces.
+      const fix = err.fix ? `\n${err.fix}` : '';
+      ctx.stderr.write(`${err.code}: ${err.message}\n${err.why}${fix}\n`);
+    } else {
+      ctx.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    }
+    return 1;
+  }
+}
+
+/**
+ * Returns an `errorMigrationCliInvalidConfigArg` envelope when `input`
+ * contains a malformed `--config`:
+ *
+ * - `--config` as the last token (no value follows).
+ * - `--config <flag>` where `<flag>` starts with `-` (silently
+ *   consuming the next flag would either drop the flag or serialize
+ *   against the wrong project).
+ * - `--config <empty>` where the value is the empty string. Shells
+ *   expand `--config ""` (or `--config "$UNSET_VAR"`) into a real
+ *   empty argv token; treating that as a usage error here surfaces
+ *   `PN-CLI-4012` instead of a less actionable loader error on an
+ *   empty path.
+ * - `--config=` (the equals form with an empty value). Same shape as
+ *   the empty-string case above; the user expressed intent to override
+ *   the config path but the override is empty.
+ *
+ * `--config=<value>` and `--config <value>` with a non-empty value are
+ * both valid (and the equals form's value is allowed to start with
+ * `-` — the `=` makes the binding explicit).
+ */
+function detectInvalidConfig(input: readonly string[]): CliStructuredError | null {
+  for (let i = 0; i < input.length; i++) {
+    const token = input[i];
+    if (token === '--config') {
+      const next = input[i + 1];
+      if (next === undefined || next === '') {
+        return errorMigrationCliInvalidConfigArg();
+      }
+      if (next.startsWith('-')) {
+        return errorMigrationCliInvalidConfigArg({ nextToken: next });
       }
-      process.exitCode = 1;
+      continue;
+    }
+    if (token === '--config=') {
+      return errorMigrationCliInvalidConfigArg();
+    }
+  }
+  return null;
+}
+
+/**
+ * Translate clipanion's parse-time errors into the project's structured
+ * error envelopes.
+ *
+ * - `UnknownSyntaxError` covers both unknown flags (`--frobnicate`) and
+ *   the bare-trailing `--config` case (where arity-1 needs a value but
+ *   none was supplied). Distinguished by inspecting the input array.
+ * - `UsageError` covers schema/validator failures from typanion. None
+ *   of the migration-file CLI's options have validators today, but we
+ *   still translate it as a usage error (exit 2) for forward-compat.
+ * - Anything else re-throws — caller's outer catch will surface it as
+ *   exit 1 (runtime error).
+ */
+function renderParseError(
+  err: unknown,
+  input: readonly string[],
+  stderr: MigrationCliWritable,
+): number {
+  if (isUnknownSyntaxError(err)) {
+    const flag = findOffendingFlag(input);
+    writeStructuredError(stderr, errorMigrationCliUnknownFlag({ flag, knownFlags: KNOWN_FLAGS }));
+    return 2;
+  }
+  if (err instanceof UsageError) {
+    // typanion validator failures and similar usage errors. None of
+    // the migration-file CLI's options have validators today, so this
+    // branch is forward-compat scaffolding — kept so that a future
+    // option declaration with a validator routes through the same PN
+    // envelope path rather than escaping as exit 1.
+    writeStructuredError(stderr, errorMigrationCliInvalidConfigArg({ nextToken: err.message }));
+    return 2;
+  }
+  throw err;
+}
+
+/**
+ * Duck-type check for clipanion's `UnknownSyntaxError`: the class is
+ * thrown by the parser but is not re-exported from the package's main
+ * entry (only `UsageError` is — see clipanion's `advanced/index.d.ts`).
+ * Identified by `name === 'UnknownSyntaxError'` and the
+ * `clipanion.type === 'none'` discriminator that clipanion's
+ * `ErrorWithMeta` interface guarantees.
+ */
+function isUnknownSyntaxError(err: unknown): err is Error {
+  if (!(err instanceof Error) || err.name !== 'UnknownSyntaxError') {
+    return false;
+  }
+  // clipanion's `ErrorWithMeta` interface guarantees a `clipanion` field with
+  // a `type` discriminator on every error it throws. Read it via a structural
+  // shape rather than importing the class (it's not re-exported from the
+  // package main).
+  const meta = (err as { clipanion?: { type?: string } }).clipanion;
+  return typeof meta === 'object' && meta !== null && meta.type === 'none';
+}
+
+/**
+ * Best-effort: pull the first input token that doesn't match a known
+ * flag. Falls back to the first token when we can't pinpoint it. The
+ * returned name is rendered into the user-visible PN-CLI-4013 envelope
+ * (`Unknown flag \`<name>\``) and round-tripped via `meta.flag` so
+ * agent consumers can render their own "did you mean" suggestions.
+ */
+function findOffendingFlag(input: readonly string[]): string {
+  for (const token of input) {
+    if (!token.startsWith('-')) {
+      continue;
+    }
+    const head = token.split('=', 1)[0] ?? token;
+    if (!KNOWN_FLAGS.includes(head) && head !== '-h') {
+      return head;
     }
   }
+  return input[0] ?? '';
+}
+
+/**
+ * Write a `CliStructuredError` envelope to the given stream. Format
+ * matches the legacy hand-rolled writer (`message: why`) so the rest of
+ * the project's error rendering stays consistent across surfaces. The
+ * full PN code (`PN-<domain>-<code>`) is included so consumers can
+ * grep for stable identifiers.
+ */
+function writeStructuredError(stream: MigrationCliWritable, err: CliStructuredError): void {
+  const envelope = err.toEnvelope();
+  const why = envelope.why ?? envelope.summary;
+  const fix = envelope.fix ? `\n${envelope.fix}` : '';
+  stream.write(`${envelope.code}: ${envelope.summary}\n${why}${fix}\n`);
 }
 
 /**
@@ -250,20 +509,69 @@ function serializeMigrationToDisk(
   instance: Migration,
   migrationDir: string,
   dryRun: boolean,
+  stdout: MigrationCliWritable,
 ): void {
   const metadataPath = join(migrationDir, 'migration.json');
   const existing = readExistingMetadata(metadataPath);
   const { opsJson, metadataJson } = buildMigrationArtifacts(instance, existing);
 
   if (dryRun) {
-    process.stdout.write(`--- migration.json ---\n${metadataJson}\n`);
-    process.stdout.write('--- ops.json ---\n');
-    process.stdout.write(`${opsJson}\n`);
+    stdout.write(`--- migration.json ---\n${metadataJson}\n`);
+    stdout.write('--- ops.json ---\n');
+    stdout.write(`${opsJson}\n`);
     return;
   }
 
   writeFileSync(join(migrationDir, 'ops.json'), opsJson);
   writeFileSync(metadataPath, metadataJson);
 
-  process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+  stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+}
+
+/**
+ * Inner orchestration: load config, probe-construct the migration,
+ * verify target, assemble the stack, construct with the stack, persist.
+ *
+ * Throws `CliStructuredError` for known failure modes (config not
+ * found, target mismatch); the outer `orchestrate` translates those to
+ * exit 1.
+ */
+async function runMigration(
+  importMetaUrl: string,
+  MigrationClass: MigrationConstructor,
+  parsed: MigrationFileCommand,
+  ctx: {
+    readonly stdout: MigrationCliWritable;
+    readonly stderr: MigrationCliWritable;
+  },
+): Promise<void> {
+  const migrationFile = fileURLToPath(importMetaUrl);
+  const migrationDir = dirname(migrationFile);
+
+  const config = await loadConfig(parsed.config);
+
+  // Probe-instantiate without a stack so we can read `targetId` before
+  // any target-specific constructor side effects (e.g.
+  // `PostgresMigration`'s `stack.adapter.create(stack)`) run. Concrete
+  // subclasses are required to accept the no-arg form; the abstract
+  // `Migration` constructor declares `stack?` and target subclasses
+  // (Postgres, Mongo) propagate that optionality. This makes the
+  // target-mismatch guard fail fast with `PN-MIG-2006` before any
+  // stack-driven adapter construction begins, even if the wrong-target
+  // adapter's `create` would otherwise succeed and silently misshapen
+  // the stored adapter cast.
+  const probe = new MigrationClass();
+
+  if (probe.targetId !== config.target.targetId) {
+    throw errorMigrationTargetMismatch({
+      migrationTargetId: probe.targetId,
+      configTargetId: config.target.targetId,
+    });
+  }
+
+  const stack = createControlStack(config);
+  const instance = new MigrationClass(stack);
+
+  serializeMigrationToDisk(instance, migrationDir, parsed.dryRun, ctx.stdout);
+  void ctx.stderr;
 }

package/src/utils/cli-errors.ts

@@ -1,6 +1,7 @@
 /**
  * Re-export all domain error factories from @prisma-next/errors for convenience.
- * CLI-specific errors (e.g., Commander.js argument validation) can be added here if needed.
+ * CLI-specific errors (e.g., Commander argument validation in the main CLI, or
+ * clipanion parse errors in the migration-file CLI) can be added here if needed.
  */
 export type { CliErrorConflict, CliErrorEnvelope } from '@prisma-next/errors/control';
 
@@ -16,6 +17,7 @@ import {
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
   errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,
@@ -36,6 +38,7 @@ export {
   errorFamilyReadMarkerSqlRequired,
   errorFileNotFound,
   errorMigrationCliInvalidConfigArg,
+  errorMigrationCliUnknownFlag,
   errorMigrationPlanningFailed,
   errorQueryRunnerFactoryRequired,
   errorTargetMigrationNotSupported,