prisma-next 0.5.0-dev.8 → 0.5.0-dev.80

package/dist/inspect-live-schema-CWYxGKlb.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-live-schema-CWYxGKlb.mjs","names":[],"sources":["../src/commands/inspect-live-schema.ts"],"sourcesContent":["import type { CoreSchemaView } from '@prisma-next/framework-components/control';\nimport type { PslDocumentAst } from '@prisma-next/framework-components/psl-ast';\nimport { notOk, ok, type Result } from '@prisma-next/utils/result';\nimport { relative, resolve } from 'pathe';\nimport { loadConfig } from '../config-loader';\nimport { createControlClient } from '../control-api/client';\nimport {\n  CliStructuredError,\n  errorDatabaseConnectionRequired,\n  errorDriverRequired,\n  errorUnexpected,\n} from '../utils/cli-errors';\nimport { maskConnectionUrl, sanitizeErrorMessage } from '../utils/command-helpers';\nimport { formatStyledHeader } from '../utils/formatters/styled';\nimport type { CommonCommandOptions, GlobalFlags } from '../utils/global-flags';\nimport { createProgressAdapter } from '../utils/progress-adapter';\nimport type { TerminalUI } from '../utils/terminal-ui';\n\nexport interface InspectLiveSchemaOptions extends CommonCommandOptions {\n  readonly db?: string;\n  readonly config?: string;\n}\n\ninterface InspectLiveSchemaContext {\n  readonly commandName: string;\n  readonly description: string;\n  readonly url: string;\n}\n\ntype LoadedCliConfig = Awaited<ReturnType<typeof loadConfig>>;\n\nexport interface InspectLiveSchemaResult {\n  readonly config: LoadedCliConfig;\n  readonly schema: unknown;\n  readonly schemaView: CoreSchemaView | undefined;\n  /**\n   * PSL AST inferred from the introspected schema, when the configured family\n   * implements `PslContractInferCapable`. `undefined` for families that do not\n   * support inference (e.g. Mongo today).\n   */\n  readonly pslContractAst: PslDocumentAst | undefined;\n  readonly target: {\n    readonly familyId: string;\n    readonly id: string;\n  };\n  readonly meta: {\n    readonly configPath?: string;\n    readonly dbUrl?: string;\n  };\n  readonly timings: {\n    readonly total: number;\n  };\n}\n\nexport async function inspectLiveSchema(\n  options: InspectLiveSchemaOptions,\n  flags: GlobalFlags,\n  ui: TerminalUI,\n  startTime: number,\n  context: InspectLiveSchemaContext,\n): Promise<Result<InspectLiveSchemaResult, CliStructuredError>> {\n  let config: LoadedCliConfig;\n  try {\n    config = await loadConfig(options.config);\n  } catch (error) {\n    if (CliStructuredError.is(error)) {\n      return notOk(error);\n    }\n\n    return notOk(\n      errorUnexpected(error instanceof Error ? error.message : String(error), {\n        why: 'Failed to load config',\n      }),\n    );\n  }\n\n  const configPath = options.config\n    ? relative(process.cwd(), resolve(options.config))\n    : 'prisma-next.config.ts';\n\n  if (!flags.json && !flags.quiet) {\n    const details: Array<{ label: string; value: string }> = [\n      { label: 'config', value: configPath },\n    ];\n\n    if (options.db) {\n      details.push({ label: 'database', value: maskConnectionUrl(options.db) });\n    } else if (config.db?.connection && typeof config.db.connection === 'string') {\n      details.push({ label: 'database', value: maskConnectionUrl(config.db.connection) });\n    }\n\n    ui.stderr(\n      formatStyledHeader({\n        command: context.commandName,\n        description: context.description,\n        url: context.url,\n        details,\n        flags,\n      }),\n    );\n  }\n\n  const dbConnection = options.db ?? config.db?.connection;\n  if (!dbConnection) {\n    return notOk(\n      errorDatabaseConnectionRequired({\n        why: `Database connection is required for ${context.commandName} (set db.connection in ${configPath}, or pass --db <url>)`,\n        commandName: context.commandName,\n      }),\n    );\n  }\n\n  if (!config.driver) {\n    return notOk(\n      errorDriverRequired({\n        why: `Config.driver is required for ${context.commandName}`,\n      }),\n    );\n  }\n\n  const client = createControlClient({\n    family: config.family,\n    target: config.target,\n    adapter: config.adapter,\n    driver: config.driver,\n    extensionPacks: config.extensionPacks ?? [],\n  });\n  const onProgress = createProgressAdapter({ ui, flags });\n\n  try {\n    const schema = await client.introspect({\n      connection: dbConnection,\n      onProgress,\n    });\n    const schemaView = client.toSchemaView(schema);\n    const pslContractAst = client.inferPslContract(schema);\n\n    const dbUrl = typeof dbConnection === 'string' ? maskConnectionUrl(dbConnection) : undefined;\n\n    return ok({\n      config,\n      schema,\n      schemaView,\n      pslContractAst,\n      target: {\n        familyId: config.family.familyId,\n        id: config.target.targetId,\n      },\n      meta: {\n        configPath,\n        ...(dbUrl ? { dbUrl } : {}),\n      },\n      timings: {\n        total: Date.now() - startTime,\n      },\n    });\n  } catch (error) {\n    if (CliStructuredError.is(error)) {\n      return notOk(error);\n    }\n\n    const rawMessage = error instanceof Error ? error.message : String(error);\n    const safeMessage = sanitizeErrorMessage(\n      rawMessage,\n      typeof dbConnection === 'string' ? dbConnection : undefined,\n    );\n    return notOk(\n      errorUnexpected(safeMessage, {\n        why: `Unexpected error during ${context.commandName}: ${safeMessage}`,\n      }),\n    );\n  } finally {\n    await client.close();\n  }\n}\n"],"mappings":";;;;;;;;AAsDA,eAAsB,kBACpB,SACA,OACA,IACA,WACA,SAC8D;CAC9D,IAAI;CACJ,IAAI;EACF,SAAS,MAAM,WAAW,QAAQ,OAAO;UAClC,OAAO;EACd,IAAI,mBAAmB,GAAG,MAAM,EAC9B,OAAO,MAAM,MAAM;EAGrB,OAAO,MACL,gBAAgB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,EAAE,EACtE,KAAK,yBACN,CAAC,CACH;;CAGH,MAAM,aAAa,QAAQ,SACvB,SAAS,QAAQ,KAAK,EAAE,QAAQ,QAAQ,OAAO,CAAC,GAChD;CAEJ,IAAI,CAAC,MAAM,QAAQ,CAAC,MAAM,OAAO;EAC/B,MAAM,UAAmD,CACvD;GAAE,OAAO;GAAU,OAAO;GAAY,CACvC;EAED,IAAI,QAAQ,IACV,QAAQ,KAAK;GAAE,OAAO;GAAY,OAAO,kBAAkB,QAAQ,GAAG;GAAE,CAAC;OACpE,IAAI,OAAO,IAAI,cAAc,OAAO,OAAO,GAAG,eAAe,UAClE,QAAQ,KAAK;GAAE,OAAO;GAAY,OAAO,kBAAkB,OAAO,GAAG,WAAW;GAAE,CAAC;EAGrF,GAAG,OACD,mBAAmB;GACjB,SAAS,QAAQ;GACjB,aAAa,QAAQ;GACrB,KAAK,QAAQ;GACb;GACA;GACD,CAAC,CACH;;CAGH,MAAM,eAAe,QAAQ,MAAM,OAAO,IAAI;CAC9C,IAAI,CAAC,cACH,OAAO,MACL,gCAAgC;EAC9B,KAAK,uCAAuC,QAAQ,YAAY,yBAAyB,WAAW;EACpG,aAAa,QAAQ;EACtB,CAAC,CACH;CAGH,IAAI,CAAC,OAAO,QACV,OAAO,MACL,oBAAoB,EAClB,KAAK,iCAAiC,QAAQ,eAC/C,CAAC,CACH;CAGH,MAAM,SAAS,oBAAoB;EACjC,QAAQ,OAAO;EACf,QAAQ,OAAO;EACf,SAAS,OAAO;EAChB,QAAQ,OAAO;EACf,gBAAgB,OAAO,kBAAkB,EAAE;EAC5C,CAAC;CACF,MAAM,aAAa,sBAAsB;EAAE;EAAI;EAAO,CAAC;CAEvD,IAAI;EACF,MAAM,SAAS,MAAM,OAAO,WAAW;GACrC,YAAY;GACZ;GACD,CAAC;EACF,MAAM,aAAa,OAAO,aAAa,OAAO;EAC9C,MAAM,iBAAiB,OAAO,iBAAiB,OAAO;EAEtD,MAAM,QAAQ,OAAO,iBAAiB,WAAW,kBAAkB,aAAa,GAAG,KAAA;EAEnF,OAAO,GAAG;GACR;GACA;GACA;GACA;GACA,QAAQ;IACN,UAAU,OAAO,OAAO;IACxB,IAAI,OAAO,OAAO;IACnB;GACD,MAAM;IACJ;IACA,GAAI,QAAQ,EAAE,OAAO,GAAG,EAAE;IAC3B;GACD,SAAS,EACP,OAAO,KAAK,KAAK,GAAG,WACrB;GACF,CAAC;UACK,OAAO;EACd,IAAI,mBAAmB,GAAG,MAAM,EAC9B,OAAO,MAAM,MAAM;EAIrB,MAAM,cAAc,qBADD,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM,EAGvE,OAAO,iBAAiB,WAAW,eAAe,KAAA,EACnD;EACD,OAAO,MACL,gBAAgB,aAAa,EAC3B,KAAK,2BAA2B,QAAQ,YAAY,IAAI,eACzD,CAAC,CACH;WACO;EACR,MAAM,OAAO,OAAO"}

