@prisma-next/migration-tools 0.4.0-dev.6 → 0.4.0-dev.8

package/dist/exports/migration.mjs

@@ -1,6 +1,9 @@
+import "../io-Cun81AIZ.mjs";
+import { n as computeMigrationId } from "../attestation-DnebS4XZ.mjs";
 import { type } from "arktype";
 import { dirname, join } from "pathe";
-import { realpathSync, writeFileSync } from "node:fs";
+import { ifDefined } from "@prisma-next/utils/defined";
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 //#region src/migration-base.ts
@@ -8,15 +11,30 @@ const MigrationMetaSchema = type({
 	from: "string",
 	to: "string",
 	"kind?": "'regular' | 'baseline'",
-	"labels?": "string[]"
+	"labels?": type("string").array()
 });
+/**
+* Base class for class-flow migrations.
+*
+* A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the
+* runner can consume it directly via `targetId`, `operations`, `origin`, and
+* `destination`. The manifest-shaped inputs come from `describe()`, which
+* every migration must implement — `migration.json` is required for a
+* migration to be valid.
+*/
 var Migration = class {
-	describe() {}
+	get origin() {
+		const from = this.describe().from;
+		return from === "" ? null : { storageHash: from };
+	}
+	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. `tsx migration.ts`)
-	* and if so, serializes the migration plan to `ops.json` (and optionally
-	* `migration.json`) in the same directory. When the file is imported by
+	* 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):
@@ -54,7 +72,7 @@ var Migration = class {
 };
 function printHelp() {
 	process.stdout.write([
-		"Usage: tsx <migration-file> [options]",
+		"Usage: node <migration-file> [options]",
 		"",
 		"Options:",
 		"  --dry-run  Print operations to stdout without writing files",
@@ -62,42 +80,78 @@ function printHelp() {
 		""
 	].join("\n"));
 }
-function buildManifest(meta) {
-	return {
+/**
+* Build the attested manifest written by `Migration.run()`.
+*
+* When a `migration.json` already exists in the directory (the common case:
+* the package 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
+* change as the author iterates. When no manifest exists yet (a bare
+* `migration.ts` run from scratch), synthesize a minimal but
+* schema-conformant manifest so the resulting package can still be read,
+* verified, and applied.
+*
+* In both cases the `migrationId` is recomputed against the current
+* manifest + ops so the on-disk artifacts are always fully attested — no
+* draft (`migrationId: null`) ever leaves this function.
+*/
+function buildAttestedManifest(migrationDir, meta, ops) {
+	const existing = readExistingManifest(join(migrationDir, "migration.json"));
+	const baseManifest = {
 		migrationId: null,
 		from: meta.from,
 		to: meta.to,
 		kind: meta.kind ?? "regular",
-		labels: meta.labels ?? [],
-		createdAt: (/* @__PURE__ */ new Date()).toISOString()
+		labels: meta.labels ?? existing?.labels ?? [],
+		createdAt: existing?.createdAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		fromContract: existing?.fromContract ?? null,
+		toContract: existing?.toContract ?? { storage: { storageHash: meta.to } },
+		hints: existing?.hints ?? {
+			used: [],
+			applied: [],
+			plannerVersion: "2.0.0",
+			planningStrategy: "class-based"
+		},
+		...ifDefined("authorship", existing?.authorship)
+	};
+	const migrationId = computeMigrationId(baseManifest, ops);
+	return {
+		...baseManifest,
+		migrationId
 	};
 }
+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();
-	const ops = instance.plan();
-	if (!Array.isArray(ops)) throw new Error("plan() must return an array of operations");
+	const ops = instance.operations;
+	if (!Array.isArray(ops)) throw new Error("operations must be an array");
 	const serializedOps = JSON.stringify(ops, null, 2);
-	let manifest;
-	if (typeof instance.describe === "function") {
-		const rawMeta = instance.describe();
-		if (rawMeta !== void 0) {
-			const parsed = MigrationMetaSchema(rawMeta);
-			if (parsed instanceof type.errors) throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
-			manifest = buildManifest(parsed);
-		}
-	}
+	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) {
-		if (manifest) {
-			process.stdout.write(`--- migration.json ---\n${JSON.stringify(manifest, null, 2)}\n`);
-			process.stdout.write("--- ops.json ---\n");
-		}
+		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);
-	if (manifest) writeFileSync(join(migrationDir, "migration.json"), JSON.stringify(manifest, null, 2));
-	const files = manifest ? "ops.json + migration.json" : "ops.json";
-	process.stdout.write(`Wrote ${files} to ${migrationDir}\n`);
+	writeFileSync(join(migrationDir, "migration.json"), JSON.stringify(manifest, null, 2));
+	process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
 }
 
 //#endregion

package/dist/exports/migration.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migration.mjs","names":["isEntrypoint: boolean","manifest: Record<string, unknown> | undefined","rawMeta: unknown"],"sources":["../../src/migration-base.ts"],"sourcesContent":["import { realpathSync, writeFileSync } from 'node:fs';\nimport { fileURLToPath } from 'node:url';\nimport { type } from 'arktype';\nimport { dirname, join } from 'pathe';\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?': 'string[]',\n});\n\nexport abstract class Migration<TOperation = unknown> {\n  abstract plan(): TOperation[];\n\n  describe(): MigrationMeta | undefined {\n    return undefined;\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. `tsx migration.ts`)\n   * and if so, serializes the migration plan to `ops.json` (and optionally\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: tsx <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\nfunction buildManifest(meta: MigrationMeta): Record<string, unknown> {\n  return {\n    migrationId: null,\n    from: meta.from,\n    to: meta.to,\n    kind: meta.kind ?? 'regular',\n    labels: meta.labels ?? [],\n    createdAt: new Date().toISOString(),\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.plan();\n\n  if (!Array.isArray(ops)) {\n    throw new Error('plan() must return an array of operations');\n  }\n\n  const serializedOps = JSON.stringify(ops, null, 2);\n\n  let manifest: Record<string, unknown> | undefined;\n  if (typeof instance.describe === 'function') {\n    const rawMeta: unknown = instance.describe();\n    if (rawMeta !== undefined) {\n      const parsed = MigrationMetaSchema(rawMeta);\n      if (parsed instanceof type.errors) {\n        throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);\n      }\n      manifest = buildManifest(parsed);\n    }\n  }\n\n  if (dryRun) {\n    if (manifest) {\n      process.stdout.write(`--- migration.json ---\\n${JSON.stringify(manifest, null, 2)}\\n`);\n      process.stdout.write('--- ops.json ---\\n');\n    }\n    process.stdout.write(`${serializedOps}\\n`);\n    return;\n  }\n\n  writeFileSync(join(migrationDir, 'ops.json'), serializedOps);\n  if (manifest) {\n    writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));\n  }\n\n  const files = manifest ? 'ops.json + migration.json' : 'ops.json';\n  process.stdout.write(`Wrote ${files} to ${migrationDir}\\n`);\n}\n"],"mappings":";;;;;;AAYA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,SAAS;CACT,WAAW;CACZ,CAAC;AAEF,IAAsB,YAAtB,MAAsD;CAGpD,WAAsC;;;;;;;;;;;;;;CAiBtC,OAAO,IAAI,eAAuB,gBAA2C;AAC3E,MAAI,CAAC,cAAe;EAEpB,MAAM,eAAe,cAAc,cAAc;EACjD,MAAM,QAAQ,QAAQ,KAAK;AAC3B,MAAI,CAAC,MAAO;EAEZ,IAAIA;AACJ,MAAI;AACF,kBAAe,aAAa,aAAa,KAAK,aAAa,MAAM;UAC3D;AACN;;AAEF,MAAI,CAAC,aAAc;EAEnB,MAAM,OAAO,QAAQ,KAAK,MAAM,EAAE;AAElC,MAAI,KAAK,SAAS,SAAS,EAAE;AAC3B,cAAW;AACX;;EAGF,MAAM,SAAS,KAAK,SAAS,YAAY;EACzC,MAAM,eAAe,QAAQ,aAAa;AAE1C,MAAI;AACF,sBAAmB,gBAAgB,cAAc,OAAO;WACjD,KAAK;AACZ,WAAQ,OAAO,MAAM,GAAG,eAAe,QAAQ,IAAI,UAAU,OAAO,IAAI,CAAC,IAAI;AAC7E,WAAQ,WAAW;;;;AAKzB,SAAS,YAAkB;AACzB,SAAQ,OAAO,MACb;EACE;EACA;EACA;EACA;EACA;EACA;EACD,CAAC,KAAK,KAAK,CACb;;AAGH,SAAS,cAAc,MAA8C;AACnE,QAAO;EACL,aAAa;EACb,MAAM,KAAK;EACX,IAAI,KAAK;EACT,MAAM,KAAK,QAAQ;EACnB,QAAQ,KAAK,UAAU,EAAE;EACzB,4BAAW,IAAI,MAAM,EAAC,aAAa;EACpC;;AAGH,SAAS,mBACP,gBACA,cACA,QACM;CACN,MAAM,WAAW,IAAI,gBAAgB;CAErC,MAAM,MAAM,SAAS,MAAM;AAE3B,KAAI,CAAC,MAAM,QAAQ,IAAI,CACrB,OAAM,IAAI,MAAM,4CAA4C;CAG9D,MAAM,gBAAgB,KAAK,UAAU,KAAK,MAAM,EAAE;CAElD,IAAIC;AACJ,KAAI,OAAO,SAAS,aAAa,YAAY;EAC3C,MAAMC,UAAmB,SAAS,UAAU;AAC5C,MAAI,YAAY,QAAW;GACzB,MAAM,SAAS,oBAAoB,QAAQ;AAC3C,OAAI,kBAAkB,KAAK,OACzB,OAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;AAE5E,cAAW,cAAc,OAAO;;;AAIpC,KAAI,QAAQ;AACV,MAAI,UAAU;AACZ,WAAQ,OAAO,MAAM,2BAA2B,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC,IAAI;AACtF,WAAQ,OAAO,MAAM,qBAAqB;;AAE5C,UAAQ,OAAO,MAAM,GAAG,cAAc,IAAI;AAC1C;;AAGF,eAAc,KAAK,cAAc,WAAW,EAAE,cAAc;AAC5D,KAAI,SACF,eAAc,KAAK,cAAc,iBAAiB,EAAE,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC;CAGxF,MAAM,QAAQ,WAAW,8BAA8B;AACvD,SAAQ,OAAO,MAAM,SAAS,MAAM,MAAM,aAAa,IAAI"}
+{"version":3,"file":"migration.mjs","names":["isEntrypoint: boolean","baseManifest: MigrationManifest","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 { 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 class-flow 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 * In both cases the `migrationId` is recomputed against the current\n * manifest + ops so the on-disk artifacts are always fully attested — no\n * draft (`migrationId: null`) ever leaves this function.\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: MigrationManifest = {\n    migrationId: null,\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: existing?.hints ?? {\n      used: [],\n      applied: [],\n      plannerVersion: '2.0.0',\n      planningStrategy: 'class-based',\n    },\n    ...ifDefined('authorship', existing?.authorship),\n  };\n\n  const migrationId = computeMigrationId(baseManifest, ops);\n  return { ...baseManifest, migrationId };\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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"}

package/dist/exports/types.d.mts

@@ -1,4 +1,4 @@
-import { a as DraftMigrationManifest, c as MigrationHints, d as isAttested, f as isDraft, i as DraftMigrationBundle, l as MigrationManifest, n as AttestedMigrationManifest, o as MigrationChainEntry, r as BaseMigrationBundle, s as MigrationGraph, t as AttestedMigrationBundle, u as MigrationOps } from "../types-DXjq7Fum.mjs";
+import { a as DraftMigrationManifest, c as MigrationHints, d as isAttested, f as isDraft, i as DraftMigrationBundle, l as MigrationManifest, n as AttestedMigrationManifest, o as MigrationChainEntry, r as BaseMigrationBundle, s as MigrationGraph, t as AttestedMigrationBundle, u as MigrationOps } from "../types-D2uX4ql7.mjs";
 
 //#region src/errors.d.ts
 

package/dist/{io-BO18-Evu.mjs → io-Cun81AIZ.mjs}

@@ -1,5 +1,5 @@
 import { a as errorInvalidJson, d as errorMissingFile, o as errorInvalidManifest, r as errorDirectoryExists, u as errorInvalidSlug } from "./errors-C_XuSbX7.mjs";
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { type } from "arktype";
 import { basename, dirname, join } from "pathe";
 
@@ -50,6 +50,27 @@ async function writeMigrationPackage(dir, manifest, ops) {
 	await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: "wx" });
 	await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: "wx" });
 }
