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

package/src/migration-base.ts

@@ -0,0 +1,229 @@
+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;
+  readonly to: string;
+  readonly kind?: 'regular' | 'baseline';
+  readonly labels?: readonly string[];
+}
+
+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.
+ */
+export 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 {
+    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. `node migration.ts`)
+   * and if so, serializes the migration plan to `ops.json` and
+   * `migration.json` in the same directory. When the file is imported by
+   * another module, this is a no-op.
+   *
+   * Usage (at module scope, after the class definition):
+   *
+   *     class MyMigration extends Migration { ... }
+   *     export default MyMigration;
+   *     Migration.run(import.meta.url, MyMigration);
+   */
+  static run(importMetaUrl: string, MigrationClass: new () => Migration): void {
+    if (!importMetaUrl) return;
+
+    const metaFilename = fileURLToPath(importMetaUrl);
+    const argv1 = process.argv[1];
+    if (!argv1) return;
+
+    let isEntrypoint: boolean;
+    try {
+      isEntrypoint = realpathSync(metaFilename) === realpathSync(argv1);
+    } catch {
+      return;
+    }
+    if (!isEntrypoint) return;
+
+    const args = process.argv.slice(2);
+
+    if (args.includes('--help')) {
+      printHelp();
+      return;
+    }
+
+    const dryRun = args.includes('--dry-run');
+    const migrationDir = dirname(metaFilename);
+
+    try {
+      serializeMigration(MigrationClass, migrationDir, dryRun);
+    } catch (err) {
+      process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+      process.exitCode = 1;
+    }
+  }
+}
+
+function printHelp(): void {
+  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: 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 ?? 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(
+  MigrationClass: new () => Migration,
+  migrationDir: string,
+  dryRun: boolean,
+): void {
+  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 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) {
+    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`);
+}

package/src/migration-ts.ts

@@ -1,153 +1,33 @@
 /**
- * Utilities for scaffolding and evaluating migration.ts files.
+ * Utilities for reading/writing `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).
+ * Rendering migration.ts source is now the target's responsibility — the CLI
+ * obtains source strings either from a class-flow planner's
+ * `plan.renderTypeScript()` or from a descriptor-flow target's
+ * `migrations.renderDescriptorTypeScript(descriptors, context)`. The helper
+ * here is limited to file I/O: writing the returned source with the right
+ * executable bit, probing for existence, and evaluating legacy descriptor-
+ * flow files.
  */
 
 import { stat, writeFile } from 'node:fs/promises';
-import type { OperationDescriptor } from '@prisma-next/framework-components/control';
-import { join, relative, resolve } from 'pathe';
+import { join, resolve } from 'pathe';
 
 const MIGRATION_TS_FILE = 'migration.ts';
 
 /**
- * Options for scaffolding a migration.ts file.
+ * Writes a pre-rendered `migration.ts` source string to the given package
+ * directory. If the source begins with a shebang, the file is written with
+ * executable permissions (0o755) so it can be run directly via
+ * `./migration.ts` by the authoring class's `Migration.run(...)` guard.
  */
-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'));
+export async function writeMigrationTs(packageDir: string, content: string): Promise<void> {
+  const isExecutable = content.startsWith('#!');
+  await writeFile(
+    join(packageDir, MIGRATION_TS_FILE),
+    content,
+    isExecutable ? { mode: 0o755 } : undefined,
+  );
 }
 
 /**
@@ -163,9 +43,13 @@ export async function hasMigrationTs(packageDir: string): Promise<boolean> {
 }
 
 /**
- * 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).
+ * Evaluates a descriptor-flow 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).
+ *
+ * Class-flow migration.ts files use a different shape — their default
+ * export is a class that extends `Migration` — and are evaluated by the
+ * target's `emit` capability, not this helper.
  *
  * Requires Node ≥24 for native TypeScript support.
  */
@@ -178,7 +62,6 @@ export async function evaluateMigrationTs(packageDir: string): Promise<readonly
     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') {

package/src/runtime-detection.ts

@@ -0,0 +1,18 @@
+export type ScaffoldRuntime = 'node' | 'bun' | 'deno';
+
+export function detectScaffoldRuntime(): ScaffoldRuntime {
+  if (typeof (globalThis as { Bun?: unknown }).Bun !== 'undefined') return 'bun';
+  if (typeof (globalThis as { Deno?: unknown }).Deno !== 'undefined') return 'deno';
+  return 'node';
+}
+
+export function shebangLineFor(runtime: ScaffoldRuntime): string {
+  switch (runtime) {
+    case 'bun':
+      return '#!/usr/bin/env -S bun';
+    case 'deno':
+      return '#!/usr/bin/env -S deno run -A';
+    case 'node':
+      return '#!/usr/bin/env -S node';
+  }
+}

package/dist/exports/attestation.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"attestation.mjs","names":["sorted: Record<string, unknown>"],"sources":["../../src/canonicalize-json.ts","../../src/attestation.ts"],"sourcesContent":["function sortKeys(value: unknown): unknown {\n  if (value === null || typeof value !== 'object') {\n    return value;\n  }\n  if (Array.isArray(value)) {\n    return value.map(sortKeys);\n  }\n  const sorted: Record<string, unknown> = {};\n  for (const key of Object.keys(value).sort()) {\n    sorted[key] = sortKeys((value as Record<string, unknown>)[key]);\n  }\n  return sorted;\n}\n\nexport function canonicalizeJson(value: unknown): string {\n  return JSON.stringify(sortKeys(value));\n}\n","import { createHash } from 'node:crypto';\nimport { canonicalizeContract } from '@prisma-next/contract/hashing';\nimport { canonicalizeJson } from './canonicalize-json';\nimport { readMigrationPackage, writeMigrationManifest } from './io';\nimport type { MigrationManifest, MigrationOps } from './types';\n\nexport interface VerifyResult {\n  readonly ok: boolean;\n  readonly reason?: 'draft' | 'mismatch';\n  readonly storedMigrationId?: string;\n  readonly computedMigrationId?: string;\n}\n\nfunction sha256Hex(input: string): string {\n  return createHash('sha256').update(input).digest('hex');\n}\n\nexport function computeMigrationId(manifest: MigrationManifest, ops: MigrationOps): string {\n  const {\n    migrationId: _migrationId,\n    signature: _signature,\n    fromContract: _fromContract,\n    toContract: _toContract,\n    ...strippedMeta\n  } = manifest;\n\n  const canonicalManifest = canonicalizeJson(strippedMeta);\n  const canonicalOps = canonicalizeJson(ops);\n\n  const canonicalFromContract =\n    manifest.fromContract !== null ? canonicalizeContract(manifest.fromContract) : 'null';\n  const canonicalToContract = canonicalizeContract(manifest.toContract);\n\n  const partHashes = [\n    canonicalManifest,\n    canonicalOps,\n    canonicalFromContract,\n    canonicalToContract,\n  ].map(sha256Hex);\n  const hash = sha256Hex(canonicalizeJson(partHashes));\n\n  return `sha256:${hash}`;\n}\n\nexport async function attestMigration(dir: string): Promise<string> {\n  const pkg = await readMigrationPackage(dir);\n  const migrationId = computeMigrationId(pkg.manifest, pkg.ops);\n\n  const updated = { ...pkg.manifest, migrationId };\n  await writeMigrationManifest(dir, updated);\n\n  return migrationId;\n}\n\nexport async function verifyMigration(dir: string): Promise<VerifyResult> {\n  const pkg = await readMigrationPackage(dir);\n\n  if (pkg.manifest.migrationId === null) {\n    return { ok: false, reason: 'draft' };\n  }\n\n  const computed = computeMigrationId(pkg.manifest, pkg.ops);\n\n  if (pkg.manifest.migrationId === computed) {\n    return { ok: true, storedMigrationId: pkg.manifest.migrationId, computedMigrationId: computed };\n  }\n\n  return {\n    ok: false,\n    reason: 'mismatch',\n    storedMigrationId: pkg.manifest.migrationId,\n    computedMigrationId: computed,\n  };\n}\n"],"mappings":";;;;;AAAA,SAAS,SAAS,OAAyB;AACzC,KAAI,UAAU,QAAQ,OAAO,UAAU,SACrC,QAAO;AAET,KAAI,MAAM,QAAQ,MAAM,CACtB,QAAO,MAAM,IAAI,SAAS;CAE5B,MAAMA,SAAkC,EAAE;AAC1C,MAAK,MAAM,OAAO,OAAO,KAAK,MAAM,CAAC,MAAM,CACzC,QAAO,OAAO,SAAU,MAAkC,KAAK;AAEjE,QAAO;;AAGT,SAAgB,iBAAiB,OAAwB;AACvD,QAAO,KAAK,UAAU,SAAS,MAAM,CAAC;;;;;ACFxC,SAAS,UAAU,OAAuB;AACxC,QAAO,WAAW,SAAS,CAAC,OAAO,MAAM,CAAC,OAAO,MAAM;;AAGzD,SAAgB,mBAAmB,UAA6B,KAA2B;CACzF,MAAM,EACJ,aAAa,cACb,WAAW,YACX,cAAc,eACd,YAAY,aACZ,GAAG,iBACD;AAiBJ,QAAO,UAFM,UAAU,iBANJ;EAPO,iBAAiB,aAAa;EACnC,iBAAiB,IAAI;EAGxC,SAAS,iBAAiB,OAAO,qBAAqB,SAAS,aAAa,GAAG;EACrD,qBAAqB,SAAS,WAAW;EAOpE,CAAC,IAAI,UAAU,CACmC,CAAC;;AAKtD,eAAsB,gBAAgB,KAA8B;CAClE,MAAM,MAAM,MAAM,qBAAqB,IAAI;CAC3C,MAAM,cAAc,mBAAmB,IAAI,UAAU,IAAI,IAAI;AAG7D,OAAM,uBAAuB,KADb;EAAE,GAAG,IAAI;EAAU;EAAa,CACN;AAE1C,QAAO;;AAGT,eAAsB,gBAAgB,KAAoC;CACxE,MAAM,MAAM,MAAM,qBAAqB,IAAI;AAE3C,KAAI,IAAI,SAAS,gBAAgB,KAC/B,QAAO;EAAE,IAAI;EAAO,QAAQ;EAAS;CAGvC,MAAM,WAAW,mBAAmB,IAAI,UAAU,IAAI,IAAI;AAE1D,KAAI,IAAI,SAAS,gBAAgB,SAC/B,QAAO;EAAE,IAAI;EAAM,mBAAmB,IAAI,SAAS;EAAa,qBAAqB;EAAU;AAGjG,QAAO;EACL,IAAI;EACJ,QAAQ;EACR,mBAAmB,IAAI,SAAS;EAChC,qBAAqB;EACtB"}

package/dist/io-LsuurzNb.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"io-LsuurzNb.mjs","names":["manifestRaw: string","opsRaw: string","manifest: MigrationManifest","ops: MigrationOps","entries: string[]","packages: BaseMigrationBundle[]"],"sources":["../src/io.ts"],"sourcesContent":["import { 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\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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"}