package/dist/migration-cli.d.mts

@@ -1,7 +1,7 @@
 import { Migration } from "@prisma-next/migration-tools/migration";
+import { Writable } from "node:stream";
 
 //#region src/migration-cli.d.ts
-
 /**
  * Constructor shape accepted by `MigrationCLI.run`. `Migration` subclasses
  * accept an optional `ControlStack` in their constructor (each subclass
@@ -18,6 +18,20 @@ import { Migration } from "@prisma-next/migration-tools/migration";
  * point for additional construction arguments.
  */
 type MigrationConstructor = new (...args: any[]) => Migration;
+/**
+ * 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.
+ *
+ * `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)`.
+ *
+ * Tests inject a `Writable` subclass that captures chunks for
+ * assertions.
+ */
+type MigrationCliWritable = Writable;
 /**
  * The CLI surface invoked by an authored `migration.ts` file. Exposed as
  * a class with a static `run` method (rather than a free function) to
@@ -32,19 +46,34 @@ type MigrationConstructor = new (...args: any[]) => Migration;
  */
 declare 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 run(importMetaUrl: string, MigrationClass: MigrationConstructor): Promise<void>;
+  static run(importMetaUrl: string, MigrationClass: MigrationConstructor, options?: {
+    readonly argv?: readonly string[];
+    readonly stdout?: MigrationCliWritable;
+    readonly stderr?: MigrationCliWritable;
+  }): Promise<number>;
 }
 //#endregion