+/**
+* Copy the destination contract artifacts (`contract.json` and the
+* colocated `contract.d.ts`) into the migration package directory so
+* authors of the scaffolded `migration.ts` can import the typed
+* contract relative to the migration directory
+* (`import type { Contract } from './contract'`).
+*
+* A missing `.d.ts` is tolerated (only the `.json` is required) so the
+* helper stays usable in tests that hand-roll a bare `contract.json`.
+* A missing `contract.json` — or any other I/O failure — throws.
+*/
+async function copyContractToMigrationDir(packageDir, contractJsonPath) {
+	await copyFile(contractJsonPath, join(packageDir, "contract.json"));
+	const dtsPath = `${contractJsonPath.slice(0, -5)}.d.ts`;
+	try {
+		await copyFile(dtsPath, join(packageDir, "contract.d.ts"));
+	} catch (error) {
+		if (hasErrnoCode(error, "ENOENT")) return;
+		throw error;
+	}
+}
 async function writeMigrationManifest(dir, manifest) {
 	await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
 }
@@ -132,5 +153,5 @@ function formatMigrationDirName(timestamp, slug) {
 }
 
 //#endregion
-export { writeMigrationOps as a, writeMigrationManifest as i, readMigrationPackage as n, writeMigrationPackage as o, readMigrationsDir as r, formatMigrationDirName as t };
-//# sourceMappingURL=io-BO18-Evu.mjs.map
+export { writeMigrationManifest as a, readMigrationsDir as i, formatMigrationDirName as n, writeMigrationOps as o, readMigrationPackage as r, writeMigrationPackage as s, copyContractToMigrationDir as t };
+//# sourceMappingURL=io-Cun81AIZ.mjs.map

