@prisma/orm-toolchain 0.16.0-dev.36

package/dist/cli__migration-cli.mjs

@@ -0,0 +1,407 @@
+import { g as errorInvalidJson, t as MigrationToolsError } from "./errors-IpZm1Skp-BH495dRd.mjs";
+import { r as loadConfig } from "./exports-Dl2aGAk7.mjs";
+import { r as buildMigrationArtifacts } from "./migration-BuUmO7It.mjs";
+import { CliStructuredError, errorMigrationCliInvalidConfigArg, errorMigrationCliUnknownFlag } from "@prisma/orm-framework/errors/control";
+import { dirname, join } from "pathe";
+import { createControlStack } from "@prisma/orm-framework/components/control";
+import { errorMigrationTargetMismatch } from "@prisma/orm-framework/errors/migration";
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Cli, Command, Option, UsageError } from "clipanion";
+//#region ../../../1-framework/3-tooling/cli/dist/migration-cli.mjs
+/**
+* The migration-file CLI interface: the actor invoked when the author runs
+* `node migration.ts` directly.
+*
+* Naming: this is *not* a "migration runner" in the apply-time sense. The
+* apply-time runner is the thing `prisma-next migrate` uses to
+* execute migration JSON ops against a database. `MigrationCLI` is the
+* tiny CLI surface owned by an authored `migration.ts` file: parse the
+* file's argv, load the project's `prisma-next.config.ts`, assemble a
+* `ControlStack`, instantiate the migration class, and serialize.
+*
+* The user authors a migration class, then calls
+* `MigrationCLI.run(import.meta.url, MigrationClass)` at module scope
+* after the class definition. When the file is invoked as a node
+* 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>`) 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
+*    `targetId` and verify it matches `config.target.targetId`
+*    (`MIGRATION.TARGET_MISMATCH` on mismatch) before any stack-driven adapter
+*    construction runs.
+* 5. Assembles a `ControlStack` from the loaded config descriptors and
+*    constructs the migration with that stack.
+* 6. Reads any previously-scaffolded `migration.json`, then calls
+*    `buildMigrationArtifacts` from `@internal/migration-tools` to
+*    produce in-memory `ops.json` + `migration.json` content. Persists
+*    the result to disk (or prints in dry-run mode).
+*
+* File I/O lives here, in `@internal/cli`: this is the only place
+* that legitimately combines config loading, stack assembly, and
+* on-disk persistence. `@internal/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).
+*/
+/**
+* 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 = [
+	"--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).
+*/
+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;
+	}
+};
+/**
+* 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
+* give the concept a stable identity in the ubiquitous language: this is
+* the "migration-file CLI", distinct from the apply-time runner that
+* executes migration JSON ops.
+*
+* Currently a single static method. Future surface (e.g. a programmatic
+* `MigrationCLI.serializeOnly(...)` for tests, or extra subcommands) can
+* land here without changing the import shape used by every authored
+* migration.
+*/
+var MigrationCLI = class {
+	/**
+	* 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.
+	*
+	* 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, 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
+* `@internal/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
+			}
+		});
+		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
+*   `CLI.CONFIG_ARG_MISSING_PATH` 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 CLI.UNKNOWN_FLAG 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 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, `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, `createdAt`) without any
+* indication something was wrong on disk.
+* Apply-time consumers always route through the verifying
+* `readMigrationPackage` in `@internal/migration-tools/io` instead.
+*/
+function readExistingMetadata(metadataPath) {
+	let raw;
+	try {
+		raw = readFileSync(metadataPath, "utf-8");
+	} catch {
+		return null;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (e) {
+		throw errorInvalidJson(metadataPath, e instanceof Error ? e.message : String(e));
+	}
+}
+/**
+* Persist a migration instance's artifacts to `migrationDir`. In
+* `dryRun` mode the artifacts are printed to stdout (with the same
+* `--- migration.json --- / --- ops.json ---` framing the legacy
+* `serializeMigration` helper used) and no files are written. Otherwise
+* `ops.json` and `migration.json` are written next to `migration.ts` and
+* a confirmation line is printed.
+*
+* File I/O lives in the CLI rather than `@internal/migration-tools`
+* so the migration-tools package stays focused on the pure
+* `Migration` → in-memory artifact conversion. The CLI is the only
+* legitimate site for combining config loading, stack assembly, and
+* filesystem persistence.
+*/
+async function serializeMigrationToDisk(instance, migrationDir, dryRun, stdout) {
+	const metadataPath = join(migrationDir, "migration.json");
+	const { opsJson, metadataJson } = await buildMigrationArtifacts(instance, readExistingMetadata(metadataPath));
+	if (dryRun) {
+		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);
+	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
+	});
+	await serializeMigrationToDisk(new MigrationClass(createControlStack(config)), migrationDir, parsed.dryRun, ctx.stdout);
+	ctx.stderr;
+}
+//#endregion
+export { MigrationCLI };
+
+//# sourceMappingURL=cli__migration-cli.mjs.map

