@prisma-next/migration-tools 0.0.1

package/src/errors.ts

@@ -0,0 +1,121 @@
+/**
+ * Structured error for migration tooling operations.
+ *
+ * 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
+ * failures (PRECHECK_FAILED, POSTCHECK_FAILED, etc.).
+ *
+ * Fields:
+ * - code:     Stable machine-readable code (MIGRATION.SUBCODE)
+ * - category: Always 'MIGRATION'
+ * - why:      Explains the cause in plain language
+ * - fix:      Actionable remediation step
+ * - details:  Machine-readable structured data for agents
+ */
+export class MigrationToolsError extends Error {
+  readonly code: string;
+  readonly category = 'MIGRATION' as const;
+  readonly why: string;
+  readonly fix: string;
+  readonly details: Record<string, unknown> | undefined;
+
+  constructor(
+    code: string,
+    summary: string,
+    options: {
+      readonly why: string;
+      readonly fix: string;
+      readonly details?: Record<string, unknown>;
+    },
+  ) {
+    super(summary);
+    this.name = 'MigrationToolsError';
+    this.code = code;
+    this.why = options.why;
+    this.fix = options.fix;
+    this.details = options.details;
+  }
+
+  static is(error: unknown): error is MigrationToolsError {
+    if (!(error instanceof Error)) return false;
+    const candidate = error as MigrationToolsError;
+    return candidate.name === 'MigrationToolsError' && typeof candidate.code === 'string';
+  }
+}
+
+export function errorDirectoryExists(dir: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.DIR_EXISTS', 'Migration directory already exists', {
+    why: `The directory "${dir}" already exists. Each migration must have a unique directory.`,
+    fix: 'Use --name to pick a different name, or delete the existing directory and re-run.',
+    details: { dir },
+  });
+}
+
+export function errorMissingFile(file: string, dir: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.FILE_MISSING', `Missing ${file}`, {
+    why: `Expected "${file}" in "${dir}" but the file does not exist.`,
+    fix: 'Ensure the migration directory contains both migration.json and ops.json. If the directory is corrupt, delete it and re-run migration plan.',
+    details: { file, dir },
+  });
+}
+
+export function errorInvalidJson(filePath: string, parseError: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_JSON', 'Invalid JSON in migration file', {
+    why: `Failed to parse "${filePath}": ${parseError}`,
+    fix: 'Fix the JSON syntax error, or delete the migration directory and re-run migration plan.',
+    details: { filePath, parseError },
+  });
+}
+
+export function errorInvalidManifest(filePath: string, reason: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_MANIFEST', 'Invalid migration manifest', {
+    why: `Manifest at "${filePath}" is invalid: ${reason}`,
+    fix: 'Ensure the manifest has all required fields (from, to, kind, toContract). If corrupt, delete and re-plan.',
+    details: { filePath, reason },
+  });
+}
+
+export function errorInvalidSlug(slug: string): MigrationToolsError {
+  return new MigrationToolsError('MIGRATION.INVALID_NAME', 'Invalid migration name', {
+    why: `The slug "${slug}" contains no valid characters after sanitization (only a-z, 0-9 are kept).`,
+    fix: 'Provide a name with at least one alphanumeric character, e.g. --name add_users.',
+    details: { slug },
+  });
+}
+
+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 errorAmbiguousLeaf(leaves: readonly string[]): MigrationToolsError {
+  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.`,
+    fix: 'Delete one of the conflicting migration directories, then re-run `migration plan` to re-plan it from the remaining branch. Or use --from <hash> to explicitly select a starting point.',
+    details: { leaves },
+  });
+}
+
+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(', ')}). Every migration references a parentMigrationId that does not exist, or the graph contains a cycle in parent pointers.`,
+    fix: 'Inspect the migrations directory for corrupted migration.json files. Exactly one migration must have parentMigrationId set to null (the first migration).',
+    details: { nodes },
+  });
+}
+
+export function errorDuplicateMigrationId(migrationId: string): MigrationToolsError {
+  return new MigrationToolsError(
+    'MIGRATION.DUPLICATE_MIGRATION_ID',
+    'Duplicate migrationId in migration graph',
+    {
+      why: `Multiple migrations share migrationId "${migrationId}". This makes parent-chain reconstruction ambiguous and unsafe.`,
+      fix: 'Regenerate one of the conflicting migrations so each migrationId is unique, then re-run migration commands.',
+      details: { migrationId },
+    },
+  );
+}

