@prisma-next/cli 0.4.0-dev.9 → 0.4.2

package/src/commands/migration-apply.ts

@@ -1,7 +1,8 @@
+import { verifyMigrationBundle } from '@prisma-next/migration-tools/attestation';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { findPathWithDecision } from '@prisma-next/migration-tools/dag';
 import { readRefs, resolveRef } from '@prisma-next/migration-tools/refs';
-import type { AttestedMigrationBundle } from '@prisma-next/migration-tools/types';
+import type { MigrationBundle } from '@prisma-next/migration-tools/types';
 import { MigrationToolsError } from '@prisma-next/migration-tools/types';
 import { notOk, ok, type Result } from '@prisma-next/utils/result';
 import { Command } from 'commander';
@@ -63,7 +64,7 @@ export interface MigrationApplyResult {
     readonly refName?: string;
     readonly selectedPath: readonly {
       readonly dirName: string;
-      readonly migrationId: string | null;
+      readonly migrationId: string;
       readonly from: string;
       readonly to: string;
     }[];
@@ -94,7 +95,7 @@ function mapApplyFailure(failure: MigrationApplyFailure): CliStructuredErrorType
   });
 }
 
-function packageToStep(pkg: AttestedMigrationBundle): MigrationApplyStep {
+function packageToStep(pkg: MigrationBundle): MigrationApplyStep {
   return {
     dirName: pkg.dirName,
     from: pkg.manifest.from,
@@ -111,7 +112,7 @@ async function executeMigrationApplyCommand(
   startTime: number,
 ): Promise<Result<MigrationApplyResult, CliStructuredErrorType>> {
   const config = await loadConfig(options.config);
-  const { configPath, migrationsDir, migrationsRelative, refsPath } = resolveMigrationPaths(
+  const { configPath, migrationsDir, migrationsRelative, refsDir } = resolveMigrationPaths(
     options.config,
     config,
   );
@@ -148,8 +149,8 @@ async function executeMigrationApplyCommand(
   if (options.ref) {
     refName = options.ref;
     try {
-      const refs = await readRefs(refsPath);
-      destinationHash = resolveRef(refs, refName);
+      const refs = await readRefs(refsDir);
+      destinationHash = resolveRef(refs, refName).hash;
     } catch (error) {
       if (MigrationToolsError.is(error)) {
         return notOk(mapMigrationToolsError(error));
@@ -198,12 +199,6 @@ async function executeMigrationApplyCommand(
   let migrations: MigrationBundleSet;
   try {
     migrations = await loadAllBundles(migrationsDir);
-    if (migrations.drafts.length > 0 && !flags.quiet) {
-      ui.warn(
-        `${migrations.drafts.length} draft migration(s) found: ${migrations.drafts.map((d) => d.dirName).join(', ')}. ` +
-          "Run 'prisma-next migration emit --dir <path>' to attest before applying.",
-      );
-    }
   } catch (error) {
     if (MigrationToolsError.is(error)) {
       return notOk(mapMigrationToolsError(error));
@@ -211,6 +206,27 @@ async function executeMigrationApplyCommand(
     throw error;
   }
 
+  // Defense in depth: re-hash every bundle and confirm the recorded
+  // `migrationId` matches the on-disk `(manifest, ops)`. Catches FS
+  // corruption, partial writes, and post-emit hand edits before we
+  // start touching the database.
+  for (const bundle of migrations.bundles) {
+    const verified = verifyMigrationBundle(bundle);
+    if (!verified.ok) {
+      return notOk(
+        errorRuntime(`Migration package is corrupt: ${bundle.dirName}`, {
+          why: `Stored migrationId "${verified.storedMigrationId}" does not match the recomputed hash "${verified.computedMigrationId}" for ${migrationsRelative}/${bundle.dirName}. The migration.json or ops.json has been edited or partially written since emit.`,
+          fix: `Re-emit the package by running \`node "${migrationsRelative}/${bundle.dirName}/migration.ts"\`, or restore the directory from version control.`,
+          meta: {
+            dirName: bundle.dirName,
+            storedMigrationId: verified.storedMigrationId,
+            computedMigrationId: verified.computedMigrationId,
+          },
+        }),
+      );
+    }
+  }
+
   const client = createControlClient({
     family: config.family,
     target: config.target,
@@ -223,12 +239,12 @@ async function executeMigrationApplyCommand(
     await client.connect(dbConnection);
     const marker = await client.readMarker();
 
-    // --- No attested migrations on disk ---
-    if (migrations.attested.length === 0) {
+    // --- No migrations on disk ---
+    if (migrations.bundles.length === 0) {
       if (marker?.storageHash) {
         return notOk(
           errorRuntime('Database has state but no migrations exist', {
-            why: `The database marker hash "${marker.storageHash}" exists but no attested migrations were found in ${migrationsRelative}`,
+            why: `The database marker hash "${marker.storageHash}" exists but no migrations were found in ${migrationsRelative}`,
             fix: 'Ensure the migrations directory is correct. If the database was managed with `db init` or `db update`, run `prisma-next db sign` to update the marker.',
             meta: { markerHash: marker.storageHash, migrationsDir: migrationsRelative },
           }),
@@ -238,8 +254,8 @@ async function executeMigrationApplyCommand(
       if (destinationHash !== EMPTY_CONTRACT_HASH) {
         return notOk(
           errorRuntime('Current contract has no planned migrations', {
-            why: `No attested migrations were found in ${migrationsRelative}, but current contract hash is "${destinationHash}"`,
-            fix: 'Run `prisma-next migration plan` to create an attested migration for the current contract.',
+            why: `No migrations were found in ${migrationsRelative}, but current contract hash is "${destinationHash}"`,
+            fix: 'Run `prisma-next migration plan` to create a migration for the current contract.',
             meta: { destinationHash, migrationsDir: migrationsRelative },
           }),
         );
@@ -251,7 +267,7 @@ async function executeMigrationApplyCommand(
         migrationsTotal: 0,
         markerHash: EMPTY_CONTRACT_HASH,
         applied: [],
-        summary: 'No attested migrations found',
+        summary: 'No migrations found',
         timings: { total: Date.now() - startTime },
       });
     }
@@ -283,15 +299,10 @@ async function executeMigrationApplyCommand(
     }
 
     if (!migrations.graph.nodes.has(destinationHash)) {
-      const matchingDraft = migrations.drafts.find((d) => d.manifest.to === destinationHash);
       return notOk(
         errorRuntime('Current contract has no planned migration path', {
-          why: matchingDraft
-            ? `A draft migration exists at "${matchingDraft.dirName}" but has not been attested`
-            : `Current contract hash "${destinationHash}" is not present in the migration history at ${migrationsRelative}`,
-          fix: matchingDraft
-            ? `Run 'prisma-next migration emit --dir "${migrationsRelative}/${matchingDraft.dirName}"' to attest, then re-run apply.`
-            : 'Run `prisma-next migration plan` to create a migration for the current contract, then re-run apply.',
+          why: `Current contract hash "${destinationHash}" is not present in the migration history at ${migrationsRelative}`,
+          fix: 'Run `prisma-next migration plan` to create a migration for the current contract, then re-run apply.',
           meta: { destinationHash, knownNodes: [...migrations.graph.nodes] },
         }),
       );
@@ -329,7 +340,7 @@ async function executeMigrationApplyCommand(
       });
     }
 
-    const bundleByDir = new Map(migrations.attested.map((b) => [b.dirName, b]));
+    const bundleByDir = new Map(migrations.bundles.map((b) => [b.dirName, b]));
     const pendingMigrations: MigrationApplyStep[] = [];
     for (const migration of pendingPath) {
       const pkg = bundleByDir.get(migration.dirName);

package/src/commands/migration-new.ts

@@ -2,8 +2,7 @@
  * `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
+ * The planner's `emptyMigration(context)` returns a
  * `MigrationPlanWithAuthoringSurface`, whose `renderTypeScript()` produces
  * the target-appropriate empty stub. The CLI writes the returned source
  * verbatim.
@@ -11,18 +10,20 @@
 
 import { readFileSync } from 'node:fs';
 import type { Contract } from '@prisma-next/contract/types';
+import { getEmittedArtifactPaths } from '@prisma-next/emitter';
 import { createControlStack } from '@prisma-next/framework-components/control';
+import { computeMigrationId } from '@prisma-next/migration-tools/attestation';
 import { EMPTY_CONTRACT_HASH } from '@prisma-next/migration-tools/constants';
 import { findLatestMigration, reconstructGraph } from '@prisma-next/migration-tools/dag';
 import {
-  copyContractToMigrationDir,
+  copyFilesWithRename,
   formatMigrationDirName,
   readMigrationsDir,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
 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 { 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';
@@ -116,16 +117,16 @@ async function executeMigrationNewCommand(
 
   let fromContract: Contract | null = null;
   let fromHash: string = EMPTY_CONTRACT_HASH;
+  let fromContractSourceDir: string | null = null;
 
   try {
     const packages = await readMigrationsDir(migrationsDir);
-    const attested = packages.filter(isAttested);
 
-    if (attested.length > 0) {
-      const graph = reconstructGraph(attested);
+    if (packages.length > 0) {
+      const graph = reconstructGraph(packages);
 
       if (options.from) {
-        const match = attested.find((p) => p.manifest.to.startsWith(options.from!));
+        const match = packages.find((p) => p.manifest.to.startsWith(options.from!));
         if (!match) {
           return notOk(
             errorRuntime('Starting contract not found', {
@@ -136,15 +137,17 @@ async function executeMigrationNewCommand(
         }
         fromHash = match.manifest.to;
         fromContract = match.manifest.toContract;
+        fromContractSourceDir = match.dirPath;
       } else {
         const latestMigration = findLatestMigration(graph);
         if (latestMigration) {
           fromHash = latestMigration.to;
-          const leafPkg = attested.find(
+          const leafPkg = packages.find(
             (p) => p.manifest.migrationId === latestMigration.migrationId,
           );
           if (leafPkg) {
             fromContract = leafPkg.manifest.toContract;
+            fromContractSourceDir = leafPkg.dirPath;
           }
         }
       }
@@ -176,10 +179,13 @@ async function executeMigrationNewCommand(
   const dirName = formatMigrationDirName(timestamp, slug);
   const packageDir = join(migrationsDir, dirName);
 
-  const manifest: MigrationManifest = {
+  // `migration new` scaffolds an empty `migration.ts` for the user to
+  // fill, so we attest over `ops: []`. Re-running self-emit after the
+  // user adds operations will produce a different `migrationId` (over
+  // the real ops). This is intentional — there is no on-disk draft.
+  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
     from: fromHash,
     to: toStorageHash,
-    migrationId: null,
     kind: 'regular',
     fromContract,
     toContract: toContractJson,
@@ -187,11 +193,14 @@ async function executeMigrationNewCommand(
       used: [],
       applied: [],
       plannerVersion: '1.0.0',
-      planningStrategy: 'manual',
     },
     labels: [],
     createdAt: timestamp.toISOString(),
   };
+  const manifest: MigrationManifest = {
+    ...baseManifest,
+    migrationId: computeMigrationId(baseManifest, []),
+  };
 
   const migrations = getTargetMigrations(config.target);
   if (!migrations) {
@@ -210,14 +219,27 @@ async function executeMigrationNewCommand(
     ]);
 
     await writeMigrationPackage(packageDir, manifest, []);
-    await copyContractToMigrationDir(packageDir, contractPathAbsolute);
+    const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+    await copyFilesWithRename(packageDir, [
+      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
+      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
+    ]);
+    if (fromContractSourceDir !== null) {
+      const sourceArtifacts = getEmittedArtifactPaths(
+        join(fromContractSourceDir, 'end-contract.json'),
+      );
+      await copyFilesWithRename(packageDir, [
+        { sourcePath: sourceArtifacts.jsonPath, destName: 'start-contract.json' },
+        { sourcePath: sourceArtifacts.dtsPath, destName: 'start-contract.d.ts' },
+      ]);
+    }
 
     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'),
+      contractJsonPath: join(packageDir, 'end-contract.json'),
       fromHash,
       toHash: toStorageHash,
     });
@@ -248,8 +270,8 @@ export function createMigrationNewCommand(): Command {
     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 emit` to resolve and attest the package.',
+      'Write the migration body in migration.ts, then run the file with Node\n' +
+      '(`node migration.ts`) to self-emit ops.json and attest the package.',
   );
   setCommandExamples(command, [
     'prisma-next migration new --name split-name',
@@ -283,7 +305,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 emit --dir "${value.dir}"\` to attest.`,
+            `\nEdit migration.ts, then run it directly (\`node "${value.dir}/migration.ts"\`) to self-emit and attest.`,
           );
         }
       });

package/src/commands/migration-plan.ts

@@ -1,10 +1,15 @@
 import { readFile } from 'node:fs/promises';
 import type { Contract } from '@prisma-next/contract/types';
-import { createControlStack } from '@prisma-next/framework-components/control';
+import { getEmittedArtifactPaths } from '@prisma-next/emitter';
+import {
+  createControlStack,
+  type MigrationPlanOperation,
+} from '@prisma-next/framework-components/control';
+import { computeMigrationId } 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 {
-  copyContractToMigrationDir,
+  copyFilesWithRename,
   formatMigrationDirName,
   writeMigrationPackage,
 } from '@prisma-next/migration-tools/io';
@@ -15,8 +20,6 @@ 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,
@@ -54,7 +57,6 @@ export interface MigrationPlanResult {
   readonly noOp: boolean;
   readonly from: string;
   readonly to: string;
-  readonly migrationId?: string;
   readonly dir?: string;
   readonly operations: readonly {
     readonly id: string;
@@ -63,6 +65,12 @@ export interface MigrationPlanResult {
   }[];
   readonly sql?: readonly string[];
   readonly summary: string;
+  /**
+   * When true, `migration.ts` was written but contains unfilled
+   * `placeholder(...)` calls. The user must edit the file and then run
+   * `node migration.ts` to self-emit `ops.json` / `migration.json`.
+   */
+  readonly pendingPlaceholders?: boolean;
   readonly timings: {
     readonly total: number;
   };
@@ -166,20 +174,10 @@ async function executeMigrationPlanCommand(
   // Read existing migrations and determine "from" contract
   let fromContract: Contract | null = null;
   let fromHash: string = EMPTY_CONTRACT_HASH;
+  let fromContractSourceDir: string | null = null;
 
   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 emit --dir ${migrationsRelative}/${existingDraft.dirName}' to attest it, or delete it and re-plan.`,
-        }),
-      );
-    }
+    const { bundles, graph } = await loadAllBundles(migrationsDir);
 
     if (options.from) {
       const resolved = resolveBundleByPrefix(bundles, options.from);
@@ -199,6 +197,7 @@ async function executeMigrationPlanCommand(
       }
       fromHash = resolved.value.manifest.to;
       fromContract = resolved.value.manifest.toContract;
+      fromContractSourceDir = resolved.value.dirPath;
     } else {
       const latestMigration = findLatestMigration(graph);
       if (latestMigration) {
@@ -206,6 +205,7 @@ async function executeMigrationPlanCommand(
         const leafPkg = bundles.find((p) => p.manifest.migrationId === latestMigration.migrationId);
         if (leafPkg) {
           fromContract = leafPkg.manifest.toContract;
+          fromContractSourceDir = leafPkg.dirPath;
         }
       }
     }
@@ -245,18 +245,15 @@ async function executeMigrationPlanCommand(
     [config.target, config.adapter, ...(config.extensionPacks ?? [])],
   );
 
-  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 = {
+  const baseManifest: Omit<MigrationManifest, 'migrationId'> = {
     from: fromHash,
     to: toStorageHash,
-    migrationId: null,
     kind: 'regular',
     fromContract,
     toContract: toContractJson,
@@ -264,41 +261,42 @@ async function executeMigrationPlanCommand(
       used: [],
       applied: [],
       plannerVersion: '2.0.0',
-      planningStrategy: strategy === 'descriptor' ? 'descriptors' : 'class-based',
     },
     labels: [],
     createdAt: timestamp.toISOString(),
   };
 
-  const scaffoldContext = {
-    packageDir,
-    contractJsonPath: contractPathAbsolute,
-    fromHash,
-    toHash: toStorageHash,
-  };
-
   try {
-    let migrationTsContent: string;
+    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,
+      fromContract,
+      frameworkComponents,
+    });
+    if (plannerResult.kind === 'failure') {
+      return notOk(
+        errorMigrationPlanningFailed({
+          conflicts: plannerResult.conflicts as readonly CliErrorConflict[],
+        }),
+      );
+    }
 
-    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) {
+    // Accessing .operations triggers toOp() on each call. If any call
+    // is a DataTransformCall with an unfilled placeholder stub, toOp()
+    // throws PN-MIG-2001. We catch that here so the migration can still
+    // be scaffolded with `ops: []`; the user fills the placeholder, then
+    // re-runs `node migration.ts` to attest with the real ops.
+    let plannedOps: readonly MigrationPlanOperation[] = [];
+    let hasPlaceholders = false;
+    try {
+      plannedOps = plannerResult.plan.operations;
+      if (plannedOps.length === 0) {
         return notOk(
           errorMigrationPlanningFailed({
             conflicts: [
@@ -312,75 +310,74 @@ async function executeMigrationPlanCommand(
           }),
         );
       }
-      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.',
-              },
-            ],
-          }),
-        );
+    } catch (e) {
+      if (CliStructuredError.is(e) && e.domain === 'MIG' && e.code === '2001') {
+        hasPlaceholders = true;
+      } else {
+        throw e;
       }
-      migrationTsContent = plannerResult.plan.renderTypeScript();
     }
 
-    await writeMigrationPackage(packageDir, manifest, []);
-    await copyContractToMigrationDir(packageDir, contractPathAbsolute);
+    const migrationTsContent = plannerResult.plan.renderTypeScript();
+
+    // Always-attest: compute migrationId over (manifest, ops). When
+    // placeholders blocked lowering, ops is `[]` and the id hashes over
+    // the empty list — re-emitting after the user fills the placeholder
+    // produces a different id (over the real ops). This is intentional;
+    // there is no on-disk "draft" state.
+    const opsForWrite = hasPlaceholders ? [] : plannedOps;
+    const manifest: MigrationManifest = {
+      ...baseManifest,
+      migrationId: computeMigrationId(baseManifest, opsForWrite),
+    };
+
+    await writeMigrationPackage(packageDir, manifest, opsForWrite);
+    const destinationArtifacts = getEmittedArtifactPaths(contractPathAbsolute);
+    await copyFilesWithRename(packageDir, [
+      { sourcePath: destinationArtifacts.jsonPath, destName: 'end-contract.json' },
+      { sourcePath: destinationArtifacts.dtsPath, destName: 'end-contract.d.ts' },
+    ]);
+    if (fromContractSourceDir !== null) {
+      const sourceArtifacts = getEmittedArtifactPaths(
+        join(fromContractSourceDir, 'end-contract.json'),
+      );
+      await copyFilesWithRename(packageDir, [
+        { sourcePath: sourceArtifacts.jsonPath, destName: 'start-contract.json' },
+        { sourcePath: sourceArtifacts.dtsPath, destName: 'start-contract.d.ts' },
+      ]);
+    }
     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,
-    });
+    if (hasPlaceholders) {
+      const result: MigrationPlanResult = {
+        ok: true,
+        noOp: false,
+        from: fromHash,
+        to: toStorageHash,
+        dir: relative(process.cwd(), packageDir),
+        operations: [],
+        pendingPlaceholders: true,
+        summary:
+          'Planned migration with placeholder(s) — edit migration.ts then run `node migration.ts` to self-emit',
+        timings: { total: Date.now() - startTime },
+      };
+      return ok(result);
+    }
 
-    const sql = extractSqlDdl(operations);
+    const sql = extractSqlDdl(plannedOps);
     const result: MigrationPlanResult = {
       ok: true,
       noOp: false,
       from: fromHash,
       to: toStorageHash,
-      migrationId,
       dir: relative(process.cwd(), packageDir),
-      operations: operations.map((op) => ({
+      operations: plannedOps.map((op) => ({
         id: op.id,
         label: op.label,
         operationClass: op.operationClass,
       })),
       sql,
-      summary: `Planned ${operations.length} operation(s)`,
+      summary: `Planned ${plannedOps.length} operation(s)`,
       timings: { total: Date.now() - startTime },
     };
     return ok(result);
@@ -442,6 +439,22 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
     return lines.join('\n');
   }
 
+  if (result.pendingPlaceholders) {
+    lines.push(`${yellow_('⚠')} ${result.summary}`);
+    lines.push('');
+    lines.push(dim_(`from: ${result.from}`));
+    lines.push(dim_(`to:   ${result.to}`));
+    if (result.dir) {
+      lines.push(dim_(`dir:  ${result.dir}`));
+    }
+    lines.push('');
+    lines.push(
+      'Open migration.ts and replace each `placeholder(...)` call with your actual query.',
+    );
+    lines.push(`Then run: ${green_(`node ${result.dir ?? '<dir>'}/migration.ts`)}`);
+    return lines.join('\n');
+  }
+
   lines.push(`${green_('✔')} ${result.summary}`);
   lines.push('');
 
@@ -470,13 +483,15 @@ function formatMigrationPlanOutput(result: MigrationPlanResult, flags: GlobalFla
 
   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}`));
   }
 
+  lines.push('');
+  lines.push(
+    `Next: ${green_(`node ${result.dir ?? '<dir>'}/migration.ts`)} to emit ops.json and attest migrationId before running ${green_('prisma-next migration apply')}.`,
+  );
+
   if (result.sql && result.sql.length > 0) {
     lines.push('');
     lines.push(dim_('DDL preview'));