-export { MigrationCLI, MigrationConstructor };
+export { MigrationCLI, MigrationCliWritable, MigrationConstructor };
 //# sourceMappingURL=migration-cli.d.mts.map

package/dist/migration-cli.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-cli.d.mts","names":[],"sources":["../src/migration-cli.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;KAqEY,oBAAA,2BAA+C;;;;;;;;;;;;;cAiE9C,YAAA;;;;;;;;;;;;;oDAa6C,uBAAuB"}
+{"version":3,"file":"migration-cli.d.mts","names":[],"sources":["../src/migration-cli.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KA6EY,oBAAA,WAA+B,IAAA,YAAgB,SAAA;;;;;;;;;;;;;;KAe/C,oBAAA,GAAuB,QAAA;;;;;;;;;;;;;cAuEtB,YAAA;;;;;;;;;;;;;;;;;;;;;;;;SAwBE,GAAA,CACX,aAAA,UACA,cAAA,EAAgB,oBAAA,EAChB,OAAA;IAAA,SACW,IAAA;IAAA,SACA,MAAA,GAAS,oBAAA;IAAA,SACT,MAAA,GAAS,oBAAA;EAAA,IAEnB,OAAA;AAAA"}

package/dist/migration-cli.mjs

@@ -1,12 +1,13 @@
-import { t as loadConfig } from "./config-loader-C25b63rJ.mjs";
-import { readFileSync, writeFileSync } from "node:fs";
-import { CliStructuredError, errorMigrationCliInvalidConfigArg } from "@prisma-next/errors/control";
+import { t as loadConfig } from "./config-loader-B6sJjXTv.mjs";
+import { CliStructuredError, errorMigrationCliInvalidConfigArg, errorMigrationCliUnknownFlag } from "@prisma-next/errors/control";
 import { dirname, join } from "pathe";
 import { createControlStack } from "@prisma-next/framework-components/control";
 import { errorMigrationTargetMismatch } from "@prisma-next/errors/migration";
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { MigrationToolsError, errorInvalidJson } from "@prisma-next/migration-tools/errors";
 import { fileURLToPath } from "node:url";
-import { buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp } from "@prisma-next/migration-tools/migration";
-
+import { buildMigrationArtifacts } from "@prisma-next/migration-tools/migration";
+import { Cli, Command, Option, UsageError } from "clipanion";
 //#region src/migration-cli.ts
 /**
 * The migration-file CLI interface: the actor invoked when the author runs
@@ -25,7 +26,8 @@ import { buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp } from
 * 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
@@ -44,44 +46,62 @@ import { buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp } from
 * 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).
 */
 /**
-* 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.
+* Flags exposed by the migration-file CLI.
 *
-* 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.
-*
-* 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.
+* 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 = [
+	"--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).
 */
-function parseArgs(argv) {
-	let help = false;
-	let dryRun = false;
-	let configPath;
-	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 === void 0) throw errorMigrationCliInvalidConfigArg();
-			if (next.startsWith("-")) throw errorMigrationCliInvalidConfigArg({ nextToken: next });
-			configPath = next;
-			i++;
-		} else if (arg.startsWith("--config=")) configPath = arg.slice(9);
+var MigrationFileCommand = class extends Command {
+	static paths = [Command.Default];
+	static 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.
+	*/
+	async execute() {
+		return 0;
 	}
-	return {
-		help,
-		dryRun,
-		configPath
-	};
-}
+};
 /**
 * The CLI surface invoked by an authored `migration.ts` file. Exposed as
 * a class with a static `run` method (rather than a free function) to
@@ -96,59 +116,243 @@ function parseArgs(argv) {
 */
 var MigrationCLI = class {
 	/**
-	* 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.
 	*
-	* 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.
+	* 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.
+	*
+	* 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, MigrationClass) {
-		if (!importMetaUrl) return;
-		if (!isDirectEntrypoint(importMetaUrl)) return;
-		try {
-			const args = parseArgs(process.argv.slice(2));
-			if (args.help) {
-				printMigrationHelp();
-				return;
+	static async run(importMetaUrl, MigrationClass, options = {}) {
+		if (!importMetaUrl) return 0;
+		const argv = options.argv ?? process.argv;
+		const stdout = options.stdout ?? process.stdout;
+		const stderr = options.stderr ?? process.stderr;
+		if (!isDirectEntrypoint(importMetaUrl, argv)) return 0;
+		const exitCode = await orchestrate(importMetaUrl, MigrationClass, {
+			argv,
+			stdout,
+			stderr
+		});
+		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, argv) {
+	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, MigrationClass, ctx) {
+	const cli = Cli.from([MigrationFileCommand], {
+		binaryName: "migration.ts",
+		binaryLabel: "Migration file CLI"
+	});
+	const input = ctx.argv.slice(2);
+	const configError = detectInvalidConfig(input);
+	if (configError) {
+		writeStructuredError(ctx.stderr, configError);
+		return 2;
+	}
+	let parsed;
+	try {
+		const command = cli.process({
+			input: [...input],
+			context: {
+				stdout: ctx.stdout,
+				stderr: ctx.stderr
 			}
-			const migrationDir = dirname(fileURLToPath(importMetaUrl));
-			const config = await loadConfig(args.configPath);
-			const probe = new MigrationClass();
-			if (probe.targetId !== config.target.targetId) throw errorMigrationTargetMismatch({
-				migrationTargetId: probe.targetId,
-				configTargetId: config.target.targetId
-			});
-			serializeMigrationToDisk(new MigrationClass(createControlStack(config)), migrationDir, args.dryRun);
-		} catch (err) {
-			if (CliStructuredError.is(err)) process.stderr.write(`${err.message}: ${err.why}\n`);
-			else process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-			process.exitCode = 1;
+		});
+		if (!(command instanceof MigrationFileCommand)) {
+			ctx.stdout.write(cli.usage(MigrationFileCommand, { detailed: true }));
+			return 0;
 		}
+		parsed = command;
+	} catch (err) {
+		return renderParseError(err, input, ctx.stderr);
 	}
-};
+	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)) {
+			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) {
+	for (let i = 0; i < input.length; i++) {
+		const token = input[i];
+		if (token === "--config") {
+			const next = input[i + 1];
+			if (next === void 0 || next === "") return errorMigrationCliInvalidConfigArg();
+			if (next.startsWith("-")) return errorMigrationCliInvalidConfigArg({ nextToken: next });
+			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, input, stderr) {
+	if (isUnknownSyntaxError(err)) {
+		writeStructuredError(stderr, errorMigrationCliUnknownFlag({
+			flag: findOffendingFlag(input),
+			knownFlags: KNOWN_FLAGS
+		}));
+		return 2;
+	}
+	if (err instanceof UsageError) {
+		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) {
+	if (!(err instanceof Error) || err.name !== "UnknownSyntaxError") return false;
+	const meta = err.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) {
+	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, err) {
+	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`);
+}
 /**
 * Read a previously-scaffolded `migration.json` from disk, returning
-* `null` when the file is missing or unparseable. The CLI feeds this into
-* `buildMigrationArtifacts` so the pure builder can preserve fields owned
-* by `migration plan` (contract bookends, hints, labels, `createdAt`)
-* across re-emits.
+* `null` when the file is missing and throwing `MIGRATION.INVALID_JSON`
+* when the file is present but cannot be parsed as JSON. The CLI feeds
+* this into `buildMigrationArtifacts` so the pure builder can preserve
+* fields owned by `migration plan` (contract bookends, hints, labels,
+* `createdAt`) across re-emits.
+*
+* Author-time path: this loader still does not verify the manifest hash
+* or schema — that is the apply-time loader's job. Hash mismatch is the
+* *expected* outcome of a re-author (the developer's source changes
+* invalidate the prior hash by construction), and verification here
+* would block legitimate regenerations. Syntactic JSON-parse failure,
+* however, is now surfaced rather than swallowed: a malformed
+* `migration.json` indicates either a hand-edit gone wrong or partial
+* write, and silently rebuilding from `describe()` would discard the
+* user's on-disk content (preserved bookends, hints, labels,
+* `createdAt`) without any indication something was wrong on disk.
+* Apply-time consumers always route through the verifying
+* `readMigrationPackage` in `@prisma-next/migration-tools/io` instead.
 */
-function readExistingManifest(manifestPath) {
+function readExistingMetadata(metadataPath) {
 	let raw;
 	try {
-		raw = readFileSync(manifestPath, "utf-8");
+		raw = readFileSync(metadataPath, "utf-8");
 	} catch {
 		return null;
 	}
 	try {
 		return JSON.parse(raw);
-	} catch {
-		return null;
+	} catch (e) {
+		throw errorInvalidJson(metadataPath, e instanceof Error ? e.message : String(e));
 	}
 }
 /**
@@ -165,20 +369,39 @@ function readExistingManifest(manifestPath) {
 * legitimate site for combining config loading, stack assembly, and
 * filesystem persistence.
 */
-function serializeMigrationToDisk(instance, migrationDir, dryRun) {
-	const manifestPath = join(migrationDir, "migration.json");
-	const { opsJson, manifestJson } = buildMigrationArtifacts(instance, readExistingManifest(manifestPath));
+function serializeMigrationToDisk(instance, migrationDir, dryRun, stdout) {
+	const metadataPath = join(migrationDir, "migration.json");
+	const { opsJson, metadataJson } = buildMigrationArtifacts(instance, readExistingMetadata(metadataPath));
 	if (dryRun) {
-		process.stdout.write(`--- migration.json ---\n${manifestJson}\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(manifestPath, manifestJson);
-	process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+	writeFileSync(metadataPath, metadataJson);
+	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, MigrationClass, parsed, ctx) {
+	const migrationDir = dirname(fileURLToPath(importMetaUrl));
+	const config = await loadConfig(parsed.config);
+	const probe = new MigrationClass();
+	if (probe.targetId !== config.target.targetId) throw errorMigrationTargetMismatch({
+		migrationTargetId: probe.targetId,
+		configTargetId: config.target.targetId
+	});
+	serializeMigrationToDisk(new MigrationClass(createControlStack(config)), migrationDir, parsed.dryRun, ctx.stdout);
+	ctx.stderr;
 }
-
 //#endregion
 export { MigrationCLI };
+
 //# sourceMappingURL=migration-cli.mjs.map