package/src/exports/attestation.ts

@@ -0,0 +1 @@
+export { attestMigration, computeMigrationId, verifyMigration } from '../attestation';

package/src/exports/dag.ts

@@ -0,0 +1,8 @@
+export {
+  detectCycles,
+  detectOrphans,
+  findLatestMigration,
+  findLeaf,
+  findPath,
+  reconstructGraph,
+} from '../dag';

package/src/exports/io.ts

@@ -0,0 +1,6 @@
+export {
+  formatMigrationDirName,
+  readMigrationPackage,
+  readMigrationsDir,
+  writeMigrationPackage,
+} from '../io';

package/src/exports/types.ts

@@ -0,0 +1,9 @@
+export { MigrationToolsError } from '../errors';
+export type {
+  MigrationChainEntry,
+  MigrationGraph,
+  MigrationHints,
+  MigrationManifest,
+  MigrationOps,
+  MigrationPackage,
+} from '../types';

package/src/io.ts

@@ -0,0 +1,197 @@
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { type } from 'arktype';
+import { basename, dirname, join } from 'pathe';
+import {
+  errorDirectoryExists,
+  errorInvalidJson,
+  errorInvalidManifest,
+  errorInvalidSlug,
+  errorMissingFile,
+} from './errors';
+import type { MigrationManifest, MigrationOps, MigrationPackage } from './types';
+
+const MANIFEST_FILE = 'migration.json';
+const OPS_FILE = 'ops.json';
+const MAX_SLUG_LENGTH = 64;
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return error instanceof Error && (error as { code?: string }).code === code;
+}
+
+const MigrationHintsSchema = type({
+  used: 'string[]',
+  applied: 'string[]',
+  plannerVersion: 'string',
+  planningStrategy: 'string',
+});
+
+const MigrationManifestSchema = type({
+  from: 'string',
+  to: 'string',
+  migrationId: 'string | null',
+  parentMigrationId: 'string | null',
+  kind: "'regular' | 'baseline'",
+  fromContract: 'object | null',
+  toContract: 'object',
+  hints: MigrationHintsSchema,
+  labels: 'string[]',
+  'authorship?': type({
+    'author?': 'string',
+    'email?': 'string',
+  }),
+  'signature?': type({
+    keyId: 'string',
+    value: 'string',
+  }).or('null'),
+  createdAt: 'string',
+});
+
+const MigrationOpSchema = type({
+  id: 'string',
+  label: 'string',
+  operationClass: "'additive' | 'widening' | 'destructive'",
+});
+
+// Intentionally shallow: operation-specific payload validation is owned by planner/runner layers.
+const MigrationOpsSchema = MigrationOpSchema.array();
+
+export async function writeMigrationPackage(
+  dir: string,
+  manifest: MigrationManifest,
+  ops: MigrationOps,
+): Promise<void> {
+  await mkdir(dirname(dir), { recursive: true });
+
+  try {
+    await mkdir(dir);
+  } catch (error) {
+    if (hasErrnoCode(error, 'EEXIST')) {
+      throw errorDirectoryExists(dir);
+    }
+    throw error;
+  }
+
+  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' });
+}
+
+export async function readMigrationPackage(dir: string): Promise<MigrationPackage> {
+  const manifestPath = join(dir, MANIFEST_FILE);
+  const opsPath = join(dir, OPS_FILE);
+
+  let manifestRaw: string;
+  try {
+    manifestRaw = await readFile(manifestPath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      throw errorMissingFile(MANIFEST_FILE, dir);
+    }
+    throw error;
+  }
+
+  let opsRaw: string;
+  try {
+    opsRaw = await readFile(opsPath, 'utf-8');
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      throw errorMissingFile(OPS_FILE, dir);
+    }
+    throw error;
+  }
+
+  let manifest: MigrationManifest;
+  try {
+    manifest = JSON.parse(manifestRaw);
+  } catch (e) {
+    throw errorInvalidJson(manifestPath, e instanceof Error ? e.message : String(e));
+  }
+
+  let ops: MigrationOps;
+  try {
+    ops = JSON.parse(opsRaw);
+  } catch (e) {
+    throw errorInvalidJson(opsPath, e instanceof Error ? e.message : String(e));
+  }
+
+  validateManifest(manifest, manifestPath);
+  validateOps(ops, opsPath);
+
+  return {
+    dirName: basename(dir),
+    dirPath: dir,
+    manifest,
+    ops,
+  };
+}
+
+function validateManifest(
+  manifest: unknown,
+  filePath: string,
+): asserts manifest is MigrationManifest {
+  const result = MigrationManifestSchema(manifest);
+  if (result instanceof type.errors) {
+    throw errorInvalidManifest(filePath, result.summary);
+  }
+}
+
+function validateOps(ops: unknown, filePath: string): asserts ops is MigrationOps {
+  const result = MigrationOpsSchema(ops);
+  if (result instanceof type.errors) {
+    throw errorInvalidManifest(filePath, result.summary);
+  }
+}
+
+export async function readMigrationsDir(
+  migrationsRoot: string,
+): Promise<readonly MigrationPackage[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(migrationsRoot);
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) {
+      return [];
+    }
+    throw error;
+  }
+
+  const packages: MigrationPackage[] = [];
+
+  for (const entry of entries.sort()) {
+    const entryPath = join(migrationsRoot, entry);
+    const entryStat = await stat(entryPath);
+    if (!entryStat.isDirectory()) continue;
+
+    const manifestPath = join(entryPath, MANIFEST_FILE);
+    try {
+      await stat(manifestPath);
+    } catch {
+      continue; // skip non-migration directories
+    }
+
+    packages.push(await readMigrationPackage(entryPath));
+  }
+
+  return packages;
+}
+
+export function formatMigrationDirName(timestamp: Date, slug: string): string {
+  const sanitized = slug
+    .toLowerCase()
+    .replace(/[^a-z0-9]/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '');
+
+  if (sanitized.length === 0) {
+    throw errorInvalidSlug(slug);
+  }
+
+  const truncated = sanitized.slice(0, MAX_SLUG_LENGTH);
+
+  const y = timestamp.getUTCFullYear();
+  const mo = String(timestamp.getUTCMonth() + 1).padStart(2, '0');
+  const d = String(timestamp.getUTCDate()).padStart(2, '0');
+  const h = String(timestamp.getUTCHours()).padStart(2, '0');
+  const mi = String(timestamp.getUTCMinutes()).padStart(2, '0');
+
+  return `${y}${mo}${d}T${h}${mi}_${truncated}`;
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+import type { ContractIR } from '@prisma-next/contract/ir';
+import type { MigrationPlanOperation } from '@prisma-next/core-control-plane/types';
+
+export interface MigrationHints {
+  readonly used: readonly string[];
+  readonly applied: readonly string[];
+  readonly plannerVersion: string;
+  readonly planningStrategy: string;
+}
+
+export interface MigrationManifest {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationId: string | null;
+  readonly parentMigrationId: string | null;
+  readonly kind: 'regular' | 'baseline';
+  readonly fromContract: ContractIR | null;
+  readonly toContract: ContractIR;
+  readonly hints: MigrationHints;
+  readonly labels: readonly string[];
+  readonly authorship?: { readonly author?: string; readonly email?: string };
+  readonly signature?: { readonly keyId: string; readonly value: string } | null;
+  readonly createdAt: string;
+}
+
+export type MigrationOps = readonly MigrationPlanOperation[];
+
+export interface MigrationPackage {
+  readonly dirName: string;
+  readonly dirPath: string;
+  readonly manifest: MigrationManifest;
+  readonly ops: MigrationOps;
+}
+
+export interface MigrationChainEntry {
+  readonly from: string;
+  readonly to: string;
+  readonly migrationId: string | null;
+  readonly parentMigrationId: string | null;
+  readonly dirName: string;
+  readonly createdAt: string;
+  readonly labels: readonly string[];
+}
+
+export interface MigrationGraph {
+  readonly nodes: ReadonlySet<string>;
+  readonly forwardChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly reverseChain: ReadonlyMap<string, readonly MigrationChainEntry[]>;
+  readonly migrationById: ReadonlyMap<string, MigrationChainEntry>;
+  readonly childrenByParentId: ReadonlyMap<string | null, readonly MigrationChainEntry[]>;
+}