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

package/src/dag.ts

@@ -1,11 +1,11 @@
-import { EMPTY_CONTRACT_HASH } from '@prisma-next/core-control-plane/constants';
 import { ifDefined } from '@prisma-next/utils/defined';
+import { EMPTY_CONTRACT_HASH } from './constants';
 import {
-  errorAmbiguousLeaf,
+  errorAmbiguousTarget,
   errorDuplicateMigrationId,
-  errorNoResolvableLeaf,
-  errorNoRoot,
-  errorSelfLoop,
+  errorNoInitialMigration,
+  errorNoTarget,
+  errorSameSourceAndTarget,
 } from './errors';
 import type { AttestedMigrationBundle, MigrationChainEntry, MigrationGraph } from './types';
 
@@ -19,7 +19,7 @@ export function reconstructGraph(packages: readonly AttestedMigrationBundle[]):
     const { from, to } = pkg.manifest;
 
     if (from === to) {
-      throw errorSelfLoop(pkg.dirName, from);
+      throw errorSameSourceAndTarget(pkg.dirName, from);
     }
 
     nodes.add(from);
@@ -203,7 +203,7 @@ export function findPathWithDecision(
 }
 
 /**
- * Walk ancestors of each leaf back from the leaves to find the last node
+ * Walk ancestors of each branch tip back to find the last node
  * that appears on all paths. Returns `fromHash` if no shared ancestor is found.
  */
 function findDivergencePoint(
@@ -246,8 +246,8 @@ function findDivergencePoint(
 }
 
 /**
- * Find all leaf nodes reachable from `fromHash` via forward edges.
- * A leaf is a node with no outgoing edges in the graph.
+ * Find all branch tips (nodes with no outgoing edges) reachable from
+ * `fromHash` via forward edges.
  */
 export function findReachableLeaves(graph: MigrationGraph, fromHash: string): readonly string[] {
   const visited = new Set<string>();
@@ -276,10 +276,10 @@ export function findReachableLeaves(graph: MigrationGraph, fromHash: string): re
 }
 
 /**
- * Find the leaf contract hash of the migration graph reachable from
- * EMPTY_CONTRACT_HASH. Throws NO_ROOT if the graph has nodes but none
- * originate from the empty hash (e.g. root migration was deleted).
- * Throws AMBIGUOUS_LEAF if multiple leaves exist.
+ * Find the target contract hash of the migration graph reachable from
+ * EMPTY_CONTRACT_HASH. Throws NO_INITIAL_MIGRATION if the graph has
+ * nodes but none originate from the empty hash.
+ * Throws AMBIGUOUS_TARGET if multiple branch tips exist.
  */
 export function findLeaf(graph: MigrationGraph): string {
   if (graph.nodes.size === 0) {
@@ -287,7 +287,7 @@ export function findLeaf(graph: MigrationGraph): string {
   }
 
   if (!graph.nodes.has(EMPTY_CONTRACT_HASH)) {
-    throw errorNoRoot([...graph.nodes]);
+    throw errorNoInitialMigration([...graph.nodes]);
   }
 
   const leaves = findReachableLeaves(graph, EMPTY_CONTRACT_HASH);
@@ -295,21 +295,21 @@ export function findLeaf(graph: MigrationGraph): string {
   if (leaves.length === 0) {
     const reachable = [...graph.nodes].filter((n) => n !== EMPTY_CONTRACT_HASH);
     if (reachable.length > 0) {
-      throw errorNoResolvableLeaf(reachable);
+      throw errorNoTarget(reachable);
     }
     return EMPTY_CONTRACT_HASH;
   }
 
   if (leaves.length > 1) {
     const divergencePoint = findDivergencePoint(graph, EMPTY_CONTRACT_HASH, leaves);
-    const branches = leaves.map((leaf) => {
-      const path = findPath(graph, divergencePoint, leaf);
+    const branches = leaves.map((tip) => {
+      const path = findPath(graph, divergencePoint, tip);
       return {
-        leaf,
+        tip,
         edges: (path ?? []).map((e) => ({ dirName: e.dirName, from: e.from, to: e.to })),
       };
     });
-    throw errorAmbiguousLeaf(leaves, { divergencePoint, branches });
+    throw errorAmbiguousTarget(leaves, { divergencePoint, branches });
   }
 
   const leaf = leaves[0];
@@ -318,8 +318,8 @@ export function findLeaf(graph: MigrationGraph): string {
 
 /**
  * Find the latest migration entry by traversing from EMPTY_CONTRACT_HASH
- * to the single leaf. Returns null for an empty graph.
- * Throws AMBIGUOUS_LEAF if the graph has multiple leaves.
+ * to the single target. Returns null for an empty graph.
+ * Throws AMBIGUOUS_TARGET if the graph has multiple branch tips.
  */
 export function findLatestMigration(graph: MigrationGraph): MigrationChainEntry | null {
   if (graph.nodes.size === 0) {

package/src/errors.ts

@@ -3,7 +3,7 @@
  *
  * Follows the NAMESPACE.SUBCODE convention from ADR 027. All codes live under
  * the MIGRATION namespace. These are tooling-time errors (file I/O, attestation,
- * migration-chain reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
+ * migration history reconstruction), distinct from the runtime MIGRATION.* codes for apply-time
  * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
  *
  * Fields:
@@ -84,40 +84,44 @@ export function errorInvalidSlug(slug: string): MigrationToolsError {
   });
 }
 
-export function errorSelfLoop(dirName: string, hash: string): MigrationToolsError {
-  return new MigrationToolsError('MIGRATION.SELF_LOOP', 'Self-loop in migration graph', {
-    why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
-    fix: 'Delete the invalid migration directory and re-run migration plan.',
-    details: { dirName, hash },
-  });
+export function errorSameSourceAndTarget(dirName: string, hash: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.SAME_SOURCE_AND_TARGET',
+    'Migration has same source and target',
+    {
+      why: `Migration "${dirName}" has from === to === "${hash}". A migration must transition between two different contract states.`,
+      fix: 'Delete the invalid migration directory and re-run migration plan.',
+      details: { dirName, hash },
+    },
+  );
 }
 
-export function errorAmbiguousLeaf(
-  leaves: readonly string[],
+export function errorAmbiguousTarget(
+  branchTips: readonly string[],
   context?: {
     divergencePoint: string;
     branches: readonly {
-      leaf: string;
+      tip: string;
       edges: readonly { dirName: string; from: string; to: string }[];
     }[];
   },
 ): MigrationToolsError {
   const divergenceInfo = context
-    ? `\nDivergence point: ${context.divergencePoint}\nBranches:\n${context.branches.map((b) => `  → ${b.leaf} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\n')}`
+    ? `\nDivergence point: ${context.divergencePoint}\nBranches:\n${context.branches.map((b) => `  → ${b.tip} (${b.edges.length} edge(s): ${b.edges.map((e) => e.dirName).join(' → ') || 'direct'})`).join('\n')}`
     : '';
-  return new MigrationToolsError('MIGRATION.AMBIGUOUS_LEAF', 'Ambiguous migration graph', {
-    why: `Multiple leaf nodes found: ${leaves.join(', ')}. The migration graph has diverged — this typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,
+  return new MigrationToolsError('MIGRATION.AMBIGUOUS_TARGET', 'Ambiguous migration target', {
+    why: `The migration history has diverged into multiple branches: ${branchTips.join(', ')}. This typically happens when two developers plan migrations from the same starting point.${divergenceInfo}`,
     fix: 'Use `migration ref set <name> <hash>` to target a specific branch, delete one of the conflicting migration directories and re-run `migration plan`, or use --from <hash> to explicitly select a starting point.',
     details: {
-      leaves,
+      branchTips,
       ...(context ? { divergencePoint: context.divergencePoint, branches: context.branches } : {}),
     },
   });
 }
 
-export function errorNoRoot(nodes: readonly string[]): MigrationToolsError {
-  return new MigrationToolsError('MIGRATION.NO_ROOT', 'Migration graph has no root', {
-    why: `No root migration found in the migration graph (nodes: ${nodes.join(', ')}). No migration starts from the empty contract hash, or all edges form a disconnected subgraph.`,
+export function errorNoInitialMigration(nodes: readonly string[]): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.NO_INITIAL_MIGRATION', 'No initial migration found', {
+    why: `No migration starts from the empty contract state (known hashes: ${nodes.join(', ')}). At least one migration must originate from the empty state.`,
     fix: 'Inspect the migrations directory for corrupted migration.json files. At least one migration must start from the empty contract hash.',
     details: { nodes },
   });
@@ -131,6 +135,14 @@ export function errorInvalidRefs(refsPath: string, reason: string): MigrationToo
   });
 }
 
+export function errorInvalidRefFile(filePath: string, reason: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_REF_FILE', 'Invalid ref file', {
+    why: `Ref file at "${filePath}" is invalid: ${reason}`,
+    fix: 'Ensure the ref file contains valid JSON with { "hash": "sha256:<64 hex chars>", "invariants": ["..."] }.',
+    details: { path: filePath, reason },
+  });
+}
+
 export function errorInvalidRefName(refName: string): MigrationToolsError {
   return new MigrationToolsError('MIGRATION.INVALID_REF_NAME', 'Invalid ref name', {
     why: `Ref name "${refName}" is invalid. Names must be lowercase alphanumeric with hyphens or forward slashes (no "." or ".." segments).`,
@@ -139,16 +151,12 @@ export function errorInvalidRefName(refName: string): MigrationToolsError {
   });
 }
 
-export function errorNoResolvableLeaf(reachableNodes: readonly string[]): MigrationToolsError {
-  return new MigrationToolsError(
-    'MIGRATION.NO_RESOLVABLE_LEAF',
-    'Migration graph has no resolvable leaf',
-    {
-      why: `The migration graph contains cycles and no node has zero outgoing edges (reachable nodes: ${reachableNodes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,
-      fix: 'Use --from <hash> to specify the planning origin explicitly.',
-      details: { reachableNodes },
-    },
-  );
+export function errorNoTarget(reachableHashes: readonly string[]): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.NO_TARGET', 'No migration target could be resolved', {
+    why: `The migration history contains cycles and no target can be resolved automatically (reachable hashes: ${reachableHashes.join(', ')}). This typically happens after rollback migrations (e.g., C1→C2→C1).`,
+    fix: 'Use --from <hash> to specify the planning origin explicitly.',
+    details: { reachableHashes },
+  });
 }
 
 export function errorInvalidRefValue(value: string): MigrationToolsError {

package/src/exports/constants.ts

@@ -0,0 +1 @@
+export { EMPTY_CONTRACT_HASH } from '../constants';

package/src/exports/io.ts

@@ -2,5 +2,7 @@ export {
   formatMigrationDirName,
   readMigrationPackage,
   readMigrationsDir,
+  writeMigrationManifest,
+  writeMigrationOps,
   writeMigrationPackage,
 } from '../io';

package/src/exports/migration-ts.ts

@@ -0,0 +1,6 @@
+export type { ScaffoldOptions } from '../migration-ts';
+export {
+  evaluateMigrationTs,
+  hasMigrationTs,
+  scaffoldMigrationTs,
+} from '../migration-ts';

package/src/exports/migration.ts

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

package/src/exports/types.ts

@@ -2,13 +2,15 @@ export { MigrationToolsError } from '../errors';
 export type {
   AttestedMigrationBundle,
   AttestedMigrationManifest,
+  BaseMigrationBundle,
+  BaseMigrationBundle as MigrationBundle,
+  BaseMigrationBundle as MigrationPackage,
+  DraftMigrationBundle,
   DraftMigrationManifest,
-  MigrationBundle,
-  MigrationBundle as MigrationPackage,
   MigrationChainEntry,
   MigrationGraph,
   MigrationHints,
   MigrationManifest,
   MigrationOps,
 } from '../types';
-export { isAttested } from '../types';
+export { isAttested, isDraft } from '../types';

package/src/io.ts

@@ -8,7 +8,7 @@ import {
   errorInvalidSlug,
   errorMissingFile,
 } from './errors';
-import type { MigrationBundle, MigrationManifest, MigrationOps } from './types';
+import type { BaseMigrationBundle, MigrationManifest, MigrationOps } from './types';
 
 const MANIFEST_FILE = 'migration.json';
 const OPS_FILE = 'ops.json';
@@ -48,7 +48,7 @@ const MigrationManifestSchema = type({
 const MigrationOpSchema = type({
   id: 'string',
   label: 'string',
-  operationClass: "'additive' | 'widening' | 'destructive'",
+  operationClass: "'additive' | 'widening' | 'destructive' | 'data'",
 });
 
 // Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.
@@ -74,7 +74,18 @@ export async function writeMigrationPackage(
   await writeFile(join(dir, OPS_FILE), JSON.stringify(ops, null, 2), { flag: 'wx' });
 }
 
-export async function readMigrationPackage(dir: string): Promise<MigrationBundle> {
+export async function writeMigrationManifest(
+  dir: string,
+  manifest: MigrationManifest,
+): Promise<void> {
+  await writeFile(join(dir, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+export async function writeMigrationOps(dir: string, ops: MigrationOps): Promise<void> {
+  await writeFile(join(dir, OPS_FILE), `${JSON.stringify(ops, null, 2)}\n`);
+}
+
+export async function readMigrationPackage(dir: string): Promise<BaseMigrationBundle> {
   const manifestPath = join(dir, MANIFEST_FILE);
   const opsPath = join(dir, OPS_FILE);
 
@@ -142,7 +153,7 @@ function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOp
 
 export async function readMigrationsDir(
   migrationsRoot: string,
-): Promise<readonly MigrationBundle[]> {
+): Promise<readonly BaseMigrationBundle[]> {
   let entries: string[];
   try {
     entries = await readdir(migrationsRoot);
@@ -153,7 +164,7 @@ export async function readMigrationsDir(
     throw error;
   }
 
-  const packages: MigrationBundle[] = [];
+  const packages: BaseMigrationBundle[] = [];
 
   for (const entry of entries.sort()) {
     const entryPath = join(migrationsRoot, entry);

package/src/migration-base.ts

@@ -0,0 +1,141 @@
+import { realpathSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { type } from 'arktype';
+import { dirname, join } from 'pathe';
+
+export interface MigrationMeta {
+  readonly from: string;
+  readonly to: string;
+  readonly kind?: 'regular' | 'baseline';
+  readonly labels?: readonly string[];
+}
+
+const MigrationMetaSchema = type({
+  from: 'string',
+  to: 'string',
+  'kind?': "'regular' | 'baseline'",
+  'labels?': 'string[]',
+});
+
+export abstract class Migration<TOperation = unknown> {
+  abstract plan(): TOperation[];
+
+  describe(): MigrationMeta | undefined {
+    return undefined;
+  }
+
+  /**
+   * 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
+   * 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;
+    }
+  }
+}
+
+function printHelp(): void {
+  process.stdout.write(
+    [
+      'Usage: tsx <migration-file> [options]',
+      '',
+      'Options:',
+      '  --dry-run  Print operations to stdout without writing files',
+      '  --help     Show this help message',
+      '',
+    ].join('\n'),
+  );
+}
+
+function buildManifest(meta: MigrationMeta): Record<string, unknown> {
+  return {
+    migrationId: null,
+    from: meta.from,
+    to: meta.to,
+    kind: meta.kind ?? 'regular',
+    labels: meta.labels ?? [],
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function serializeMigration(
+  MigrationClass: new () => Migration,
+  migrationDir: string,
+  dryRun: boolean,
+): void {
+  const instance = new MigrationClass();
+
+  const ops = instance.plan();
+
+  if (!Array.isArray(ops)) {
+    throw new Error('plan() must return an array of operations');
+  }
+
+  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);
+    }
+  }
+
+  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(`${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`);
+}

package/src/migration-ts.ts

@@ -0,0 +1,199 @@
+/**
+ * Utilities for scaffolding and evaluating migration.ts files.
+ *
+ * - scaffoldMigrationTs: writes a migration.ts file with boilerplate
+ * - evaluateMigrationTs: loads migration.ts via native Node import, returns descriptors
+ *
+ * Shared by migration plan (scaffold), migration new (scaffold), and
+ * migration verify (evaluate).
+ */
+
+import { stat, writeFile } from 'node:fs/promises';
+import type { OperationDescriptor } from '@prisma-next/framework-components/control';
+import { join, relative, resolve } from 'pathe';
+
+const MIGRATION_TS_FILE = 'migration.ts';
+
+/**
+ * Options for scaffolding a migration.ts file.
+ */
+export interface ScaffoldOptions {
+  /** Operation descriptors to serialize as builder calls. */
+  readonly descriptors?: readonly OperationDescriptor[];
+  /** Absolute path to contract.json — used to derive contract.d.ts import for typed builders. */
+  readonly contractJsonPath?: string;
+}
+
+function serializeQueryInput(input: unknown): string {
+  if (typeof input === 'boolean') return String(input);
+  if (typeof input === 'symbol') return 'TODO /* fill in using db.sql.from(...) */';
+  if (input === null || input === undefined) return 'null';
+  if (Array.isArray(input)) {
+    if (input.length === 0) return '[]';
+    if (input.every((item) => typeof item === 'symbol'))
+      return '[TODO /* fill in using db.sql.from(...) */]';
+    return `[${input.map(serializeQueryInput).join(', ')}]`;
+  }
+  return JSON.stringify(input);
+}
+
+function descriptorToBuilderCall(desc: OperationDescriptor): string {
+  switch (desc.kind) {
+    case 'createTable':
+      return `createTable(${JSON.stringify(desc['table'])})`;
+    case 'dropTable':
+      return `dropTable(${JSON.stringify(desc['table'])})`;
+    case 'addColumn': {
+      const args = [JSON.stringify(desc['table']), JSON.stringify(desc['column'])];
+      if (desc['overrides']) {
+        args.push(JSON.stringify(desc['overrides']));
+      }
+      return `addColumn(${args.join(', ')})`;
+    }
+    case 'dropColumn':
+      return `dropColumn(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])})`;
+    case 'alterColumnType': {
+      const opts: Record<string, unknown> = {};
+      if (desc['using']) opts['using'] = desc['using'];
+      if (desc['toType']) opts['toType'] = desc['toType'];
+      const hasOpts = Object.keys(opts).length > 0;
+      return hasOpts
+        ? `alterColumnType(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])}, ${JSON.stringify(opts)})`
+        : `alterColumnType(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])})`;
+    }
+    case 'setNotNull':
+      return `setNotNull(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])})`;
+    case 'dropNotNull':
+      return `dropNotNull(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])})`;
+    case 'setDefault':
+      return `setDefault(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])})`;
+    case 'dropDefault':
+      return `dropDefault(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['column'])})`;
+    case 'addPrimaryKey':
+      return `addPrimaryKey(${JSON.stringify(desc['table'])})`;
+    case 'addUnique':
+      return `addUnique(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['columns'])})`;
+    case 'addForeignKey':
+      return `addForeignKey(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['columns'])})`;
+    case 'dropConstraint':
+      return `dropConstraint(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['constraintName'])})`;
+    case 'createIndex':
+      return `createIndex(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['columns'])})`;
+    case 'dropIndex':
+      return `dropIndex(${JSON.stringify(desc['table'])}, ${JSON.stringify(desc['indexName'])})`;
+    case 'createEnumType':
+      return desc['values']
+        ? `createEnumType(${JSON.stringify(desc['typeName'])}, ${JSON.stringify(desc['values'])})`
+        : `createEnumType(${JSON.stringify(desc['typeName'])})`;
+    case 'addEnumValues':
+      return `addEnumValues(${JSON.stringify(desc['typeName'])}, ${JSON.stringify(desc['values'])})`;
+    case 'dropEnumType':
+      return `dropEnumType(${JSON.stringify(desc['typeName'])})`;
+    case 'renameType':
+      return `renameType(${JSON.stringify(desc['fromName'])}, ${JSON.stringify(desc['toName'])})`;
+    case 'createDependency':
+      return `createDependency(${JSON.stringify(desc['dependencyId'])})`;
+    case 'dataTransform':
+      return `dataTransform(${JSON.stringify(desc['name'])}, {\n    check: ${serializeQueryInput(desc['check'])},\n    run: ${serializeQueryInput(desc['run'])},\n  })`;
+    default:
+      throw new Error(`Unknown descriptor kind: ${desc.kind}`);
+  }
+}
+
+/**
+ * Scaffolds a migration.ts file in the given package directory.
+ * Serializes operation descriptors as builder calls that the user can edit.
+ * On verify, this file is re-evaluated to produce the final ops.
+ */
+export async function scaffoldMigrationTs(
+  packageDir: string,
+  options: ScaffoldOptions = {},
+): Promise<void> {
+  const filePath = join(packageDir, MIGRATION_TS_FILE);
+
+  const descriptors = options.descriptors ?? [];
+  const hasDataTransform = descriptors.some((d) => d.kind === 'dataTransform');
+
+  const lines: string[] = [];
+
+  if (hasDataTransform && options.contractJsonPath) {
+    const relativeContractDts = relative(packageDir, options.contractJsonPath).replace(
+      /\.json$/,
+      '.d',
+    );
+    lines.push(`import type { Contract } from "${relativeContractDts}"`);
+    lines.push(`import { createBuilders } from "@prisma-next/target-postgres/migration-builders"`);
+    lines.push('');
+    const importList = [...new Set(descriptors.map((d) => d.kind))];
+    importList.push('TODO');
+    lines.push(`const { ${importList.join(', ')} } = createBuilders<Contract>()`);
+  } else {
+    const importList = [...new Set(descriptors.map((d) => d.kind))];
+    if (importList.length === 0) {
+      importList.push('createTable');
+    }
+    if (hasDataTransform) {
+      importList.push('TODO');
+    }
+    lines.push(
+      `import { ${importList.join(', ')} } from "@prisma-next/target-postgres/migration-builders"`,
+    );
+  }
+
+  const calls = descriptors.map((d) => `  ${descriptorToBuilderCall(d)},`).join('\n');
+  const body = calls.length > 0 ? `\n${calls}\n` : '';
+
+  lines.push('');
+  lines.push(`export default () => [${body}]`);
+  lines.push('');
+
+  await writeFile(filePath, lines.join('\n'));
+}
+
+/**
+ * Checks whether a migration.ts file exists in the package directory.
+ */
+export async function hasMigrationTs(packageDir: string): Promise<boolean> {
+  try {
+    const s = await stat(join(packageDir, MIGRATION_TS_FILE));
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Evaluates a migration.ts file by loading it via native Node import.
+ * Returns the result of calling the default export (expected to be a
+ * function returning an array of operation descriptors).
+ *
+ * Requires Node ≥24 for native TypeScript support.
+ */
+export async function evaluateMigrationTs(packageDir: string): Promise<readonly unknown[]> {
+  const filePath = resolve(join(packageDir, MIGRATION_TS_FILE));
+
+  try {
+    await stat(filePath);
+  } catch {
+    throw new Error(`migration.ts not found at "${filePath}"`);
+  }
+
+  // Use native Node TS import (Node ≥24, stable type stripping)
+  const mod = (await import(filePath)) as { default?: unknown };
+
+  if (typeof mod.default !== 'function') {
+    throw new Error(
+      `migration.ts must export a default function returning an operation list. Got: ${typeof mod.default}`,
+    );
+  }
+
+  const result: unknown = mod.default();
+
+  if (!Array.isArray(result)) {
+    throw new Error(
+      `migration.ts default export must return an array of operations. Got: ${typeof result}`,
+    );
+  }
+
+  return result;
+}