@prisma-next/cli 0.4.0-dev.5 → 0.4.0-dev.7

package/src/commands/migration-emit.ts

@@ -0,0 +1,134 @@
+import { MigrationToolsError } from '@prisma-next/migration-tools/types';
+import { notOk, ok, type Result } from '@prisma-next/utils/result';
+import { Command } from 'commander';
+import { loadConfig } from '../config-loader';
+import { emitMigration } from '../lib/migration-emit';
+import {
+  CliStructuredError,
+  errorRuntime,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+} from '../utils/cli-errors';
+import {
+  addGlobalOptions,
+  getTargetMigrations,
+  setCommandDescriptions,
+  setCommandExamples,
+} from '../utils/command-helpers';
+import { formatMigrationEmitCommandOutput } from '../utils/formatters/migrations';
+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';
+
+export interface MigrationEmitOptions extends CommonCommandOptions {
+  readonly dir: string;
+  readonly config?: string;
+}
+
+export interface MigrationEmitResult {
+  readonly ok: boolean;
+  readonly dir: string;
+  readonly migrationId: string;
+  readonly summary: string;
+}
+
+async function executeMigrationEmitCommand(
+  options: MigrationEmitOptions,
+  flags: GlobalFlags,
+  ui: TerminalUI,
+): Promise<Result<MigrationEmitResult, CliStructuredError>> {
+  const dir = options.dir;
+
+  if (!flags.json && !flags.quiet) {
+    const header = formatStyledHeader({
+      command: 'migration emit',
+      description: 'Emit ops.json from migration.ts and compute migrationId',
+      details: [{ label: 'dir', value: dir }],
+      flags,
+    });
+    ui.stderr(header);
+  }
+
+  try {
+    const config = await loadConfig(options.config);
+    const migrations = getTargetMigrations(config.target);
+    if (!migrations) {
+      throw 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 ?? [])],
+    );
+
+    const { migrationId } = await emitMigration(dir, {
+      targetId: config.target.targetId,
+      migrations,
+      frameworkComponents,
+    });
+
+    return ok({
+      ok: true,
+      dir,
+      migrationId,
+      summary: `Emitted ops.json and attested migrationId: ${migrationId}`,
+    });
+  } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
+    if (MigrationToolsError.is(error)) {
+      return notOk(
+        errorRuntime(error.message, {
+          why: error.why,
+          fix: error.fix,
+          meta: { code: error.code, ...(error.details ?? {}) },
+        }),
+      );
+    }
+    return notOk(
+      errorUnexpected(error instanceof Error ? error.message : String(error), {
+        why: `Failed to emit migration: ${error instanceof Error ? error.message : String(error)}`,
+      }),
+    );
+  }
+}
+
+export function createMigrationEmitCommand(): Command {
+  const command = new Command('emit');
+  setCommandDescriptions(
+    command,
+    'Emit ops.json from migration.ts and compute migrationId',
+    'Evaluates migration.ts in the package directory, resolves it to ops.json,\n' +
+      'then computes and persists the content-addressed migrationId in migration.json.\n' +
+      'If the file contains unfilled placeholder() slots, emit fails with PN-MIG-2001\n' +
+      'and reports the slot to fill in.',
+  );
+  setCommandExamples(command, ['prisma-next migration emit --dir migrations/20250101-add-users']);
+  addGlobalOptions(command)
+    .requiredOption('--dir <path>', 'Path to the migration package directory')
+    .option('--config <path>', 'Path to prisma-next.config.ts')
+    .action(async (options: MigrationEmitOptions) => {
+      const flags = parseGlobalFlags(options);
+      const ui = new TerminalUI({ color: flags.color, interactive: flags.interactive });
+
+      const result = await executeMigrationEmitCommand(options, flags, ui);
+
+      const exitCode = handleResult(result, flags, ui, (emitResult) => {
+        if (flags.json) {
+          ui.output(JSON.stringify(emitResult, null, 2));
+        } else if (!flags.quiet) {
+          ui.log(formatMigrationEmitCommandOutput(emitResult, flags));
+        }
+      });
+
+      process.exit(exitCode);
+    });
+
+  return command;
+}

package/src/commands/migration-new.ts

