@prisma-next/migration-tools 0.4.1 → 0.5.0-dev.2

package/dist/exports/migration-ts.d.mts

@@ -11,7 +11,11 @@
  * Writes a pre-rendered `migration.ts` source string to the given package
  * directory. If the source begins with a shebang, the file is written with
  * executable permissions (0o755) so it can be run directly via
- * `./migration.ts` by the authoring class's `Migration.run(...)` guard.
+ * `./migration.ts` — the rendered scaffold ends with
+ * `MigrationCLI.run(import.meta.url, M)` from
+ * `@prisma-next/cli/migration-cli` (re-exported by the postgres facade),
+ * which guards on the entrypoint and serializes when the file is the main
+ * module.
  *
  * The source is run through prettier before writing so migration renderers
  * can produce structurally-correct but loosely-indented source and rely on

package/dist/exports/migration-ts.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration-ts.d.mts","names":[],"sources":["../../src/migration-ts.ts","../../src/runtime-detection.ts"],"sourcesContent":[],"mappings":";;AA0BA;AAsBA;;;;AChDA;AAEA;AAMA;;;;;;;;;;;iBDkBsB,gBAAA,uCAAuD;;;;iBAsBvD,cAAA,sBAAoC;;;KChD9C,eAAA;AD0BU,iBCxBN,qBAAA,CAAA,CDwBoE,ECxB3C,eDwB2C;AAsB9D,iBCxCN,cAAA,CDwC0C,OAAO,ECxCzB,eDwCyB,CAAA,EAAA,MAAA"}
+{"version":3,"file":"migration-ts.d.mts","names":[],"sources":["../../src/migration-ts.ts","../../src/runtime-detection.ts"],"sourcesContent":[],"mappings":";;AA8BA;AAsBA;;;;ACpDA;AAEA;AAMA;;;;;;;;;;;;;;;iBDsBsB,gBAAA,uCAAuD;;;;iBAsBvD,cAAA,sBAAoC;;;KCpD9C,eAAA;AD8BU,iBC5BN,qBAAA,CAAA,CD4BoE,EC5B3C,eD4B2C;AAsB9D,iBC5CN,cAAA,CD4C0C,OAAO,EC5CzB,eD4CyB,CAAA,EAAA,MAAA"}

package/dist/exports/migration-ts.mjs

@@ -16,7 +16,11 @@ const MIGRATION_TS_FILE = "migration.ts";
 * Writes a pre-rendered `migration.ts` source string to the given package
 * directory. If the source begins with a shebang, the file is written with
 * executable permissions (0o755) so it can be run directly via
-* `./migration.ts` by the authoring class's `Migration.run(...)` guard.
+* `./migration.ts` — the rendered scaffold ends with
+* `MigrationCLI.run(import.meta.url, M)` from
+* `@prisma-next/cli/migration-cli` (re-exported by the postgres facade),
+* which guards on the entrypoint and serializes when the file is the main
+* module.
 *
 * The source is run through prettier before writing so migration renderers
 * can produce structurally-correct but loosely-indented source and rely on