package/dist/io-Cun81AIZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"io-Cun81AIZ.mjs","names":["manifestRaw: string","opsRaw: string","manifest: MigrationManifest","ops: MigrationOps","entries: string[]","packages: BaseMigrationBundle[]"],"sources":["../src/io.ts"],"sourcesContent":["import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';\nimport { type } from 'arktype';\nimport { basename, dirname, join } from 'pathe';\nimport {\n  errorDirectoryExists,\n  errorInvalidJson,\n  errorInvalidManifest,\n  errorInvalidSlug,\n  errorMissingFile,\n} from './errors';\nimport type { BaseMigrationBundle, MigrationManifest, MigrationOps } from './types';\n\nconst MANIFEST_FILE = 'migration.json';\nconst OPS_FILE = 'ops.json';\nconst MAX_SLUG_LENGTH = 64;\n\nfunction hasErrnoCode(error: unknown, code: string): boolean {\n  return error instanceof Error && (error as { code?: string }).code === code;\n}\n\nconst MigrationHintsSchema = type({\n  used: 'string[]',\n  applied: 'string[]',\n  plannerVersion: 'string',\n  planningStrategy: 'string',\n});\n\nconst MigrationManifestSchema = type({\n  from: 'string',\n  to: 'string',\n  migrationId: 'string | null',\n  kind: \"'regular' | 'baseline'\",\n  fromContract: 'object | null',\n  toContract: 'object',\n  hints: MigrationHintsSchema,\n  labels: 'string[]',\n  'authorship?': type({\n    'author?': 'string',\n    'email?': 'string',\n  }),\n  'signature?': type({\n    keyId: 'string',\n    value: 'string',\n  }).or('null'),\n  createdAt: 'string',\n});\n\nconst MigrationOpSchema = type({\n  id: 'string',\n  label: 'string',\n  operationClass: \"'additive' | 'widening' | 'destructive' | 'data'\",\n});\n\n// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.\nconst MigrationOpsSchema = MigrationOpSchema.array();\n\nexport async function writeMigrationPackage(\n  dir: string,\n  manifest: MigrationManifest,\n  ops: MigrationOps,\n): Promise<void> {\n  await mkdir(dirname(dir), { recursive: true });\n\n  try {\n    await mkdir(dir);\n  } catch (error) {\n    if (hasErrnoCode(error, 'EEXIST')) {\n      throw errorDirectoryExists(dir);\n    }\n    throw error;\n  }\n\n  await writeFile(join(dir, MANIFEST_FILE), JSON.stringify(manifest, null, 2), { flag: 'wx' });\n  await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });\n}\n\n/**\n * Copy the destination contract artifacts (`contract.json` and the\n * colocated `contract.d.ts`) into the migration package directory so\n * authors of the scaffolded `migration.ts` can import the typed\n * contract relative to the migration directory\n * (`import type { Contract } from './contract'`).\n *\n * A missing `.d.ts` is tolerated (only the `.json` is required) so the\n * helper stays usable in tests that hand-roll a bare `contract.json`.\n * A missing `contract.json` — or any other I/O failure — throws.\n */\nexport async function copyContractToMigrationDir(\n  packageDir: string,\n  contractJsonPath: string,\n): Promise<void> {\n  await copyFile(contractJsonPath, join(packageDir, 'contract.json'));\n  const dtsPath = `${contractJsonPath.slice(0, -'.json'.length)}.d.ts`;\n  try {\n    await copyFile(dtsPath, join(packageDir, 'contract.d.ts'));\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) return;\n    throw error;\n  }\n}\n\nexport async function writeMigrationManifest(\n  dir: string,\n  manifest: MigrationManifest,\n): Promise<void> {\n  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\\n`);\n}\n\nexport async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {\n  await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\\n`);\n}\n\nexport async function readMigrationPackage(dir: string): Promise<BaseMigrationBundle> {\n  const manifestPath = join(dir, MANIFEST_FILE);\n  const opsPath = join(dir, OPS_FILE);\n\n  let manifestRaw: string;\n  try {\n    manifestRaw = await readFile(manifestPath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile(MANIFEST_FILE, dir);\n    }\n    throw error;\n  }\n\n  let opsRaw: string;\n  try {\n    opsRaw = await readFile(opsPath, 'utf-8');\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      throw errorMissingFile(OPS_FILE, dir);\n    }\n    throw error;\n  }\n\n  let manifest: MigrationManifest;\n  try {\n    manifest = JSON.parse(manifestRaw);\n  } catch (e) {\n    throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));\n  }\n\n  let ops: MigrationOps;\n  try {\n    ops = JSON.parse(opsRaw);\n  } catch (e) {\n    throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));\n  }\n\n  validateManifest(manifest, manifestPath);\n  validateOps(ops, opsPath);\n\n  return {\n    dirName: basename(dir),\n    dirPath: dir,\n    manifest,\n    ops,\n  };\n}\n\nfunction validateManifest(\n  manifest: unknown,\n  filePath: string,\n): asserts manifest is MigrationManifest {\n  const result = MigrationManifestSchema(manifest);\n  if (result instanceof type.errors) {\n    throw errorInvalidManifest(filePath, result.summary);\n  }\n}\n\nfunction validateOps(ops: unknown, filePath: string): asserts ops is MigrationOps {\n  const result = MigrationOpsSchema(ops);\n  if (result instanceof type.errors) {\n    throw errorInvalidManifest(filePath, result.summary);\n  }\n}\n\nexport async function readMigrationsDir(\n  migrationsRoot: string,\n): Promise<readonly BaseMigrationBundle[]> {\n  let entries: string[];\n  try {\n    entries = await readdir(migrationsRoot);\n  } catch (error) {\n    if (hasErrnoCode(error, 'ENOENT')) {\n      return [];\n    }\n    throw error;\n  }\n\n  const packages: BaseMigrationBundle[] = [];\n\n  for (const entry of entries.sort()) {\n    const entryPath = join(migrationsRoot, entry);\n    const entryStat = await stat(entryPath);\n    if (!entryStat.isDirectory()) continue;\n\n    const manifestPath = join(entryPath, MANIFEST_FILE);\n    try {\n      await stat(manifestPath);\n    } catch {\n      continue; // skip non-migration directories\n    }\n\n    packages.push(await readMigrationPackage(entryPath));\n  }\n\n  return packages;\n}\n\nexport function formatMigrationDirName(timestamp: Date, slug: string): string {\n  const sanitized = slug\n    .toLowerCase()\n    .replace(/[^a-z0-9]/g, '_')\n    .replace(/_+/g, '_')\n    .replace(/^_|_$/g, '');\n\n  if (sanitized.length === 0) {\n    throw errorInvalidSlug(slug);\n  }\n\n  const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);\n\n  const y = timestamp.getUTCFullYear();\n  const mo = String(timestamp.getUTCMonth() + 1).padStart(2, '0');\n  const d = String(timestamp.getUTCDate()).padStart(2, '0');\n  const h = String(timestamp.getUTCHours()).padStart(2, '0');\n  const mi = String(timestamp.getUTCMinutes()).padStart(2, '0');\n\n  return `${y}${mo}${d}T${h}${mi}_${truncated}`;\n}\n"],"mappings":";;;;;;AAYA,MAAM,gBAAgB;AACtB,MAAM,WAAW;AACjB,MAAM,kBAAkB;AAExB,SAAS,aAAa,OAAgB,MAAuB;AAC3D,QAAO,iBAAiB,SAAU,MAA4B,SAAS;;AAUzE,MAAM,0BAA0B,KAAK;CACnC,MAAM;CACN,IAAI;CACJ,aAAa;CACb,MAAM;CACN,cAAc;CACd,YAAY;CACZ,OAd2B,KAAK;EAChC,MAAM;EACN,SAAS;EACT,gBAAgB;EAChB,kBAAkB;EACnB,CAAC;CAUA,QAAQ;CACR,eAAe,KAAK;EAClB,WAAW;EACX,UAAU;EACX,CAAC;CACF,cAAc,KAAK;EACjB,OAAO;EACP,OAAO;EACR,CAAC,CAAC,GAAG,OAAO;CACb,WAAW;CACZ,CAAC;AASF,MAAM,qBAPoB,KAAK;CAC7B,IAAI;CACJ,OAAO;CACP,gBAAgB;CACjB,CAAC,CAG2C,OAAO;AAEpD,eAAsB,sBACpB,KACA,UACA,KACe;AACf,OAAM,MAAM,QAAQ,IAAI,EAAE,EAAE,WAAW,MAAM,CAAC;AAE9C,KAAI;AACF,QAAM,MAAM,IAAI;UACT,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,OAAM,qBAAqB,IAAI;AAEjC,QAAM;;AAGR,OAAM,UAAU,KAAK,KAAK,cAAc,EAAE,KAAK,UAAU,UAAU,MAAM,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;AAC5F,OAAM,UAAU,KAAK,KAAK,SAAS,EAAE,KAAK,UAAU,KAAK,MAAM,EAAE,EAAE,EAAE,MAAM,MAAM,CAAC;;;;;;;;;;;;;AAcpF,eAAsB,2BACpB,YACA,kBACe;AACf,OAAM,SAAS,kBAAkB,KAAK,YAAY,gBAAgB,CAAC;CACnE,MAAM,UAAU,GAAG,iBAAiB,MAAM,GAAG,GAAgB,CAAC;AAC9D,KAAI;AACF,QAAM,SAAS,SAAS,KAAK,YAAY,gBAAgB,CAAC;UACnD,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAAE;AACnC,QAAM;;;AAIV,eAAsB,uBACpB,KACA,UACe;AACf,OAAM,UAAU,KAAK,KAAK,cAAc,EAAE,GAAG,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC,IAAI;;AAGrF,eAAsB,kBAAkB,KAAa,KAAkC;AACrF,OAAM,UAAU,KAAK,KAAK,SAAS,EAAE,GAAG,KAAK,UAAU,KAAK,MAAM,EAAE,CAAC,IAAI;;AAG3E,eAAsB,qBAAqB,KAA2C;CACpF,MAAM,eAAe,KAAK,KAAK,cAAc;CAC7C,MAAM,UAAU,KAAK,KAAK,SAAS;CAEnC,IAAIA;AACJ,KAAI;AACF,gBAAc,MAAM,SAAS,cAAc,QAAQ;UAC5C,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,OAAM,iBAAiB,eAAe,IAAI;AAE5C,QAAM;;CAGR,IAAIC;AACJ,KAAI;AACF,WAAS,MAAM,SAAS,SAAS,QAAQ;UAClC,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,OAAM,iBAAiB,UAAU,IAAI;AAEvC,QAAM;;CAGR,IAAIC;AACJ,KAAI;AACF,aAAW,KAAK,MAAM,YAAY;UAC3B,GAAG;AACV,QAAM,iBAAiB,cAAc,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,CAAC;;CAGlF,IAAIC;AACJ,KAAI;AACF,QAAM,KAAK,MAAM,OAAO;UACjB,GAAG;AACV,QAAM,iBAAiB,SAAS,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,CAAC;;AAG7E,kBAAiB,UAAU,aAAa;AACxC,aAAY,KAAK,QAAQ;AAEzB,QAAO;EACL,SAAS,SAAS,IAAI;EACtB,SAAS;EACT;EACA;EACD;;AAGH,SAAS,iBACP,UACA,UACuC;CACvC,MAAM,SAAS,wBAAwB,SAAS;AAChD,KAAI,kBAAkB,KAAK,OACzB,OAAM,qBAAqB,UAAU,OAAO,QAAQ;;AAIxD,SAAS,YAAY,KAAc,UAA+C;CAChF,MAAM,SAAS,mBAAmB,IAAI;AACtC,KAAI,kBAAkB,KAAK,OACzB,OAAM,qBAAqB,UAAU,OAAO,QAAQ;;AAIxD,eAAsB,kBACpB,gBACyC;CACzC,IAAIC;AACJ,KAAI;AACF,YAAU,MAAM,QAAQ,eAAe;UAChC,OAAO;AACd,MAAI,aAAa,OAAO,SAAS,CAC/B,QAAO,EAAE;AAEX,QAAM;;CAGR,MAAMC,WAAkC,EAAE;AAE1C,MAAK,MAAM,SAAS,QAAQ,MAAM,EAAE;EAClC,MAAM,YAAY,KAAK,gBAAgB,MAAM;AAE7C,MAAI,EADc,MAAM,KAAK,UAAU,EACxB,aAAa,CAAE;EAE9B,MAAM,eAAe,KAAK,WAAW,cAAc;AACnD,MAAI;AACF,SAAM,KAAK,aAAa;UAClB;AACN;;AAGF,WAAS,KAAK,MAAM,qBAAqB,UAAU,CAAC;;AAGtD,QAAO;;AAGT,SAAgB,uBAAuB,WAAiB,MAAsB;CAC5E,MAAM,YAAY,KACf,aAAa,CACb,QAAQ,cAAc,IAAI,CAC1B,QAAQ,OAAO,IAAI,CACnB,QAAQ,UAAU,GAAG;AAExB,KAAI,UAAU,WAAW,EACvB,OAAM,iBAAiB,KAAK;CAG9B,MAAM,YAAY,UAAU,MAAM,GAAG,gBAAgB;AAQrD,QAAO,GANG,UAAU,gBAAgB,GACzB,OAAO,UAAU,aAAa,GAAG,EAAE,CAAC,SAAS,GAAG,IAAI,GACrD,OAAO,UAAU,YAAY,CAAC,CAAC,SAAS,GAAG,IAAI,CAIpC,GAHX,OAAO,UAAU,aAAa,CAAC,CAAC,SAAS,GAAG,IAAI,GAC/C,OAAO,UAAU,eAAe,CAAC,CAAC,SAAS,GAAG,IAAI,CAE9B,GAAG"}