@@ -1,33 +1,47 @@
 /**
- * `migration new` — scaffolds a migration package with a migration.ts file
- * for manual authoring. The user writes operation descriptors and data
- * transforms; `migration verify` resolves them to ops.json.
+ * `migration new` — scaffolds a migration package with a `migration.ts` file
+ * for manual authoring.
+ *
+ * Both descriptor-flow (Postgres) and class-flow (Mongo) targets go through
+ * the same path here: the planner's `emptyMigration(context)` returns a
+ * `MigrationPlanWithAuthoringSurface`, whose `renderTypeScript()` produces
+ * the target-appropriate empty stub. The CLI writes the returned source
+ * verbatim.
  */
 
 import { readFileSync } from 'node:fs';
 import type { Contract } from '@prisma-next/contract/types';
+import { createControlStack } from '@prisma-next/framework-components/control';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { findLatestMigration, reconstructGraph } from '@prisma-next/migration-tools/dag';
 import {
+  copyContractToMigrationDir,
   formatMigrationDirName,
   readMigrationsDir,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
-import { scaffoldMigrationTs } from '@prisma-next/migration-tools/migration-ts';
+import { writeMigrationTs } from '@prisma-next/migration-tools/migration-ts';
 import type { MigrationManifest } from '@prisma-next/migration-tools/types';
 import { isAttested, MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
 import { join, relative, resolve } from 'pathe';
 import { loadConfig } from '../config-loader';
-import { type CliStructuredError, errorRuntime, errorUnexpected } from '../utils/cli-errors';
+import {
+  CliStructuredError,
+  errorRuntime,
+  errorTargetMigrationNotSupported,
+  errorUnexpected,
+} from '../utils/cli-errors';
 import {
   addGlobalOptions,
+  getTargetMigrations,
   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 { parseGlobalFlags } from '../utils/global-flags';
 import { handleResult } from '../utils/result-handler';
@@ -53,7 +67,6 @@ async function executeMigrationNewCommand(
   const config = await loadConfig(options.config);
   const { migrationsDir, migrationsRelative } = resolveMigrationPaths(options.config, config);
 
-  // Read the emitted contract (destination)
   const contractPath = config.contract?.output ?? 'contract.json';
   const contractPathAbsolute = resolve(
     options.config ? resolve(options.config, '..') : process.cwd(),
@@ -101,7 +114,6 @@ async function executeMigrationNewCommand(
     );
   }
 
-  // Determine "from" hash
   let fromContract: Contract | null = null;
   let fromHash: string = EMPTY_CONTRACT_HASH;
 
@@ -113,7 +125,6 @@ async function executeMigrationNewCommand(
       const graph = reconstructGraph(attested);
 
       if (options.from) {
-        // Explicit --from: find the migration with matching to hash
         const match = attested.find((p) => p.manifest.to.startsWith(options.from!));
         if (!match) {
           return notOk(
@@ -151,7 +162,6 @@ async function executeMigrationNewCommand(
     throw error;
   }
 
-  // Check for no-op
   if (fromHash === toStorageHash) {
     return notOk(
       errorRuntime('No changes detected', {
@@ -161,7 +171,6 @@ async function executeMigrationNewCommand(
     );
   }
 
-  // Build manifest and write package
   const timestamp = new Date();
   const slug = options.name ?? 'migration';
   const dirName = formatMigrationDirName(timestamp, slug);
@@ -184,12 +193,35 @@ async function executeMigrationNewCommand(
     createdAt: timestamp.toISOString(),
   };
 
+  const migrations = getTargetMigrations(config.target);
+  if (!migrations) {
+    return notOk(
+      errorTargetMigrationNotSupported({
+        why: `Target "${config.target.targetId}" does not support migrations`,
+      }),
+    );
+  }
+
   try {
-    // Write package with empty ops (draft)
+    assertFrameworkComponentsCompatible(config.family.familyId, config.target.targetId, [
+      config.target,
+      config.adapter,
+      ...(config.extensionPacks ?? []),
+    ]);
+
     await writeMigrationPackage(packageDir, manifest, []);
+    await copyContractToMigrationDir(packageDir, contractPathAbsolute);
 
-    // Scaffold migration.ts
-    await scaffoldMigrationTs(packageDir);
+    const stack = createControlStack(config);
+    const familyInstance = config.family.create(stack);
+    const planner = migrations.createPlanner(familyInstance);
+    const emptyPlan = planner.emptyMigration({
+      packageDir,
+      contractJsonPath: join(packageDir, 'contract.json'),
+      fromHash,
+      toHash: toStorageHash,
+    });
+    await writeMigrationTs(packageDir, emptyPlan.renderTypeScript());
 
     return ok({
       ok: true as const,
@@ -199,6 +231,9 @@ async function executeMigrationNewCommand(
       summary: `Scaffolded migration at ${relative(process.cwd(), packageDir)}`,
     });
   } catch (error) {
+    if (CliStructuredError.is(error)) {
+      return notOk(error);
+    }
     return notOk(
       errorUnexpected(error instanceof Error ? error.message : String(error), {
         why: `Failed to scaffold migration: ${error instanceof Error ? error.message : String(error)}`,
@@ -214,7 +249,7 @@ export function createMigrationNewCommand(): Command {
     'Scaffold a new migration for manual authoring',
     'Creates a migration package with a migration.ts file for manual authoring.\n' +
       'Write operation descriptors and data transforms in migration.ts, then run\n' +
-      '`migration verify` to resolve and attest the package.',
+      '`migration emit` to resolve and attest the package.',
   );
   setCommandExamples(command, [
     'prisma-next migration new --name split-name',
@@ -248,7 +283,7 @@ export function createMigrationNewCommand(): Command {
           ui.output(`  from: ${value.from}`);
           ui.output(`  to:   ${value.to}`);
           ui.output(
-            `\nEdit migration.ts, then run \`prisma-next migration verify --dir ${value.dir}\` to attest.`,
+            `\nEdit migration.ts, then run \`prisma-next migration emit --dir "${value.dir}"\` to attest.`,
           );
         }
       });

package/src/commands/migration-plan.ts

@@ -1,24 +1,22 @@
 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 { createControlStack } from '@prisma-next/framework-components/control';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { findLatestMigration } from '@prisma-next/migration-tools/dag';
 import {
+  copyContractToMigrationDir,
   formatMigrationDirName,
-  writeMigrationOps,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
-import {
-  evaluateMigrationTs,
-  scaffoldMigrationTs,
-} from '@prisma-next/migration-tools/migration-ts';
+import { writeMigrationTs } 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 { emitMigration } from '../lib/migration-emit';
+import { migrationStrategy } from '../lib/migration-strategy';
 import {
   type CliErrorConflict,
   CliStructuredError,
@@ -178,7 +176,7 @@ async function executeMigrationPlanCommand(
       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.`,
+          fix: `Run 'prisma-next migration emit --dir ${migrationsRelative}/${existingDraft.dirName}' to attest it, or delete it and re-plan.`,
         }),
       );
     }
@@ -247,138 +245,148 @@ async function executeMigrationPlanCommand(
     [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,
-    });
+  const strategy = migrationStrategy(migrations, config.target.targetId);
+
+  // 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: strategy === 'descriptor' ? 'descriptors' : 'class-based',
+    },
+    labels: [],
+    createdAt: timestamp.toISOString(),
+  };
 
-    if (!descriptorResult.ok) {
-      return notOk(
-        errorMigrationPlanningFailed({
-          conflicts: descriptorResult.conflicts as readonly CliErrorConflict[],
-        }),
-      );
-    }
+  const scaffoldContext = {
+    packageDir,
+    contractJsonPath: contractPathAbsolute,
+    fromHash,
+    toHash: toStorageHash,
+  };
 
-    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.',
-            },
-          ],
-        }),
+  try {
+    let migrationTsContent: string;
+
+    if (strategy === 'descriptor') {
+      if (!migrations.planWithDescriptors || !migrations.renderDescriptorTypeScript) {
+        throw errorTargetMigrationNotSupported({
+          why: `Target "${config.target.targetId}" advertises descriptor flow but is missing required hooks`,
+        });
+      }
+      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.',
+              },
+            ],
+          }),
+        );
+      }
+      migrationTsContent = migrations.renderDescriptorTypeScript(
+        descriptorResult.descriptors,
+        scaffoldContext,
       );
+    } else {
+      const stack = createControlStack(config);
+      const familyInstance = config.family.create(stack);
+      const planner = migrations.createPlanner(familyInstance);
+      const fromSchema = migrations.contractToSchema(fromContract, frameworkComponents);
+      const plannerResult = planner.plan({
+        contract: toContractJson,
+        schema: fromSchema,
+        policy: { allowedOperationClasses: ['additive', 'widening', 'destructive', 'data'] },
+        fromHash,
+        frameworkComponents,
+      });
+      if (plannerResult.kind === 'failure') {
+        return notOk(
+          errorMigrationPlanningFailed({
+            conflicts: plannerResult.conflicts as readonly CliErrorConflict[],
+          }),
+        );
+      }
+      if (plannerResult.plan.operations.length === 0) {
+        return notOk(
+          errorMigrationPlanningFailed({
+            conflicts: [
+              {
+                kind: 'unsupportedChange',
+                summary:
+                  'Contract changed but planner produced no operations. ' +
+                  'This indicates unsupported or ignored changes.',
+              },
+            ],
+          }),
+        );
+      }
+      migrationTsContent = plannerResult.plan.renderTypeScript();
     }
 
-    // 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);
+    await writeMigrationPackage(packageDir, manifest, []);
+    await copyContractToMigrationDir(packageDir, contractPathAbsolute);
+    await writeMigrationTs(packageDir, migrationTsContent);
+
+    // Always run emit inline. If migration.ts contains unfilled
+    // placeholders (e.g. user must hand-author a dataTransform body),
+    // emitMigration throws errorUnfilledPlaceholder (PN-MIG-2001) and
+    // we propagate that structured error to the user.
+    const { operations, migrationId } = await emitMigration(packageDir, {
+      targetId: config.target.targetId,
+      migrations,
+      frameworkComponents,
+    });
 
-    const manifest: MigrationManifest = {
+    const sql = extractSqlDdl(operations);
+    const result: MigrationPlanResult = {
+      ok: true,
+      noOp: false,
       from: fromHash,
       to: toStorageHash,
-      migrationId: null,
-      kind: 'regular',
-      fromContract,
-      toContract: toContractJson,
-      hints: {
-        used: [],
-        applied: [],
-        plannerVersion: '2.0.0',
-        planningStrategy: 'descriptors',
-      },
-      labels: [],
-      createdAt: timestamp.toISOString(),
+      migrationId,
+      dir: relative(process.cwd(), packageDir),
+      operations: operations.map((op) => ({
+        id: op.id,
+        label: op.label,
+        operationClass: op.operationClass,
+      })),
+      sql,
+      summary: `Planned ${operations.length} operation(s)`,
+      timings: { total: Date.now() - startTime },
     };
-
-    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 ok(result);
+  } catch (error) {
+    return notOk(mapMigrationToolsError(error));
   }
-
-  return notOk(
-    errorTargetMigrationNotSupported({
-      why: `Target "${config.target.id}" does not support planWithDescriptors`,
-    }),
-  );
 }
 
 export function createMigrationPlanCommand(): Command {

package/src/commands/migration-show.ts

@@ -137,7 +137,7 @@ async function executeMigrationShowCommand(
           return notOk(
             errorRuntime('No attested migrations found', {
               why: `All migrations in ${migrationsRelative} are drafts (migrationId: null)`,
-              fix: 'Run `prisma-next migration verify --dir <path>` to attest a draft migration.',
+              fix: 'Run `prisma-next migration emit --dir <path>` to attest a draft migration.',
             }),
           );
         }

package/src/commands/migration-status.ts

@@ -460,7 +460,7 @@ async function executeMigrationStatusCommand(
       severity: 'warn',
       message: `${drafts.length} draft migration(s) found: ${drafts.map((d) => d.dirName).join(', ')}`,
       hints: [
-        "Run 'prisma-next migration verify --dir <path>' to attest draft migrations before applying",
+        "Run 'prisma-next migration emit --dir <path>' to attest draft migrations before applying",
       ],
     });
   }

package/src/control-api/operations/db-init.ts

@@ -83,6 +83,9 @@ export async function executeDbInit<TFamilyId extends string, TTargetId extends
     contract,
     schema: schemaIR,
     policy,
+    // `db init` does not produce a `migration.ts`, so the from-hash on the
+    // resulting plan is never surfaced to authoring — pass empty string.
+    fromHash: '',
     frameworkComponents,
   });
 

package/src/control-api/operations/db-update.ts

@@ -83,6 +83,9 @@ export async function executeDbUpdate<TFamilyId extends string, TTargetId extend
     contract,
     schema: schemaIR,
     policy,
+    // `db update` does not produce a `migration.ts`, so the from-hash on the
+    // resulting plan is never surfaced to authoring — pass empty string.
+    fromHash: '',
     frameworkComponents,
   });
   if (plannerResult.kind === 'failure') {