package/dist/exports/migration-ts.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration-ts.mjs","names":[],"sources":["../../src/migration-ts.ts","../../src/runtime-detection.ts"],"sourcesContent":["/**\n * Utilities for reading/writing `migration.ts` files.\n *\n * Rendering migration.ts source is the target's responsibility — the CLI\n * obtains source strings from a planner's `plan.renderTypeScript()`. The\n * helper here is limited to file I/O: writing the returned source with the\n * right executable bit and probing for existence.\n */\n\nimport { stat, writeFile } from 'node:fs/promises';\nimport { join } from 'pathe';\nimport { format } from 'prettier';\n\nconst MIGRATION_TS_FILE = 'migration.ts';\n\n/**\n * Writes a pre-rendered `migration.ts` source string to the given package\n * directory. If the source begins with a shebang, the file is written with\n * executable permissions (0o755) so it can be run directly via\n * `./migration.ts` by the authoring class's `Migration.run(...)` guard.\n *\n * The source is run through prettier before writing so migration renderers\n * can produce structurally-correct but loosely-indented source and rely on\n * a single canonical format on disk. Matches what `@prisma-next/emitter`\n * already does for generated `contract.d.ts`.\n */\nexport async function writeMigrationTs(packageDir: string, content: string): Promise<void> {\n  const formatted = await formatMigrationTsSource(content);\n  const isExecutable = formatted.startsWith('#!');\n  await writeFile(\n    join(packageDir, MIGRATION_TS_FILE),\n    formatted,\n    isExecutable ? { mode: 0o755 } : undefined,\n  );\n}\n\nasync function formatMigrationTsSource(source: string): Promise<string> {\n  return format(source, {\n    parser: 'typescript',\n    singleQuote: true,\n    semi: true,\n    printWidth: 100,\n  });\n}\n\n/**\n * Checks whether a migration.ts file exists in the package directory.\n */\nexport async function hasMigrationTs(packageDir: string): Promise<boolean> {\n  try {\n    const s = await stat(join(packageDir, MIGRATION_TS_FILE));\n    return s.isFile();\n  } catch {\n    return false;\n  }\n}\n","export type ScaffoldRuntime = 'node' | 'bun' | 'deno';\n\nexport function detectScaffoldRuntime(): ScaffoldRuntime {\n  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') return 'bun';\n  if (typeof (globalThis as { Deno?: unknown }).Deno !== 'undefined') return 'deno';\n  return 'node';\n}\n\nexport function shebangLineFor(runtime: ScaffoldRuntime): string {\n  switch (runtime) {\n    case 'bun':\n      return '#!/usr/bin/env -S bun';\n    case 'deno':\n      return '#!/usr/bin/env -S deno run -A';\n    case 'node':\n      return '#!/usr/bin/env -S node';\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAM,oBAAoB;;;;;;;;;;;;AAa1B,eAAsB,iBAAiB,YAAoB,SAAgC;CACzF,MAAM,YAAY,MAAM,wBAAwB,QAAQ;CACxD,MAAM,eAAe,UAAU,WAAW,KAAK;AAC/C,OAAM,UACJ,KAAK,YAAY,kBAAkB,EACnC,WACA,eAAe,EAAE,MAAM,KAAO,GAAG,OAClC;;AAGH,eAAe,wBAAwB,QAAiC;AACtE,QAAO,OAAO,QAAQ;EACpB,QAAQ;EACR,aAAa;EACb,MAAM;EACN,YAAY;EACb,CAAC;;;;;AAMJ,eAAsB,eAAe,YAAsC;AACzE,KAAI;AAEF,UADU,MAAM,KAAK,KAAK,YAAY,kBAAkB,CAAC,EAChD,QAAQ;SACX;AACN,SAAO;;;;;;ACnDX,SAAgB,wBAAyC;AACvD,KAAI,OAAQ,WAAiC,QAAQ,YAAa,QAAO;AACzE,KAAI,OAAQ,WAAkC,SAAS,YAAa,QAAO;AAC3E,QAAO;;AAGT,SAAgB,eAAe,SAAkC;AAC/D,SAAQ,SAAR;EACE,KAAK,MACH,QAAO;EACT,KAAK,OACH,QAAO;EACT,KAAK,OACH,QAAO"}
+{"version":3,"file":"migration-ts.mjs","names":[],"sources":["../../src/migration-ts.ts","../../src/runtime-detection.ts"],"sourcesContent":["/**\n * Utilities for reading/writing `migration.ts` files.\n *\n * Rendering migration.ts source is the target's responsibility — the CLI\n * obtains source strings from a planner's `plan.renderTypeScript()`. The\n * helper here is limited to file I/O: writing the returned source with the\n * right executable bit and probing for existence.\n */\n\nimport { stat, writeFile } from 'node:fs/promises';\nimport { join } from 'pathe';\nimport { format } from 'prettier';\n\nconst MIGRATION_TS_FILE = 'migration.ts';\n\n/**\n * Writes a pre-rendered `migration.ts` source string to the given package\n * directory. If the source begins with a shebang, the file is written with\n * executable permissions (0o755) so it can be run directly via\n * `./migration.ts` — the rendered scaffold ends with\n * `MigrationCLI.run(import.meta.url, M)` from\n * `@prisma-next/cli/migration-cli` (re-exported by the postgres facade),\n * which guards on the entrypoint and serializes when the file is the main\n * module.\n *\n * The source is run through prettier before writing so migration renderers\n * can produce structurally-correct but loosely-indented source and rely on\n * a single canonical format on disk. Matches what `@prisma-next/emitter`\n * already does for generated `contract.d.ts`.\n */\nexport async function writeMigrationTs(packageDir: string, content: string): Promise<void> {\n  const formatted = await formatMigrationTsSource(content);\n  const isExecutable = formatted.startsWith('#!');\n  await writeFile(\n    join(packageDir, MIGRATION_TS_FILE),\n    formatted,\n    isExecutable ? { mode: 0o755 } : undefined,\n  );\n}\n\nasync function formatMigrationTsSource(source: string): Promise<string> {\n  return format(source, {\n    parser: 'typescript',\n    singleQuote: true,\n    semi: true,\n    printWidth: 100,\n  });\n}\n\n/**\n * Checks whether a migration.ts file exists in the package directory.\n */\nexport async function hasMigrationTs(packageDir: string): Promise<boolean> {\n  try {\n    const s = await stat(join(packageDir, MIGRATION_TS_FILE));\n    return s.isFile();\n  } catch {\n    return false;\n  }\n}\n","export type ScaffoldRuntime = 'node' | 'bun' | 'deno';\n\nexport function detectScaffoldRuntime(): ScaffoldRuntime {\n  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') return 'bun';\n  if (typeof (globalThis as { Deno?: unknown }).Deno !== 'undefined') return 'deno';\n  return 'node';\n}\n\nexport function shebangLineFor(runtime: ScaffoldRuntime): string {\n  switch (runtime) {\n    case 'bun':\n      return '#!/usr/bin/env -S bun';\n    case 'deno':\n      return '#!/usr/bin/env -S deno run -A';\n    case 'node':\n      return '#!/usr/bin/env -S node';\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAaA,MAAM,oBAAoB;;;;;;;;;;;;;;;;AAiB1B,eAAsB,iBAAiB,YAAoB,SAAgC;CACzF,MAAM,YAAY,MAAM,wBAAwB,QAAQ;CACxD,MAAM,eAAe,UAAU,WAAW,KAAK;AAC/C,OAAM,UACJ,KAAK,YAAY,kBAAkB,EACnC,WACA,eAAe,EAAE,MAAM,KAAO,GAAG,OAClC;;AAGH,eAAe,wBAAwB,QAAiC;AACtE,QAAO,OAAO,QAAQ;EACpB,QAAQ;EACR,aAAa;EACb,MAAM;EACN,YAAY;EACb,CAAC;;;;;AAMJ,eAAsB,eAAe,YAAsC;AACzE,KAAI;AAEF,UADU,MAAM,KAAK,KAAK,YAAY,kBAAkB,CAAC,EAChD,QAAQ;SACX;AACN,SAAO;;;;;;ACvDX,SAAgB,wBAAyC;AACvD,KAAI,OAAQ,WAAiC,QAAQ,YAAa,QAAO;AACzE,KAAI,OAAQ,WAAkC,SAAS,YAAa,QAAO;AAC3E,QAAO;;AAGT,SAAgB,eAAe,SAAkC;AAC/D,SAAQ,SAAR;EACE,KAAK,MACH,QAAO;EACT,KAAK,OACH,QAAO;EACT,KAAK,OACH,QAAO"}

package/dist/exports/migration.d.mts

@@ -1,4 +1,5 @@
-import { MigrationPlan, MigrationPlanOperation } from "@prisma-next/framework-components/control";
+import { a as MigrationManifest } from "../types-DyGXcWWp.mjs";
+import { ControlStack, MigrationPlan, MigrationPlanOperation } from "@prisma-next/framework-components/control";
 
 //#region src/migration-base.d.ts
 interface MigrationMeta {
@@ -16,8 +17,19 @@ interface MigrationMeta {
  * every migration must implement — `migration.json` is required for a
  * migration to be valid.
  */
-declare abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation> implements MigrationPlan {
+declare abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation, TFamilyId extends string = string, TTargetId extends string = string> implements MigrationPlan {
   abstract readonly targetId: string;
+  /**
+   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).
+   *
+   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their
+   * adapter once per instance. Optional at the abstract level so unit tests can
+   * construct `Migration` instances purely for `operations` / `describe`
+   * assertions without needing a real stack; concrete subclasses that need the
+   * stack at runtime should narrow the parameter to required.
+   */
+  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;
+  constructor(stack?: ControlStack<TFamilyId, TTargetId>);
   /**
    * Ordered list of operations this migration performs.
    *
@@ -37,21 +49,39 @@ declare abstract class Migration<TOperation extends MigrationPlanOperation = Mig
   get destination(): {
     readonly storageHash: string;
   };
-  /**
-   * Entrypoint guard for migration files. When called at module scope,
-   * detects whether the file is being run directly (e.g. `node migration.ts`)
-   * and if so, serializes the migration plan to `ops.json` and
-   * `migration.json` in the same directory. When the file is imported by
-   * another module, this is a no-op.
-   *
-   * Usage (at module scope, after the class definition):
-   *
-   *     class MyMigration extends Migration { ... }
-   *     export default MyMigration;
-   *     Migration.run(import.meta.url, MyMigration);
-   */
-  static run(importMetaUrl: string, MigrationClass: new () => Migration): void;
 }
+/**
+ * Returns true when `import.meta.url` resolves to the same file that was
+ * invoked as the node entrypoint (`process.argv[1]`). Used by
+ * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when
+ * the migration module is being imported (e.g. by another script) rather
+ * than executed directly.
+ */
+declare function isDirectEntrypoint(importMetaUrl: string): boolean;
+declare function printMigrationHelp(): void;
+/**
+ * In-memory artifacts produced from a `Migration` instance: the
+ * serialized `ops.json` body, the `migration.json` manifest object, and
+ * its serialized form. Returned by `buildMigrationArtifacts` so callers
+ * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can
+ * decide how to persist them — write to disk, print in dry-run, ship
+ * over the wire — without coupling artifact construction to file I/O.
+ */
+interface MigrationArtifacts {
+  readonly opsJson: string;
+  readonly manifest: MigrationManifest;
+  readonly manifestJson: string;
+}
+/**
+ * Pure conversion from a `Migration` instance (plus the previously
+ * scaffolded manifest, when one exists on disk) to the in-memory
+ * artifacts that downstream tooling persists. Owns metadata validation,
+ * manifest synthesis/preservation, hint normalization, and the
+ * content-addressed `migrationId` computation, but performs no file I/O
+ * — callers handle reads (to source `existing`) and writes (to persist
+ * `opsJson` / `manifestJson`).
+ */
+declare function buildMigrationArtifacts(instance: Migration, existing: Partial<MigrationManifest> | null): MigrationArtifacts;
 //#endregion
-export { Migration, type MigrationMeta };
+export { Migration, type MigrationArtifacts, type MigrationMeta, buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp };
 //# sourceMappingURL=migration.d.mts.map

package/dist/exports/migration.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":[],"mappings":";;;UAaiB,aAAA;;EAAA,SAAA,EAAA,EAAA,MAAa;EAuBR,SAAA,IAAS,CAAA,EAAA,SAAA,GAAA,UAAA;EAAoB,SAAA,MAAA,CAAA,EAAA,SAAA,MAAA,EAAA;;;;;;;;;;;uBAA7B,6BAA6B,yBAAyB,mCAC/D;;;;;;;;sCAUyB;;;;;;uBAOf;;;;;;;;;;;;;;;;;;;;8DA4BuC"}
+{"version":3,"file":"migration.d.mts","names":[],"sources":["../../src/migration-base.ts"],"sourcesContent":[],"mappings":";;;;UAaiB,aAAA;;EAAA,SAAA,EAAA,EAAA,MAAa;EAuBR,SAAA,IAAS,CAAA,EAAA,SAAA,GAAA,UAAA;EACV,SAAA,MAAA,CAAA,EAAA,SAAA,MAAA,EAAA;;;;;;;;;;;AAGK,uBAJJ,SAII,CAAA,mBAHL,sBAGK,GAHoB,sBAGpB,EAAA,kBAAA,MAAA,GAAA,MAAA,EAAA,kBAAA,MAAA,GAAA,MAAA,CAAA,YAAb,aAAa,CAAA;EAuDV,kBAAA,QAAkB,EAAA,MAAA;EAWlB;AAyBhB;AAyEA;;;;;;;4BAvJ4B,aAAa,WAAW;sBAE9B,aAAa,WAAW;;;;;;;sCAUR;;;;;;uBAOf;;;;;;;;;;;;;;;iBAuBP,kBAAA;iBAWA,kBAAA,CAAA;;;;;;;;;UAyBC,kBAAA;;qBAEI;;;;;;;;;;;;iBAuEL,uBAAA,WACJ,qBACA,QAAQ,4BACjB"}

package/dist/exports/migration.mjs

@@ -1,9 +1,8 @@
 import "../io-CCnYsUHU.mjs";
 import { t as computeMigrationId } from "../attestation-DtF8tEOM.mjs";
 import { type } from "arktype";
-import { dirname, join } from "pathe";
 import { ifDefined } from "@prisma-next/utils/defined";
-import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 //#region src/migration-base.ts
@@ -23,6 +22,19 @@ const MigrationMetaSchema = type({
 * migration to be valid.
 */
 var Migration = class {
+	/**
+	* Assembled `ControlStack` injected by the orchestrator (`runMigration`).
+	*
+	* Subclasses (e.g. `PostgresMigration`) read the stack to materialize their
+	* adapter once per instance. Optional at the abstract level so unit tests can
+	* construct `Migration` instances purely for `operations` / `describe`
+	* assertions without needing a real stack; concrete subclasses that need the
+	* stack at runtime should narrow the parameter to required.
+	*/
+	stack;
+	constructor(stack) {
+		this.stack = stack;
+	}
 	get origin() {
 		const from = this.describe().from;
 		return from === "" ? null : { storageHash: from };
@@ -30,46 +42,27 @@ var Migration = class {
 	get destination() {
 		return { storageHash: this.describe().to };
 	}
-	/**
-	* Entrypoint guard for migration files. When called at module scope,
-	* detects whether the file is being run directly (e.g. `node migration.ts`)
-	* and if so, serializes the migration plan to `ops.json` and
-	* `migration.json` in the same directory. When the file is imported by
-	* another module, this is a no-op.
-	*
-	* Usage (at module scope, after the class definition):
-	*
-	*     class MyMigration extends Migration { ... }
-	*     export default MyMigration;
-	*     Migration.run(import.meta.url, MyMigration);
-	*/
-	static run(importMetaUrl, MigrationClass) {
-		if (!importMetaUrl) return;
-		const metaFilename = fileURLToPath(importMetaUrl);
-		const argv1 = process.argv[1];
-		if (!argv1) return;
-		let isEntrypoint;
-		try {
-			isEntrypoint = realpathSync(metaFilename) === realpathSync(argv1);
-		} catch {
-			return;
-		}
-		if (!isEntrypoint) return;
-		const args = process.argv.slice(2);
-		if (args.includes("--help")) {
-			printHelp();
-			return;
-		}
-		const dryRun = args.includes("--dry-run");
-		const migrationDir = dirname(metaFilename);
-		try {
-			serializeMigration(MigrationClass, migrationDir, dryRun);
-		} catch (err) {
-			process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-			process.exitCode = 1;
-		}
-	}
 };
+/**
+* Returns true when `import.meta.url` resolves to the same file that was
+* invoked as the node entrypoint (`process.argv[1]`). Used by
+* `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when
+* the migration module is being imported (e.g. by another script) rather
+* than executed directly.
+*/
+function isDirectEntrypoint(importMetaUrl) {
+	const metaFilename = fileURLToPath(importMetaUrl);
+	const argv1 = process.argv[1];
+	if (!argv1) return false;
+	try {
+		return realpathSync(metaFilename) === realpathSync(argv1);
+	} catch {
+		return false;
+	}
+}
+function printMigrationHelp() {
+	printHelp();
+}
 function printHelp() {
 	process.stdout.write([
 		"Usage: node <migration-file> [options]",
@@ -81,10 +74,11 @@ function printHelp() {
 	].join("\n"));
 }
 /**
-* Build the attested manifest written by `Migration.run()`.
+* Build the attested manifest from `describe()`-derived metadata, the
+* operations list, and the previously-scaffolded manifest (if any).
 *
-* When a `migration.json` already exists in the directory (the common case:
-* the package was scaffolded by `migration plan`), preserve the contract
+* When a `migration.json` already exists for this package (the common
+* case: it was scaffolded by `migration plan`), preserve the contract
 * bookends, hints, labels, and `createdAt` set there — those fields are
 * owned by the CLI scaffolder, not the authored class. Only the
 * `describe()`-derived fields (`from`, `to`, `kind`) and the operations
@@ -96,8 +90,7 @@ function printHelp() {
 * The `migrationId` is recomputed against the current manifest + ops so
 * the on-disk artifacts are always fully attested.
 */
-function buildAttestedManifest(migrationDir, meta, ops) {
-	const existing = readExistingManifest(join(migrationDir, "migration.json"));
+function buildAttestedManifest(meta, ops, existing) {
 	const baseManifest = {
 		from: meta.from,
 		to: meta.to,
@@ -129,38 +122,28 @@ function normalizeHints(existing) {
 		plannerVersion: existing?.plannerVersion ?? "2.0.0"
 	};
 }
-function readExistingManifest(manifestPath) {
-	let raw;
-	try {
-		raw = readFileSync(manifestPath, "utf-8");
-	} catch {
-		return null;
-	}
-	try {
-		return JSON.parse(raw);
-	} catch {
-		return null;
-	}
-}
-function serializeMigration(MigrationClass, migrationDir, dryRun) {
-	const instance = new MigrationClass();
+/**
+* Pure conversion from a `Migration` instance (plus the previously
+* scaffolded manifest, when one exists on disk) to the in-memory
+* artifacts that downstream tooling persists. Owns metadata validation,
+* manifest synthesis/preservation, hint normalization, and the
+* content-addressed `migrationId` computation, but performs no file I/O
+* — callers handle reads (to source `existing`) and writes (to persist
+* `opsJson` / `manifestJson`).
+*/
+function buildMigrationArtifacts(instance, existing) {
 	const ops = instance.operations;
 	if (!Array.isArray(ops)) throw new Error("operations must be an array");
-	const serializedOps = JSON.stringify(ops, null, 2);
 	const parsed = MigrationMetaSchema(instance.describe());
 	if (parsed instanceof type.errors) throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
-	const manifest = buildAttestedManifest(migrationDir, parsed, ops);
-	if (dryRun) {
-		process.stdout.write(`--- migration.json ---\n${JSON.stringify(manifest, null, 2)}\n`);
-		process.stdout.write("--- ops.json ---\n");
-		process.stdout.write(`${serializedOps}\n`);
-		return;
-	}
-	writeFileSync(join(migrationDir, "ops.json"), serializedOps);
-	writeFileSync(join(migrationDir, "migration.json"), JSON.stringify(manifest, null, 2));
-	process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+	const manifest = buildAttestedManifest(parsed, ops, existing);
+	return {
+		opsJson: JSON.stringify(ops, null, 2),
+		manifest,
+		manifestJson: JSON.stringify(manifest, null, 2)
+	};
 }
 
 //#endregion
-export { Migration };
+export { Migration, buildMigrationArtifacts, isDirectEntrypoint, printMigrationHelp };
 //# sourceMappingURL=migration.mjs.map

package/dist/exports/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":["isEntrypoint: boolean","baseManifest: Omit<MigrationManifest, 'migrationId'>","raw: string"],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { readFileSync, realpathSync, writeFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type {\n  MigrationPlan,\n  MigrationPlanOperation,\n} from '@prisma-next/framework-components/control';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { type } from 'arktype';\nimport { dirname, join } from 'pathe';\nimport { computeMigrationId } from './attestation';\nimport type { MigrationHints, MigrationManifest, MigrationOps } from './types';\n\nexport interface MigrationMeta {\n  readonly from: string;\n  readonly to: string;\n  readonly kind?: 'regular' | 'baseline';\n  readonly labels?: readonly string[];\n}\n\nconst MigrationMetaSchema = type({\n  from: 'string',\n  to: 'string',\n  'kind?': \"'regular' | 'baseline'\",\n  'labels?': type('string').array(),\n});\n\n/**\n * Base class for migrations.\n *\n * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the\n * runner can consume it directly via `targetId`, `operations`, `origin`, and\n * `destination`. The manifest-shaped inputs come from `describe()`, which\n * every migration must implement — `migration.json` is required for a\n * migration to be valid.\n */\nexport abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation>\n  implements MigrationPlan\n{\n  abstract readonly targetId: string;\n\n  /**\n   * Ordered list of operations this migration performs.\n   *\n   * Implemented as a getter so that subclasses can either precompute the list\n   * in their constructor or build it lazily per access.\n   */\n  abstract get operations(): readonly TOperation[];\n\n  /**\n   * Metadata inputs used to build `migration.json` and to derive the plan's\n   * origin/destination identities. Every migration must provide this —\n   * omitting it would produce an invalid on-disk migration package.\n   */\n  abstract describe(): MigrationMeta;\n\n  get origin(): { readonly storageHash: string } | null {\n    const from = this.describe().from;\n    // An empty `from` represents a migration with no prior origin (e.g.\n    // initial baseline, or an in-process plan that was never persisted).\n    // Surface that as a null origin so runners treat the plan as\n    // origin-less rather than matching against an empty storage hash.\n    return from === '' ? null : { storageHash: from };\n  }\n\n  get destination(): { readonly storageHash: string } {\n    return { storageHash: this.describe().to };\n  }\n\n  /**\n   * Entrypoint guard for migration files. When called at module scope,\n   * detects whether the file is being run directly (e.g. `node migration.ts`)\n   * and if so, serializes the migration plan to `ops.json` and\n   * `migration.json` in the same directory. When the file is imported by\n   * another module, this is a no-op.\n   *\n   * Usage (at module scope, after the class definition):\n   *\n   *     class MyMigration extends Migration { ... }\n   *     export default MyMigration;\n   *     Migration.run(import.meta.url, MyMigration);\n   */\n  static run(importMetaUrl: string, MigrationClass: new () => Migration): void {\n    if (!importMetaUrl) return;\n\n    const metaFilename = fileURLToPath(importMetaUrl);\n    const argv1 = process.argv[1];\n    if (!argv1) return;\n\n    let isEntrypoint: boolean;\n    try {\n      isEntrypoint = realpathSync(metaFilename) === realpathSync(argv1);\n    } catch {\n      return;\n    }\n    if (!isEntrypoint) return;\n\n    const args = process.argv.slice(2);\n\n    if (args.includes('--help')) {\n      printHelp();\n      return;\n    }\n\n    const dryRun = args.includes('--dry-run');\n    const migrationDir = dirname(metaFilename);\n\n    try {\n      serializeMigration(MigrationClass, migrationDir, dryRun);\n    } catch (err) {\n      process.stderr.write(`${err instanceof Error ? err.message : String(err)}\\n`);\n      process.exitCode = 1;\n    }\n  }\n}\n\nfunction printHelp(): void {\n  process.stdout.write(\n    [\n      'Usage: node <migration-file> [options]',\n      '',\n      'Options:',\n      '  --dry-run  Print operations to stdout without writing files',\n      '  --help     Show this help message',\n      '',\n    ].join('\\n'),\n  );\n}\n\n/**\n * Build the attested manifest written by `Migration.run()`.\n *\n * When a `migration.json` already exists in the directory (the common case:\n * the package was scaffolded by `migration plan`), preserve the contract\n * bookends, hints, labels, and `createdAt` set there — those fields are\n * owned by the CLI scaffolder, not the authored class. Only the\n * `describe()`-derived fields (`from`, `to`, `kind`) and the operations\n * change as the author iterates. When no manifest exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant manifest so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationId` is recomputed against the current manifest + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedManifest(\n  migrationDir: string,\n  meta: MigrationMeta,\n  ops: MigrationOps,\n): MigrationManifest {\n  const existing = readExistingManifest(join(migrationDir, 'migration.json'));\n\n  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {\n    from: meta.from,\n    to: meta.to,\n    kind: meta.kind ?? 'regular',\n    labels: meta.labels ?? existing?.labels ?? [],\n    createdAt: existing?.createdAt ?? new Date().toISOString(),\n    fromContract: existing?.fromContract ?? null,\n    // When no scaffolded manifest exists we synthesize a minimal contract\n    // stub so the package is still readable end-to-end. The cast is\n    // intentional: only the storage bookend matters for hash computation\n    // (everything else is stripped by `computeMigrationId`), and a real\n    // contract bookend would only be available after `migration plan`.\n    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),\n    hints: normalizeHints(existing?.hints),\n    ...ifDefined('authorship', existing?.authorship),\n  };\n\n  const migrationId = computeMigrationId(baseManifest, ops);\n  return { ...baseManifest, migrationId };\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in manifests scaffolded by older CLI\n * versions (e.g. `planningStrategy`). Picking fields explicitly instead of\n * spreading keeps refreshed `migration.json` files schema-clean regardless\n * of what was on disk before.\n */\nfunction normalizeHints(existing: MigrationHints | undefined): MigrationHints {\n  return {\n    used: existing?.used ?? [],\n    applied: existing?.applied ?? [],\n    plannerVersion: existing?.plannerVersion ?? '2.0.0',\n  };\n}\n\nfunction readExistingManifest(manifestPath: string): Partial<MigrationManifest> | null {\n  let raw: string;\n  try {\n    raw = readFileSync(manifestPath, 'utf-8');\n  } catch {\n    return null;\n  }\n  try {\n    return JSON.parse(raw) as Partial<MigrationManifest>;\n  } catch {\n    return null;\n  }\n}\n\nfunction serializeMigration(\n  MigrationClass: new () => Migration,\n  migrationDir: string,\n  dryRun: boolean,\n): void {\n  const instance = new MigrationClass();\n\n  const ops = instance.operations;\n\n  if (!Array.isArray(ops)) {\n    throw new Error('operations must be an array');\n  }\n\n  const serializedOps = JSON.stringify(ops, null, 2);\n\n  const rawMeta: unknown = instance.describe();\n  const parsed = MigrationMetaSchema(rawMeta);\n  if (parsed instanceof type.errors) {\n    throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n  }\n\n  const manifest = buildAttestedManifest(migrationDir, parsed, ops);\n\n  if (dryRun) {\n    process.stdout.write(`--- migration.json ---\\n${JSON.stringify(manifest, null, 2)}\\n`);\n    process.stdout.write('--- ops.json ---\\n');\n    process.stdout.write(`${serializedOps}\\n`);\n    return;\n  }\n\n  writeFileSync(join(migrationDir, 'ops.json'), serializedOps);\n  writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));\n\n  process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\\n`);\n}\n"],"mappings":"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"}
+{"version":3,"file":"migration.mjs","names":["baseManifest: Omit<MigrationManifest, 'migrationId'>"],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { realpathSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport type { Contract } from '@prisma-next/contract/types';\nimport type {\n  ControlStack,\n  MigrationPlan,\n  MigrationPlanOperation,\n} from '@prisma-next/framework-components/control';\nimport { ifDefined } from '@prisma-next/utils/defined';\nimport { type } from 'arktype';\nimport { computeMigrationId } from './attestation';\nimport type { MigrationHints, MigrationManifest, MigrationOps } from './types';\n\nexport interface MigrationMeta {\n  readonly from: string;\n  readonly to: string;\n  readonly kind?: 'regular' | 'baseline';\n  readonly labels?: readonly string[];\n}\n\nconst MigrationMetaSchema = type({\n  from: 'string',\n  to: 'string',\n  'kind?': \"'regular' | 'baseline'\",\n  'labels?': type('string').array(),\n});\n\n/**\n * Base class for migrations.\n *\n * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the\n * runner can consume it directly via `targetId`, `operations`, `origin`, and\n * `destination`. The manifest-shaped inputs come from `describe()`, which\n * every migration must implement — `migration.json` is required for a\n * migration to be valid.\n */\nexport abstract class Migration<\n  TOperation extends MigrationPlanOperation = MigrationPlanOperation,\n  TFamilyId extends string = string,\n  TTargetId extends string = string,\n> implements MigrationPlan\n{\n  abstract readonly targetId: string;\n\n  /**\n   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).\n   *\n   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their\n   * adapter once per instance. Optional at the abstract level so unit tests can\n   * construct `Migration` instances purely for `operations` / `describe`\n   * assertions without needing a real stack; concrete subclasses that need the\n   * stack at runtime should narrow the parameter to required.\n   */\n  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;\n\n  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {\n    this.stack = stack;\n  }\n\n  /**\n   * Ordered list of operations this migration performs.\n   *\n   * Implemented as a getter so that subclasses can either precompute the list\n   * in their constructor or build it lazily per access.\n   */\n  abstract get operations(): readonly TOperation[];\n\n  /**\n   * Metadata inputs used to build `migration.json` and to derive the plan's\n   * origin/destination identities. Every migration must provide this —\n   * omitting it would produce an invalid on-disk migration package.\n   */\n  abstract describe(): MigrationMeta;\n\n  get origin(): { readonly storageHash: string } | null {\n    const from = this.describe().from;\n    // An empty `from` represents a migration with no prior origin (e.g.\n    // initial baseline, or an in-process plan that was never persisted).\n    // Surface that as a null origin so runners treat the plan as\n    // origin-less rather than matching against an empty storage hash.\n    return from === '' ? null : { storageHash: from };\n  }\n\n  get destination(): { readonly storageHash: string } {\n    return { storageHash: this.describe().to };\n  }\n}\n\n/**\n * Returns true when `import.meta.url` resolves to the same file that was\n * invoked as the node entrypoint (`process.argv[1]`). Used by\n * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when\n * the migration module is being imported (e.g. by another script) rather\n * than executed directly.\n */\nexport function isDirectEntrypoint(importMetaUrl: string): boolean {\n  const metaFilename = fileURLToPath(importMetaUrl);\n  const argv1 = process.argv[1];\n  if (!argv1) return false;\n  try {\n    return realpathSync(metaFilename) === realpathSync(argv1);\n  } catch {\n    return false;\n  }\n}\n\nexport function printMigrationHelp(): void {\n  printHelp();\n}\n\nfunction printHelp(): void {\n  process.stdout.write(\n    [\n      'Usage: node <migration-file> [options]',\n      '',\n      'Options:',\n      '  --dry-run  Print operations to stdout without writing files',\n      '  --help     Show this help message',\n      '',\n    ].join('\\n'),\n  );\n}\n\n/**\n * In-memory artifacts produced from a `Migration` instance: the\n * serialized `ops.json` body, the `migration.json` manifest object, and\n * its serialized form. Returned by `buildMigrationArtifacts` so callers\n * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can\n * decide how to persist them — write to disk, print in dry-run, ship\n * over the wire — without coupling artifact construction to file I/O.\n */\nexport interface MigrationArtifacts {\n  readonly opsJson: string;\n  readonly manifest: MigrationManifest;\n  readonly manifestJson: string;\n}\n\n/**\n * Build the attested manifest from `describe()`-derived metadata, the\n * operations list, and the previously-scaffolded manifest (if any).\n *\n * When a `migration.json` already exists for this package (the common\n * case: it was scaffolded by `migration plan`), preserve the contract\n * bookends, hints, labels, and `createdAt` set there — those fields are\n * owned by the CLI scaffolder, not the authored class. Only the\n * `describe()`-derived fields (`from`, `to`, `kind`) and the operations\n * change as the author iterates. When no manifest exists yet (a bare\n * `migration.ts` run from scratch), synthesize a minimal but\n * schema-conformant manifest so the resulting package can still be read,\n * verified, and applied.\n *\n * The `migrationId` is recomputed against the current manifest + ops so\n * the on-disk artifacts are always fully attested.\n */\nfunction buildAttestedManifest(\n  meta: MigrationMeta,\n  ops: MigrationOps,\n  existing: Partial<MigrationManifest> | null,\n): MigrationManifest {\n  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {\n    from: meta.from,\n    to: meta.to,\n    kind: meta.kind ?? 'regular',\n    labels: meta.labels ?? existing?.labels ?? [],\n    createdAt: existing?.createdAt ?? new Date().toISOString(),\n    fromContract: existing?.fromContract ?? null,\n    // When no scaffolded manifest exists we synthesize a minimal contract\n    // stub so the package is still readable end-to-end. The cast is\n    // intentional: only the storage bookend matters for hash computation\n    // (everything else is stripped by `computeMigrationId`), and a real\n    // contract bookend would only be available after `migration plan`.\n    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),\n    hints: normalizeHints(existing?.hints),\n    ...ifDefined('authorship', existing?.authorship),\n  };\n\n  const migrationId = computeMigrationId(baseManifest, ops);\n  return { ...baseManifest, migrationId };\n}\n\n/**\n * Project `existing.hints` down to the known `MigrationHints` shape, dropping\n * any legacy keys that may linger in manifests scaffolded by older CLI\n * versions (e.g. `planningStrategy`). Picking fields explicitly instead of\n * spreading keeps refreshed `migration.json` files schema-clean regardless\n * of what was on disk before.\n */\nfunction normalizeHints(existing: MigrationHints | undefined): MigrationHints {\n  return {\n    used: existing?.used ?? [],\n    applied: existing?.applied ?? [],\n    plannerVersion: existing?.plannerVersion ?? '2.0.0',\n  };\n}\n\n/**\n * Pure conversion from a `Migration` instance (plus the previously\n * scaffolded manifest, when one exists on disk) to the in-memory\n * artifacts that downstream tooling persists. Owns metadata validation,\n * manifest synthesis/preservation, hint normalization, and the\n * content-addressed `migrationId` computation, but performs no file I/O\n * — callers handle reads (to source `existing`) and writes (to persist\n * `opsJson` / `manifestJson`).\n */\nexport function buildMigrationArtifacts(\n  instance: Migration,\n  existing: Partial<MigrationManifest> | null,\n): MigrationArtifacts {\n  const ops = instance.operations;\n  if (!Array.isArray(ops)) {\n    throw new Error('operations must be an array');\n  }\n\n  const rawMeta: unknown = instance.describe();\n  const parsed = MigrationMetaSchema(rawMeta);\n  if (parsed instanceof type.errors) {\n    throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n  }\n\n  const manifest = buildAttestedManifest(parsed, ops, existing);\n\n  return {\n    opsJson: JSON.stringify(ops, null, 2),\n    manifest,\n    manifestJson: JSON.stringify(manifest, null, 2),\n  };\n}\n"],"mappings":";;;;;;;;AAoBA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,SAAS;CACT,WAAW,KAAK,SAAS,CAAC,OAAO;CAClC,CAAC;;;;;;;;;;AAWF,IAAsB,YAAtB,MAKA;;;;;;;;;;CAYE,AAAmB;CAEnB,YAAY,OAA4C;AACtD,OAAK,QAAQ;;CAkBf,IAAI,SAAkD;EACpD,MAAM,OAAO,KAAK,UAAU,CAAC;AAK7B,SAAO,SAAS,KAAK,OAAO,EAAE,aAAa,MAAM;;CAGnD,IAAI,cAAgD;AAClD,SAAO,EAAE,aAAa,KAAK,UAAU,CAAC,IAAI;;;;;;;;;;AAW9C,SAAgB,mBAAmB,eAAgC;CACjE,MAAM,eAAe,cAAc,cAAc;CACjD,MAAM,QAAQ,QAAQ,KAAK;AAC3B,KAAI,CAAC,MAAO,QAAO;AACnB,KAAI;AACF,SAAO,aAAa,aAAa,KAAK,aAAa,MAAM;SACnD;AACN,SAAO;;;AAIX,SAAgB,qBAA2B;AACzC,YAAW;;AAGb,SAAS,YAAkB;AACzB,SAAQ,OAAO,MACb;EACE;EACA;EACA;EACA;EACA;EACA;EACD,CAAC,KAAK,KAAK,CACb;;;;;;;;;;;;;;;;;;;AAkCH,SAAS,sBACP,MACA,KACA,UACmB;CACnB,MAAMA,eAAuD;EAC3D,MAAM,KAAK;EACX,IAAI,KAAK;EACT,MAAM,KAAK,QAAQ;EACnB,QAAQ,KAAK,UAAU,UAAU,UAAU,EAAE;EAC7C,WAAW,UAAU,8BAAa,IAAI,MAAM,EAAC,aAAa;EAC1D,cAAc,UAAU,gBAAgB;EAMxC,YAAY,UAAU,cAAe,EAAE,SAAS,EAAE,aAAa,KAAK,IAAI,EAAE;EAC1E,OAAO,eAAe,UAAU,MAAM;EACtC,GAAG,UAAU,cAAc,UAAU,WAAW;EACjD;CAED,MAAM,cAAc,mBAAmB,cAAc,IAAI;AACzD,QAAO;EAAE,GAAG;EAAc;EAAa;;;;;;;;;AAUzC,SAAS,eAAe,UAAsD;AAC5E,QAAO;EACL,MAAM,UAAU,QAAQ,EAAE;EAC1B,SAAS,UAAU,WAAW,EAAE;EAChC,gBAAgB,UAAU,kBAAkB;EAC7C;;;;;;;;;;;AAYH,SAAgB,wBACd,UACA,UACoB;CACpB,MAAM,MAAM,SAAS;AACrB,KAAI,CAAC,MAAM,QAAQ,IAAI,CACrB,OAAM,IAAI,MAAM,8BAA8B;CAIhD,MAAM,SAAS,oBADU,SAAS,UAAU,CACD;AAC3C,KAAI,kBAAkB,KAAK,OACzB,OAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;CAG5E,MAAM,WAAW,sBAAsB,QAAQ,KAAK,SAAS;AAE7D,QAAO;EACL,SAAS,KAAK,UAAU,KAAK,MAAM,EAAE;EACrC;EACA,cAAc,KAAK,UAAU,UAAU,MAAM,EAAE;EAChD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.4.1",
+  "version": "0.5.0-dev.2",
   "type": "module",
   "sideEffects": false,
   "description": "On-disk migration persistence, attestation, and chain reconstruction for Prisma Next",
@@ -8,16 +8,16 @@
     "arktype": "^2.1.29",
     "pathe": "^2.0.3",
     "prettier": "^3.6.2",
-    "@prisma-next/contract": "0.4.1",
-    "@prisma-next/framework-components": "0.4.1",
-    "@prisma-next/utils": "0.4.1"
+    "@prisma-next/contract": "0.5.0-dev.2",
+    "@prisma-next/framework-components": "0.5.0-dev.2",
+    "@prisma-next/utils": "0.5.0-dev.2"
   },
   "devDependencies": {
     "tsdown": "0.18.4",
     "typescript": "5.9.3",
     "vitest": "4.0.17",
-    "@prisma-next/tsconfig": "0.0.0",
-    "@prisma-next/tsdown": "0.0.0"
+    "@prisma-next/tsdown": "0.0.0",
+    "@prisma-next/tsconfig": "0.0.0"
   },
   "files": [
     "dist",

package/src/exports/migration.ts

@@ -1 +1,8 @@
-export { Migration, type MigrationMeta } from '../migration-base';
+export {
+  buildMigrationArtifacts,
+  isDirectEntrypoint,
+  Migration,
+  type MigrationArtifacts,
+  type MigrationMeta,
+  printMigrationHelp,
+} from '../migration-base';

package/src/migration-base.ts

@@ -1,13 +1,13 @@
-import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { Contract } from '@prisma-next/contract/types';
 import type {
+  ControlStack,
   MigrationPlan,
   MigrationPlanOperation,
 } from '@prisma-next/framework-components/control';
 import { ifDefined } from '@prisma-next/utils/defined';
 import { type } from 'arktype';
-import { dirname, join } from 'pathe';
 import { computeMigrationId } from './attestation';
 import type { MigrationHints, MigrationManifest, MigrationOps } from './types';
 
@@ -34,11 +34,29 @@ const MigrationMetaSchema = type({
  * every migration must implement — `migration.json` is required for a
  * migration to be valid.
  */
-export abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation>
-  implements MigrationPlan
+export abstract class Migration<
+  TOperation extends MigrationPlanOperation = MigrationPlanOperation,
+  TFamilyId extends string = string,
+  TTargetId extends string = string,
+> implements MigrationPlan
 {
   abstract readonly targetId: string;
 
+  /**
+   * Assembled `ControlStack` injected by the orchestrator (`runMigration`).
+   *
+   * Subclasses (e.g. `PostgresMigration`) read the stack to materialize their
+   * adapter once per instance. Optional at the abstract level so unit tests can
+   * construct `Migration` instances purely for `operations` / `describe`
+   * assertions without needing a real stack; concrete subclasses that need the
+   * stack at runtime should narrow the parameter to required.
+   */
+  protected readonly stack: ControlStack<TFamilyId, TTargetId> | undefined;
+
+  constructor(stack?: ControlStack<TFamilyId, TTargetId>) {
+    this.stack = stack;
+  }
+
   /**
    * Ordered list of operations this migration performs.
    *
@@ -66,54 +84,30 @@ export abstract class Migration<TOperation extends MigrationPlanOperation = Migr
   get destination(): { readonly storageHash: string } {
     return { storageHash: this.describe().to };
   }
+}
 
-  /**
-   * Entrypoint guard for migration files. When called at module scope,
-   * detects whether the file is being run directly (e.g. `node migration.ts`)
-   * and if so, serializes the migration plan to `ops.json` and
-   * `migration.json` in the same directory. When the file is imported by
-   * another module, this is a no-op.
-   *
-   * Usage (at module scope, after the class definition):
-   *
-   *     class MyMigration extends Migration { ... }
-   *     export default MyMigration;
-   *     Migration.run(import.meta.url, MyMigration);
-   */
-  static run(importMetaUrl: string, MigrationClass: new () => Migration): void {
-    if (!importMetaUrl) return;
-
-    const metaFilename = fileURLToPath(importMetaUrl);
-    const argv1 = process.argv[1];
-    if (!argv1) return;
-
-    let isEntrypoint: boolean;
-    try {
-      isEntrypoint = realpathSync(metaFilename) === realpathSync(argv1);
-    } catch {
-      return;
-    }
-    if (!isEntrypoint) return;
-
-    const args = process.argv.slice(2);
-
-    if (args.includes('--help')) {
-      printHelp();
-      return;
-    }
-
-    const dryRun = args.includes('--dry-run');
-    const migrationDir = dirname(metaFilename);
-
-    try {
-      serializeMigration(MigrationClass, migrationDir, dryRun);
-    } catch (err) {
-      process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-      process.exitCode = 1;
-    }
+/**
+ * Returns true when `import.meta.url` resolves to the same file that was
+ * invoked as the node entrypoint (`process.argv[1]`). Used by
+ * `MigrationCLI.run` (in `@prisma-next/cli/migration-cli`) to no-op when
+ * the migration module is being imported (e.g. by another script) rather
+ * than executed directly.
+ */
+export function isDirectEntrypoint(importMetaUrl: string): boolean {
+  const metaFilename = fileURLToPath(importMetaUrl);
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  try {
+    return realpathSync(metaFilename) === realpathSync(argv1);
+  } catch {
+    return false;
   }
 }
 
+export function printMigrationHelp(): void {
+  printHelp();
+}
+
 function printHelp(): void {
   process.stdout.write(
     [
@@ -128,10 +122,25 @@ function printHelp(): void {
 }
 
 /**
- * Build the attested manifest written by `Migration.run()`.
+ * In-memory artifacts produced from a `Migration` instance: the
+ * serialized `ops.json` body, the `migration.json` manifest object, and
+ * its serialized form. Returned by `buildMigrationArtifacts` so callers
+ * (today: `MigrationCLI.run` in `@prisma-next/cli/migration-cli`) can
+ * decide how to persist them — write to disk, print in dry-run, ship
+ * over the wire — without coupling artifact construction to file I/O.
+ */
+export interface MigrationArtifacts {
+  readonly opsJson: string;
+  readonly manifest: MigrationManifest;
+  readonly manifestJson: string;
+}
+
+/**
+ * Build the attested manifest from `describe()`-derived metadata, the
+ * operations list, and the previously-scaffolded manifest (if any).
  *
- * When a `migration.json` already exists in the directory (the common case:
- * the package was scaffolded by `migration plan`), preserve the contract
+ * When a `migration.json` already exists for this package (the common
+ * case: it was scaffolded by `migration plan`), preserve the contract
  * bookends, hints, labels, and `createdAt` set there — those fields are
  * owned by the CLI scaffolder, not the authored class. Only the
  * `describe()`-derived fields (`from`, `to`, `kind`) and the operations
@@ -144,12 +153,10 @@ function printHelp(): void {
  * the on-disk artifacts are always fully attested.
  */
 function buildAttestedManifest(
-  migrationDir: string,
   meta: MigrationMeta,
   ops: MigrationOps,
+  existing: Partial<MigrationManifest> | null,
 ): MigrationManifest {
-  const existing = readExistingManifest(join(migrationDir, 'migration.json'));
-
   const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
     from: meta.from,
     to: meta.to,
@@ -186,52 +193,35 @@ function normalizeHints(existing: MigrationHints | undefined): MigrationHints {
   };
 }
 
-function readExistingManifest(manifestPath: string): Partial<MigrationManifest> | null {
-  let raw: string;
-  try {
-    raw = readFileSync(manifestPath, 'utf-8');
-  } catch {
-    return null;
-  }
-  try {
-    return JSON.parse(raw) as Partial<MigrationManifest>;
-  } catch {
-    return null;
-  }
-}
-
-function serializeMigration(
-  MigrationClass: new () => Migration,
-  migrationDir: string,
-  dryRun: boolean,
-): void {
-  const instance = new MigrationClass();
-
+/**
+ * Pure conversion from a `Migration` instance (plus the previously
+ * scaffolded manifest, when one exists on disk) to the in-memory
+ * artifacts that downstream tooling persists. Owns metadata validation,
+ * manifest synthesis/preservation, hint normalization, and the
+ * content-addressed `migrationId` computation, but performs no file I/O
+ * — callers handle reads (to source `existing`) and writes (to persist
+ * `opsJson` / `manifestJson`).
+ */
+export function buildMigrationArtifacts(
+  instance: Migration,
+  existing: Partial<MigrationManifest> | null,
+): MigrationArtifacts {
   const ops = instance.operations;
-
   if (!Array.isArray(ops)) {
     throw new Error('operations must be an array');
   }
 
-  const serializedOps = JSON.stringify(ops, null, 2);
-
   const rawMeta: unknown = instance.describe();
   const parsed = MigrationMetaSchema(rawMeta);
   if (parsed instanceof type.errors) {
     throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
   }
 
-  const manifest = buildAttestedManifest(migrationDir, parsed, ops);
+  const manifest = buildAttestedManifest(parsed, ops, existing);
 
-  if (dryRun) {
-    process.stdout.write(`--- migration.json ---\n${JSON.stringify(manifest, null, 2)}\n`);
-    process.stdout.write('--- ops.json ---\n');
-    process.stdout.write(`${serializedOps}\n`);
-    return;
-  }
-
-  writeFileSync(join(migrationDir, 'ops.json'), serializedOps);
-  writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));
-
-  process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
+  return {
+    opsJson: JSON.stringify(ops, null, 2),
+    manifest,
+    manifestJson: JSON.stringify(manifest, null, 2),
+  };
 }

package/src/migration-ts.ts

@@ -17,7 +17,11 @@ const MIGRATION_TS_FILE = 'migration.ts';
  * Writes a pre-rendered `migration.ts` source string to the given package
  * directory. If the source begins with a shebang, the file is written with
  * executable permissions (0o755) so it can be run directly via
- * `./migration.ts` by the authoring class's `Migration.run(...)` guard.
+ * `./migration.ts` — the rendered scaffold ends with
+ * `MigrationCLI.run(import.meta.url, M)` from
+ * `@prisma-next/cli/migration-cli` (re-exported by the postgres facade),
+ * which guards on the entrypoint and serializes when the file is the main
+ * module.
  *
  * The source is run through prettier before writing so migration renderers
  * can produce structurally-correct but loosely-indented source and rely on