package/dist/cli__migration-cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli__migration-cli.mjs","names":[],"sources":["../../../../1-framework/3-tooling/cli/dist/migration-cli.mjs"],"sourcesContent":["import { loadConfig } from \"@internal/config-loader\";\nimport { CliStructuredError, errorMigrationCliInvalidConfigArg, errorMigrationCliUnknownFlag } from \"@internal/errors/control\";\nimport { dirname, join } from \"pathe\";\nimport { createControlStack } from \"@internal/framework-components/control\";\nimport { errorMigrationTargetMismatch } from \"@internal/errors/migration\";\nimport { readFileSync, realpathSync, writeFileSync } from \"node:fs\";\nimport { MigrationToolsError, errorInvalidJson } from \"@internal/migration-tools/errors\";\nimport { fileURLToPath } from \"node:url\";\nimport { buildMigrationArtifacts } from \"@internal/migration-tools/migration\";\nimport { Cli, Command, Option, UsageError } from \"clipanion\";\n//#region src/migration-cli.ts\n/**\n* The migration-file CLI interface: the actor invoked when the author runs\n* `node migration.ts` directly.\n*\n* Naming: this is *not* a \"migration runner\" in the apply-time sense. The\n* apply-time runner is the thing `prisma-next migrate` uses to\n* execute migration JSON ops against a database. `MigrationCLI` is the\n* tiny CLI surface owned by an authored `migration.ts` file: parse the\n* file's argv, load the project's `prisma-next.config.ts`, assemble a\n* `ControlStack`, instantiate the migration class, and serialize.\n*\n* The user authors a migration class, then calls\n* `MigrationCLI.run(import.meta.url, MigrationClass)` at module scope\n* after the class definition. When the file is invoked as a node\n* entrypoint (`node migration.ts`), the CLI:\n*\n* 1. Detects whether the file is the direct entrypoint (no-op when imported).\n* 2. Parses CLI args (`--help`, `--dry-run`, `--config <path>`) via\n*    [clipanion](https://github.com/arcanis/clipanion).\n* 3. Loads the project's `prisma-next.config.ts` via the same `loadConfig`\n*    the CLI commands use, walking up from the migration file's directory.\n* 4. Probe-instantiates the migration class without a stack so it can read\n*    `targetId` and verify it matches `config.target.targetId`\n*    (`MIGRATION.TARGET_MISMATCH` on mismatch) before any stack-driven adapter\n*    construction runs.\n* 5. Assembles a `ControlStack` from the loaded config descriptors and\n*    constructs the migration with that stack.\n* 6. Reads any previously-scaffolded `migration.json`, then calls\n*    `buildMigrationArtifacts` from `@internal/migration-tools` to\n*    produce in-memory `ops.json` + `migration.json` content. Persists\n*    the result to disk (or prints in dry-run mode).\n*\n* File I/O lives here, in `@internal/cli`: this is the only place\n* that legitimately combines config loading, stack assembly, and\n* on-disk persistence. `@internal/migration-tools` owns the pure\n* conversion from a `Migration` instance to artifact strings; `Migration`\n* stays a pure abstract class.\n*\n* Parser library: clipanion (chosen over Commander/citty/`node:util.parseArgs`\n* for its in-process testability and runtime-agnostic execution surface; see\n* `docs/architecture docs/research/commander-friction-points.md` for the\n* evaluation rubric and the durable rationale that drove the choice).\n*/\n/**\n* Flags exposed by the migration-file CLI.\n*\n* Must stay in sync with the `Option` declarations on\n* `MigrationFileCommand` below. This list is rendered in the\n* `errorMigrationCliUnknownFlag` envelope's `fix` text and `meta`,\n* so order matters for user-visible output (declaration order is the\n* order users see when they run `--help`).\n*/\nconst KNOWN_FLAGS = [\n\t\"--help\",\n\t\"--dry-run\",\n\t\"--config\"\n];\n/**\n* The clipanion command that owns the migration-file CLI's option\n* declarations. The class is internal — `MigrationCLI.run` is the\n* stable public surface. Adding a flag here automatically updates\n* `--help` rendering and the `KNOWN_FLAGS` list (the latter must be\n* updated in tandem).\n*/\nvar MigrationFileCommand = class extends Command {\n\tstatic paths = [Command.Default];\n\tstatic usage = Command.Usage({\n\t\tdescription: \"Self-emit ops.json and migration.json from a class-flow migration\",\n\t\tdetails: `\n      Loads the project's prisma-next.config.ts, assembles a ControlStack\n      from the configured target/adapter/extensions, and serializes the\n      migration's operations + metadata next to this file.\n    `,\n\t\texamples: [\n\t\t\t[\"Self-emit ops.json + migration.json next to migration.ts\", \"$0\"],\n\t\t\t[\"Preview without writing files\", \"$0 --dry-run\"],\n\t\t\t[\"Use a non-default config path\", \"$0 --config ./custom.config.ts\"]\n\t\t]\n\t});\n\tdryRun = Option.Boolean(\"--dry-run\", false, { description: \"Print operations to stdout without writing files\" });\n\tconfig = Option.String(\"--config\", { description: \"Path to prisma-next.config.ts\" });\n\t/**\n\t* Unused: orchestration runs inside `MigrationCLI.run` so error\n\t* routing stays under our control (clipanion's `cli.run` writes\n\t* error output to `context.stdout`, but our contract requires\n\t* structured errors on stderr). `cli.process` is used to parse\n\t* argv into a populated `MigrationFileCommand` instance whose\n\t* fields drive the orchestration directly.\n\t*/\n\tasync execute() {\n\t\treturn 0;\n\t}\n};\n/**\n* The CLI surface invoked by an authored `migration.ts` file. Exposed as\n* a class with a static `run` method (rather than a free function) to\n* give the concept a stable identity in the ubiquitous language: this is\n* the \"migration-file CLI\", distinct from the apply-time runner that\n* executes migration JSON ops.\n*\n* Currently a single static method. Future surface (e.g. a programmatic\n* `MigrationCLI.serializeOnly(...)` for tests, or extra subcommands) can\n* land here without changing the import shape used by every authored\n* migration.\n*/\nvar MigrationCLI = class {\n\t/**\n\t* Orchestrates a class-flow `migration.ts` script run.\n\t*\n\t* The third argument is the in-process testability surface: callers\n\t* (and tests) may inject `argv`, `stdout`, and `stderr` instead of\n\t* relying on `process.argv` / `process.stdout` / `process.stderr`.\n\t* Each option defaults to its `process` global when omitted, so\n\t* existing two-argument call sites\n\t* (`MigrationCLI.run(import.meta.url, MyMigration)`) continue to\n\t* compile and behave identically.\n\t*\n\t* Returns the exit code so the caller can branch on it. Also writes\n\t* the same code to `process.exitCode` so script-style callers that\n\t* don't await the return value still surface a non-zero exit when\n\t* something fails.\n\t*\n\t* Exit codes:\n\t* - 0 — success, or `--help`, or imported-not-entrypoint no-op.\n\t* - 1 — runtime/orchestration error (config not found, target\n\t*   mismatch, etc.).\n\t* - 2 — usage error (unknown flag, malformed `--config`). Aligns\n\t*   with `docs/CLI Style Guide.md` § Exit Codes.\n\t*/\n\tstatic async run(importMetaUrl, MigrationClass, options = {}) {\n\t\tif (!importMetaUrl) return 0;\n\t\tconst argv = options.argv ?? process.argv;\n\t\tconst stdout = options.stdout ?? process.stdout;\n\t\tconst stderr = options.stderr ?? process.stderr;\n\t\tif (!isDirectEntrypoint(importMetaUrl, argv)) return 0;\n\t\tconst exitCode = await orchestrate(importMetaUrl, MigrationClass, {\n\t\t\targv,\n\t\t\tstdout,\n\t\t\tstderr\n\t\t});\n\t\tif (exitCode !== 0 || !process.exitCode) process.exitCode = exitCode;\n\t\treturn exitCode;\n\t}\n};\n/**\n* Argv-aware variant of the entrypoint guard. The shared\n* `@internal/migration-tools` helper of the same name reads\n* `process.argv[1]` directly, which doesn't compose with the new\n* in-process testability surface (tests inject `argv` without mutating\n* the process global). Inlined here so the migration-file CLI's check\n* follows the injected `argv[1]` consistently.\n*/\nfunction isDirectEntrypoint(importMetaUrl, argv) {\n\tconst argv1 = argv[1];\n\tif (!argv1) return false;\n\ttry {\n\t\treturn realpathSync(fileURLToPath(importMetaUrl)) === realpathSync(argv1);\n\t} catch {\n\t\treturn false;\n\t}\n}\n/**\n* Argv-and-stream-driven orchestration body. Pulled out of the static\n* method so the entrypoint guard / process-default plumbing stays\n* separate from the parse + load + serialize steps.\n*/\nasync function orchestrate(importMetaUrl, MigrationClass, ctx) {\n\tconst cli = Cli.from([MigrationFileCommand], {\n\t\tbinaryName: \"migration.ts\",\n\t\tbinaryLabel: \"Migration file CLI\"\n\t});\n\tconst input = ctx.argv.slice(2);\n\tconst configError = detectInvalidConfig(input);\n\tif (configError) {\n\t\twriteStructuredError(ctx.stderr, configError);\n\t\treturn 2;\n\t}\n\tlet parsed;\n\ttry {\n\t\tconst command = cli.process({\n\t\t\tinput: [...input],\n\t\t\tcontext: {\n\t\t\t\tstdout: ctx.stdout,\n\t\t\t\tstderr: ctx.stderr\n\t\t\t}\n\t\t});\n\t\tif (!(command instanceof MigrationFileCommand)) {\n\t\t\tctx.stdout.write(cli.usage(MigrationFileCommand, { detailed: true }));\n\t\t\treturn 0;\n\t\t}\n\t\tparsed = command;\n\t} catch (err) {\n\t\treturn renderParseError(err, input, ctx.stderr);\n\t}\n\tif (parsed.help) {\n\t\tctx.stdout.write(cli.usage(MigrationFileCommand, { detailed: true }));\n\t\treturn 0;\n\t}\n\ttry {\n\t\tawait runMigration(importMetaUrl, MigrationClass, parsed, ctx);\n\t\treturn 0;\n\t} catch (err) {\n\t\tif (CliStructuredError.is(err)) writeStructuredError(ctx.stderr, err);\n\t\telse if (MigrationToolsError.is(err)) {\n\t\t\tconst fix = err.fix ? `\\n${err.fix}` : \"\";\n\t\t\tctx.stderr.write(`${err.code}: ${err.message}\\n${err.why}${fix}\\n`);\n\t\t} else ctx.stderr.write(`${err instanceof Error ? err.message : String(err)}\\n`);\n\t\treturn 1;\n\t}\n}\n/**\n* Returns an `errorMigrationCliInvalidConfigArg` envelope when `input`\n* contains a malformed `--config`:\n*\n* - `--config` as the last token (no value follows).\n* - `--config <flag>` where `<flag>` starts with `-` (silently\n*   consuming the next flag would either drop the flag or serialize\n*   against the wrong project).\n* - `--config <empty>` where the value is the empty string. Shells\n*   expand `--config \"\"` (or `--config \"$UNSET_VAR\"`) into a real\n*   empty argv token; treating that as a usage error here surfaces\n*   `CLI.CONFIG_ARG_MISSING_PATH` instead of a less actionable loader error on an\n*   empty path.\n* - `--config=` (the equals form with an empty value). Same shape as\n*   the empty-string case above; the user expressed intent to override\n*   the config path but the override is empty.\n*\n* `--config=<value>` and `--config <value>` with a non-empty value are\n* both valid (and the equals form's value is allowed to start with\n* `-` — the `=` makes the binding explicit).\n*/\nfunction detectInvalidConfig(input) {\n\tfor (let i = 0; i < input.length; i++) {\n\t\tconst token = input[i];\n\t\tif (token === \"--config\") {\n\t\t\tconst next = input[i + 1];\n\t\t\tif (next === void 0 || next === \"\") return errorMigrationCliInvalidConfigArg();\n\t\t\tif (next.startsWith(\"-\")) return errorMigrationCliInvalidConfigArg({ nextToken: next });\n\t\t\tcontinue;\n\t\t}\n\t\tif (token === \"--config=\") return errorMigrationCliInvalidConfigArg();\n\t}\n\treturn null;\n}\n/**\n* Translate clipanion's parse-time errors into the project's structured\n* error envelopes.\n*\n* - `UnknownSyntaxError` covers both unknown flags (`--frobnicate`) and\n*   the bare-trailing `--config` case (where arity-1 needs a value but\n*   none was supplied). Distinguished by inspecting the input array.\n* - `UsageError` covers schema/validator failures from typanion. None\n*   of the migration-file CLI's options have validators today, but we\n*   still translate it as a usage error (exit 2) for forward-compat.\n* - Anything else re-throws — caller's outer catch will surface it as\n*   exit 1 (runtime error).\n*/\nfunction renderParseError(err, input, stderr) {\n\tif (isUnknownSyntaxError(err)) {\n\t\twriteStructuredError(stderr, errorMigrationCliUnknownFlag({\n\t\t\tflag: findOffendingFlag(input),\n\t\t\tknownFlags: KNOWN_FLAGS\n\t\t}));\n\t\treturn 2;\n\t}\n\tif (err instanceof UsageError) {\n\t\twriteStructuredError(stderr, errorMigrationCliInvalidConfigArg({ nextToken: err.message }));\n\t\treturn 2;\n\t}\n\tthrow err;\n}\n/**\n* Duck-type check for clipanion's `UnknownSyntaxError`: the class is\n* thrown by the parser but is not re-exported from the package's main\n* entry (only `UsageError` is — see clipanion's `advanced/index.d.ts`).\n* Identified by `name === 'UnknownSyntaxError'` and the\n* `clipanion.type === 'none'` discriminator that clipanion's\n* `ErrorWithMeta` interface guarantees.\n*/\nfunction isUnknownSyntaxError(err) {\n\tif (!(err instanceof Error) || err.name !== \"UnknownSyntaxError\") return false;\n\tconst meta = err.clipanion;\n\treturn typeof meta === \"object\" && meta !== null && meta.type === \"none\";\n}\n/**\n* Best-effort: pull the first input token that doesn't match a known\n* flag. Falls back to the first token when we can't pinpoint it. The\n* returned name is rendered into the user-visible CLI.UNKNOWN_FLAG envelope\n* (`Unknown flag \\`<name>\\``) and round-tripped via `meta.flag` so\n* agent consumers can render their own \"did you mean\" suggestions.\n*/\nfunction findOffendingFlag(input) {\n\tfor (const token of input) {\n\t\tif (!token.startsWith(\"-\")) continue;\n\t\tconst head = token.split(\"=\", 1)[0] ?? token;\n\t\tif (!KNOWN_FLAGS.includes(head) && head !== \"-h\") return head;\n\t}\n\treturn input[0] ?? \"\";\n}\n/**\n* Write a `CliStructuredError` envelope to the given stream. Format\n* matches the legacy hand-rolled writer (`message: why`) so the rest of\n* the project's error rendering stays consistent across surfaces. The\n* full PN code (`PN-<domain>-<code>`) is included so consumers can\n* grep for stable identifiers.\n*/\nfunction writeStructuredError(stream, err) {\n\tconst envelope = err.toEnvelope();\n\tconst why = envelope.why ?? envelope.summary;\n\tconst fix = envelope.fix ? `\\n${envelope.fix}` : \"\";\n\tstream.write(`${envelope.code}: ${envelope.summary}\\n${why}${fix}\\n`);\n}\n/**\n* Read a previously-scaffolded `migration.json` from disk, returning\n* `null` when the file is missing and throwing `MIGRATION.INVALID_JSON`\n* when the file is present but cannot be parsed as JSON. The CLI feeds\n* this into `buildMigrationArtifacts` so the pure builder can preserve\n* fields owned by `migration plan` (contract bookends, `createdAt`) across\n* re-emits.\n*\n* Author-time path: this loader still does not verify the manifest hash\n* or schema — that is the apply-time loader's job. Hash mismatch is the\n* *expected* outcome of a re-author (the developer's source changes\n* invalidate the prior hash by construction), and verification here\n* would block legitimate regenerations. Syntactic JSON-parse failure,\n* however, is now surfaced rather than swallowed: a malformed\n* `migration.json` indicates either a hand-edit gone wrong or partial\n* write, and silently rebuilding from `describe()` would discard the\n* user's on-disk content (preserved bookends, `createdAt`) without any\n* indication something was wrong on disk.\n* Apply-time consumers always route through the verifying\n* `readMigrationPackage` in `@internal/migration-tools/io` instead.\n*/\nfunction readExistingMetadata(metadataPath) {\n\tlet raw;\n\ttry {\n\t\traw = readFileSync(metadataPath, \"utf-8\");\n\t} catch {\n\t\treturn null;\n\t}\n\ttry {\n\t\treturn JSON.parse(raw);\n\t} catch (e) {\n\t\tthrow errorInvalidJson(metadataPath, e instanceof Error ? e.message : String(e));\n\t}\n}\n/**\n* Persist a migration instance's artifacts to `migrationDir`. In\n* `dryRun` mode the artifacts are printed to stdout (with the same\n* `--- migration.json --- / --- ops.json ---` framing the legacy\n* `serializeMigration` helper used) and no files are written. Otherwise\n* `ops.json` and `migration.json` are written next to `migration.ts` and\n* a confirmation line is printed.\n*\n* File I/O lives in the CLI rather than `@internal/migration-tools`\n* so the migration-tools package stays focused on the pure\n* `Migration` → in-memory artifact conversion. The CLI is the only\n* legitimate site for combining config loading, stack assembly, and\n* filesystem persistence.\n*/\nasync function serializeMigrationToDisk(instance, migrationDir, dryRun, stdout) {\n\tconst metadataPath = join(migrationDir, \"migration.json\");\n\tconst { opsJson, metadataJson } = await buildMigrationArtifacts(instance, readExistingMetadata(metadataPath));\n\tif (dryRun) {\n\t\tstdout.write(`--- migration.json ---\\n${metadataJson}\\n`);\n\t\tstdout.write(\"--- ops.json ---\\n\");\n\t\tstdout.write(`${opsJson}\\n`);\n\t\treturn;\n\t}\n\twriteFileSync(join(migrationDir, \"ops.json\"), opsJson);\n\twriteFileSync(metadataPath, metadataJson);\n\tstdout.write(`Wrote ops.json + migration.json to ${migrationDir}\\n`);\n}\n/**\n* Inner orchestration: load config, probe-construct the migration,\n* verify target, assemble the stack, construct with the stack, persist.\n*\n* Throws `CliStructuredError` for known failure modes (config not\n* found, target mismatch); the outer `orchestrate` translates those to\n* exit 1.\n*/\nasync function runMigration(importMetaUrl, MigrationClass, parsed, ctx) {\n\tconst migrationDir = dirname(fileURLToPath(importMetaUrl));\n\tconst config = await loadConfig(parsed.config);\n\tconst probe = new MigrationClass();\n\tif (probe.targetId !== config.target.targetId) throw errorMigrationTargetMismatch({\n\t\tmigrationTargetId: probe.targetId,\n\t\tconfigTargetId: config.target.targetId\n\t});\n\tawait serializeMigrationToDisk(new MigrationClass(createControlStack(config)), migrationDir, parsed.dryRun, ctx.stdout);\n\tctx.stderr;\n}\n//#endregion\nexport { MigrationCLI };\n\n//# sourceMappingURL=migration-cli.mjs.map"],"mappings":"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"}