package/dist/{types-DXjq7Fum.d.mts → types-D2uX4ql7.d.mts}

@@ -97,4 +97,4 @@ declare function isAttested(bundle: BaseMigrationBundle): bundle is AttestedMigr
 declare function isDraft(bundle: BaseMigrationBundle): bundle is DraftMigrationBundle;
 //#endregion
 export { DraftMigrationManifest as a, MigrationHints as c, isAttested as d, isDraft as f, DraftMigrationBundle as i, MigrationManifest as l, AttestedMigrationManifest as n, MigrationChainEntry as o, BaseMigrationBundle as r, MigrationGraph as s, AttestedMigrationBundle as t, MigrationOps as u };
-//# sourceMappingURL=types-DXjq7Fum.d.mts.map
+//# sourceMappingURL=types-D2uX4ql7.d.mts.map

package/dist/{types-DXjq7Fum.d.mts.map → types-D2uX4ql7.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"types-DXjq7Fum.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,cAAA;;EAAA,SAAA,OAAA,EAAc,SAAA,MAAA,EAAA;EAUrB,SAAA,cAAA,EAAqB,MAAA;EAIN,SAAA,gBAAA,EAAA,MAAA;;;;AAczB;AAQA,UA1BU,qBAAA,CA0BiC;EAS/B,SAAA,IAAA,EAAA,MAAiB;EAEjB,SAAA,EAAA,EAAA,MAAY;EAMP,SAAA,IAAA,EAAA,SAAmB,GAAA,UAGf;EAQJ,SAAA,YAAA,EAlDQ,QAkDgB,GAAA,IACpB;EAGJ,SAAA,UAAA,EArDM,QAqDe;EAQrB,SAAA,KAAA,EA5DC,cA4DkB;EASnB,SAAA,MAAA,EAAc,SAAA,MAAA,EAAA;EACb,SAAA,UAAA,CAAA,EAAA;IACoC,SAAA,MAAA,CAAA,EAAA,MAAA;IAA7B,SAAA,KAAA,CAAA,EAAA,MAAA;EAC6B,CAAA;EAA7B,SAAA,SAAA,CAAA,EAAA;IACqB,SAAA,KAAA,EAAA,MAAA;IAApB,SAAA,KAAA,EAAA,MAAA;EAAW,CAAA,GAAA,IAAA;EAOrB,SAAA,SAAU,EAAA,MAAS;AAInC;;;;;;UAxEiB,sBAAA,SAA+B;;;;;;;UAQ/B,yBAAA,SAAkC;;;;;;;;KASvC,iBAAA,GAAoB,yBAAyB;KAE7C,YAAA,YAAwB;;;;;UAMnB,mBAAA;;;qBAGI;gBACL;;;;;;UAOC,uBAAA,SAAgC;qBAC5B;;UAGJ,oBAAA,SAA6B;qBACzB;;;;;;UAOJ,mBAAA;;;;;;;;UASA,cAAA;kBACC;yBACO,6BAA6B;yBAC7B,6BAA6B;0BAC5B,oBAAoB;;;;;;iBAO9B,UAAA,SAAmB,gCAAgC;iBAInD,OAAA,SAAgB,gCAAgC"}
+{"version":3,"file":"types-D2uX4ql7.d.mts","names":[],"sources":["../src/types.ts"],"sourcesContent":[],"mappings":";;;;UAGiB,cAAA;;EAAA,SAAA,OAAA,EAAc,SAAA,MAAA,EAAA;EAUrB,SAAA,cAAA,EAAqB,MAAA;EAIN,SAAA,gBAAA,EAAA,MAAA;;;;AAczB;AAQA,UA1BU,qBAAA,CA0BiC;EAS/B,SAAA,IAAA,EAAA,MAAiB;EAEjB,SAAA,EAAA,EAAA,MAAY;EAMP,SAAA,IAAA,EAAA,SAAmB,GAAA,UAGf;EAQJ,SAAA,YAAA,EAlDQ,QAkDgB,GAAA,IACpB;EAGJ,SAAA,UAAA,EArDM,QAqDe;EAQrB,SAAA,KAAA,EA5DC,cA4DkB;EASnB,SAAA,MAAA,EAAc,SAAA,MAAA,EAAA;EACb,SAAA,UAAA,CAAA,EAAA;IACoC,SAAA,MAAA,CAAA,EAAA,MAAA;IAA7B,SAAA,KAAA,CAAA,EAAA,MAAA;EAC6B,CAAA;EAA7B,SAAA,SAAA,CAAA,EAAA;IACqB,SAAA,KAAA,EAAA,MAAA;IAApB,SAAA,KAAA,EAAA,MAAA;EAAW,CAAA,GAAA,IAAA;EAOrB,SAAA,SAAU,EAAA,MAAS;AAInC;;;;;;UAxEiB,sBAAA,SAA+B;;;;;;;UAQ/B,yBAAA,SAAkC;;;;;;;;KASvC,iBAAA,GAAoB,yBAAyB;KAE7C,YAAA,YAAwB;;;;;UAMnB,mBAAA;;;qBAGI;gBACL;;;;;;UAOC,uBAAA,SAAgC;qBAC5B;;UAGJ,oBAAA,SAA6B;qBACzB;;;;;;UAOJ,mBAAA;;;;;;;;UASA,cAAA;kBACC;yBACO,6BAA6B;yBAC7B,6BAA6B;0BAC5B,oBAAoB;;;;;;iBAO9B,UAAA,SAAmB,gCAAgC;iBAInD,OAAA,SAAgB,gCAAgC"}

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.4.0-dev.6",
+  "version": "0.4.0-dev.8",
   "type": "module",
   "sideEffects": false,
   "description": "On-disk migration persistence, attestation, and chain reconstruction for Prisma Next",
   "dependencies": {
     "arktype": "^2.1.29",
     "pathe": "^2.0.3",
-    "@prisma-next/contract": "0.4.0-dev.6",
-    "@prisma-next/framework-components": "0.4.0-dev.6",
-    "@prisma-next/utils": "0.4.0-dev.6"
+    "@prisma-next/framework-components": "0.4.0-dev.8",
+    "@prisma-next/contract": "0.4.0-dev.8",
+    "@prisma-next/utils": "0.4.0-dev.8"
   },
   "devDependencies": {
     "tsdown": "0.18.4",

package/src/exports/io.ts

@@ -1,4 +1,5 @@
 export {
+  copyContractToMigrationDir,
   formatMigrationDirName,
   readMigrationPackage,
   readMigrationsDir,

package/src/exports/migration-ts.ts

@@ -1,6 +1,3 @@
-export type { ScaffoldOptions } from '../migration-ts';
-export {
-  evaluateMigrationTs,
-  hasMigrationTs,
-  scaffoldMigrationTs,
-} from '../migration-ts';
+export { evaluateMigrationTs, hasMigrationTs, writeMigrationTs } from '../migration-ts';
+export type { ScaffoldRuntime } from '../runtime-detection';
+export { detectScaffoldRuntime, shebangLineFor } from '../runtime-detection';

package/src/io.ts

@@ -1,4 +1,4 @@
-import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
 import { type } from 'arktype';
 import { basename, dirname, join } from 'pathe';
 import {
@@ -74,6 +74,31 @@ export async function writeMigrationPackage(
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
+/**
+ * Copy the destination contract artifacts (`contract.json` and the
+ * colocated `contract.d.ts`) into the migration package directory so
+ * authors of the scaffolded `migration.ts` can import the typed
+ * contract relative to the migration directory
+ * (`import type { Contract } from './contract'`).
+ *
+ * A missing `.d.ts` is tolerated (only the `.json` is required) so the
+ * helper stays usable in tests that hand-roll a bare `contract.json`.
+ * A missing `contract.json` — or any other I/O failure — throws.
+ */
+export async function copyContractToMigrationDir(
+  packageDir: string,
+  contractJsonPath: string,
+): Promise<void> {
+  await copyFile(contractJsonPath, join(packageDir, 'contract.json'));
+  const dtsPath = `${contractJsonPath.slice(0, -'.json'.length)}.d.ts`;
+  try {
+    await copyFile(dtsPath, join(packageDir, 'contract.d.ts'));
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) return;
+    throw error;
+  }
+}
+
 export async function writeMigrationManifest(
   dir: string,
   manifest: MigrationManifest,

package/src/migration-base.ts

@@ -1,7 +1,15 @@
-import { realpathSync, writeFileSync } from 'node:fs';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import type { Contract } from '@prisma-next/contract/types';
+import type {
+  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 { MigrationManifest, MigrationOps } from './types';
 
 export interface MigrationMeta {
   readonly from: string;
@@ -14,21 +22,56 @@ const MigrationMetaSchema = type({
   from: 'string',
   to: 'string',
   'kind?': "'regular' | 'baseline'",
-  'labels?': 'string[]',
+  'labels?': type('string').array(),
 });
 
-export abstract class Migration<TOperation = unknown> {
-  abstract plan(): TOperation[];
+/**
+ * Base class for class-flow migrations.
+ *
+ * A `Migration` subclass is itself a `MigrationPlan`: CLI commands and the
+ * runner can consume it directly via `targetId`, `operations`, `origin`, and
+ * `destination`. The manifest-shaped inputs come from `describe()`, which
+ * every migration must implement — `migration.json` is required for a
+ * migration to be valid.
+ */
+export abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation>
+  implements MigrationPlan
+{
+  abstract readonly targetId: string;
 
-  describe(): MigrationMeta | undefined {
-    return undefined;
+  /**
+   * Ordered list of operations this migration performs.
+   *
+   * Implemented as a getter so that subclasses can either precompute the list
+   * in their constructor or build it lazily per access.
+   */
+  abstract get operations(): readonly TOperation[];
+
+  /**
+   * Metadata inputs used to build `migration.json` and to derive the plan's
+   * origin/destination identities. Every migration must provide this —
+   * omitting it would produce an invalid on-disk migration package.
+   */
+  abstract describe(): MigrationMeta;
+
+  get origin(): { readonly storageHash: string } | null {
+    const from = this.describe().from;
+    // An empty `from` represents a migration with no prior origin (e.g.
+    // initial baseline, or an in-process plan that was never persisted).
+    // Surface that as a null origin so runners treat the plan as
+    // origin-less rather than matching against an empty storage hash.
+    return from === '' ? null : { storageHash: from };
+  }
+
+  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. `tsx migration.ts`)
-   * and if so, serializes the migration plan to `ops.json` (and optionally
-   * `migration.json`) in the same directory. When the file is imported by
+   * 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):
@@ -74,7 +117,7 @@ export abstract class Migration<TOperation = unknown> {
 function printHelp(): void {
   process.stdout.write(
     [
-      'Usage: tsx <migration-file> [options]',
+      'Usage: node <migration-file> [options]',
       '',
       'Options:',
       '  --dry-run  Print operations to stdout without writing files',
@@ -84,15 +127,69 @@ function printHelp(): void {
   );
 }
 
-function buildManifest(meta: MigrationMeta): Record<string, unknown> {
-  return {
+/**
+ * Build the attested manifest written by `Migration.run()`.
+ *
+ * When a `migration.json` already exists in the directory (the common case:
+ * the package 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
+ * change as the author iterates. When no manifest exists yet (a bare
+ * `migration.ts` run from scratch), synthesize a minimal but
+ * schema-conformant manifest so the resulting package can still be read,
+ * verified, and applied.
+ *
+ * In both cases the `migrationId` is recomputed against the current
+ * manifest + ops so the on-disk artifacts are always fully attested — no
+ * draft (`migrationId: null`) ever leaves this function.
+ */
+function buildAttestedManifest(
+  migrationDir: string,
+  meta: MigrationMeta,
+  ops: MigrationOps,
+): MigrationManifest {
+  const existing = readExistingManifest(join(migrationDir, 'migration.json'));
+
+  const baseManifest: MigrationManifest = {
     migrationId: null,
     from: meta.from,
     to: meta.to,
     kind: meta.kind ?? 'regular',
-    labels: meta.labels ?? [],
-    createdAt: new Date().toISOString(),
+    labels: meta.labels ?? existing?.labels ?? [],
+    createdAt: existing?.createdAt ?? new Date().toISOString(),
+    fromContract: existing?.fromContract ?? null,
+    // When no scaffolded manifest exists we synthesize a minimal contract
+    // stub so the package is still readable end-to-end. The cast is
+    // intentional: only the storage bookend matters for hash computation
+    // (everything else is stripped by `computeMigrationId`), and a real
+    // contract bookend would only be available after `migration plan`.
+    toContract: existing?.toContract ?? ({ storage: { storageHash: meta.to } } as Contract),
+    hints: existing?.hints ?? {
+      used: [],
+      applied: [],
+      plannerVersion: '2.0.0',
+      planningStrategy: 'class-based',
+    },
+    ...ifDefined('authorship', existing?.authorship),
   };
+
+  const migrationId = computeMigrationId(baseManifest, ops);
+  return { ...baseManifest, migrationId };
+}
+
+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(
@@ -102,40 +199,31 @@ function serializeMigration(
 ): void {
   const instance = new MigrationClass();
 
-  const ops = instance.plan();
+  const ops = instance.operations;
 
   if (!Array.isArray(ops)) {
-    throw new Error('plan() must return an array of operations');
+    throw new Error('operations must be an array');
   }
 
   const serializedOps = JSON.stringify(ops, null, 2);
 
-  let manifest: Record<string, unknown> | undefined;
-  if (typeof instance.describe === 'function') {
-    const rawMeta: unknown = instance.describe();
-    if (rawMeta !== undefined) {
-      const parsed = MigrationMetaSchema(rawMeta);
-      if (parsed instanceof type.errors) {
-        throw new Error(`describe() returned invalid metadata: ${parsed.summary}`);
-      }
-      manifest = buildManifest(parsed);
-    }
+  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);
+
   if (dryRun) {
-    if (manifest) {
-      process.stdout.write(`--- migration.json ---\n${JSON.stringify(manifest, null, 2)}\n`);
-      process.stdout.write('--- ops.json ---\n');
-    }
+    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);
-  if (manifest) {
-    writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));
-  }
+  writeFileSync(join(migrationDir, 'migration.json'), JSON.stringify(manifest, null, 2));
 
-  const files = manifest ? 'ops.json + migration.json' : 'ops.json';
-  process.stdout.write(`Wrote ${files} to ${migrationDir}\n`);
+  process.stdout.write(`Wrote ops.json + migration.json to ${migrationDir}\n`);
 }