@prisma-next/cli 0.3.0-pr.99.5 → 0.3.0

package/src/commands/migration-plan.ts

@@ -0,0 +1,519 @@
+import { readFile } from 'node:fs/promises';
+import type { Contract } from '@prisma-next/contract/types';
+import type { OperationDescriptor } from '@prisma-next/framework-components/control';
+import { attestMigration } from '@prisma-next/migration-tools/attestation';
+import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
+import { findLatestMigration } from '@prisma-next/migration-tools/dag';
+import {
+  formatMigrationDirName,
+  writeMigrationOps,
+  writeMigrationPackage,
+} from '@prisma-next/migration-tools/io';
+import {
+  evaluateMigrationTs,
+  scaffoldMigrationTs,
+} from '@prisma-next/migration-tools/migration-ts';
+import { type MigrationManifest, MigrationToolsError } from '@prisma-next/migration-tools/types';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { join, relative } from 'pathe';
+import { loadConfig } from '../config-loader';
+import { extractSqlDdl } from '../control-api/operations/extract-sql-ddl';
+import {
+  type CliErrorConflict,
+  CliStructuredError,
+  errorContractValidationFailed,
+  errorFileNotFound,
+  errorMigrationPlanningFailed,
+  errorRuntime,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  getTargetMigrations,
+  loadAllBundles,
+  resolveContractPath,
+  resolveMigrationPaths,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../utils/command-helpers';
+import { formatStyledHeader } from '../utils/formatters/styled';
+import { assertFrameworkComponentsCompatible } from '../utils/framework-components';
+import type { CommonCommandOptions } from '../utils/global-flags';
+import { type GlobalFlags, parseGlobalFlags } from '../utils/global-flags';
+import { handleResult } from '../utils/result-handler';
+import { TerminalUI } from '../utils/terminal-ui';
+
+interface MigrationPlanOptions extends CommonCommandOptions {
+  readonly config?: string;
+  readonly name?: string;
+  readonly from?: string;
+}
+
+export interface MigrationPlanResult {
+  readonly ok: boolean;
+  readonly noOp: boolean;
+  readonly from: string;
+  readonly to: string;
+  readonly migrationId?: string;
+  readonly dir?: string;
+  readonly operations: readonly {
+    readonly id: string;
+    readonly label: string;
+    readonly operationClass: string;
+  }[];
+  readonly sql?: readonly string[];
+  readonly summary: string;
+  readonly timings: {
+    readonly total: number;
+  };
+}
+
+function mapMigrationToolsError(error: unknown): CliStructuredError {
+  if (CliStructuredError.is(error)) {
+    return error;
+  }
+  if (MigrationToolsError.is(error)) {
+    return errorRuntime(error.message, {
+      why: error.why,
+      fix: error.fix,
+      meta: { code: error.code, ...(error.details ?? {}) },
+    });
+  }
+  return errorUnexpected(error instanceof Error ? error.message : String(error), {
+    why: `Unexpected error during migration plan: ${error instanceof Error ? error.message : String(error)}`,
+  });
+}
+
+async function executeMigrationPlanCommand(
+  options: MigrationPlanOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+  startTime: number,
+): Promise<Result<MigrationPlanResult, CliStructuredError>> {
+  const config = await loadConfig(options.config);
+  const { configPath, migrationsDir, migrationsRelative } = resolveMigrationPaths(
+    options.config,
+    config,
+  );
+
+  const contractPathAbsolute = resolveContractPath(config);
+  const contractPath = relative(process.cwd(), contractPathAbsolute);
+
+  if (!flags.json && !flags.quiet) {
+    const details: Array<{ label: string; value: string }> = [
+      { label: 'config', value: configPath },
+      { label: 'contract', value: contractPath },
+      { label: 'migrations', value: migrationsRelative },
+    ];
+    if (options.from) {
+      details.push({ label: 'from', value: options.from });
+    }
+    if (options.name) {
+      details.push({ label: 'name', value: options.name });
+    }
+    const header = formatStyledHeader({
+      command: 'migration plan',
+      description: 'Plan a migration from contract changes',
+      url: 'https://pris.ly/migration-plan',
+      details,
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  // Load contract file (the "to" contract)
+  let contractJsonContent: string;
+  try {
+    contractJsonContent = await readFile(contractPathAbsolute, 'utf-8');
+  } catch (error) {
+    if (error instanceof Error && (error as { code?: string }).code === 'ENOENT') {
+      return notOk(
+        errorFileNotFound(contractPathAbsolute, {
+          why: `Contract file not found at ${contractPathAbsolute}`,
+          fix: `Run \`prisma-next contract emit\` to generate ${contractPath}, or update \`config.contract.output\` in ${configPath}`,
+        }),
+      );
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to read contract file: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+
+  let toContractJson: Contract;
+  try {
+    toContractJson = JSON.parse(contractJsonContent) as Contract;
+  } catch (error) {
+    return notOk(
+      errorContractValidationFailed(
+        `Contract JSON is invalid: ${error instanceof Error ? error.message : String(error)}`,
+        { where: { path: contractPathAbsolute } },
+      ),
+    );
+  }
+
+  const rawStorageHash = toContractJson.storage?.storageHash;
+  if (typeof rawStorageHash !== 'string') {
+    return notOk(
+      errorContractValidationFailed('Contract is missing storageHash', {
+        where: { path: contractPathAbsolute },
+      }),
+    );
+  }
+  const toStorageHash = rawStorageHash;
+
+  // Read existing migrations and determine "from" contract
+  let fromContract: Contract | null = null;
+  let fromHash: string = EMPTY_CONTRACT_HASH;
+
+  try {
+    const { attested: bundles, drafts, graph } = await loadAllBundles(migrationsDir);
+
+    // Check if a draft migration already targets this contract
+    const existingDraft = drafts.find((d) => d.manifest.to === toStorageHash);
+    if (existingDraft) {
+      return notOk(
+        errorRuntime('A draft migration to this contract already exists', {
+          why: `Draft migration at "${existingDraft.dirName}" already targets ${toStorageHash}`,
+          fix: `Run 'prisma-next migration verify --dir ${migrationsRelative}/${existingDraft.dirName}' to attest it, or delete it and re-plan.`,
+        }),
+      );
+    }
+
+    if (options.from) {
+      const resolved = resolveBundleByPrefix(bundles, options.from);
+      if (!resolved.ok) {
+        const f = resolved.failure;
+        return notOk(
+          f.reason === 'ambiguous'
+            ? errorRuntime('Multiple matching migrations found', {
+                why: `Prefix "${options.from}" matches ${f.count} migrations in ${migrationsRelative}`,
+                fix: 'Provide a longer prefix to disambiguate, or omit --from to use the latest migration target.',
+              })
+            : errorRuntime('Starting contract not found', {
+                why: `No migration with to hash matching "${options.from}" exists in ${migrationsRelative}`,
+                fix: 'Check that the --from hash matches a known migration target hash, or omit --from to use the latest migration target.',
+              }),
+        );
+      }
+      fromHash = resolved.value.manifest.to;
+      fromContract = resolved.value.manifest.toContract;
+    } else {
+      const latestMigration = findLatestMigration(graph);
+      if (latestMigration) {
+        fromHash = latestMigration.to;
+        const leafPkg = bundles.find((p) => p.manifest.migrationId === latestMigration.migrationId);
+        if (leafPkg) {
+          fromContract = leafPkg.manifest.toContract;
+        }
+      }
+    }
+  } catch (error) {
+    if (MigrationToolsError.is(error)) {
+      return notOk(mapMigrationToolsError(error));
+    }
+    throw error;
+  }
+
+  // Check for no-op (same hash means no changes)
+  if (fromHash === toStorageHash) {
+    const result: MigrationPlanResult = {
+      ok: true,
+      noOp: true,
+      from: fromHash,
+      to: toStorageHash,
+      operations: [],
+      summary: 'No changes detected between contracts',
+      timings: { total: Date.now() - startTime },
+    };
+    return ok(result);
+  }
+
+  // Check target supports migrations
+  const migrations = getTargetMigrations(config.target);
+  if (!migrations) {
+    return notOk(
+      errorTargetMigrationNotSupported({
+        why: `Target "${config.target.id}" does not support migrations`,
+      }),
+    );
+  }
+  const frameworkComponents = assertFrameworkComponentsCompatible(
+    config.family.familyId,
+    config.target.targetId,
+    [config.target, config.adapter, ...(config.extensionPacks ?? [])],
+  );
+
+  // Use descriptor-based planner if available, fall back to old planner
+  if (migrations.planWithDescriptors) {
+    const descriptorResult = migrations.planWithDescriptors({
+      fromContract,
+      toContract: toContractJson,
+      frameworkComponents,
+    });
+
+    if (!descriptorResult.ok) {
+      return notOk(
+        errorMigrationPlanningFailed({
+          conflicts: descriptorResult.conflicts as readonly CliErrorConflict[],
+        }),
+      );
+    }
+
+    if (descriptorResult.descriptors.length === 0) {
+      return notOk(
+        errorMigrationPlanningFailed({
+          conflicts: [
+            {
+              kind: 'unsupportedChange',
+              summary:
+                'Contract changed but planner produced no operations. ' +
+                'This indicates unsupported or ignored changes.',
+            },
+          ],
+        }),
+      );
+    }
+
+    // Build manifest and write migration package
+    const timestamp = new Date();
+    const slug = options.name ?? 'migration';
+    const dirName = formatMigrationDirName(timestamp, slug);
+    const packageDir = join(migrationsDir, dirName);
+
+    const manifest: MigrationManifest = {
+      from: fromHash,
+      to: toStorageHash,
+      migrationId: null,
+      kind: 'regular',
+      fromContract,
+      toContract: toContractJson,
+      hints: {
+        used: [],
+        applied: [],
+        plannerVersion: '2.0.0',
+        planningStrategy: 'descriptors',
+      },
+      labels: [],
+      createdAt: timestamp.toISOString(),
+    };
+
+    try {
+      // Always write migration.ts with the descriptors
+      // Write package with empty ops first (draft)
+      await writeMigrationPackage(packageDir, manifest, []);
+      await scaffoldMigrationTs(packageDir, {
+        descriptors: descriptorResult.descriptors,
+        contractJsonPath: contractPathAbsolute,
+      });
+
+      if (descriptorResult.needsDataMigration) {
+        // Draft — user must fill in dataTransform and run verify
+        const result: MigrationPlanResult = {
+          ok: true,
+          noOp: false,
+          from: fromHash,
+          to: toStorageHash,
+          dir: relative(process.cwd(), packageDir),
+          operations: descriptorResult.descriptors.map((d) => ({
+            id: (d as { kind: string }).kind,
+            label: (d as { kind: string }).kind,
+            operationClass: 'data' as const,
+          })),
+          sql: [],
+          summary: `Planned ${descriptorResult.descriptors.length} operation(s) — data migration required. Edit migration.ts and run \`migration verify --dir ${relative(process.cwd(), packageDir)}\` to attest.`,
+          timings: { total: Date.now() - startTime },
+        };
+        return ok(result);
+      }
+
+      // No data migration — evaluate, resolve, write ops, attest
+      const evaluatedDescriptors = await evaluateMigrationTs(packageDir);
+
+      if (!migrations.resolveDescriptors) {
+        throw errorTargetMigrationNotSupported({
+          why: `Target "${config.target.targetId}" does not implement resolveDescriptors; cannot finalize migration plan with migration.ts`,
+        });
+      }
+
+      const resolvedOps = migrations.resolveDescriptors(
+        evaluatedDescriptors as OperationDescriptor[],
+        {
+          fromContract,
+          toContract: toContractJson,
+          frameworkComponents,
+        },
+      );
+
+      await writeMigrationOps(packageDir, resolvedOps);
+      const migrationId = await attestMigration(packageDir);
+
+      const sql = extractSqlDdl(resolvedOps);
+      const result: MigrationPlanResult = {
+        ok: true,
+        noOp: false,
+        from: fromHash,
+        to: toStorageHash,
+        migrationId,
+        dir: relative(process.cwd(), packageDir),
+        operations: resolvedOps.map((op) => ({
+          id: op.id,
+          label: op.label,
+          operationClass: op.operationClass,
+        })),
+        sql,
+        summary: `Planned ${resolvedOps.length} operation(s)`,
+        timings: { total: Date.now() - startTime },
+      };
+      return ok(result);
+    } catch (error) {
+      return notOk(mapMigrationToolsError(error));
+    }
+  }
+
+  return notOk(
+    errorTargetMigrationNotSupported({
+      why: `Target "${config.target.id}" does not support planWithDescriptors`,
+    }),
+  );
+}
+
+export function createMigrationPlanCommand(): Command {
+  const command = new Command('plan');
+  setCommandDescriptions(
+    command,
+    'Plan a migration from contract changes',
+    'Compares the emitted contract against the latest on-disk migration state and\n' +
+      'produces a new migration package with the required operations. No database\n' +
+      'connection is needed — this is a fully offline operation.',
+  );
+  setCommandExamples(command, [
+    'prisma-next migration plan',
+    'prisma-next migration plan --name add-users-table',
+  ]);
+  addGlobalOptions(command)
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .option('--name <slug>', 'Name slug for the migration directory', 'migration')
+    .option('--from <hash>', 'Explicit starting contract hash (overrides latest migration target)')
+    .action(async (options: MigrationPlanOptions) => {
+      const flags = parseGlobalFlags(options);
+      const startTime = Date.now();
+
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+      const result = await executeMigrationPlanCommand(options, flags, ui, startTime);
+
+      const exitCode = handleResult(result, flags, ui, (planResult) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(planResult, null, 2));
+        } else if (!flags.quiet) {
+          ui.log(formatMigrationPlanOutput(planResult, flags));
+        }
+      });
+
+      process.exit(exitCode);
+    });
+
+  return command;
+}
+
+function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFlags): string {
+  const lines: string[] = [];
+  const useColor = flags.color !== false;
+
+  const green_ = useColor ? (s: string) => `\x1b[32m${s}\x1b[0m` : (s: string) => s;
+  const yellow_ = useColor ? (s: string) => `\x1b[33m${s}\x1b[0m` : (s: string) => s;
+  const dim_ = useColor ? (s: string) => `\x1b[2m${s}\x1b[0m` : (s: string) => s;
+
+  if (result.noOp) {
+    lines.push(`${green_('✔')} No changes detected`);
+    lines.push(dim_(`  from: ${result.from}`));
+    lines.push(dim_(`  to:   ${result.to}`));
+    return lines.join('\n');
+  }
+
+  lines.push(`${green_('✔')} ${result.summary}`);
+  lines.push('');
+
+  if (result.operations.length > 0) {
+    lines.push(dim_('│'));
+    for (let i = 0; i < result.operations.length; i++) {
+      const op = result.operations[i]!;
+      const isLast = i === result.operations.length - 1;
+      const treeChar = isLast ? '└' : '├';
+      const opClassLabel =
+        op.operationClass === 'destructive'
+          ? yellow_(`[${op.operationClass}]`)
+          : dim_(`[${op.operationClass}]`);
+      lines.push(`${dim_(treeChar)}─ ${op.label} ${opClassLabel}`);
+    }
+
+    const hasDestructive = result.operations.some((op) => op.operationClass === 'destructive');
+    if (hasDestructive) {
+      lines.push('');
+      lines.push(
+        `${yellow_('⚠')} This migration contains destructive operations that may cause data loss.`,
+      );
+    }
+    lines.push('');
+  }
+
+  lines.push(dim_(`from:   ${result.from}`));
+  lines.push(dim_(`to:     ${result.to}`));
+  if (result.migrationId) {
+    lines.push(dim_(`migrationId: ${result.migrationId}`));
+  }
+  if (result.dir) {
+    lines.push(dim_(`dir:    ${result.dir}`));
+  }
+
+  if (result.sql && result.sql.length > 0) {
+    lines.push('');
+    lines.push(dim_('DDL preview'));
+    lines.push('');
+    for (const statement of result.sql) {
+      const trimmed = statement.trim();
+      if (!trimmed) continue;
+      const line = trimmed.endsWith(';') ? trimmed : `${trimmed};`;
+      lines.push(line);
+    }
+  }
+
+  if (flags.verbose && result.timings) {
+    lines.push('');
+    lines.push(dim_(`Total time: ${result.timings.total}ms`));
+  }
+
+  return lines.join('\n');
+}
+
+export type PrefixResolutionFailure =
+  | { reason: 'ambiguous'; count: number }
+  | { reason: 'not-found' };
+
+/**
+ * Resolve a migration bundle by exact hash or prefix match.
+ *
+ * Tries exact match first, then prefix match (auto-prepending `sha256:` when
+ * the needle omits the scheme). Returns the matched bundle on success, or a
+ * discriminated failure indicating whether the prefix was ambiguous or simply
+ * not found.
+ *
+ * @internal Exported for testing only.
+ */
+export function resolveBundleByPrefix<T extends { manifest: { to: string } }>(
+  bundles: readonly T[],
+  needle: string,
+): Result<T, PrefixResolutionFailure> {
+  const exact = bundles.find((p) => p.manifest.to === needle);
+  if (exact) return ok(exact);
+
+  const prefixWithScheme = needle.startsWith('sha256:') ? needle : `sha256:${needle}`;
+  const candidates = bundles.filter((p) => p.manifest.to.startsWith(prefixWithScheme));
+
+  if (candidates.length === 1) return ok(candidates[0]!);
+  if (candidates.length > 1) return notOk({ reason: 'ambiguous', count: candidates.length });
+  return notOk({ reason: 'not-found' });
+}