@prisma-next/migration-tools 0.3.0 → 0.4.0-dev.10

package/dist/exports/migration.d.mts

@@ -0,0 +1,57 @@
+import { MigrationPlan, MigrationPlanOperation } from "@prisma-next/framework-components/control";
+
+//#region src/migration-base.d.ts
+interface MigrationMeta {
+  readonly from: string;
+  readonly to: string;
+  readonly kind?: 'regular' | 'baseline';
+  readonly labels?: readonly string[];
+}
+/**
+ * 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.
+ */
+declare abstract class Migration<TOperation extends MigrationPlanOperation = MigrationPlanOperation> implements MigrationPlan {
+  abstract readonly targetId: string;
+  /**
+   * 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;
+  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;
+}
+//#endregion
+export { Migration, type MigrationMeta };
+//# sourceMappingURL=migration.d.mts.map

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

@@ -0,0 +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"}

package/dist/exports/migration.mjs

@@ -0,0 +1,159 @@
+import "../io-Cun81AIZ.mjs";
+import { n as computeMigrationId } from "../attestation-DnebS4XZ.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 { fileURLToPath } from "node:url";
+
+//#region src/migration-base.ts
+const MigrationMetaSchema = type({
+	from: "string",
+	to: "string",
+	"kind?": "'regular' | 'baseline'",
+	"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 {
+	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. `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;
+		}
+	}
+};
+function printHelp() {
+	process.stdout.write([
+		"Usage: node <migration-file> [options]",
+		"",
+		"Options:",
+		"  --dry-run  Print operations to stdout without writing files",
+		"  --help     Show this help message",
+		""
+	].join("\n"));
+}
+/**
+* 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 ?? 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.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`);
+}
+
+//#endregion
+export { Migration };
+//# sourceMappingURL=migration.mjs.map

package/dist/exports/migration.mjs.map

@@ -0,0 +1 @@
+{"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":";;;;;;;;;AAoBA,MAAM,sBAAsB,KAAK;CAC/B,MAAM;CACN,IAAI;CACJ,SAAS;CACT,WAAW,KAAK,SAAS,CAAC,OAAO;CAClC,CAAC;;;;;;;;;;AAWF,IAAsB,YAAtB,MAEA;CAkBE,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;;;;;;;;;;;;;;;CAgB5C,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;;;;;;;;;;;;;;;;;;;AAoBH,SAAS,sBACP,cACA,MACA,KACmB;CACnB,MAAM,WAAW,qBAAqB,KAAK,cAAc,iBAAiB,CAAC;CAE3E,MAAMC,eAAkC;EACtC,aAAa;EACb,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,UAAU,SAAS;GACxB,MAAM,EAAE;GACR,SAAS,EAAE;GACX,gBAAgB;GAChB,kBAAkB;GACnB;EACD,GAAG,UAAU,cAAc,UAAU,WAAW;EACjD;CAED,MAAM,cAAc,mBAAmB,cAAc,IAAI;AACzD,QAAO;EAAE,GAAG;EAAc;EAAa;;AAGzC,SAAS,qBAAqB,cAAyD;CACrF,IAAIC;AACJ,KAAI;AACF,QAAM,aAAa,cAAc,QAAQ;SACnC;AACN,SAAO;;AAET,KAAI;AACF,SAAO,KAAK,MAAM,IAAI;SAChB;AACN,SAAO;;;AAIX,SAAS,mBACP,gBACA,cACA,QACM;CACN,MAAM,WAAW,IAAI,gBAAgB;CAErC,MAAM,MAAM,SAAS;AAErB,KAAI,CAAC,MAAM,QAAQ,IAAI,CACrB,OAAM,IAAI,MAAM,8BAA8B;CAGhD,MAAM,gBAAgB,KAAK,UAAU,KAAK,MAAM,EAAE;CAGlD,MAAM,SAAS,oBADU,SAAS,UAAU,CACD;AAC3C,KAAI,kBAAkB,KAAK,OACzB,OAAM,IAAI,MAAM,yCAAyC,OAAO,UAAU;CAG5E,MAAM,WAAW,sBAAsB,cAAc,QAAQ,IAAI;AAEjE,KAAI,QAAQ;AACV,UAAQ,OAAO,MAAM,2BAA2B,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC,IAAI;AACtF,UAAQ,OAAO,MAAM,qBAAqB;AAC1C,UAAQ,OAAO,MAAM,GAAG,cAAc,IAAI;AAC1C;;AAGF,eAAc,KAAK,cAAc,WAAW,EAAE,cAAc;AAC5D,eAAc,KAAK,cAAc,iBAAiB,EAAE,KAAK,UAAU,UAAU,MAAM,EAAE,CAAC;AAEtF,SAAQ,OAAO,MAAM,sCAAsC,aAAa,IAAI"}

package/dist/exports/refs.mjs

@@ -1,4 +1,4 @@
-import { c as errorInvalidRefValue, l as errorInvalidRefs, s as errorInvalidRefName, t as MigrationToolsError } from "../errors-CSAAto11.mjs";
+import { c as errorInvalidRefValue, l as errorInvalidRefs, s as errorInvalidRefName, t as MigrationToolsError } from "../errors-C_XuSbX7.mjs";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { type } from "arktype";
 import { dirname, join } from "pathe";

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-BW_pJEe8.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/exports/types.mjs

@@ -1,4 +1,4 @@
-import { t as MigrationToolsError } from "../errors-CSAAto11.mjs";
+import { t as MigrationToolsError } from "../errors-C_XuSbX7.mjs";
 
 //#region src/types.ts
 /**

package/dist/{io-LsuurzNb.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-CSAAto11.mjs";
-import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { a as errorInvalidJson, d as errorMissingFile, o as errorInvalidManifest, r as errorDirectoryExists, u as errorInvalidSlug } from "./errors-C_XuSbX7.mjs";
+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-LsuurzNb.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":"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"}

package/dist/{types-BW_pJEe8.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-BW_pJEe8.d.mts.map
+//# sourceMappingURL=types-D2uX4ql7.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types-BW_pJEe8.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,22 +1,22 @@
 {
   "name": "@prisma-next/migration-tools",
-  "version": "0.3.0",
+  "version": "0.4.0-dev.10",
   "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.3.0",
-    "@prisma-next/framework-components": "0.3.0",
-    "@prisma-next/utils": "0.3.0"
+    "@prisma-next/framework-components": "0.4.0-dev.10",
+    "@prisma-next/contract": "0.4.0-dev.10",
+    "@prisma-next/utils": "0.4.0-dev.10"
   },
   "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",
@@ -54,6 +54,10 @@
       "types": "./dist/exports/migration-ts.d.mts",
       "import": "./dist/exports/migration-ts.mjs"
     },
+    "./migration": {
+      "types": "./dist/exports/migration.d.mts",
+      "import": "./dist/exports/migration.mjs"
+    },
     "./package.json": "./package.json"
   },
   "repository": {

package/src/attestation.ts

@@ -1,5 +1,4 @@
 import { createHash } from 'node:crypto';
-import { canonicalizeContract } from '@prisma-next/contract/hashing';
 import { canonicalizeJson } from './canonicalize-json';
 import { readMigrationPackage, writeMigrationManifest } from './io';
 import type { MigrationManifest, MigrationOps } from './types';
@@ -15,33 +14,33 @@ function sha256Hex(input: string): string {
   return createHash('sha256').update(input).digest('hex');
 }
 
+/**
+ * Content-addressed migration identity over (manifest envelope sans
+ * contracts/hints, ops). See ADR 199 "Storage-only migration identity"
+ * for the rationale: contracts are anchored separately by the
+ * storage-hash bookends inside the envelope; planner hints are advisory
+ * and must not affect identity.
+ */
 export function computeMigrationId(manifest: MigrationManifest, ops: MigrationOps): string {
   const {
     migrationId: _migrationId,
     signature: _signature,
     fromContract: _fromContract,
     toContract: _toContract,
+    hints: _hints,
     ...strippedMeta
   } = manifest;
 
   const canonicalManifest = canonicalizeJson(strippedMeta);
   const canonicalOps = canonicalizeJson(ops);
 
-  const canonicalFromContract =
-    manifest.fromContract !== null ? canonicalizeContract(manifest.fromContract) : 'null';
-  const canonicalToContract = canonicalizeContract(manifest.toContract);
-
-  const partHashes = [
-    canonicalManifest,
-    canonicalOps,
-    canonicalFromContract,
-    canonicalToContract,
-  ].map(sha256Hex);
+  const partHashes = [canonicalManifest, canonicalOps].map(sha256Hex);
   const hash = sha256Hex(canonicalizeJson(partHashes));
 
   return `sha256:${hash}`;
 }
 
+/** Compute and persist `migrationId` to `manifest.json`. */
 export async function attestMigration(dir: string): Promise<string> {
   const pkg = await readMigrationPackage(dir);
   const migrationId = computeMigrationId(pkg.manifest, pkg.ops);

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/exports/migration.ts

@@ -0,0 +1 @@
+export { Migration, type MigrationMeta } from '../migration-base';

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,